SSL Certificates HOWTO

Franck Martin

Revision History
Revision v0.32002-05-09Revised by: FM
Adding x509v3 extension information - Correcting spelling
Revision v0.22001-12-06Revised by: FM
Adding openssl.cnf file - Adding CRL info from Averroes- Correcting spelling
Revision v0.12001-11-18Revised by: FM
Creation of the HOWTO

Table of Contents
1. Generalities
1.1. Introduction
1.2. What is SSL and what are Certificates?
1.3. What about S/Mime or other protocols?
2. Certificate Management
2.1. Installation
2.2. Create a Root Certification Authority Certificate.
2.3. Create a non root Certification Authority Certificate.
2.4. Install the CA root certificate as a Trusted Root Certificate
2.5. Certificate management
2.6. Securing Internet Protocols.
2.7. Securing E-mails.
2.8. Securing Code

Chapter 1. Generalities

1.1. Introduction

Dear reader, like myself, you have intensively read the man pages of the applications of the OpenSSL project, and like myself, you couldn't figure out where to start, and how to work securely with certificates. Here is the answer to most of your questions.

This HOWTO will also deal with non-linux applications: there is no use to issue certificates if you can't use them... All applications won't be listed here, but please, send me additional paragraphs and corrections. I can be reached at the following address:franck@sopac.org.


1.1.1. Disclaimer and Licence

This document is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

In short, if the advises given here break the security of your e-commerce application, then tough luck- it's never our fault. Sorry.

Copyright (c) 2001 by Franck Martin and others from the openssl-users mailing list under GFDL (the GNU Free Documentation License).

Please freely copy and distribute (sell or give away) this document in any format. It's requested that corrections and/or comments be forwarded to the document maintainer. You may create a derivative work and distribute it provided that you:

  1. Send your derivative work (in the most suitable format such as sgml) to the LDP (Linux Documentation Project) or the like for posting on the Internet. If not the LDP, then let the LDP know where it is available.

  2. License the derivative work with this same license or use GPL. Include a copyright notice and at least a pointer to the license used.

  3. Give due credit to previous authors and major contributors. If you're considering making a derived work other than a translation, it's requested that you discuss your plans with the current maintainer.

It is also requested that if you publish this HOWTO in hardcopy that you send the authors some samples for 'review purposes' :-). You may also want to send something to cook my noodles ;-)


1.2. What is SSL and what are Certificates?

