Up: Howtos

9.1 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:

       $ gpgsm --gen-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

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

Let's continue:

       What keysize do you want? (2048)
       Requested keysize is 2048 bits

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

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

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:

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

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.

       E-Mail addresses (end with an empty line):

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. 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.

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

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.

       URIs (optional; end with an empty line):

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

       Create self-signed certificate? (y/N)

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 gpgsm will display what it has gathered and ask whether to create the certificate request:

       These parameters are used:
           Key-Type: RSA
           Key-Length: 2048
           Key-Usage: sign, encrypt
           Name-DN: CN=example.com
           Name-DNS: example.com
           Name-DNS: www.example.com
       Proceed with creation? (y/N) y

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:

       gpgsm: certificate request created
       Ready.  You should now send this request to your CA.

Now, you may look at the created request:

       $ cat example.com.cert-req.pem

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

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

     $ gpgsm --import

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

       -----BEGIN CERTIFICATE-----
       -----END CERTIFICATE-----
       gpgsm: issuer certificate (#/CN=CAcert Class 3 Ro[...]) not found
       gpgsm: certificate imported
       gpgsm: total number processed: 1
       gpgsm:               imported: 1

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:

       $ gpgsm -K example.com
       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: 2048 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

I used -K above because this will only list certificates for which a private key is available. To see more details, you may use --dump-secret-keys instead of -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:

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

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:

       $ 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-----
       [...many more lines...]
       -----END PKCS12-----

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.