agent: New option --pinentry-timeout
[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 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 --gen-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   gpgsm: certificate request created
149   Ready.  You should now send this request to your CA.
150 @end example
151 @end cartouche
152
153 Now, you may look at the created request:
154
155 @cartouche
156 @example
157   $ cat example.com.cert-req.pem
158   -----BEGIN CERTIFICATE REQUEST-----
159   MIIClTCCAX0CAQAwFjEUMBIGA1UEAxMLZXhhbXBsZS5jb20wggEiMA0GCSqGSIb3
160   DQEBAQUAA4IBDwAwggEKAoIBAQDP1QEcbTvOLLCX4gAoOzH9AW7jNOMj7OSOL0uW
161   h2bCdkK5YVpnX212Z6COTC3ZG0pJiCeGt1TbbDJUlTa4syQ6JXavjK66N8ASZsyC
162   Rwcl0m6hbXp541t1dbgt2VgeGk25okWw3j+brw6zxLD2TnthJxOatID0lDIG47HW
163   GqzZmA6WHbIBIONmGnReIHTpPAPCDm92vUkpKG1xLPszuRmsQbwEl870W/FHrsvm
164   DPvVUUSdIvTV9NuRt7/WY6G4nPp9QlIuTf1ESPzIuIE91gKPdrRCAx0yuT708S1n
165   xCv3ETQ/bKPoAQ67eE3mPBqkcVwv9SE/2/36Lz06kAizRgs5AgMBAAGgOjA4Bgkq
166   hkiG9w0BCQ4xKzApMCcGA1UdEQQgMB6CC2V4YW1wbGUuY29tgg93d3cuZXhhbXBs
167   ZS5jb20wDQYJKoZIhvcNAQELBQADggEBAEWD0Qqz4OENLYp6yyO/KqF0ig9FDsLN
168   b5/R+qhms5qlhdB5+Dh+j693Sj0UgbcNKc6JT86IuBqEBZmRCJuXRoKoo5aMS1cJ
169   hXga7N9IA3qb4VBUzBWvlL92U2Iptr/cEbikFlYZF2Zv3PBv8RfopVlI3OLbKV9D
170   bJJTt/6kuoydXKo/Vx4G0DFzIKNdFdJk86o/Ziz8NOs9JjZxw9H9VY5sHKFM5LKk
171   VcLwnnLRlNjBGB+9VK/Tze575eG0cJomTp7UGIB+1xzIQVAhUZOizRDv9tHDeaK3
172   k+tUhV0kuJcYHucpJycDSrP/uAY5zuVJ0rs2QSjdnav62YrRgEsxJrU=
173   -----END CERTIFICATE REQUEST-----
174   $
175 @end example
176 @end cartouche
177
178 You may now proceed by logging into your account at the CAcert website,
179 choose @code{Server Certificates - New}, check @code{sign by class 3 root
180 certificate}, paste the above request block into the text field and
181 click on @code{Submit}.
182
183 If everything works out fine, a certificate will be shown. Now run
184
185 @cartouche
186 @example
187 $ gpgsm --import
188 @end example
189 @end cartouche
190
191 and paste the certificate from the CAcert page into your terminal
192 followed by a Ctrl-D
193
194 @cartouche
195 @example
196   -----BEGIN CERTIFICATE-----
197   MIIEIjCCAgqgAwIBAgIBTDANBgkqhkiG9w0BAQQFADBUMRQwEgYDVQQKEwtDQWNl
198    [...]
199   rUTFlNElRXCwIl0YcJkIaYYqWf7+A/aqYJCi8+51usZwMy3Jsq3hJ6MA3h1BgwZs
200   Rtct3tIX
201   -----END CERTIFICATE-----
202   gpgsm: issuer certificate (#/CN=CAcert Class 3 Ro[...]) not found
203   gpgsm: certificate imported
204   
205   gpgsm: total number processed: 1
206   gpgsm:               imported: 1
207 @end example
208 @end cartouche
209
210 gpgsm tells you that it has imported the certificate. It is now
211 associated with the key you used when creating the request. The root
212 certificate has not been found, so you may want to import it from the
213 CACert website.
214
215 To see the content of your certificate, you may now enter:
216
217 @cartouche
218 @example
219   $ gpgsm -K example.com
220   /home/foo/.gnupg/pubring.kbx
221   ---------------------------
222   Serial number: 4C
223          Issuer: /CN=CAcert Class 3 Root/OU=http:\x2f\x2fwww.[...]
224         Subject: /CN=example.com
225             aka: (dns-name example.com)
226             aka: (dns-name www.example.com)
227        validity: 2015-07-01 16:20:51 through 2016-07-01 16:20:51
228        key type: 2048 bit RSA
229       key usage: digitalSignature keyEncipherment
230   ext key usage: clientAuth (suggested), serverAuth (suggested), [...]
231     fingerprint: 0F:9C:27:B2:DA:05:5F:CB:33:D8:19:E9:65:B9:4F:BD:B1:98:CC:57
232 @end example
233 @end cartouche
234
235 I used @option{-K} above because this will only list certificates for
236 which a private key is available.  To see more details, you may use
237 @option{--dump-secret-keys} instead of @option{-K}.
238
239
240 To make actual use of the certificate you need to install it on your
241 server. Server software usually expects a PKCS\#12 file with key and
242 certificate. To create such a file, run:
243
244 @cartouche
245 @example
246   $ gpgsm --export-secret-key-p12 -a >example.com-cert.pem
247 @end example
248 @end cartouche
249
250 You will be asked for the passphrase as well as for a new passphrase to
251 be used to protect the PKCS\#12 file. The file now contains the
252 certificate as well as the private key:
253
254 @cartouche
255 @example
256   $ cat example-cert.pem
257   Issuer ...: /CN=CAcert Class 3 Root/OU=http:\x2f\x2fwww.CA[...]
258   Serial ...: 4C
259   Subject ..: /CN=example.com
260       aka ..: (dns-name example.com)
261       aka ..: (dns-name www.example.com)
262   
263   -----BEGIN PKCS12-----
264   MIIHlwIBAzCCB5AGCSqGSIb37QdHAaCCB4EEggd9MIIHeTk1BJ8GCSqGSIb3DQEu
265   [...many more lines...]
266   -----END PKCS12-----
267   $
268 @end example
269 @end cartouche
270
271 Copy this file in a secure way to the server, install it there and
272 delete the file then. You may export the file again at any time as long
273 as it is available in GnuPG's private key database.
274
275