Skip to content

Commit 8bf339a

Browse files
dd9jndd9jn
committed
Add a howto section.
Makefile fixes
1 parent 1db69a8 commit 8bf339a

File tree

6 files changed

+313
-6
lines changed

6 files changed

+313
-6
lines changed

‎TODO

+1-5
Original file line numberDiff line numberDiff line change
@@ -109,11 +109,7 @@
109109

110110
* Remove -sat PGP2 compatibility hack
111111

112-
* Cleanup m4/ on next gettext update
113-
There is at least one couple of duplicate files: inttype[_-]h.m4.
114-
115-
* UTF-8
116-
(UTF-8 specific TODO0
112+
* UTF-8 specific TODOs
117113

118114
* Pinpad Reader
119115
We do not yet support P15 applications. The trivial thing using

‎doc/ChangeLog

+4
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,9 @@
11
2007-05-08 Werner Koch <[email protected]>
22

3+
* howtos.texi: New.
4+
* howto-create-a-server-cert.texi: New.
5+
* Makefile.am (gnupg_TEXINFOS): Add new files.
6+
37
* gnupg.texi: Moved the logo for HTML more to the top.
48
* Makefile.am (install-html-local): New.
59
(DVIPS): Redefine to include srcdir.

‎doc/Makefile.am

+2-1
Original file line numberDiff line numberDiff line change
@@ -42,7 +42,8 @@ dist_pkgdata_DATA = qualified.txt FAQ faq.html com-certs.pem
4242
gnupg_TEXINFOS = \
4343
gpg.texi gpgsm.texi gpg-agent.texi scdaemon.texi instguide.texi \
4444
tools.texi debugging.texi glossary.texi contrib.texi gpl.texi \
45-
sysnotes.texi gnupg-card-architecture.fig
45+
sysnotes.texi gnupg-card-architecture.fig \
46+
howtos.texi howto-create-a-server-cert.texi
4647

4748
DVIPS = TEXINPUTS="$(srcdir)$(PATH_SEPARATOR)$$TEXINPUTS" dvips
4849

‎doc/gnupg.texi

+3
Original file line numberDiff line numberDiff line change
@@ -128,6 +128,7 @@ the administration and the architecture.
128128
129129
* Helper Tools:: Description of small helper tools
130130
131+
* Howtos:: How to do certain things.
131132
* System Notes:: Notes pertaining to certain OSes.
132133
* Debugging:: How to solve problems
133134
@@ -163,6 +164,8 @@ the administration and the architecture.
163164

164165
@include tools.texi
165166

167+
@include howtos.texi
168+
166169
@include sysnotes.texi
167170

168171
@include debugging.texi

‎doc/howto-create-a-server-cert.texi

+288
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,288 @@
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 usally 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+

‎doc/howtos.texi

+15
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
@c Copyright (C) 2007 Free Software Foundation, Inc.
2+
@c This is part of the GnuPG manual.
3+
@c For copying conditions, see the file gnupg.texi.
4+
5+
@node Howtos
6+
@chapter How to do certain things
7+
8+
This is a collection of small howto documents.
9+
10+
@menu
11+
* Howto Create a Server Cert:: Creating a TLS server certificate.
12+
@end menu
13+
14+
15+
@include howto-create-a-server-cert.texi

0 commit comments

Comments
 (0)