File: howto-create-a-server-cert.texi

package info (click to toggle)
gnupg2 2.2.12-1+deb10u1
  • links: PTS, VCS
  • area: main
  • in suites: bullseye, buster, sid
  • size: 47,236 kB
  • sloc: ansic: 231,709; sh: 7,598; lisp: 6,034; makefile: 1,604; awk: 126; xml: 51; python: 16; sed: 16; php: 14; perl: 13
file content (274 lines) | stat: -rw-r--r-- 8,679 bytes parent folder | download | duplicates (8)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
@node Howto Create a Server Cert
@section Creating a TLS server certificate


Here is a brief run up on how to create a server certificate. It has
actually been done this way to get a certificate from CAcert to be used
on a real server.  It has only been tested with this CA, but there
shouldn't be any problem to run this against any other CA.

We start by generating an X.509 certificate signing request. As there
is no need for a configuration file, you may simply enter:

@cartouche
@example
  $ gpgsm --generate-key >example.com.cert-req.pem
  Please select what kind of key you want:
     (1) RSA
     (2) Existing key
     (3) Existing key from card
  Your selection? 1
@end example
@end cartouche

I opted for creating a new RSA key. The other option is to use an
already existing key, by selecting @kbd{2} and entering the so-called
keygrip.  Running the command @samp{gpgsm --dump-secret-key USERID}
shows you this keygrip.  Using @kbd{3} offers another menu to create a
certificate directly from a smart card based key.

Let's continue:

@cartouche
@example
  What keysize do you want? (3072)
  Requested keysize is 3072 bits
@end example
@end cartouche

Hitting enter chooses the default RSA key size of 3072 bits.  Keys
smaller than 2048 bits are too weak on the modern Internet.  If you
choose a larger (stronger) key, your server will need to do more work.

@cartouche
@example
  Possible actions for a RSA key:
     (1) sign, encrypt
     (2) sign
     (3) encrypt
  Your selection? 1
@end example
@end cartouche

Selecting ``sign'' enables use of the key for Diffie-Hellman key
exchange mechanisms (DHE and ECDHE) in TLS, which are preferred
because they offer forward secrecy.  Selecting ``encrypt'' enables RSA
key exchange mechanisms, which are still common in some places.
Selecting both enables both key exchange mechanisms.

Now for some real data:

@cartouche
@example
  Enter the X.509 subject name: CN=example.com
@end example
@end cartouche

This is the most important value for a server certificate. Enter here
the canonical name of your server machine. You may add other virtual
server names later.

@cartouche
@example
  E-Mail addresses (end with an empty line):
  > 
@end example
@end cartouche

We don't need email addresses in a TLS server certificate and CAcert
would anyway ignore such a request. Thus just hit enter.

If you want to create a client certificate for email encryption, this
would be the place to enter your mail address
(e.g. @email{joe@@example.org}). You may enter as many addresses as you like,
however the CA may not accept them all or reject the entire request.

@cartouche
@example
  Enter DNS names (optional; end with an empty line):
  > example.com
  > www.example.com
  > 
@end example
@end cartouche

Here I entered the names of the services which the machine actually
provides.  You almost always want to include the canonical name here
too. The browser will accept a certificate for any of these names. As
usual the CA must approve all of these names.

@cartouche
@example
  URIs (optional; end with an empty line):
  >
@end example
@end cartouche

It is possible to insert arbitrary URIs into a certificate; for a server
certificate this does not make sense.

@cartouche
@example
  Create self-signed certificate? (y/N)
@end example
@end cartouche

Since we are creating a certificate signing request, and not a full
certificate, we answer no here, or just hit enter for the default.

We have now entered all required information and @command{gpgsm} will
display what it has gathered and ask whether to create the certificate
request:

@cartouche
@example
  These parameters are used:
      Key-Type: RSA
      Key-Length: 3072
      Key-Usage: sign, encrypt
      Name-DN: CN=example.com
      Name-DNS: example.com
      Name-DNS: www.example.com

  Proceed with creation? (y/N) y
@end example
@end cartouche

@command{gpgsm} will now start working on creating the request. As this
includes the creation of an RSA key it may take a while. During this
time you will be asked 3 times for a passphrase to protect the created
private key on your system. A pop up window will appear to ask for
it. The first two prompts are for the new passphrase and for re-entering it;
the third one is required to actually create the certificate signing request.

When it is ready, you should see the final notice:

@cartouche
@example
  Ready.  You should now send this request to your CA.
@end example
@end cartouche

Now, you may look at the created request:

