|Tasks||The steps in this article include how to:|
- Generate a keypair using openSSL.
- Generate a certificate signing request (CSR) using that keypair in openSSL.
- Give the CSR to your CA, who will return to you a signed certificate, a root CA certificate, and zero or more intermediate CA certificates which form the signing chain.
- Combine all certificates into one file in their chaining order by copying the contents of each certificate into a new file.
- Import the keypair and cert chain into a new keystore using Keystore Explorer.
- Save the new keystore, backup the existing keystore, and replace the existing keystore with the new one.
- To generate a keypair you can use openSSL. There are many options available for generating keys, but here is a simple example:
openssl genrsa -out host-key.pem -aes256 -passout pass:Av3k5a15num83r0n3 2048
This will generate a new file, named host-key.pem, containing the private key. This key MUST be kept private. It is suggested that you encrypt the key file, as is done in the example command above.
- To generate a CSR from the private key generated in step 1, use the following openSSL command:
openssl req -new -sha256 -key host-key.pem -passin pass:Av3k5a15num83r0n3 -out root-csr.csr
This will generate a CSR based on the keypair generated in step 1.
- Send the CSR generated in step 2 to your CA to have it signed. The CA will return to you a certificate for the host (end-point) as well as a root CA certificate and possibly some intermediate CA certificates. Typically these certificates will be in PEM format (base-64 encoded DER), with a file extension of .pem, .cer, .crt, or possibly others. For the purpose of this article we will assume the CA returns to you a certificate named host-certificate.cer.
- Note that each certificate provided by the CA form a trust chain that represents the signing order in which the CA signed each certificate. This chain is of the form root CA certificate > zero or more Intermediate CA certificate(s) > Host certificate (referred to as end-point or leaf). There may not be intermediate CA certificates, but if there are, they must be included in the chain in the correct order. We must copy the contents of each certificate into a new file, which we'll call chain-certificate.pem, in the order in which they signed each other. If you open each certificate in a text editor you will find the certificate data is wrapped in a BEGIN and END header/footer as illustrated here:
<BASE64 ENCODED DATA>
In order to build the chain file copy the contents of the certificate file, including the header and footer lines, into a new file. The first item in that new file should be the contents of the root CA certificate, followed by the first intermediate certificate, followed by any other intermediate certificates, and then last, the host certificate. For example, the chain file for a certificate signed by a CA using two intermediate certificates would look something like:
<Root CA Certificate Data>
<Intermediate CA Certificate 1 Data>
<Intermediate CA Certificate 2 Data>
<Host Certificate Data>
If in doubt as to the order in which certificates were signed, the certificates can be examined (double click in Windows) and the subject and issuing fields inspected. The issuing field of the certificate will match the subject field of the certificate which signed it. Root CA certificates will be self-signed, meaning the issuing and subject fields will match. When this step is completed you will have a number of certificate files provided by your CA, the newly created chain-certificate.pem, and the host-key.pem file generated in step 1.
- Download and install Keystore Explorer, if you haven't already. Keystore Explorer is a free, open-source, GUI replacement for the Java command-line utility keytool. It overcomes some of the limitations of keytool, such as the ability to import public/private key-pairs. To use Keystore Explorer:
- Run Keystore Explorer.
- When prompted, choose Create a new KeyStore.
- Choose type JKS.
- In the new keystore, choose Tools > Import Key Pair.
- Select OpenSSL as the type.
- If you encrypted your private key file with a password (as in step 1 by adding the -aes256 and -passout parameters), check the Encrypted Private Key box and enter the password used for the Decryption Password field.
- For the OpenSSL Private Key File field, select the host-key.pem file generated in step 1.
- For the Certificate(s) File, select the chain-certificate.pem created in step 4.
- Click Import .
- When prompted for an alias name use server. There should now be an entry in the keystore named server. Verify that the chain order is correct by double-clicking the entry and inspecting the Certificate Hierarchy at the top of the details. The hierarchy should reflect the signing order, with the root CA certificate listed at the top, and the host certificate listed at the bottom, with any intermediate CA certificates listed between.
- Use File > Save as, save the keystore as aveksa.keystore.
- Backup the existing keystore used by Aveksa (note the ticks are true ticks, not apostrophes):
cp /home/oracle/keystore/aveksa.keystore /home/oracle/keystore/aveksa.keystore.backup_`date +%F_%T`
- Replace the /home/oracle/keystore/aveksa.keystore on the appliance with the one created in Keystore Explorer.
- Restart Aveksa.
- Ensure the root CA certificate provided by your CA is trusted on the system from which you intend to access Aveksa then test the connection to ensure it validates the new UI certificate as trusted. This root CA certificate can also be set to trusted by the Aveksa server by following the instructions in Appendix A of the RSA Via Lifecycle and Governance Installation Guide V7.0, for how to import certificates into the Java cacerts file.