Red Hat Training

A Red Hat training course is available for Red Hat Fuse

2.5. Creating Your Own Certificates

2.5.1. Prerequisites

OpenSSL utilities

The steps described in this section are based on the OpenSSL command-line utilities from the OpenSSL project. Further documentation of the OpenSSL command-line utilities can be obtained at http://www.openssl.org/docs/.

Sample CA directory structure

For the purposes of illustration, the CA database is assumed to have the following directory structure:
X509CA/ca
X509CA/certs
X509CA/newcerts
X509CA/crl
Where X509CA is the parent directory of the CA database.

2.5.2. Set Up Your Own CA

Substeps to perform

This section describes how to set up your own private CA. Before setting up a CA for a real deployment, read the additional notes in Section 2.2.3, “Private Certification Authorities” .
To set up your own CA, perform the following steps:
  1. Add the bin directory to your PATH
  2. Create the CA directory hierarchy
  3. Copy and edit the openssl.cnf file
  4. Initialize the CA database
  5. Create a self-signed CA certificate and private key

Add the bin directory to your PATH

On the secure CA host, add the OpenSSL bin directory to your path:
Windows 
> set PATH=OpenSSLDir\bin;%PATH%
UNIX 
% PATH=OpenSSLDir/bin:$PATH; export PATH
This step makes the openssl utility available from the command line.

Create the CA directory hierarchy

Create a new directory, X509CA, to hold the new CA. This directory is used to hold all of the files associated with the CA. Under the X509CA directory, create the following hierarchy of directories:
X509CA/ca
X509CA/certs
X509CA/newcerts
X509CA/crl

Copy and edit the openssl.cnf file

Copy the sample openssl.cnf from your OpenSSL installation to the X509CA directory.
Edit the openssl.cnf to reflect the directory structure of the X509CA directory, and to identify the files used by the new CA.
Edit the [CA_default] section of the openssl.cnf file to look like the following: 
#############################################################
[ CA_default ]
    
dir        = X509CA            # Where CA files are kept
certs      = $dir/certs  # Where 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/ca/new_ca.pem # The CA certificate
serial        = $dir/serial        # The current serial number
crl           = $dir/crl.pem       # The current CRL
private_key   = $dir/ca/new_ca_pk.pem  # The private key
RANDFILE      = $dir/ca/.rand
# Private random number file

x509_extensions = usr_cert  # The extensions to add to the cert
...
You might decide to edit other details of the OpenSSL configuration at this point—for more details, see http://www.openssl.org/docs/.

Initialize the CA database

In the X509CA directory, initialize two files, serial and index.txt.
Windows
To initialize the serial file in Windows, enter the following command: 
> echo 01 > serial
To create an empty file, index.txt, in Windows start Windows Notepad at the command line in the X509CA directory, as follows: 
> notepad index.txt
In response to the dialog box with the text, Cannot find the text.txt file. Do you want to create a new file?, click Yes, and close Notepad.
UNIX
To initialize the serial file and the index.txt file in UNIX, enter the following command: 
% echo "01" > serial
% touch index.txt
These files are used by the CA to maintain its database of certificate files.
Note
The index.txt file must initially be completely empty, not even containing white space.

Create a self-signed CA certificate and private key

Create a new self-signed CA certificate and private key with the following command: 
openssl req -x509 -new -config X509CA/openssl.cnf -days 365 -out X509CA/ca/new_ca.pem -keyout X509CA/ca/new_ca_pk.pem
The command prompts you for a pass phrase for the CA private key and details of the CA distinguished name. For example: 
Using configuration from X509CA/openssl.cnf
Generating a 512 bit RSA private key
....+++++
.+++++
writing new private key to 'new_ca_pk.pem'
Enter PEM pass phrase:
Verifying password - Enter PEM pass phrase:
-----
You are about to be asked to enter information that will be
incorporated into your certificate request.
What you are about to enter is what is called a Distinguished
Name or a DN. There are quite a few fields but you can leave
some blank. For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) []:IE
State or Province Name (full name) []:Co. Dublin
Locality Name (eg, city) []:Dublin
Organization Name (eg, company) []:Red Hat
Organizational Unit Name (eg, section) []:Finance
Common Name (eg, YOUR name) []:Gordon Brown
Email Address []:gbrown@redhat.com
Note
The security of the CA depends on the security of the private key file and the private key pass phrase used in this step.
You must ensure that the file names and location of the CA certificate and private key, new_ca.pem and new_ca_pk.pem, are the same as the values specified in openssl.cnf (see the preceding step).
You are now ready to sign certificates with your CA.

2.5.3. Use the CA to Create Signed Certificates in a Java Keystore

Substeps to perform

To create and sign a certificate in a Java keystore (JKS), CertName.jks, perform the following substeps:
  1. Add the Java bin directory to your PATH
  2. Generate a certificate and private key pair
  3. Create a certificate signing request
  4. Sign the CSR
  5. Convert to PEM format
  6. Concatenate the files
  7. Update keystore with the full certificate chain
  8. Repeat steps as required

Add the Java bin directory to your PATH

