doc/howto-create-a-server-cert.texi

   1 @node Howto Create a Server Cert
   2 @section Creating a TLS server certificate
   3
   4
   5 Here is a brief run up on how to create a server certificate. It has
   6 actually been done this way to get a certificate from CAcert to be used
   7 on a real server.  It has only been tested with this CA, but there
   8 shouldn't be any problem to run this against any other CA.
   9
  10 We start by generating an X.509 certificate signing request. As there
  11 is no need for a configuration file, you may simply enter:
  12
  13 @cartouche
  14 @example
  15   $ gpgsm --generate-key >example.com.cert-req.pem
  16   Please select what kind of key you want:
  17      (1) RSA
  18      (2) Existing key
  19      (3) Existing key from card
  20   Your selection? 1
  21 @end example
  22 @end cartouche
  23
  24 I opted for creating a new RSA key. The other option is to use an
  25 already existing key, by selecting @kbd{2} and entering the so-called
  26 keygrip.  Running the command @samp{gpgsm --dump-secret-key USERID}
  27 shows you this keygrip.  Using @kbd{3} offers another menu to create a
  28 certificate directly from a smart card based key.
  29
  30 Let's continue:
  31
  32 @cartouche
  33 @example
  34   What keysize do you want? (2048)
  35   Requested keysize is 2048 bits
  36 @end example
  37 @end cartouche
  38
  39 Hitting enter chooses the default RSA key size of 2048 bits.  Smaller
  40 keys are too weak on the modern Internet.  If you choose a larger
  41 (stronger) key, your server will need to do more work.
  42
  43 @cartouche
  44 @example
  45   Possible actions for a RSA key:
  46      (1) sign, encrypt
  47      (2) sign
  48      (3) encrypt
  49   Your selection? 1
  50 @end example
  51 @end cartouche
  52
  53 Selecting ``sign'' enables use of the key for Diffie-Hellman key
  54 exchange mechanisms (DHE and ECDHE) in TLS, which are preferred
  55 because they offer forward secrecy.  Selecting ``encrypt'' enables RSA
  56 key exchange mechanisms, which are still common in some places.
  57 Selecting both enables both key exchange mechanisms.
  58
  59 Now for some real data:
  60
  61 @cartouche
  62 @example
  63   Enter the X.509 subject name: CN=example.com
  64 @end example
  65 @end cartouche
  66
  67 This is the most important value for a server certificate. Enter here
  68 the canonical name of your server machine. You may add other virtual
  69 server names later.
  70
  71 @cartouche
  72 @example
  73   E-Mail addresses (end with an empty line):
  74   >
  75 @end example
  76 @end cartouche
  77
  78 We don't need email addresses in a TLS server certificate and CAcert
  79 would anyway ignore such a request. Thus just hit enter.
  80
  81 If you want to create a client certificate for email encryption, this
  82 would be the place to enter your mail address
  83 (e.g. @email{joe@@example.org}). You may enter as many addresses as you like,
  84 however the CA may not accept them all or reject the entire request.
  85
  86 @cartouche
  87 @example
  88   Enter DNS names (optional; end with an empty line):
  89   > example.com
  90   > www.example.com
  91   >
  92 @end example
  93 @end cartouche
  94
  95 Here I entered the names of the services which the machine actually
  96 provides.  You almost always want to include the canonical name here
  97 too. The browser will accept a certificate for any of these names. As
  98 usual the CA must approve all of these names.
  99
 100 @cartouche
 101 @example
 102   URIs (optional; end with an empty line):
 103   >
 104 @end example
 105 @end cartouche
 106
 107 It is possible to insert arbitrary URIs into a certificate; for a server
 108 certificate this does not make sense.
 109
 110 @cartouche
 111 @example
 112   Create self-signed certificate? (y/N)
 113 @end example
 114 @end cartouche
 115
 116 Since we are creating a certificate signing request, and not a full
 117 certificate, we answer no here, or just hit enter for the default.
 118
 119 We have now entered all required information and @command{gpgsm} will
 120 display what it has gathered and ask whether to create the certificate
 121 request:
 122
 123 @cartouche
 124 @example
 125   These parameters are used:
 126       Key-Type: RSA
 127       Key-Length: 2048
 128       Key-Usage: sign, encrypt
 129       Name-DN: CN=example.com
 130       Name-DNS: example.com
 131       Name-DNS: www.example.com
 132
 133   Proceed with creation? (y/N) y
 134 @end example
 135 @end cartouche
 136
 137 @command{gpgsm} will now start working on creating the request. As this
 138 includes the creation of an RSA key it may take a while. During this
 139 time you will be asked 3 times for a passphrase to protect the created
 140 private key on your system. A pop up window will appear to ask for
 141 it. The first two prompts are for the new passphrase and for re-entering it;
 142 the third one is required to actually create the certificate signing request.
 143
 144 When it is ready, you should see the final notice:
 145
 146 @cartouche
 147 @example
 148   Ready.  You should now send this request to your CA.
 149 @end example
 150 @end cartouche
 151
 152 Now, you may look at the created request:
 153
 154 @cartouche
 155 @example
 156   $ cat example.com.cert-req.pem
 157   -----BEGIN CERTIFICATE REQUEST-----
 158   MIIClTCCAX0CAQAwFjEUMBIGA1UEAxMLZXhhbXBsZS5jb20wggEiMA0GCSqGSIb3
 159   DQEBAQUAA4IBDwAwggEKAoIBAQDP1QEcbTvOLLCX4gAoOzH9AW7jNOMj7OSOL0uW
 160   h2bCdkK5YVpnX212Z6COTC3ZG0pJiCeGt1TbbDJUlTa4syQ6JXavjK66N8ASZsyC
 161   Rwcl0m6hbXp541t1dbgt2VgeGk25okWw3j+brw6zxLD2TnthJxOatID0lDIG47HW
 162   GqzZmA6WHbIBIONmGnReIHTpPAPCDm92vUkpKG1xLPszuRmsQbwEl870W/FHrsvm
 163   DPvVUUSdIvTV9NuRt7/WY6G4nPp9QlIuTf1ESPzIuIE91gKPdrRCAx0yuT708S1n
 164   xCv3ETQ/bKPoAQ67eE3mPBqkcVwv9SE/2/36Lz06kAizRgs5AgMBAAGgOjA4Bgkq
 165   hkiG9w0BCQ4xKzApMCcGA1UdEQQgMB6CC2V4YW1wbGUuY29tgg93d3cuZXhhbXBs
 166   ZS5jb20wDQYJKoZIhvcNAQELBQADggEBAEWD0Qqz4OENLYp6yyO/KqF0ig9FDsLN
 167   b5/R+qhms5qlhdB5+Dh+j693Sj0UgbcNKc6JT86IuBqEBZmRCJuXRoKoo5aMS1cJ
 168   hXga7N9IA3qb4VBUzBWvlL92U2Iptr/cEbikFlYZF2Zv3PBv8RfopVlI3OLbKV9D
 169   bJJTt/6kuoydXKo/Vx4G0DFzIKNdFdJk86o/Ziz8NOs9JjZxw9H9VY5sHKFM5LKk
 170   VcLwnnLRlNjBGB+9VK/Tze575eG0cJomTp7UGIB+1xzIQVAhUZOizRDv9tHDeaK3
 171   k+tUhV0kuJcYHucpJycDSrP/uAY5zuVJ0rs2QSjdnav62YrRgEsxJrU=
 172   -----END CERTIFICATE REQUEST-----
 173   $
 174 @end example
 175 @end cartouche
 176
 177 You may now proceed by logging into your account at the CAcert website,
 178 choose @code{Server Certificates - New}, check @code{sign by class 3 root
 179 certificate}, paste the above request block into the text field and
 180 click on @code{Submit}.
 181
 182 If everything works out fine, a certificate will be shown. Now run
 183
 184 @cartouche
 185 @example
 186 $ gpgsm --import
 187 @end example
 188 @end cartouche
 189
 190 and paste the certificate from the CAcert page into your terminal
 191 followed by a Ctrl-D
 192
 193 @cartouche
 194 @example
 195   -----BEGIN CERTIFICATE-----
 196   MIIEIjCCAgqgAwIBAgIBTDANBgkqhkiG9w0BAQQFADBUMRQwEgYDVQQKEwtDQWNl
 197    [...]
 198   rUTFlNElRXCwIl0YcJkIaYYqWf7+A/aqYJCi8+51usZwMy3Jsq3hJ6MA3h1BgwZs
 199   Rtct3tIX
 200   -----END CERTIFICATE-----
 201   gpgsm: issuer certificate (#/CN=CAcert Class 3 Ro[...]) not found
 202   gpgsm: certificate imported
 203
 204   gpgsm: total number processed: 1
 205   gpgsm:               imported: 1
 206 @end example
 207 @end cartouche
 208
 209 @command{gpgsm} tells you that it has imported the certificate. It is now
 210 associated with the key you used when creating the request. The root
 211 certificate has not been found, so you may want to import it from the
 212 CACert website.
 213
 214 To see the content of your certificate, you may now enter:
 215
 216 @cartouche
 217 @example
 218   $ gpgsm -K example.com
 219   /home/foo/.gnupg/pubring.kbx
 220   ---------------------------
 221   Serial number: 4C
 222          Issuer: /CN=CAcert Class 3 Root/OU=http:\x2f\x2fwww.[...]
 223         Subject: /CN=example.com
 224             aka: (dns-name example.com)
 225             aka: (dns-name www.example.com)
 226        validity: 2015-07-01 16:20:51 through 2016-07-01 16:20:51
 227        key type: 2048 bit RSA
 228       key usage: digitalSignature keyEncipherment
 229   ext key usage: clientAuth (suggested), serverAuth (suggested), [...]
 230     fingerprint: 0F:9C:27:B2:DA:05:5F:CB:33:D8:19:E9:65:B9:4F:BD:B1:98:CC:57
 231 @end example
 232 @end cartouche
 233
 234 I used @option{-K} above because this will only list certificates for
 235 which a private key is available.  To see more details, you may use
 236 @option{--dump-secret-keys} instead of @option{-K}.
 237
 238
 239 To make actual use of the certificate you need to install it on your
 240 server. Server software usually expects a PKCS\#12 file with key and
 241 certificate. To create such a file, run:
 242
 243 @cartouche
 244 @example
 245   $ gpgsm --export-secret-key-p12 -a >example.com-cert.pem
 246 @end example
 247 @end cartouche
 248
 249 You will be asked for the passphrase as well as for a new passphrase to
 250 be used to protect the PKCS\#12 file. The file now contains the
 251 certificate as well as the private key:
 252
 253 @cartouche
 254 @example
 255   $ cat example-cert.pem
 256   Issuer ...: /CN=CAcert Class 3 Root/OU=http:\x2f\x2fwww.CA[...]
 257   Serial ...: 4C
 258   Subject ..: /CN=example.com
 259       aka ..: (dns-name example.com)
 260       aka ..: (dns-name www.example.com)
 261
 262   -----BEGIN PKCS12-----
 263   MIIHlwIBAzCCB5AGCSqGSIb37QdHAaCCB4EEggd9MIIHeTk1BJ8GCSqGSIb3DQEu
 264   [...many more lines...]
 265   -----END PKCS12-----
 266   $
 267 @end example
 268 @end cartouche
 269
 270 Copy this file in a secure way to the server, install it there and
 271 delete the file then. You may export the file again at any time as long
 272 as it is available in GnuPG's private key database.
 273
 274