@cartouche
@example
  $ cat example.com.cert-req.pem
  -----BEGIN CERTIFICATE REQUEST-----
  MIIClTCCAX0CAQAwFjEUMBIGA1UEAxMLZXhhbXBsZS5jb20wggEiMA0GCSqGSIb3
  DQEBAQUAA4IBDwAwggEKAoIBAQDP1QEcbTvOLLCX4gAoOzH9AW7jNOMj7OSOL0uW
  h2bCdkK5YVpnX212Z6COTC3ZG0pJiCeGt1TbbDJUlTa4syQ6JXavjK66N8ASZsyC
  Rwcl0m6hbXp541t1dbgt2VgeGk25okWw3j+brw6zxLD2TnthJxOatID0lDIG47HW
  GqzZmA6WHbIBIONmGnReIHTpPAPCDm92vUkpKG1xLPszuRmsQbwEl870W/FHrsvm
  DPvVUUSdIvTV9NuRt7/WY6G4nPp9QlIuTf1ESPzIuIE91gKPdrRCAx0yuT708S1n
  xCv3ETQ/bKPoAQ67eE3mPBqkcVwv9SE/2/36Lz06kAizRgs5AgMBAAGgOjA4Bgkq
  hkiG9w0BCQ4xKzApMCcGA1UdEQQgMB6CC2V4YW1wbGUuY29tgg93d3cuZXhhbXBs
  ZS5jb20wDQYJKoZIhvcNAQELBQADggEBAEWD0Qqz4OENLYp6yyO/KqF0ig9FDsLN
  b5/R+qhms5qlhdB5+Dh+j693Sj0UgbcNKc6JT86IuBqEBZmRCJuXRoKoo5aMS1cJ
  hXga7N9IA3qb4VBUzBWvlL92U2Iptr/cEbikFlYZF2Zv3PBv8RfopVlI3OLbKV9D
  bJJTt/6kuoydXKo/Vx4G0DFzIKNdFdJk86o/Ziz8NOs9JjZxw9H9VY5sHKFM5LKk
  VcLwnnLRlNjBGB+9VK/Tze575eG0cJomTp7UGIB+1xzIQVAhUZOizRDv9tHDeaK3
  k+tUhV0kuJcYHucpJycDSrP/uAY5zuVJ0rs2QSjdnav62YrRgEsxJrU=
  -----END CERTIFICATE REQUEST-----
  $
@end example
@end cartouche

You may now proceed by logging into your account at the CAcert website,
choose @code{Server Certificates - New}, check @code{sign by class 3 root
certificate}, paste the above request block into the text field and
click on @code{Submit}.

If everything works out fine, a certificate will be shown. Now run

@cartouche
@example
$ gpgsm --import
@end example
@end cartouche

and paste the certificate from the CAcert page into your terminal
followed by a Ctrl-D

@cartouche
@example
  -----BEGIN CERTIFICATE-----
  MIIEIjCCAgqgAwIBAgIBTDANBgkqhkiG9w0BAQQFADBUMRQwEgYDVQQKEwtDQWNl
   [...]
  rUTFlNElRXCwIl0YcJkIaYYqWf7+A/aqYJCi8+51usZwMy3Jsq3hJ6MA3h1BgwZs
  Rtct3tIX
  -----END CERTIFICATE-----
  gpgsm: issuer certificate (#/CN=CAcert Class 3 Ro[...]) not found
  gpgsm: certificate imported
  
  gpgsm: total number processed: 1
  gpgsm:               imported: 1
@end example
@end cartouche

@command{gpgsm} tells you that it has imported the certificate. It is now
associated with the key you used when creating the request. The root
certificate has not been found, so you may want to import it from the
CACert website.

To see the content of your certificate, you may now enter:

@cartouche
@example
  $ gpgsm -K example.com
  /home/foo/.gnupg/pubring.kbx
  ---------------------------
  Serial number: 4C
         Issuer: /CN=CAcert Class 3 Root/OU=http:\x2f\x2fwww.[...]
        Subject: /CN=example.com
            aka: (dns-name example.com)
            aka: (dns-name www.example.com)
       validity: 2015-07-01 16:20:51 through 2016-07-01 16:20:51
       key type: 3072 bit RSA
      key usage: digitalSignature keyEncipherment
  ext key usage: clientAuth (suggested), serverAuth (suggested), [...]
    fingerprint: 0F:9C:27:B2:DA:05:5F:CB:33:D8:19:E9:65:B9:4F:BD:B1:98:CC:57
@end example
@end cartouche

I used @option{-K} above because this will only list certificates for
which a private key is available.  To see more details, you may use
@option{--dump-secret-keys} instead of @option{-K}.


To make actual use of the certificate you need to install it on your
server. Server software usually expects a PKCS\#12 file with key and
certificate. To create such a file, run:

@cartouche
@example
  $ gpgsm --export-secret-key-p12 -a >example.com-cert.pem
@end example
@end cartouche

You will be asked for the passphrase as well as for a new passphrase to
be used to protect the PKCS\#12 file. The file now contains the
certificate as well as the private key:

@cartouche
@example
  $ cat example-cert.pem
  Issuer ...: /CN=CAcert Class 3 Root/OU=http:\x2f\x2fwww.CA[...]
  Serial ...: 4C
  Subject ..: /CN=example.com
      aka ..: (dns-name example.com)
      aka ..: (dns-name www.example.com)
  
  -----BEGIN PKCS12-----
  MIIHlwIBAzCCB5AGCSqGSIb37QdHAaCCB4EEggd9MIIHeTk1BJ8GCSqGSIb3DQEu
  [...many more lines...]
  -----END PKCS12-----
  $
@end example
@end cartouche

Copy this file in a secure way to the server, install it there and
delete the file then. You may export the file again at any time as long
as it is available in GnuPG's private key database.