Adding upstream version 2.2.40.upstream/2.2.40

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 274 insertions, 0 deletions

diff --git a/doc/howto-create-a-server-cert.texi b/doc/howto-create-a-server-cert.texi
new file mode 100644
index 0000000..30e28bd
--- /dev/null
+++ b/doc/howto-create-a-server-cert.texi
@@ -0,0 +1,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.
+
+