[svn] GnuPG - r4498 - in trunk: . doc
svn author wk
cvs at cvs.gnupg.org
Tue May 8 16:00:10 CEST 2007
Author: wk
Date: 2007-05-08 15:59:41 +0200 (Tue, 08 May 2007)
New Revision: 4498
Added:
trunk/doc/howto-create-a-server-cert.texi
trunk/doc/howtos.texi
Modified:
trunk/TODO
trunk/doc/ChangeLog
trunk/doc/Makefile.am
trunk/doc/gnupg.texi
Log:
Add a howto section.
Makefile fixes
Modified: trunk/TODO
===================================================================
--- trunk/TODO 2007-05-08 08:15:55 UTC (rev 4497)
+++ trunk/TODO 2007-05-08 13:59:41 UTC (rev 4498)
@@ -109,12 +109,8 @@
* 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 specific TODOs
-* UTF-8
- (UTF-8 specific TODO0
-
* Pinpad Reader
We do not yet support P15 applications. The trivial thing using
ASCII characters will be easy to implement but the other cases need
Modified: trunk/doc/ChangeLog
===================================================================
--- trunk/doc/ChangeLog 2007-05-08 08:15:55 UTC (rev 4497)
+++ trunk/doc/ChangeLog 2007-05-08 13:59:41 UTC (rev 4498)
@@ -1,5 +1,9 @@
2007-05-08 Werner Koch <wk at g10code.com>
+ * 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.
Modified: trunk/doc/Makefile.am
===================================================================
--- trunk/doc/Makefile.am 2007-05-08 08:15:55 UTC (rev 4497)
+++ trunk/doc/Makefile.am 2007-05-08 13:59:41 UTC (rev 4498)
@@ -42,7 +42,8 @@
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
Modified: trunk/doc/gnupg.texi
===================================================================
--- trunk/doc/gnupg.texi 2007-05-08 08:15:55 UTC (rev 4497)
+++ trunk/doc/gnupg.texi 2007-05-08 13:59:41 UTC (rev 4498)
@@ -128,6 +128,7 @@
* 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 @@
@include tools.texi
+ at include howtos.texi
+
@include sysnotes.texi
@include debugging.texi
Added: trunk/doc/howto-create-a-server-cert.texi
===================================================================
--- trunk/doc/howto-create-a-server-cert.texi 2007-05-08 08:15:55 UTC (rev 4497)
+++ trunk/doc/howto-create-a-server-cert.texi 2007-05-08 13:59:41 UTC (rev 4498)
@@ -0,0 +1,288 @@
+ at node Howto Create a Server Cert
+ at 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:
+
+ at cartouche
+ at example
+ $ gpgsm-gencert.sh >a.p10
+ Key type
+ [1] RSA
+ [2] Existing key
+ [3] Direct from card
+ Your selection: 1
+ You selected: RSA
+ at end example
+ at 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:
+
+ at cartouche
+ at example
+ Key length
+ [1] 1024
+ [2] 2048
+ Your selection: 1
+ You selected: 1024
+ at end example
+ at 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).
+
+ at cartouche
+ at example
+ Key usage
+ [1] sign, encrypt
+ [2] sign
+ [3] encrypt
+ Your selection: 1
+ You selected: sign, encrypt
+ at end example
+ at 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:
+
+ at cartouche
+ at example
+ Name (DN)
+ > CN=kerckhoffs.g10code.com
+ at end example
+ at 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.
+
+ at cartouche
+ at example
+ E-Mail addresses (end with an empty line)
+ >
+ at end example
+ at 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.
+
+ at cartouche
+ at 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)
+ >
+ at end example
+ at 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.
+
+ at cartouche
+ at example
+ URIs (optional; end with an empty line)
+ >
+ at end example
+ at 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:
+
+ at cartouche
+ at 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
+ at end example
+ at end cartouche
+
+ at 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:
+
+ at cartouche
+ at example
+ gpgsm: certificate request created
+ at end example
+ at end cartouche
+
+Now, you may look at the created request:
+
+ at cartouche
+ at 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-----
+ $
+ at end example
+ at 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
+
+ at cartouche
+ at example
+$ gpgsm --import
+ at end example
+ at end cartouche
+
+and paste the certificate from the CAcert page into your terminal
+followed by a Ctrl-D
+
+ at cartouche
+ at 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
+ at end example
+ at 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:
+
+ at cartouche
+ at 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
+ at end example
+ at 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
+ at 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:
+
+ at cartouche
+ at example
+ $ gpgsm --export-secret-key-p12 -a >kerckhoffs-cert.pem
+ at end example
+ at 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:
+
+ at cartouche
+ at 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-----
+ $
+ at end example
+ at 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.
+
+
Added: trunk/doc/howtos.texi
===================================================================
--- trunk/doc/howtos.texi 2007-05-08 08:15:55 UTC (rev 4497)
+++ trunk/doc/howtos.texi 2007-05-08 13:59:41 UTC (rev 4498)
@@ -0,0 +1,15 @@
+ at c Copyright (C) 2007 Free Software Foundation, Inc.
+ at c This is part of the GnuPG manual.
+ at c For copying conditions, see the file gnupg.texi.
+
+ at node Howtos
+ at chapter How to do certain things
+
+This is a collection of small howto documents.
+
+ at menu
+* Howto Create a Server Cert:: Creating a TLS server certificate.
+ at end menu
+
+
+ at include howto-create-a-server-cert.texi
More information about the Gnupg-commits
mailing list