Red Hat Training

A Red Hat training course is available for Red Hat Fuse

A.5. Creating Your Own Certificates

Overview

If you choose to use a private CA you will need to generate your own certificates for your applications to use. The OpenSSL project provides free command-line utilities for setting up a private CA, creating signed certificates, and adding the CA to your Java keystore.

OpenSSL utilities

You can download the OpenSSL utilities from http://openssl.org/.
This section describes using the OpenSSL command-line utilities to create certificates. Further documentation of the OpenSSL command-line utilities can be obtained at http://www.openssl.org/docs.

Procedure

To create your own CA and certificates:
  1. Add the OpenSSL bin directory to your path.
  2. Create your own private CA.
    1. Create the directory structure for the CA.
      The directory structure should be:
      • X509CA/ca
      • X509CA/certs
      • X509CA/newcerts
      • X509CA/crl
      Where X509CA is the name of the CA's home directory.
    2. Copy the openssl.cnf file from your OpenSSL installation to your X509CA directory.
    3. Open your copy of openssl.cnf in a text editor.
    4. Edit the [CA_default] section to look like Example A.1, “OpenSSL Configuration”.

      Example A.1. OpenSSL Configuration

      #############################################################
[ 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
...
      Note
      You might decide to edit other details of the OpenSSL configuration at this point. For more details, see the OpenSSL documentation.
    5. Initialize the CA database as described in the section called “CA database files”.
    6. Create a new self-signed CA certificate and private key with the command: 
      openssl req -x509 -new -config X509CA/openssl.cnf -days 365 -out X509CA/ca/new_ca.pem -keyout X509CA/ca/new_ca_pk.pem
      You are prompted for a pass phrase for the CA private key and details of the CA distinguished name as shown in Example A.2, “Creating a CA Certificate”.

      Example A.2. Creating a CA Certificate

      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) []:Content Services
Common Name (eg, YOUR name) []:Dita Pressgang
Email Address []:nobody@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 during Step 2.d.
  3. Create signed certificates in a Java keystore.
    1. Generate a certificate and private key pair using the keytool -genkeypair command.
      For details on the options to use when using keytool -genkeypair see the section called “Generate a certificate and private key pair”.
    2. Create a certificate signing request using the keystore -certreq command.
      Example A.3, “Creating a CSR” creates a new certificate signing request for the fusesample.jks certificate and exports it to the fusesample_csr.pem file.

      Example A.3. Creating a CSR

      keytool -certreq -alias fuse -file fusesample_csr.pem -keypass fusepass -keystore fusesample.jks -storepass fusestorepass
    3. Sign the CSR using the openssl ca command.
      You will prompted to enter the CA private key pass phrase you used when creating the CA in Step 2.f).
      See the section called “Signing a CSR” for details on the options to use when signing the CSR.
    4. Convert the signed certificate to PEM only format using the openssl x509 command with the -outform option set to PEM.
      Example A.4, “Converting a Signed Certificate to PEM” converts the signed certificate fusesigned.pem.

      Example A.4. Converting a Signed Certificate to PEM

      openssl x509 -in fusesigned.pem -out fusesigned.pem -outform PEM
    5. Concatenate the CA certificate file and the converted, signed certificate file to form a certificate chain.
      The CA certificate file is stored in the CA's ca directory. For example, the certificate file for the CA created in Step 2.f would be ca/new_ca.pem.
    6. Import the new certificate's full certificate chain into the Java keystore using the keytool -import command.
      Example A.5, “Importing a Certificate Chain” imports the chain fusesample.chain into the fusesample.jks keystore.

      Example A.5. Importing a Certificate Chain

      keytool -import -file fusesample.chain -keypass fusepass -keystore fusesample.jks -storepass fusestorepass
  4. Repeat Step 3 to create a full set of certificates for your system.
  5. Add trusted CAs to your Java trust store.
    1. Assemble the collection of trusted CA certificates that you want to deploy.
      The trusted CA certificates can be obtained from public CAs or private CAs. The trusted CA certificates can be in any format that is compatible with the Java keystore utility; for example, PEM format. All you need are the certificates themselves—the private keys and passwords are not required.
    2. Add a CA certificate to the trust store using the keytool -import command.
      Example A.6, “Adding a CA to the Trust Store” adds the CA certificate cacert.pem, in PEM format, to a JKS trust store.

      Example A.6. Adding a CA to the Trust Store

      keytool -import -file cacert.pem -alias CAAlias -keystore truststore.ts -storepass StorePass
      truststore.ts is a keystore file containing CA certificates. If this file does not already exist, the keytool command creates one. StorePass is the password required to access the keystore file.
    3. Repeat Step 5.b to add all of the CA certificates to the trust store.

CA database files

The CA uses two files, serial and index.txt to maintain its database of certificate files. Both files must be stored in the X509CA directory.
When you first create your CA the OpenSSL tools require that they have very specific initial contents:
  • serial
    The initial contents of this file must be 01.
  • index.txt
    Initially this file must be completely empty. It cannot even contain white space.

Generate a certificate and private key pair

To generate a certificate and private key pair you use the keytool -genkeypair command. For example, Example A.7, “Creating a Certificate and Private Key using Keytool” creates a certificate and key pair that are valid for 365 days and is stored in the keystore file fusesample.jks. The generated key store entry will use the alias fuse and the password fusepass.

Example A.7. Creating a Certificate and Private Key using Keytool

keytool -genkeypair -dname "CN=Alice, OU=Engineering, O=Progress, ST=Co. Dublin, C=IE" -validity 365 -alias fuse -keypass fusepass -keystore fusesample.jks -storepass fusestorepass
Because the specified keystore, fusessample.jks, did not exist prior to issuing the command implicitly creates a new keystore and sets its password to fusestorepass.
The -dname and -validity flags define the contents of the newly created X.509 certificate.
The -dname flag specifies the subject DN. For more details about DN format, see Appendix B, 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 Step 2.f ).
The -validity flag specifies the number of days for which the certificate is valid.

Signing a CSR

To sign a CSR using your CA, you use the openssl ca command. At a minimum you will need to specify the following options:
  • -config—the path to the CA's openssl.cnf file
  • -in—the path to certificate to be signed
  • -out—the path to the signed certificates
Example A.8, “Signing a CSR” signs the fusesample_csr.pem certificate using the CA stored at /etc/fuseCA.

Example A.8. Signing a CSR

openssl ca -config /etc/fuse/openssl.cnf -days 365 -in fusesample_csr.pem -out fusesigned.pem
For more details on the openssl ca command see http://www.openssl.org/docs/apps/ca.html#.