Note: Wrong author in previous commit 049b3d9.
[gnupg.git] / 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