If you have not already done so, add the Java bin directory to your path:
Windows 
> set PATH=JAVA_HOME\bin;%PATH%
UNIX 
% PATH=JAVA_HOME/bin:$PATH; export PATH
This step makes the keytool utility available from the command line.

Generate a certificate and private key pair

Open a command prompt and change directory to the directory where you store your keystore files, KeystoreDir. Enter the following command: 
keytool -genkey -dname "CN=Alice, OU=Engineering, O=Progress, ST=Co. Dublin, C=IE" -validity 365 -alias CertAlias -keypass CertPassword -keystore CertName.jks -storepass CertPassword
This keytool command, invoked with the -genkey option, generates an X.509 certificate and a matching private key. The certificate and the key are both placed in a key entry in a newly created keystore, CertName.jks. Because the specified keystore, CertName.jks, did not exist prior to issuing the command, keytool implicitly creates a new keystore.
The -dname and -validity flags define the contents of the newly created X.509 certificate, specifying the subject DN and the days before expiration respectively. For more details about DN format, see Appendix A, ASN.1 and Distinguished Names.
Some parts of the subject DN must match the values in the CA certificate (specified in the CA Policy section of the openssl.cnf file). The default openssl.cnf file requires the following entries to match:
  • Country Name (C)
  • State or Province Name (ST)
  • Organization Name (O)
Note
If you do not observe the constraints, the OpenSSL CA will refuse to sign the certificate (see the section called “Sign the CSR” ).

Create a certificate signing request

Create a new certificate signing request (CSR) for the CertName.jks certificate, as follows: 
keytool -certreq -alias CertAlias -file CertName_csr.pem -keypass CertPassword -keystore CertName.jks -storepass CertPassword
This command exports a CSR to the file, CertName_csr.pem.

Sign the CSR

Sign the CSR using your CA, as follows: 
openssl ca -config X509CA/openssl.cnf -days 365 -in CertName_csr.pem -out CertName.pem
To sign the certificate successfully, you must enter the CA private key pass phrase (see Section 2.5.2, “Set Up Your Own CA”).
Note
If you want to sign the CSR using a CA certificate other than the default CA, use the -cert and -keyfile options to specify the CA certificate and its private key file, respectively.

Convert to PEM format

Convert the signed certificate, CertName.pem, to PEM only format, as follows: 
openssl x509 -in CertName.pem -out CertName.pem -outform PEM

Concatenate the files

Concatenate the CA certificate file and CertName.pem certificate file, as follows:
Windows 
copy CertName.pem + X509CA\ca\new_ca.pem CertName.chain
UNIX 
cat CertName.pem X509CA/ca/new_ca.pem > CertName.chain

Update keystore with the full certificate chain

Update the keystore, CertName.jks, by importing the full certificate chain for the certificate, as follows: 
keytool -import -file CertName.chain -keypass CertPassword -keystore CertName.jks -storepass CertPassword

Repeat steps as required

Repeat steps 2 through 7, to create a complete set of certificates for your system.

2.5.4. Use the CA to Create Signed PKCS#12 Certificates

Substeps to perform

If you have set up a private CA, as described in Section 2.5.2, “Set Up Your Own CA” , you are now ready to create and sign your own certificates.
To create and sign a certificate in PKCS#12 format, CertName.p12, perform the following substeps:
  1. Add the bin directory to your PATH .
  2. Configure the subjectAltName extension (Optional) .
  3. Create a certificate signing request .
  4. Sign the CSR .
  5. Concatenate the files .
  6. Create a PKCS#12 file .
  7. Repeat steps as required .
  8. (Optional) Clear the subjectAltName extension .

Add the bin directory to your PATH

If you have not already done so, add the OpenSSL bin directory to your path, as follows:
Windows 
> set PATH=OpenSSLDir\bin;%PATH%
UNIX 
% PATH=OpenSSLDir/bin:$PATH; export PATH
This step makes the openssl utility available from the command line.

Configure the subjectAltName extension (Optional)

Perform this step, if the certificate is intended for a HTTPS server whose clients enforce URL integrity check, and if you plan to deploy the server on a multi-homed host or a host with several DNS name aliases (for example, if you are deploying the certificate on a multi-homed Web server). In this case, the certificate identity must match multiple host names and this can be done only by adding a subjectAltName certificate extension (see Section 2.4, “Special Requirements on HTTPS Certificates”).
To configure the subjectAltName extension, edit your CA’s openssl.cnf file as follows:
  1. Add the following req_extensions setting to the [req] section (if not already present in your openssl.cnf file): 
    # openssl Configuration File
...
[req]
req_extensions=v3_req
  2. Add the [v3_req] section header (if not already present in your openssl.cnf file). Under the [v3_req] section, add or modify the subjectAltName setting, setting it to the list of your DNS host names. For example, if the server host supports the alternative DNS names, www.redhat.com and jboss.org, set the subjectAltName as follows: 
    # openssl Configuration File
