Configure Codar to use trusted Certificate Authority-Signed or subordinate Certificate Authority-Signed certificate

This section describes the process you should follow to obtain, install, and configure a trusted third-party Certificate Authority-signed or subordinate Certificate Authority-signed certificate for use by Codar. The process by which you acquire a certificate depends on your organization. If you are obtaining a certificate from a trusted third-party Certificate Authority, such as Verisign, perform the following general steps, which are described in detail below. If you are generating and/or obtaining a certificate from an internal Certificate Authority, such as a corporate Certificate Authority, you should perform the general steps in Configure Codar to use internal Certificate Authority-Signed certificate.

Step 1: Create a keystore and self-signed certificate

Step 2: Create a Certificate Signing Request

Step 3: Submit the certificate signing request to a Certificate Authority

Step 4: Import the Certificate Authority's root certificate

Step 5: Import Certificate Authority-Signed certificate

Step 6: Configure the web server

Step 7: Configure client browsers

Step 8: Test secure connections

Step 1: Create a keystore and self-signed certificate

Create a self-signed certificate to send with your request to a Certificate Authority by completing the following steps:

1. Open a command prompt and change directories to CSA_HOME.

2. Run the following command:

   Windows:

   "CSA_JRE_HOME\bin\keytool" -genkeypair -alias codar_ca_signed
-validity 365 -keyalg rsa -keysize 2048 -keystore .\jboss‑as\standalone\configuration\.keystore_ca_signed

   Linux:

   CSA_JRE_HOME/bin/keytool -genkeypair -alias codar_ca_signed-validity 365 -keyalg rsa -keysize 2048 -keystore./jboss-as/standalone/configuration/.keystore_ca_signed

   CSA_JRE_HOME is the directory in which the JRE that is used by Codar is installed.

   You can use different values for -alias, -validity, -keysize and -keystore. These instructions assume that you will use the -alias and -keystore values recommended here. You will need to adjust the commands accordingly if you use different values.

3. Enter a keystore password.

   This password is used to control access to the keystore. This password must be the same as the password you enter for the key later in this procedure.

4. When you are prompted for your first and last name, enter the fully qualified domain name of the Codar server.

5. Follow the prompts to enter the remaining organization and location values.

6. Enter the keystore password you supplied earlier to use as the key password.

   Although keytool allows you to enter different passwords for the keystore and the key, the two passwords must be the same to work with Codar.

Step 2: Create a Certificate Signing Request

To enable a Certificate Authority to sign the self-signed certificate, you will need to create a Certificate Signing Request using the following procedure:

1. Open a command prompt and change directories to CSA_HOME.

2. Run the following command:

   Windows:

   "CSA_JRE_HOME\bin\keytool" -certreq -alias codar_ca_signed
-file C:\codarcsr.txt -keystore .\jboss‑as\standalone\configuration\.keystore_ca_signed

   Linux:

   CSA_JRE_HOME/bin/keytool -certreq -alias codar_ca_signed-file /tmp/codarcsr.txt -keystore ./jboss-as/standalone/configuration/.keystore_ca_signed

3. When you are prompted for a password, enter the password you supplied for the keystore and key when you created the keystore and self-signed certificate in step 1.

Step 3: Submit the certificate signing request to a Certificate Authority

Submit the Certificate Signing Request to the Certified Authority following the procedure used by your organization or the third-party provider. After the submission has been processed, you will receive a Certificate Authority-signed certificate and a root certificate for the Certificate Authority.

In this example, it is assumed that the Certificate Authority's root certificate is named codarca.cer, the Certificate Authority-signed certificate is named codar_ca_signed.cer, and that both are located in C:\ on Windows or /tmp on Linux.

Step 4: Import the Certificate Authority's root certificate

This step configures the JRE so it trusts the Certificate Authority that has signed your certificate. The JRE ships with a list of common, trusted Certificate Authority certificates that are stored in a keystore named cacerts. If the Certificate Authority used to sign your certificate is well known, it is likely that this root certificate is already present in the cacerts keystore. It is recommended that you perform the following steps even if you suspect that the certificate is already installed. The keytool command will detect if the certificate is already present, and you can exit the import process if the certificate exists.

1. Open a command prompt.

2. Run the following command:

   Windows:

   "CSA_JRE_HOME\bin\keytool" -importcert -alias codarca -file C:\codarca.cer -trustcacerts -keystore "CSA_JRE_HOME\lib\security\cacerts"

   Linux:

   CSA_JRE_HOME/bin/keytool -importcert -alias codarca -file /tmp/codarca.cer -trustcacerts -keystore CSA_JRE_HOME/lib/security/cacerts

3. When prompted enter the password for the keystore.

4. Enter yes when prompted to trust the certificate.

Step 5: Import Certificate Authority-Signed certificate

