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 Before you start, make sure that gpg-agent is running.  As there is no
  11 need for a configuration file, you may simply enter:
  12
  13 @cartouche
  14 @example
  15   $ gpgsm-gencert.sh >a.p10
  16   Key type
  17    [1] RSA
  18    [2] Existing key
  19    [3] Direct from card
  20   Your selection: 1
  21   You selected: RSA
  22 @end example
  23 @end cartouche
  24
  25 I opted for creating a new RSA key. The other option is to use an
  26 already existing key, by selecting @kbd{2} and entering the so-called
  27 keygrip.  Running the command @samp{gpgsm --dump-secret-key USERID}
  28 shows you this keygrip.  Using @kbd{3} offers another menu to create a
  29 certificate directly from a smart card based key.
  30
  31 Let's continue:
  32
  33 @cartouche
  34 @example
  35   Key length
  36    [1] 1024
  37    [2] 2048
  38   Your selection: 1
  39   You selected: 1024
  40 @end example
  41 @end cartouche
  42
  43 The script offers  two common key sizes. With the current setup of
  44 CAcert, it does not make much sense to use a 2k key; their policies need
  45 to be revised anyway (a CA root key valid for 30 years is not really
  46 serious).
  47
  48 @cartouche
  49 @example
  50   Key usage
  51    [1] sign, encrypt
  52    [2] sign
  53    [3] encrypt
  54   Your selection: 1
  55   You selected: sign, encrypt
  56 @end example
  57 @end cartouche
  58
  59 We want to sign and encrypt using this key. This is just a suggestion
  60 and the CA may actually assign other key capabilities.
  61
  62 Now for some real data:
  63
  64 @cartouche
  65 @example
  66   Name (DN)
  67   > CN=kerckhoffs.g10code.com
  68 @end example
  69 @end cartouche
  70
  71 This is the most important value for a server certificate. Enter here
  72 the canonical name of your server machine. You may add other virtual
  73 server names later.
  74
  75 @cartouche
  76 @example
  77   E-Mail addresses (end with an empty line)
  78   >
  79 @end example
  80 @end cartouche
  81
  82 We don't need email addresses in a server certificate and CAcert would
  83 anyway ignore such a request. Thus just hit enter.
  84
  85 If you want to create a client certificate for email encryption, this
  86 would be the place to enter your mail address
  87 (e.g. @email{joe@@example.org}). You may enter as many addresses as you like,
  88 however the CA may not accept them all or reject the entire request.
  89
  90 @cartouche
  91 @example
  92   DNS Names (optional; end with an empty line)
  93   > www.g10code.com
  94   DNS Names (optional; end with an empty line)
  95   > ftp.g10code.com
  96   DNS Names (optional; end with an empty line)
  97   >
  98 @end example
  99 @end cartouche
 100
 101 Here I entered the names of the servers which actually run on the
 102 machine given in the DN above. The browser will accept a certificate for
 103 any of these names. As usual the CA must approve all of these names.
 104
 105 @cartouche
 106 @example
 107   URIs (optional; end with an empty line)
 108   >
 109 @end example
 110 @end cartouche
 111
 112 It is possible to insert arbitrary URIs into a certificate; for a server
 113 certificate this does not make sense.
 114
 115 We have now entered all required information and @command{gpgsm} will
 116 display what it has gathered and ask whether to create the certificate
 117 request:
 118
 119 @cartouche
 120 @example
 121   Parameters for certificate request to create:
 122        1        Key-Type: RSA
 123        2        Key-Length: 1024
 124        3        Key-Usage: sign, encrypt
 125        4        Name-DN: CN=kerckhoffs.g10code.com
 126        5        Name-DNS: www.g10code.com
 127        6        Name-DNS: ftp.g10code.com
 128
 129   Really create such a CSR?
 130    [1] yes
 131    [2] no
 132   Your selection: 1
 133   You selected: yes
 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   gpgsm: certificate request created
 149 @end example
 150 @end cartouche
 151
 152 Now, you may look at the created request:
 153
 154 @cartouche
 155 @example
 156   $ cat a.p10
 157   -----BEGIN CERTIFICATE REQUEST-----
 158   MIIBnzCCAQgCAQAwITEfMB0GA1UEAxMWa2VyY2tob2Zmcy5nMTBjb2RlLmNvbTCB
 159   nzANBgkqhkiG9w0BAQEFAAOBjQAwgYkCgYEA5h+uKRenpvbe+BnMY6siPO50LVyg
 160   HtB7kr+YISlPJ5JAFO12yQFz9Y0sBLHbjR+V+TOawwP1dZhGjlgnEBkMdWKuEBlS
 161   wFTALLX78GAyvAYAmPqSPDEYXkMECyUXVX/bbGI1bY8Y2OGy4w4D+v7e+xD2NBkm
 162   Bj5cNy+YMbGVldECAwEAAaA+MDwGCSqGSIb3DQEJDjEvMC0wKwYDVR0RBCQwIoIP
 163   d3d3LmcxMGNvZGUuY29tgg9mdHAuZzEwY29kZS5jb20wDQYJKoZIhvcNAQEFBQAD
 164   gYEAzBRIi8KTfKyebOlMtDN6oDYBOv+r9A4w3u/Z1ikjffaiN1Bmd2o9Ez9KXKHA
 165   IezLeSEA/rGUPN5Ur5qIJnRNQ8xrS+iLftr8msWQSZppVnA/vnqMrtqBUpitqAr0
 166   eYBmt1Uem2Y3UFABrKPglv2xzgGkrKX6AqmFoOnJWQ0QcTw=
 167   -----END CERTIFICATE REQUEST-----
 168   $
 169 @end example
 170 @end cartouche
 171
 172 You may now proceed by logging into your account at the CAcert website,
 173 choose @code{Server Certificates - New}, check @code{sign by class 3 root
 174 certificate}, paste the above request block into the text field and
 175 click on @code{Submit}.
 176
 177 If everything works out fine, a certificate will be shown. Now run
 178
 179 @cartouche
 180 @example
 181 $ gpgsm --import
 182 @end example
 183 @end cartouche
 184
 185 and paste the certificate from the CAcert page into your terminal
 186 followed by a Ctrl-D
 187
 188 @cartouche
 189 @example
 190   -----BEGIN CERTIFICATE-----
 191   MIIEIjCCAgqgAwIBAgIBTDANBgkqhkiG9w0BAQQFADBUMRQwEgYDVQQKEwtDQWNl
 192   cnQgSW5jLjEeMBwGA1UECxMVaHR0cDovL3d3dy5DQWNlcnQub3JnMRwwGgYDVQQD
 193   ExNDQWNlcnQgQ2xhc3MgMyBSb290MB4XDTA1MTAyODE2MjA1MVoXDTA3MTAyODE2
 194   MjA1MVowITEfMB0GA1UEAxMWa2VyY2tob2Zmcy5nMTBjb2RlLmNvbTCBnzANBgkq
 195   hkiG9w0BAQEFAAOBjQAwgYkCgYEA5h+uKRenpvbe+BnMY6siPO50LVygHtB7kr+Y
 196   ISlPJ5JAFO12yQFz9Y0sBLHbjR+V+TOawwP1dZhGjlgnEBkMdWKuEBlSwFTALLX7
 197   8GAyvAYAmPqSPDEYXkMECyUXVX/bbGI1bY8Y2OGy4w4D+v7e+xD2NBkmBj5cNy+Y
 198   MbGVldECAwEAAaOBtTCBsjAMBgNVHRMBAf8EAjAAMDQGA1UdJQQtMCsGCCsGAQUF
 199   BwMCBggrBgEFBQcDAQYJYIZIAYb4QgQBBgorBgEEAYI3CgMDMAsGA1UdDwQEAwIF
 200   oDAyBggrBgEFBQcBAQQmMCQwIgYIKwYBBQUHMAGGFmh0dHA6Ly9vY3NwLmNhY2Vy
 201   dC5vcmcwKwYDVR0RBCQwIoIPd3d3LmcxMGNvZGUuY29tgg9mdHAuZzEwY29kZS5j
 202   b20wDQYJKoZIhvcNAQEEBQADggIBAAj5XAHCtzQR8PV6PkQBgZqUCbcfxGO/ZIp9
 203   aIT6J2z0Jo1OZI6KmConbqnZG9WyDlV5P7msQXW/Z9nBfoj4KSmNR8G/wtb8ClJn
 204   W8s75+K3ZLq1UgEyxBDrS7GjtbVaj7gsfZsuiQzxmk9lbl1gbkpJ3VEMjwVCTMlM
 205   fpjp8etyPhUZqOZaoKVaq//KTOsjhPMwz7TcfOkHvXketPrWTcefJQU7NKLH16D3
 206   mZAwnBxp3P51H6E6VG8AoJO8xCBuVwsbXKEf/FW+tmKG9pog6CaZQ9WibROTtnKj
 207   NJjSBsrUk5C+JowO/EyZRGm6R1tlok8iFXj+2aimyeBqDcxozNmFgh9F3S5u0wK0
 208   6cfYgkPVMHxgwV3f3Qh+tJkgLExN7KfO9hvpZqAh+CLQtxVmvpxEVEXKR6nwBI5U
 209   BaseulvVy3wUfg2daPkG17kDDBzQlsWC0BRF8anH+FWSrvseC3nS0a9g3sXF1Ic3
 210   gIqeAMhkant1Ac3RR6YCWtJKr2rcQNdDAxXK35/gUSQNCi9dclEzoOgjziuA1Mha
 211   94jYcvGKcwThn0iITVS5hOsCfaySBLxTzfIruLbPxXlpWuCW/6I/7YyivppKgEZU
 212   rUTFlNElRXCwIl0YcJkIaYYqWf7+A/aqYJCi8+51usZwMy3Jsq3hJ6MA3h1BgwZs
 213   Rtct3tIX
 214   -----END CERTIFICATE-----
 215   gpgsm: issuer certificate (#/CN=CAcert Class 3 Ro[...]) not found
 216   gpgsm: certificate imported
 217
 218   gpgsm: total number processed: 1
 219   gpgsm:               imported: 1
 220 @end example
 221 @end cartouche
 222
 223 gpgsm tells you that it has imported the certificate. It is now
 224 associated with the key you used when creating the request. The root
 225 certificate has not been found, so you may want to import it from the
 226 CACert website.
 227
 228 To see the content of your certificate, you may now enter:
 229
 230 @cartouche
 231 @example
 232   $ gpgsm -K kerckhoffs.g10code.com
 233   /home/foo/.gnupg/pubring.kbx
 234   ---------------------------
 235   Serial number: 4C
 236          Issuer: /CN=CAcert Class 3 Root/OU=http:\x2f\x2fwww.[...]
 237         Subject: /CN=kerckhoffs.g10code.com
 238             aka: (dns-name www.g10code.com)
 239             aka: (dns-name ftp.g10code.com)
 240        validity: 2005-10-28 16:20:51 through 2007-10-28 16:20:51
 241        key type: 1024 bit RSA
 242       key usage: digitalSignature keyEncipherment
 243   ext key usage: clientAuth (suggested), serverAuth (suggested), [...]
 244     fingerprint: 0F:9C:27:B2:DA:05:5F:CB:33:19:D8:E9:65:B9:BD:4F:B1:98:CC:57
 245 @end example
 246 @end cartouche
 247
 248 I used @option{-K} above because this will only list certificates for
 249 which a private key is available.  To see more details, you may use
 250 @option{--dump-secret-keys} instead of @option{-K}.
 251
 252
 253 To make actual use of the certificate you need to install it on your
 254 server. Server software usually expects a PKCS\#12 file with key and
 255 certificate. To create such a file, run:
 256
 257 @cartouche
 258 @example
 259   $ gpgsm --export-secret-key-p12 -a >kerckhoffs-cert.pem
 260 @end example
 261 @end cartouche
 262
 263 You will be asked for the passphrase as well as for a new passphrase to
 264 be used to protect the PKCS\#12 file. The file now contains the
 265 certificate as well as the private key:
 266
 267 @cartouche
 268 @example
 269   $ cat kerckhoffs-cert.pem
 270   Issuer ...: /CN=CAcert Class 3 Root/OU=http:\x2f\x2fwww.CA[...]
 271   Serial ...: 4C
 272   Subject ..: /CN=kerckhoffs.g10code.com
 273       aka ..: (dns-name www.g10code.com)
 274       aka ..: (dns-name ftp.g10code.com)
 275
 276   -----BEGIN PKCS12-----
 277   MIIHlwIBAzCCB5AGCSqGSIb37QdHAaCCB4EEggd9MIIHeTk1BJ8GCSqGSIb3DQEu
 278   [...many more lines...]
 279   -----END PKCS12-----
 280   $
 281 @end example
 282 @end cartouche
 283
 284 Copy this file in a secure way to the server, install it there and
 285 delete the file then. You may export the file again at any time as long
 286 as it is available in GnuPG's private key database.
 287
 288