...
[v3_req]
subjectAltName=DNS:www.redhat.com,DNS:jboss.org
  3. Add a copy_extensions setting to the appropriate CA configuration section. The CA configuration section used for signing certificates is one of the following:
    • The section specified by the -name option of the openssl ca command,
    • The section specified by the default_ca setting under the [ca] section (usually [CA_default]).
    For example, if the appropriate CA configuration section is [CA_default], set the copy_extensions property as follows: 
    # openssl Configuration File
...
[CA_default]
copy_extensions=copy
    This setting ensures that certificate extensions present in the certificate signing request are copied into the signed certificate.

Create a certificate signing request

Create a new certificate signing request (CSR) for the CertName.p12 certificate, as shown: 
openssl req -new -config X509CA/openssl.cnf -days 365 -out X509CA/certs/CertName_csr.pem -keyout X509CA/certs/CertName_pk.pem
This command prompts you for a pass phrase for the certificate’s private key, and for information about the certificate’s distinguished name.
Some of the entries in the CSR distinguished name must match the values in the CA certificate (specified in the CA Policy section of the openssl.cnf file). The default openssl.cnf file requires that the following entries match:
  • Country Name
  • State or Province Name
  • Organization Name
The certificate subject DN’s Common Name is the field that is usually used to represent the certificate owner’s identity. The Common Name must comply with the following conditions:
  • The Common Name must be distinct for every certificate generated by the OpenSSL certificate authority.
  • If your HTTPS clients implement the URL integrity check, you must ensure that the Common Name is identical to the DNS name of the host where the certificate is to be deployed (see Section 2.4, “Special Requirements on HTTPS Certificates”).
Note
For the purpose of the HTTPS URL integrity check, the subjectAltName extension takes precedence over the Common Name. 
Using configuration from X509CA/openssl.cnf
Generating a 512 bit RSA private key
.+++++
.+++++
writing new private key to
      'X509CA/certs/CertName_pk.pem'
Enter PEM pass phrase:
Verifying password - Enter PEM pass phrase:
-----
You are about to be asked to enter information that will be
incorporated into your certificate request.
What you are about to enter is what is called a Distinguished
Name or a DN. There are quite a few fields but you can leave
some blank. For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) []:IE
State or Province Name (full name) []:Co. Dublin
Locality Name (eg, city) []:Dublin
Organization Name (eg, company) []:Red Hat
Organizational Unit Name (eg, section) []:Systems
Common Name (eg, YOUR name) []:Artix
Email Address []:info@redhat.com

Please enter the following 'extra' attributes
to be sent with your certificate request
A challenge password []:password
An optional company name []:Red Hat

Sign the CSR

Sign the CSR using your CA, as follows: 
openssl ca -config X509CA/openssl.cnf -days 365 -in X509CA/certs/CertName_csr.pem -out X509CA/certs/CertName.pem
This command requires the pass phrase for the private key associated with the new_ca.pem CA certificate. For example: 
Using configuration from X509CA/openssl.cnf
Enter PEM pass phrase:
Check that the request matches the signature
Signature ok
The Subjects Distinguished Name is as follows
countryName :PRINTABLE:'IE'
stateOrProvinceName :PRINTABLE:'Co. Dublin'
localityName :PRINTABLE:'Dublin'
organizationName :PRINTABLE:'Red Hat'
organizationalUnitName:PRINTABLE:'Systems'
commonName :PRINTABLE:'Bank Server Certificate'
emailAddress :IA5STRING:'info@redhat.com'
Certificate is to be certified until May 24 13:06:57 2000 GMT (365 days)
Sign the certificate? [y/n]:y
1 out of 1 certificate requests certified, commit? [y/n]y
Write out database with 1 new entries
Data Base Updated
To sign the certificate successfully, you must enter the CA private key pass phrase (see Section 2.5.2, “Set Up Your Own CA”).
Note
If you did not set copy_extensions=copy under the [CA_default] section in the openssl.cnf file, the signed certificate will not include any of the certificate extensions that were in the original CSR.

Concatenate the files

Concatenate the CA certificate file, CertName.pem certificate file, and CertName_pk.pem private key file as follows:
Windows 
copy X509CA\ca\new_ca.pem + X509CA\certs\CertName.pem + X509CA\certs\CertName_pk.pem X509CA\certs\CertName_list.pem
UNIX 
cat X509CA/ca/new_ca.pem X509CA/certs/CertName.pem X509CA/certs/CertName_pk.pem > X509CA/certs/CertName_list.pem

Create a PKCS#12 file

Create a PKCS#12 file from the CertName_list.pem file as follows: 
openssl pkcs12 -export -in X509CA/certs/CertName_list.pem -out X509CA/certs/CertName.p12 -name "New cert"
You are prompted to enter a password to encrypt the PKCS#12 certificate. Usually this password is the same as the CSR password (this is required by many certificate repositories).

Repeat steps as required

Repeat steps 3 through 6, to create a complete set of certificates for your system.

(Optional) Clear the subjectAltName extension

After generating certificates for a particular host machine, it is advisable to clear the subjectAltName setting in the openssl.cnf file to avoid accidentally assigning the wrong DNS names to another set of certificates.
In the openssl.cnf file, comment out the subjectAltName setting (by adding a # character at the start of the line), and also comment out the copy_extensions setting.