1. The Certificate Authority-signed certificate (codar_ca_signed.cer) contains a chain of certificates and you must copy the root and any intermediate certificates in the chain to separate files. Work with your security expert to copy each certificate to a separate file.

2. Open a command prompt and change directories to CSA_HOME.

3. Import the certificate file(s). Import each separate file in the following order (each certificate must have a unique alias):

   • root certificate

   • intermediate or subordinate certificate(s) in hierarchical order

     primary or end-user certificate

     For example, if the Certificate Authority-signed certificate contains three certificates (root, intermediate, and primary) and you copied the root certificate to /tmp/root.cer and the intermediate certificate to /tmp/intermediate.cer (you will use the Certificate Authority-signed certificate as the primary certificate), run the following commands in the following order to import each certificate:

     Windows:

     "CSA_JRE_HOME\bin\keytool" -importcert -alias codar_ca_signed
-file C:\codar_ca_signed.cer -trustcacerts -keystore .\jboss‑as\standalone\configuration\.keystore_ca_signed

     Linux:

     CSA_JRE_HOME/bin/keytool -importcert -alias codar_ca_signed
-file /tmp/codar_ca_signed.cer -trustcacerts -keystore ./jboss‑as/standalone/configuration/.keystore_ca_signed

     Use the alias of the primary certificate (codar_ca_signed) and keystore name when you configure the Web server.

4. When prompted, enter the password for the key and keystore.

   Use this password when you configure the Web server.

Step 6: Configure the web server

Configure the web server by completing the following steps:

1. Open CSA_HOME\jboss‑as\standalone\configuration\
standalone.xml in a text editor.

2. Locate the following entry:

   <keystore path="CSA_HOME/jboss-as/standalone/configuration/.keystore"
   keystore-password="changeit"/>

3. Set the path attribute to the keystore you used in step 2, set the keystore-password attribute to the value that corresponds to the password you selected for the keystore, and add the key-alias attribute and set it to the alias you used in step 2.

   <keystore path="CSA_HOME/jboss-as/standalone/
   configuration/.keystore_self_signed" keystore-password="keystorePassword"
   alias="csa_self_signed"/>

   Note This example stores the password in clear text. If you want to use an encrypted password, follow the instructions at https://community.jboss.org/wiki/JBossAS7SecuringPasswords to create a password vault for JBoss.

   Note If you are using the vault scripts, verify that the JAVA_HOME environment variable has been defined. Verify that JAVA_HOME has been set to the directory in which the JRE that is used by Codar is installed.

   Windows:

   If the directory path name includes a space, verify that the value has been enclosed in quotations marks. For example, to set JAVA_HOME to a directory path name that includes a space, from a command prompt, type
   set JAVA_HOME="C:\Program Files\HPE\Codar\jre"

   To verify that JAVA_HOME has been defined, from a command prompt, type:
   echo %JAVA_HOME%

   Linux:

   To verify that JAVA_HOME has been defined, from a command prompt, type:
   echo $JAVA_HOME

   The following is an example of an encrypted password attribute using the JBoss password vault:

   password="${VAULT::<vault_block_example>::password::N2NhZDzOMtES0ZGE4MmEtx0}"

4. Restart Codar service, see Restart Codar.
5. After the service has started, review the log files in CSA_HOME\jboss‑as\
standalone\log\ and verify that no TLS or keystore errors are present.

Step 7: Configure client browsers

The client browser must be configured to trust certificates that are signed by the Certificate Authority. In most situations, this step will already have occurred. Client browsers are likely to already trust well-known third-party Certificate Authorities, or will have previously accessed and trusted Web sites that use internal Certificate Authority root certificates.

To test whether or not the browser on a client system is configured to trust certificates signed by your Certificate Authority, open a supported Web browser and navigate to https://<codarhostname>:8444/csa. If you do not see a certificate warning, then the browser is configured properly.

If client browsers need to be configured to trust certificates signed by your Certificate Authority, then you will need to make the root certificate available to clients so it can be installed in the browser. The process of installing the root certificate will vary based on the browser.

• Microsoft Internet Explorer and Chrome: From Windows Explorer, double-click on the .cer file to begin the import process. Install the certificate in the Trusted Root Certification Authorities store. For information on how to import the certificate, see the browser's online documentation.
  
• Firefox: To begin the import process, select Tools > Options, select Advanced, select the Encryption tab, and click View Certificates. Import the root certificate into the Authorities tab. For information on how to import the certificate, see the browser's online documentation.

Step 8: Test secure connections

To test the connection to the Codar Console, on a client system, open a supported Web browser and navigate to https://<codarhostname>:8444/csa where <codarhostname> is the fully-qualified domain name of the system that was used when the certificate was created. If the client browser is configured to accept the Certificate Authority's root certificate and the web application opens without a certificate warning, then you have successfully configured Codar to use a Certificate Authority-signed certificate. If a certificate warning is displayed, review steps 1-7 to be sure they were followed as documented.