diff options
Diffstat (limited to 'doc/howto-create-a-server-cert.texi')
| -rw-r--r-- | doc/howto-create-a-server-cert.texi | 274 |
1 files changed, 274 insertions, 0 deletions
diff --git a/doc/howto-create-a-server-cert.texi b/doc/howto-create-a-server-cert.texi new file mode 100644 index 0000000..30e28bd --- /dev/null +++ b/doc/howto-create-a-server-cert.texi @@ -0,0 +1,274 @@ +@node Howto Create a Server Cert +@section Creating a TLS server certificate + + +Here is a brief run up on how to create a server certificate. It has +actually been done this way to get a certificate from CAcert to be used +on a real server. It has only been tested with this CA, but there +shouldn't be any problem to run this against any other CA. + +We start by generating an X.509 certificate signing request. As there +is no need for a configuration file, you may simply enter: + +@cartouche +@example + $ gpgsm --generate-key >example.com.cert-req.pem + Please select what kind of key you want: + (1) RSA + (2) Existing key + (3) Existing key from card + Your selection? 1 +@end example +@end cartouche + +I opted for creating a new RSA key. The other option is to use an +already existing key, by selecting @kbd{2} and entering the so-called +keygrip. Running the command @samp{gpgsm --dump-secret-key USERID} +shows you this keygrip. Using @kbd{3} offers another menu to create a +certificate directly from a smart card based key. + +Let's continue: + +@cartouche +@example + What keysize do you want? (3072) + Requested keysize is 3072 bits +@end example +@end cartouche + +Hitting enter chooses the default RSA key size of 3072 bits. Keys +smaller than 2048 bits are too weak on the modern Internet. If you +choose a larger (stronger) key, your server will need to do more work. + +@cartouche +@example + Possible actions for a RSA key: + (1) sign, encrypt + (2) sign + (3) encrypt + Your selection? 1 +@end example +@end cartouche + +Selecting ``sign'' enables use of the key for Diffie-Hellman key +exchange mechanisms (DHE and ECDHE) in TLS, which are preferred +because they offer forward secrecy. Selecting ``encrypt'' enables RSA +key exchange mechanisms, which are still common in some places. +Selecting both enables both key exchange mechanisms. + +Now for some real data: + +@cartouche +@example + Enter the X.509 subject name: CN=example.com +@end example +@end cartouche + +This is the most important value for a server certificate. Enter here +the canonical name of your server machine. You may add other virtual +server names later. + +@cartouche +@example + E-Mail addresses (end with an empty line): + > +@end example +@end cartouche + +We don't need email addresses in a TLS server certificate and CAcert +would anyway ignore such a request. Thus just hit enter. + +If you want to create a client certificate for email encryption, this +would be the place to enter your mail address +(e.g. @email{joe@@example.org}). You may enter as many addresses as you like, +however the CA may not accept them all or reject the entire request. + +@cartouche +@example + Enter DNS names (optional; end with an empty line): + > example.com + > www.example.com + > +@end example +@end cartouche + +Here I entered the names of the services which the machine actually +provides. You almost always want to include the canonical name here +too. The browser will accept a certificate for any of these names. As +usual the CA must approve all of these names. + +@cartouche +@example + URIs (optional; end with an empty line): + > +@end example +@end cartouche + +It is possible to insert arbitrary URIs into a certificate; for a server +certificate this does not make sense. + +@cartouche +@example + Create self-signed certificate? (y/N) +@end example +@end cartouche + +Since we are creating a certificate signing request, and not a full +certificate, we answer no here, or just hit enter for the default. + +We have now entered all required information and @command{gpgsm} will +display what it has gathered and ask whether to create the certificate +request: + +@cartouche +@example + These parameters are used: + Key-Type: RSA + Key-Length: 3072 + Key-Usage: sign, encrypt + Name-DN: CN=example.com + Name-DNS: example.com + Name-DNS: www.example.com + + Proceed with creation? (y/N) y +@end example +@end cartouche + +@command{gpgsm} will now start working on creating the request. As this +includes the creation of an RSA key it may take a while. During this +time you will be asked 3 times for a passphrase to protect the created +private key on your system. A pop up window will appear to ask for +it. The first two prompts are for the new passphrase and for re-entering it; +the third one is required to actually create the certificate signing request. + +When it is ready, you should see the final notice: + +@cartouche +@example + Ready. You should now send this request to your CA. +@end example +@end cartouche + +Now, you may look at the created request: + +@cartouche +@example + $ cat example.com.cert-req.pem + -----BEGIN CERTIFICATE REQUEST----- + MIIClTCCAX0CAQAwFjEUMBIGA1UEAxMLZXhhbXBsZS5jb20wggEiMA0GCSqGSIb3 + DQEBAQUAA4IBDwAwggEKAoIBAQDP1QEcbTvOLLCX4gAoOzH9AW7jNOMj7OSOL0uW + h2bCdkK5YVpnX212Z6COTC3ZG0pJiCeGt1TbbDJUlTa4syQ6JXavjK66N8ASZsyC + Rwcl0m6hbXp541t1dbgt2VgeGk25okWw3j+brw6zxLD2TnthJxOatID0lDIG47HW + GqzZmA6WHbIBIONmGnReIHTpPAPCDm92vUkpKG1xLPszuRmsQbwEl870W/FHrsvm + DPvVUUSdIvTV9NuRt7/WY6G4nPp9QlIuTf1ESPzIuIE91gKPdrRCAx0yuT708S1n + xCv3ETQ/bKPoAQ67eE3mPBqkcVwv9SE/2/36Lz06kAizRgs5AgMBAAGgOjA4Bgkq + hkiG9w0BCQ4xKzApMCcGA1UdEQQgMB6CC2V4YW1wbGUuY29tgg93d3cuZXhhbXBs + ZS5jb20wDQYJKoZIhvcNAQELBQADggEBAEWD0Qqz4OENLYp6yyO/KqF0ig9FDsLN + b5/R+qhms5qlhdB5+Dh+j693Sj0UgbcNKc6JT86IuBqEBZmRCJuXRoKoo5aMS1cJ + hXga7N9IA3qb4VBUzBWvlL92U2Iptr/cEbikFlYZF2Zv3PBv8RfopVlI3OLbKV9D + bJJTt/6kuoydXKo/Vx4G0DFzIKNdFdJk86o/Ziz8NOs9JjZxw9H9VY5sHKFM5LKk + VcLwnnLRlNjBGB+9VK/Tze575eG0cJomTp7UGIB+1xzIQVAhUZOizRDv9tHDeaK3 + k+tUhV0kuJcYHucpJycDSrP/uAY5zuVJ0rs2QSjdnav62YrRgEsxJrU= + -----END CERTIFICATE REQUEST----- + $ +@end example +@end cartouche + +You may now proceed by logging into your account at the CAcert website, +choose @code{Server Certificates - New}, check @code{sign by class 3 root +certificate}, paste the above request block into the text field and +click on @code{Submit}. + +If everything works out fine, a certificate will be shown. Now run + +@cartouche +@example +$ gpgsm --import +@end example +@end cartouche + +and paste the certificate from the CAcert page into your terminal +followed by a Ctrl-D + +@cartouche +@example + -----BEGIN CERTIFICATE----- + MIIEIjCCAgqgAwIBAgIBTDANBgkqhkiG9w0BAQQFADBUMRQwEgYDVQQKEwtDQWNl + [...] + rUTFlNElRXCwIl0YcJkIaYYqWf7+A/aqYJCi8+51usZwMy3Jsq3hJ6MA3h1BgwZs + Rtct3tIX + -----END CERTIFICATE----- + gpgsm: issuer certificate (#/CN=CAcert Class 3 Ro[...]) not found + gpgsm: certificate imported + + gpgsm: total number processed: 1 + gpgsm: imported: 1 +@end example +@end cartouche + +@command{gpgsm} tells you that it has imported the certificate. It is now +associated with the key you used when creating the request. The root +certificate has not been found, so you may want to import it from the +CACert website. + +To see the content of your certificate, you may now enter: + +@cartouche +@example + $ gpgsm -K example.com + /home/foo/.gnupg/pubring.kbx + --------------------------- + Serial number: 4C + Issuer: /CN=CAcert Class 3 Root/OU=http:\x2f\x2fwww.[...] + Subject: /CN=example.com + aka: (dns-name example.com) + aka: (dns-name www.example.com) + validity: 2015-07-01 16:20:51 through 2016-07-01 16:20:51 + key type: 3072 bit RSA + key usage: digitalSignature keyEncipherment + ext key usage: clientAuth (suggested), serverAuth (suggested), [...] + fingerprint: 0F:9C:27:B2:DA:05:5F:CB:33:D8:19:E9:65:B9:4F:BD:B1:98:CC:57 +@end example +@end cartouche + +I used @option{-K} above because this will only list certificates for +which a private key is available. To see more details, you may use +@option{--dump-secret-keys} instead of @option{-K}. + + +To make actual use of the certificate you need to install it on your +server. Server software usually expects a PKCS\#12 file with key and +certificate. To create such a file, run: + +@cartouche +@example + $ gpgsm --export-secret-key-p12 -a >example.com-cert.pem +@end example +@end cartouche + +You will be asked for the passphrase as well as for a new passphrase to +be used to protect the PKCS\#12 file. The file now contains the +certificate as well as the private key: + +@cartouche +@example + $ cat example-cert.pem + Issuer ...: /CN=CAcert Class 3 Root/OU=http:\x2f\x2fwww.CA[...] + Serial ...: 4C + Subject ..: /CN=example.com + aka ..: (dns-name example.com) + aka ..: (dns-name www.example.com) + + -----BEGIN PKCS12----- + MIIHlwIBAzCCB5AGCSqGSIb37QdHAaCCB4EEggd9MIIHeTk1BJ8GCSqGSIb3DQEu + [...many more lines...] + -----END PKCS12----- + $ +@end example +@end cartouche + +Copy this file in a secure way to the server, install it there and +delete the file then. You may export the file again at any time as long +as it is available in GnuPG's private key database. + + |