From 8bf339ab591c1dd11739cee7a72533a51c3c7ade Mon Sep 17 00:00:00 2001 From: Werner Koch Date: Tue, 8 May 2007 13:59:41 +0000 Subject: [PATCH] Add a howto section. Makefile fixes --- TODO | 6 +- doc/ChangeLog | 4 + doc/Makefile.am | 3 +- doc/gnupg.texi | 3 + doc/howto-create-a-server-cert.texi | 288 ++++++++++++++++++++++++++++ doc/howtos.texi | 15 ++ 6 files changed, 313 insertions(+), 6 deletions(-) create mode 100644 doc/howto-create-a-server-cert.texi create mode 100644 doc/howtos.texi diff --git a/TODO b/TODO index 33a7c89fd..c86088300 100644 --- a/TODO +++ b/TODO @@ -109,11 +109,7 @@ * Remove -sat PGP2 compatibility hack -* Cleanup m4/ on next gettext update - There is at least one couple of duplicate files: inttype[_-]h.m4. - -* UTF-8 - (UTF-8 specific TODO0 +* UTF-8 specific TODOs * Pinpad Reader We do not yet support P15 applications. The trivial thing using diff --git a/doc/ChangeLog b/doc/ChangeLog index 60b15d956..00ba9cd03 100644 --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,5 +1,9 @@ 2007-05-08 Werner Koch + * howtos.texi: New. + * howto-create-a-server-cert.texi: New. + * Makefile.am (gnupg_TEXINFOS): Add new files. + * gnupg.texi: Moved the logo for HTML more to the top. * Makefile.am (install-html-local): New. (DVIPS): Redefine to include srcdir. diff --git a/doc/Makefile.am b/doc/Makefile.am index 91f52974e..0a588474f 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -42,7 +42,8 @@ dist_pkgdata_DATA = qualified.txt FAQ faq.html com-certs.pem gnupg_TEXINFOS = \ gpg.texi gpgsm.texi gpg-agent.texi scdaemon.texi instguide.texi \ tools.texi debugging.texi glossary.texi contrib.texi gpl.texi \ - sysnotes.texi gnupg-card-architecture.fig + sysnotes.texi gnupg-card-architecture.fig \ + howtos.texi howto-create-a-server-cert.texi DVIPS = TEXINPUTS="$(srcdir)$(PATH_SEPARATOR)$$TEXINPUTS" dvips diff --git a/doc/gnupg.texi b/doc/gnupg.texi index 415724b1a..f7dfdb42f 100644 --- a/doc/gnupg.texi +++ b/doc/gnupg.texi @@ -128,6 +128,7 @@ the administration and the architecture. * Helper Tools:: Description of small helper tools +* Howtos:: How to do certain things. * System Notes:: Notes pertaining to certain OSes. * Debugging:: How to solve problems @@ -163,6 +164,8 @@ the administration and the architecture. @include tools.texi +@include howtos.texi + @include sysnotes.texi @include debugging.texi diff --git a/doc/howto-create-a-server-cert.texi b/doc/howto-create-a-server-cert.texi new file mode 100644 index 000000000..57702f46f --- /dev/null +++ b/doc/howto-create-a-server-cert.texi @@ -0,0 +1,288 @@ +@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. + +Before you start, make sure that gpg-agent is running. As there is no +need for a configuration file, you may simply enter: + +@cartouche +@example + $ gpgsm-gencert.sh >a.p10 + Key type + [1] RSA + [2] Existing key + [3] Direct from card + Your selection: 1 + You selected: RSA +@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 + Key length + [1] 1024 + [2] 2048 + Your selection: 1 + You selected: 1024 +@end example +@end cartouche + +The script offers two common key sizes. With the current setup of +CAcert, it does not make much sense to use a 2k key; their policies need +to be revised anyway (a CA root key valid for 30 years is not really +serious). + +@cartouche +@example + Key usage + [1] sign, encrypt + [2] sign + [3] encrypt + Your selection: 1 + You selected: sign, encrypt +@end example +@end cartouche + +We want to sign and encrypt using this key. This is just a suggestion +and the CA may actually assign other key capabilities. + +Now for some real data: + +@cartouche +@example + Name (DN) + > CN=kerckhoffs.g10code.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 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 + DNS Names (optional; end with an empty line) + > www.g10code.com + DNS Names (optional; end with an empty line) + > ftp.g10code.com + DNS Names (optional; end with an empty line) + > +@end example +@end cartouche + +Here I entered the names of the servers which actually run on the +machine given in the DN above. 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. + +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 + Parameters for certificate request to create: + 1 Key-Type: RSA + 2 Key-Length: 1024 + 3 Key-Usage: sign, encrypt + 4 Name-DN: CN=kerckhoffs.g10code.com + 5 Name-DNS: www.g10code.com + 6 Name-DNS: ftp.g10code.com + + Really create such a CSR? + [1] yes + [2] no + Your selection: 1 + You selected: yes +@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 + gpgsm: certificate request created +@end example +@end cartouche + +Now, you may look at the created request: + +@cartouche +@example + $ cat a.p10 + -----BEGIN CERTIFICATE REQUEST----- + MIIBnzCCAQgCAQAwITEfMB0GA1UEAxMWa2VyY2tob2Zmcy5nMTBjb2RlLmNvbTCB + nzANBgkqhkiG9w0BAQEFAAOBjQAwgYkCgYEA5h+uKRenpvbe+BnMY6siPO50LVyg + HtB7kr+YISlPJ5JAFO12yQFz9Y0sBLHbjR+V+TOawwP1dZhGjlgnEBkMdWKuEBlS + wFTALLX78GAyvAYAmPqSPDEYXkMECyUXVX/bbGI1bY8Y2OGy4w4D+v7e+xD2NBkm + Bj5cNy+YMbGVldECAwEAAaA+MDwGCSqGSIb3DQEJDjEvMC0wKwYDVR0RBCQwIoIP + d3d3LmcxMGNvZGUuY29tgg9mdHAuZzEwY29kZS5jb20wDQYJKoZIhvcNAQEFBQAD + gYEAzBRIi8KTfKyebOlMtDN6oDYBOv+r9A4w3u/Z1ikjffaiN1Bmd2o9Ez9KXKHA + IezLeSEA/rGUPN5Ur5qIJnRNQ8xrS+iLftr8msWQSZppVnA/vnqMrtqBUpitqAr0 + eYBmt1Uem2Y3UFABrKPglv2xzgGkrKX6AqmFoOnJWQ0QcTw= + -----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 + cnQgSW5jLjEeMBwGA1UECxMVaHR0cDovL3d3dy5DQWNlcnQub3JnMRwwGgYDVQQD + ExNDQWNlcnQgQ2xhc3MgMyBSb290MB4XDTA1MTAyODE2MjA1MVoXDTA3MTAyODE2 + MjA1MVowITEfMB0GA1UEAxMWa2VyY2tob2Zmcy5nMTBjb2RlLmNvbTCBnzANBgkq + hkiG9w0BAQEFAAOBjQAwgYkCgYEA5h+uKRenpvbe+BnMY6siPO50LVygHtB7kr+Y + ISlPJ5JAFO12yQFz9Y0sBLHbjR+V+TOawwP1dZhGjlgnEBkMdWKuEBlSwFTALLX7 + 8GAyvAYAmPqSPDEYXkMECyUXVX/bbGI1bY8Y2OGy4w4D+v7e+xD2NBkmBj5cNy+Y + MbGVldECAwEAAaOBtTCBsjAMBgNVHRMBAf8EAjAAMDQGA1UdJQQtMCsGCCsGAQUF + BwMCBggrBgEFBQcDAQYJYIZIAYb4QgQBBgorBgEEAYI3CgMDMAsGA1UdDwQEAwIF + oDAyBggrBgEFBQcBAQQmMCQwIgYIKwYBBQUHMAGGFmh0dHA6Ly9vY3NwLmNhY2Vy + dC5vcmcwKwYDVR0RBCQwIoIPd3d3LmcxMGNvZGUuY29tgg9mdHAuZzEwY29kZS5j + b20wDQYJKoZIhvcNAQEEBQADggIBAAj5XAHCtzQR8PV6PkQBgZqUCbcfxGO/ZIp9 + aIT6J2z0Jo1OZI6KmConbqnZG9WyDlV5P7msQXW/Z9nBfoj4KSmNR8G/wtb8ClJn + W8s75+K3ZLq1UgEyxBDrS7GjtbVaj7gsfZsuiQzxmk9lbl1gbkpJ3VEMjwVCTMlM + fpjp8etyPhUZqOZaoKVaq//KTOsjhPMwz7TcfOkHvXketPrWTcefJQU7NKLH16D3 + mZAwnBxp3P51H6E6VG8AoJO8xCBuVwsbXKEf/FW+tmKG9pog6CaZQ9WibROTtnKj + NJjSBsrUk5C+JowO/EyZRGm6R1tlok8iFXj+2aimyeBqDcxozNmFgh9F3S5u0wK0 + 6cfYgkPVMHxgwV3f3Qh+tJkgLExN7KfO9hvpZqAh+CLQtxVmvpxEVEXKR6nwBI5U + BaseulvVy3wUfg2daPkG17kDDBzQlsWC0BRF8anH+FWSrvseC3nS0a9g3sXF1Ic3 + gIqeAMhkant1Ac3RR6YCWtJKr2rcQNdDAxXK35/gUSQNCi9dclEzoOgjziuA1Mha + 94jYcvGKcwThn0iITVS5hOsCfaySBLxTzfIruLbPxXlpWuCW/6I/7YyivppKgEZU + 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 + +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 kerckhoffs.g10code.com + /home/foo/.gnupg/pubring.kbx + --------------------------- + Serial number: 4C + Issuer: /CN=CAcert Class 3 Root/OU=http:\x2f\x2fwww.[...] + Subject: /CN=kerckhoffs.g10code.com + aka: (dns-name www.g10code.com) + aka: (dns-name ftp.g10code.com) + validity: 2005-10-28 16:20:51 through 2007-10-28 16:20:51 + key type: 1024 bit RSA + key usage: digitalSignature keyEncipherment + ext key usage: clientAuth (suggested), serverAuth (suggested), [...] + fingerprint: 0F:9C:27:B2:DA:05:5F:CB:33:19:D8:E9:65:B9:BD:4F: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 usally expects a PKCS\#12 file with key and +certificate. To create such a file, run: + +@cartouche +@example + $ gpgsm --export-secret-key-p12 -a >kerckhoffs-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 kerckhoffs-cert.pem + Issuer ...: /CN=CAcert Class 3 Root/OU=http:\x2f\x2fwww.CA[...] + Serial ...: 4C + Subject ..: /CN=kerckhoffs.g10code.com + aka ..: (dns-name www.g10code.com) + aka ..: (dns-name ftp.g10code.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. + + diff --git a/doc/howtos.texi b/doc/howtos.texi new file mode 100644 index 000000000..bd48de049 --- /dev/null +++ b/doc/howtos.texi @@ -0,0 +1,15 @@ +@c Copyright (C) 2007 Free Software Foundation, Inc. +@c This is part of the GnuPG manual. +@c For copying conditions, see the file gnupg.texi. + +@node Howtos +@chapter How to do certain things + +This is a collection of small howto documents. + +@menu +* Howto Create a Server Cert:: Creating a TLS server certificate. +@end menu + + +@include howto-create-a-server-cert.texi