The Secure Socket Layer protocol was created by Netscape to ensure secure transactions between web servers and browsers. The protocol uses a third party, a Certificate Authority (CA), to identify one end or both end of the transactions. This is in short how it works.

  1. A browser requests a secure page (usually https://).

  2. The web server sends its public key with its certificate.

  3. The browser checks that the certificate was issued by a trusted party (usually a trusted root CA), that the certificate is still valid and that the certificate is related to the site contacted.

  4. The browser then uses the public key, to encrypt a random symmetric encryption key and sends it to the server with the encrypted URL required as well as other encrypted http data.

  5. The web server decrypts the symmetric encryption key using its private key and uses the symmetric key to decrypt the URL and http data.

  6. The web server sends back the requested html document and http data encrypted with the symmetric key.

  7. The browser decrypts the http data and html document using the symmetric key and displays the information.

Several concepts have to be understood here.


Chapter 2. Certificate Management

2.1. Installation

Nowadays, you do not have to worry too much about installing OpenSSL: most distributions use package management applications. Refer to your distribution documentation, or read the README and INSTALL file inside the OpenSSL tarball. I want also to avoid to make this HOWTO, an installation HOWTO rather than an HOWTO use certificates.

I describe here some standard installation options which are necessary to know for the samples following. Your installation may differ.

The directory for all OpenSSL certificates is /var/ssl/. All commands and paths in this document are issued from this directory, it is not mandatory but it will help the examples.

OpenSSL by default looks for a configuration file in /usr/lib/ssl/openssl.cnf so always add -config /etc/openssl.cnf to the commands openssl ca or openssl req for instance. I use /etc/openssl.cnf so all my configuration files are all in /etc.

Utilities and other libraries are located in /usr/lib/ssl.


2.1.2. The openssl.cnf file

/etc/openssl.cnf must be configured accordingly to minimize input entry.


#---Begin---
# 
# OpenSSL example configuration file. 
# This is mostly being used for generation of certificate requests. 
#

RANDFILE  = $ENV::HOME/.rnd 
oid_file  = $ENV::HOME/.oid 
oid_section  = new_oids

# To use this configuration file with the "-extfile" option of the 
# "openssl x509" utility, name here the section containing the 
# X.509v3 extensions to use: 
# extensions  = 
# (Alternatively, use a configuration file that has only 
# X.509v3 extensions in its main [= default] section.)

[ new_oids ]

# We can add new OIDs in here for use by 'ca' and 'req'. 
# Add a simple OID like this: 
# testoid1=1.2.3.4 
# Or use config file substitution like this: 
# testoid2=${testoid1}.5.6

#################################################################### 
[ ca ] 
default_ca = CA_default  # The default ca section

#################################################################### 

[ CA_default ]
dir             = /var/ssl                # Where everything is kept 
certs           = $dir/certs              # Where the issued certs are kept 
crl_dir         = $dir/crl                # Where the issued crl are kept 
database        = $dir/index.txt          # database index file. 
new_certs_dir   = $dir/newcerts           # default place for new certs.

certificate     = $dir/cacert.pem         # The CA certificate 
serial          = $dir/serial             # The current serial number 
crl             = $dir/crl.pem            # The current CRL 
private_key     = $dir/private/cakey.pem  # The private key 
RANDFILE        = $dir/private/.rand      # private random number file
x509_extensions = usr_cert                # The extentions to add to the cert

# Extensions to add to a CRL. Note: Netscape communicator chokes on V2 CRLs 
# so this is commented out by default to leave a V1 CRL.
# crl_extensions = crl_ext

default_days    = 365                     # how long to certify for 
default_crl_days= 30                      # how long before next CRL 
default_md      = sha1                    # which md to use. 
preserve        = no                      # keep passed DN ordering

# A few difference way of specifying how similar the request should look 
# For type CA, the listed attributes must be the same, and the optional 
# and supplied fields are just that :-) 
policy  = policy_match

# For the CA policy 
[ policy_match ] 
countryName            = match 
stateOrProvinceName    = optional 
localityName           = match 
organizationName       = match 
organizationalUnitName = optional 
commonName             = supplied 
emailAddress           = optional

# For the 'anything' policy 
# At this point in time, you must list all acceptable 'object' 
# types. 
[ policy_anything ] 
countryName            = optional 
stateOrProvinceName    = optional 
localityName           = optional 
organizationName       = optional 
organizationalUnitName = optional 
commonName             = supplied 
emailAddress           = optional

#################################################################### 
[ req ] 
default_bits       = 1024 
default_keyfile    = privkey.pem 
distinguished_name = req_distinguished_name 
attributes         = req_attributes 
default_md         = sha1
x509_extensions    = v3_ca # The extentions to add to the self signed cert

[ req_distinguished_name ] 
countryName         = Country Name (2 letter code) 
countryName_default = FJ 
countryName_min     = 2 
countryName_max     = 2
 
stateOrProvinceName         = State or Province Name (full name) 
stateOrProvinceName_default = Fiji

localityName          = Locality Name (eg, city) 
localityName_default  = Suva

0.organizationName         = Organization Name (eg, company) 
0.organizationName_default = SOPAC

# we can do this but it is not needed normally :-) 
#1.organizationName         = Second Organization Name (eg, company) 
#1.organizationName_default = World Wide Web Pty Ltd

organizationalUnitName         = Organizational Unit Name (eg, section) 
organizationalUnitName_default = ITU

commonName       = Common Name (eg, YOUR name) 
commonName_max   = 64
emailAddress     = Email Address 
emailAddress_max = 40

# SET-ex3   = SET extension number 3

[ req_attributes ] 
challengePassword     = A challenge password 
challengePassword_min = 4 
challengePassword_max = 20

unstructuredName      = An optional company name

[ usr_cert ]

# These extensions are added when 'ca' signs a request.
# This goes against PKIX guidelines but some CAs do it and some software 
# requires this to avoid interpreting an end user certificate as a CA.

basicConstraints=CA:FALSE

# Here are some examples of the usage of nsCertType. If it is omitted 
# the certificate can be used for anything *except* object signing.

# This is OK for an SSL server. 
# nsCertType   = server

# For an object signing certificate this would be used. 
# nsCertType = objsign

# For normal client use this is typical 
# nsCertType = client, email

# and for everything including object signing: 
# nsCertType = client, email, objsign

# This is typical in keyUsage for a client certificate. 
# keyUsage = nonRepudiation, digitalSignature, keyEncipherment

# This will be displayed in Netscape's comment listbox. 
nsComment  = "Certificate issued by https://www.sopac.org/ssl/"

# PKIX recommendations harmless if included in all certificates. 
subjectKeyIdentifier=hash 

authorityKeyIdentifier=keyid,issuer:always

# This stuff is for subjectAltName and issuerAltname. 
# Import the email address. 
# subjectAltName=email:copy

# Copy subject details 
# issuerAltName=issuer:copy

# This is the base URL for all others URL addresses 
# if not supplied
nsBaseUrl  = https://www.sopac.org/ssl/

# This is the link where to download the latest Certificate
# Revocation List (CRL)
nsCaRevocationUrl = https://www.sopac.org/ssl/sopac-ca.crl

# This is the link where to revoke the certificate
nsRevocationUrl  = https://www.sopac.org/ssl/revocation.html? 

# This is the location where the certificate can be renewed
nsRenewalUrl  = https://www.sopac.org/ssl/renewal.html? 

# This is the link where the CA policy can be found
nsCaPolicyUrl  = https://www.sopac.org/ssl/policy.html 

# This is the link where we can get the issuer certificate
issuerAltName = URI:https://www.sopac.org/ssl/sopac.crt

# This is the link where to get the latest CRL
crlDistributionPoints = URI:https://www.sopac.org/ssl/sopac-ca.crl

[ v3_ca ]

# Extensions for a typical CA

# PKIX recommendation.
 
subjectKeyIdentifier=hash

authorityKeyIdentifier=keyid:always,issuer:always

# This is what PKIX recommends but some broken software chokes on critical 
# extensions. 
# basicConstraints = critical,CA:true 
# So we do this instead. 
basicConstraints = CA:true

# Key usage: this is typical for a CA certificate. However since it will 
# prevent it being used as an test self-signed certificate it is best 
# left out by default. 
# keyUsage = cRLSign, keyCertSign

# Some might want this also 
# nsCertType = sslCA, emailCA

# Include email address in subject alt name: another PKIX recommendation 
# subjectAltName=email:copy 
# Copy issuer details 
# issuerAltName=issuer:copy

# RAW DER hex encoding of an extension: beware experts only! 
# 1.2.3.5=RAW:02:03 
# You can even override a supported extension: 
# basicConstraints= critical, RAW:30:03:01:01:FF

# This will be displayed in Netscape's comment listbox. 
nsComment  = "Certificate issued by https://www.sopac.org/ssl/"

# This is the base URL for all others URL addresses 
# if not supplied
nsBaseUrl  = https://www.sopac.org/ssl/

# This is the link where to download the latest Certificate
# Revocation List (CRL)
nsCaRevocationUrl = https://www.sopac.org/ssl/sopac-ca.crl

# This is the link where to revoke the certificate
nsRevocationUrl  = https://www.sopac.org/ssl/revocation.html? 

# This is the location where the certificate can be renewed
nsRenewalUrl  = https://www.sopac.org/ssl/renewal.html? 

# This is the link where the CA policy can be found
nsCaPolicyUrl  = https://www.sopac.org/ssl/policy.html 

# This is the link where we can get the issuer certificate
issuerAltName = URI:https://www.sopac.org/ssl/sopac.crt

# This is the link where to get the latest CRL
crlDistributionPoints = URI:https://www.sopac.org/ssl/sopac-ca.crl

[ crl_ext ]
# CRL extensions. 
# Only issuerAltName and authorityKeyIdentifier make any sense in a CRL.
# issuerAltName=issuer:copy 
authorityKeyIdentifier=keyid:always,issuer:always


#----End----
   

A few comments on openssl.cnf.


2.2. Create a Root Certification Authority Certificate.

CA.pl -newcert 
(openssl req -config /etc/openssl.cnf -new -x509 -keyout newreq.pem -out newreq.pem -days 365) 
  

creates a self signed certificate (for Certificate Authority). The resulting file goes into newreq.pem. For the common Name (CN) use something like “ACME root Certificate”. This file needs to be split into 2 files cacert.pem and private/cakey.pem. The part -RSA PRIVATE KEY- goes into private/cakey.pem while the part -CERTIFICATE- goes into cacert.pem. Delete newreq.pem when finished.

Now ensure that the file index.txt is empty and that the file serial contains 1.

You may want to increase the number of days so that your root certificate and all the certificates signed by this root does not have to be changed when the root certificate expires. I think professional companies work over 5 years to 10 years for their root certificates.

openssl req -config /etc/openssl.cnf-new -x509 -keyout private/cakey.pem -out cacert.pem -days 3650
  

This last command is better than “CA.pl -newcert” as it will place the files in the required locations and create a root CA valid for 10 years.

Now ensure that this self signed root certificate is used only to sign other certificates. The private key is highly sensible, never compromise it, by removing the passphrase that protects it. Some people will place the private key on a floppy and will load it only when signing other certificates. If you computer gets hacked they can't physically get hold of the private key, if it is on a floppy.

Now you have a root Certification Authority. Other people need to trust your self-signed root CA Certificate, and therefore download it and register it on their browser.

You will have to type the passphrase each time you want to sign another certificate with it.


2.4. Install the CA root certificate as a Trusted Root Certificate

First strip the certificate from all its text to keep only the -CERTIFICATE- section

openssl x509 -in cacert.pem -out cacert.crt
  

Place this file on your web site as http://mysite.com/ssl/cacert.crt. Your web server should have a mime entry for .crt files. Your certificate is ready to be downloaded by any browser and saved.

It is important to publish the root CA Certificate on a web site as it is unlikely that people will have it already loaded on their browser. Beware, somebody could fake your web site and fake your root CA Certificate. If you can have more than one way for users to get your certificate, it is unlikely that a hacker will be able to corrupt everything.


2.5. Certificate management

2.5.1. Generate and Sign a certificate request

CA.pl -newreq 
(openssl req -config /etc/openssl.cnf -new -keyout newreq.pem -out newreq.pem -days 365) 
   

creates a new private key and a certificate request and place it as newreq.pem. Enter a Common Name (CN) the main usage of the certificate for instance www.sopac.org if you want to secure the website www.sopac.org, or enter franck@sopac.org if you want to use to secure the e-mails of franck@sopac.org.

CA.pl -sign 
(openssl ca -config /etc/openssl.cnf -policy policy_anything -out newcert.pem -infiles newreq.pem) 
   

will sign the request using the cacert.pem and commit the certificate as newcert.pem. You will need to enter the passphrase of the cacert.pem (your CA Certificate). The file newcerts/xx.pem will be created and index.txt and serial will be updated.

You private key is in newreq.pem -PRIVATE KEY- and your certificate is in newcert.pem -CERTIFICATE-

A copy of newcert.pem is placed in newcerts/ with an adequate entry in index.txt so that a client can request this information via a web server to ensure the authenticity of the certificate.

Beware of your newreq.pem file, because it contains a certificate request, but also your private key. The -PRIVATE KEY- section is not required when you sign it. So if you request someone else to sign your certificate request, ensure that you have removed the -PRIVATE KEY- section from the file. If you sign someone else certificate request, request from this person its -CERTIFICATE REQUEST- section not its private key.


2.6. Securing Internet Protocols.

2.6.1. Using a certificate with mod_ssl in apache

First never use your self-signed root CA Certificate with any application and especially with apache as it requires you to remove the passphrase on your private key.

First generate and sign a certificate request with the Common Name (CN) as www.mysite.com. Remove any extra information to keep only the ---CERTIFCATE --- part.

The key needs to be made insecure, so no password is required when reading the private key. Take the newreq.pem files that contains your private key and remove the passphrase from it.

openssl rsa -in newreq.pem -out wwwkeyunsecure.pem
   

Because the key (PRIVATE Key) is insecure, you must know what you are doing: check file permissions, etc... If someone gets its hand on it, your site is compromised (you have been warned). Now you can use the newcert and cakeyunsecure.pem for apache.

Copy wwwkeyunsecure.pem and newcert.pem in the directory /etc/httpd/conf/ssl/ as wwwkeyunsecure.pem and wwwcert.crt respectively.

Edit /etc/httpd/conf/ssl/ssl.default-vhost.conf.

---- 
# Server Certificate: 
# Point SSLCertificateFile at a PEM encoded certificate. If 
# the certificate is encrypted, then you will be prompted for a 
# pass phrase. Note that a kill -HUP will prompt again. A test 
# certificate can be generated with `make certificate' under 
# built time. 
#SSLCertificateFile conf/ssl/ca.crt 
SSLCertificateFile wwwcert.crt
# Server Private Key: 
# If the key is not combined with the certificate, use this 
# directive to point at the key file. 
#SSLCertificateKeyFile conf/ssl/ca.key.unsecure 
SSLCertificateKeyFile wwwkeyunsecure.pem 
----
   

Stop and start httpd (/etc/rc.d/init.d/httpd stop) ensure that all processes are dead (killall httpd) and start httpd (/etc/rc.d/init.d/httpd start)


2.7. Securing E-mails.


2.7.2. To use this certificate with MS Outlook

You need to import it in Outlook as a pkcs12 file. To generate the pkcs12 file from your newcert.pem and newreq.pem:

CA.pl -pkcs12 "Franck Martin"
(openssl pkcs12 -export -in newcert.pem -inkey newreq.pem -out newcert.p12 -name "Franck Martin")
   

Beware this certificate contains your public and private key and is only secured by the passphrase. This is a file not to let into everybody's hand.

In MS Outlook go to Tools, Options and Security, Click on the import/export button select to import the newcert.p12 file, enter the export password and the Digital ID "Franck Martin" (That's my name so use your name in the above examples). And Click on Ok.

Now click on the Settings button, MS Outlook should have selected the default setting so just click on New. And finally click on Ok, except if you want to change the default settings. You are ready to send signed e-mails. When you send a signed e-mail the user at the other end will receive your public key, and will therefore be able to send you encrypted e-mails.

As you have issued this certificate from a self-signed certificate (root CA Certificate), the trust path won't be valid because the application does not know the root CA Certificate. The root CA certificate has to be downloaded and installed. Refer to the chapter "Install the CA root certificate as a Trusted Root Certificate in Internet Explorer".

You can send your message as encrypted signed messages or clear text message. The encryption is not really an encryption as the message contains everything needed to decrypt the message, but it ensures that the recipient won't read the message if he does not have an s/mime compliant reader.