Configuring an SSL certificate for use by BMC AMI SQL Assurance

Adding CA certificate to the Java truststore for SQL Assurance Jenkins

The deployment tool requires mainframe server authentication via the SSL protocol. This process is called an SSL handshake. The server sends the deployment tool an SSL certificate to authenticate itself. The deployment tool validates the SSL certificate root against its list of root certificates of trusted Certificate Authorities (CAs) available in the truststore. This validation process involves the following steps:

• Verifying that the server's certificate is signed by the same CA that has issued a root certificate available in the truststore.
• Verifying that the certificate is valid (not expired), not revoked, and that its common name is valid for the website or host name to which it is connecting.

For a successful SSL certificate validation, you must install the CA root certificate of the mainframe server in one of the following truststores. The environment in which you run the deployment must contain one of the following truststores:

• An existing truststore defined by the following system properties:
  • javax.net.ssl.trustStore as the file path of the truststore
  • javax.net.ssl.trustStorePassword as the truststore password
• java-home/lib/security/jssecacerts file
• java-home/lib/security/cacerts file

The java-home variable represents the directory on which the Java Runtime Environment (JRE) is installed.

The SSL certificate validation occurs by default unless you change the value of the TSFLAG variable to FALSE in the plug-in variables file. For more information, see Sample-plug-in-variables-file-AMI_DevOps-properties.

Adding a CA certificate into image and import to the Java truststore for BMC AMI SQL Assurance Universal Connector

Perform the following procedure each time you pull a new BMC image from containers.bmc.com using a CA certificate or a new CA certificate:

1. Create a file named Dockerfile in the same directory on your VM as the one where the CA certificate file for the z/OSMF server resides.

   Important

   A Dockerfile is a text file that contains a set of instructions for building a Docker image.  
   Dockerfile is the default name, but other names are allowed. The docker build command does not require the Dockerfile name when you use the default name.

2. Add the following script into the Dockerfile:

   FROM containers.bmc.com/bmc/sqlassuranceuc:<imageTag>
   ADD <CACertificateFileName> <CACertificateFileName>
   RUN yes | keytool -import -alias ca-server-alias -keystore /usr/local/openjdk-8/jre/lib/security/cacerts -file <CACertificateFileName> -storepass changeit

   Replace the Dockerfile variables as they apply to your environment:

   Variable	Description
   imageTag	BMC image tag pulled from the containers.bmc.com container registry
   CACertificateFileName	CA certificate file name for the z/OSMF server

   Example

   Image tag: 13.01.00.0001-GA
   CA certificate file name: zosmf.der
   
   ‘Dockerfile’:
   -------------
   FROM containers.bmc.com/bmc/sqlassuranceuc: 13.01.00.0001-GA
   ADD zosmf.der zosmf.der
   RUN yes | keytool -import -alias ca-server-alias -keystore /usr/local/openjdk-8/jre/lib/security/cacerts -file zosmf.der -storepass changeit
   -------------

3. Run the following command to build a new image with the CA certificate installed in the Java truststore of the base image:
   docker build . -t newTag
   
   In the docker build command, replace newTag with a new image name that starts with the container registry host name to which you want to push the new image. Confirm the new tag name with your container registry administrator.

   The docker build command uses the commands in the Dockerfile to perform the following actions:

   • Uses the image specified from containers.bmc.com as its base image.
   • Adds CA certificate into the base image.
   • Imports CA certificate into the image’s Java truststore.

4. Run the following command, with variable replaced for your environment, to push the new image to your container registry: 
   docker push newTag

   Important

   If the container registry is private, you must provide the docker login to the container registry before pushing the image. In this case, you must run the docker login command by using the user ID, password or token of a registered user in the container registry and the host name of the container registry server. Consult with your container registry administrator regarding docker login.

To use the image with the CA certificate, in the pipeline or workflow, specify the newly pushed container image tag name.
Verify that your config.yaml file, referenced in the pipeline or workflow script, is using TSFLAG=TRUE in the plug-in variables file.