gpgsm: default to 3072-bit keys.
[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 --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? (3072)
35   Requested keysize is 3072 bits
36 @end example
37 @end cartouche
38
39 Hitting enter chooses the default RSA key size of 3072 bits.  Keys
40 smaller than 2048 bits are too weak on the modern Internet.  If you
41 choose a larger (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: 3072
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: 3072 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