Configuring security with self-signed certificates

A self-signed certificate is a digital certificate that is not signed by a trusted certificate authority (CA). These certificates are created, issued, and signed by the developer responsible for managing the application, and consequently are not considered safe for general use. Self-signed certificates can be used to test a TLS configuration before you create and install a CA signed certificate.

About this task

Learn how to configure mutual TLS between z/OS® Connect Designer and Db2®. This configuration creates the following artifacts: 
  • The clientKey.p12 keystore contains a self-signed personal certificate for IBM® z/OS Connect that consists of the public and private key.
  • The clientTrust.p12 truststore that contains the Db2 public-key certificate.
If you require only TLS server authentication, complete step 6. This configuration creates the following artifacts:
  • The clientTrust.p12 truststore that contains the Db2 public-key certificate.
Figure 1. Mutual TLS with self-signed certificates.
TLS self signed certificate.
Note: These commands use paths based on MacOS. If you use Windows, you need to change the paths to suit your configuration.

Procedure

  1. Generate a self-signed personal certificate that includes a public and private key.
    Enter the following command:
    docker run -it --rm -v /Users/<username>/Desktop/ZCWorkspace/certs:/tmp/cert/output icr.io/zosconnect/ibm-zcon-designer:3.0.75 keytool -genkey -keyalg RSA -keysize 2048 -alias clientKey -dname "CN=localhost, O=IBM, C=US" -validity 365 -keystore /tmp/cert/output/clientKey.p12 -storetype PKCS12
    Replace the following attributes with values for your local configuration:
    • /Users/<username>/Desktop/ZCWorkspace/certs is an example path to the keystore.
    • clientKey is the alias of the personal certificate to be created.
    • CN=localhost, O=IBM, C=US is an example distinguished name (DN) for the certificate. The CN value is typically the hostname of the client that owns the certificate.
    • clientKey.p12 is the name of the .p12 file to be dynamically created to act as the IBM z/OS Connect keystore.
    You are prompted to provide a password for the keystore. For this tutorial, the password is myPassword.
  2. Verify that the clientKey.p12 keystore is created in the certs subdirectory of the project workspace directory. In this tutorial, the project workspace directory is ZCWorkspace. 
    
       |-- ZCWorkspace
                |-- /certs
                        |-- clientKey.p12
  3. Export a public key certificate from the self-signed certificate.
    Enter the following command.
    docker run -it --rm -v /Users/<username>/Desktop/ZCWorkspace/certs:/tmp/cert/input -v /Users/username/Desktop/certificates/:/tmp/cert/output icr.io/zosconnect/ibm-zcon-designer:3.0.75 keytool -exportcert -file /tmp/cert/output/zconPublicCert.cer -keystore /tmp/cert/input/clientKey.p12 -storetype PKCS12 -alias clientKey
    Replace the following attributes with values for your local configuration:
    • /Users/<username>/Desktop/ZCWorkspace/certs is an example path to the keystore.
    • /Users/<username>/Desktop/certificates/ is an example path of where CA signed personal certificate (clientCertSigned.cer) is exported.
    • zconPublicCert.cer is an example name of the exported public-key certificate.
    • clientKey.p12 is the name of the keystore from which the self-signed certificate is exported.
    • clientKey is the alias of the personal certificate that was created in step 1.
    You are prompted to provide a password for the keystore. For this tutorial, the password is myPassword, as defined in step 1.
  4. Verify that the zconPublicCert.cer file is created in the export directory specified.
    For this tutorial, the directory is /certificates, located in the Desktop directory if you are using a Mac or the root directory if you are using Windows.
    
        |-- certificates/
                |-- zconPublicCert.cer
  5. Transfer the public-key certificate (zconPublicCert.cer) in binary mode to the system that hosts the Db2 instance.
    Transferring the certificate shares the IBM z/OS Connect public-key certificate with Db2. The public-key certificate must be stored in the Db2 truststore. Speak to the Db2 administrator who is responsible for adding this certificate to the truststore. The instructions for storing the certificate depend on the Db2 environment.
  6. Create the IBM z/OS Connect truststore to contain the Db2 public-key certificates.
    1. Obtain the Db2 public-key certificate from the Db2 administrator, or your organization's certificate authority.
    2. Transfer the Db2 public-key certificate in binary mode to your local workstation with the name clientTrust.
      The file extension of this certificate might vary, for the purposes of this tutorial, it is a .crt file.
    3. Save this file on your local workstation.
      For this tutorial, this certificate is saved in the /certificates directory in the Desktop directory if you are using a Mac or the root directory if you are using Windows.
      
        |-- certificates/
                |-- zconPublicCert.cer
                |-- clientTrust.crt 
    4. Create the IBM z/OS Connect truststore and import the Db2 public-key certificate.
      Enter the following command:
      docker run -it --rm -v /Users/<username>/Desktop/certificates/:/tmp/cert/input -v /Users/<username>/Desktop/ZCWorkspace/certs:/tmp/cert/output icr.io/zosconnect/ibm-zcon-designer:3.0.75 keytool -importcert -file /tmp/cert/input/clientTrust.crt -keystore /tmp/cert/output/clientTrust.p12 -storetype PKCS12 -noprompt
      Replace the following attributes with values for your local configuration:
      • /Users/<username>/Desktop/certificates/ is an example path to the location of the Db2 public certificate (clientTrust.crt)
      • /Users/<username>/Desktop/ZCWorkspace/certs is an example path to the truststore.
      • clientTrust.p12 is the name of the truststore that is created with the Db2 public-key certificate.
      You are prompted to provide a password for the keystore.
      Note: This prompt might use the term keystore instead of truststore.
      For convenience, use the same password you used to secure the keystore. For this tutorial, the password is myPassword.
    5. Verify the clientTrust.p12 truststore is created by looking in the certs folder in the project workspace directory. 
      
        |-- ZCWorkspace
                |-- /certs
                        |-- clientKey.p12
                        |--clientTrust.p12
  7. Confirm that the IBM z/OS Connect keystore is created correctly.
    1. List the contents of the keystore.
      Run the following command:
      docker run -it --rm -v /Users/<username>/Desktop/ZCWorkspace/certs:/tmp/cert/output icr.io/zosconnect/ibm-zcon-designer:beta keytool -v -list -keystore /tmp/cert/output/clientKey.p12 -storetype PKCS12
      Replace the following attributes with values for your local configuration:
      • /Users/<username>/Desktop/ZCWorkspace/certs is an example path to the truststore.
      • clientKey.p12 is the name of the keystore.
      You are prompted to provide a password for the keystore. For this tutorial, the password is myPassword.
    2. Verify that your keystore includes the certificate alias: clientkey.
      If this certificate is missing, repeat steps 1 and 3.
  8. Confirm that the IBM z/OS Connect truststore is created correctly.
    1. List the contents of the truststore.
      Run the following command:
      docker run -it --rm -v /Users/<username>/Desktop/ZCWorkspace/certs:/tmp/cert/output icr.io/zosconnect/ibm-zcon-designer:3.0.75 keytool -v -list -keystore /tmp/cert/output/clientTrust.p12 -storetype PKCS12
      Replace the following attributes with your local configuration:
      • /Users/<username>/Desktop/ZCWorkspace/certs is an example path to the truststore.
      • clientTrust.p12 is the name of the truststore.
      You are prompted to provide a password for the keystore. For this tutorial, the password is myPassword.
    2. Verify that your keystore includes the alias of the Db2 public-key certificate.
      If this certificate is missing, repeat step 6.
  9. Populate the docker-compose.yaml file with the keystore and truststore password.
    1. Open the docker-compose.yaml file and add the environmental variable - DB2_CERT_PASSWORD=<db2certpassword>.  
      - DB2_CERT_PASSWORD=<db2certpassword>
    2. Replace <db2certpassword> with the password used to protect the keystore and truststore certificates. For this tutorial, the password is myPassword.
      Your docker-compose.yaml file now looks like this:
      version: "3.2"
services:
    zosConnect:
        image: icr.io/zosconnect/ibm-zcon-designer:beta
        environment:
            - DB2_USERNAME=userName
            - DB2_PASSWORD={aes}APu1HaGpBzYbH+g8xVbuqUgJPz1ydNS9VbpAq1hstGdF
            - DB2_HOST=myhost
            - DB2_PORT=myport
            - HTTP_PORT=9080
            - DB2_CERT_PASSWORD=myPassword
        ports:
            - "9443:9443"
            - "9080:9080"
        volumes:
            - ./EmployeesApi:/workspace/project
            - ./logs/:/logs/
            - ./certs:/config/resources/security/:ro
    3. Optional: Encrypt your password by using the built-in securityUtility Liberty feature.
      Enter the following command, replacing myPassword with the password you used to secure the keystore and truststore.
      docker run icr.io/zosconnect/ibm-zcon-designer:3.0.75 securityUtility encode myPassword --encoding=aes
      The output looks something like this:
      {aes}AIlvyBGrBXaG1gikSy47+vVsdZraHqLsrB02eV/moEIy
      Update your docker-compose.yaml file with the encrypted password.
      version: "3.2"
services:
    zosConnect:
        image: icr.io/zosconnect/ibm-zcon-designer:3.0.75
        environment:
            - DB2_USERNAME=userName
            - DB2_PASSWORD={aes}APu1HaGpBzYbH+g8xVbuqUgJPz1ydNS9VbpAq1hstGdF
            - DB2_HOST=myhost
            - DB2_PORT=myport
            - HTTP_PORT=9080
            - DB2_CERT_PASSWORD={aes}AIlvyBGrBXaG1gikSy47+vVsdZraHqLsrB02eV/moEIy
        ports:
            - "9443:9443"
            - "9080:9080"
        volumes:
            - ./EmployeesApi:/workspace/project
            - ./logs/:/logs/
            - ./certs:/config/resources/security/:ro
  10. Create the db2.xml file.
    1. Open a new file in your text editor and populate it with the following code: 
      <?xml version="1.0" encoding="UTF-8" ?>
<server description="Default server">
    <featureManager>
        <feature>zosconnect:db2-1.0</feature>
    </featureManager>


  <zosconnect_credential user="${DB2_USERNAME}" password="${DB2_PASSWORD}" id="commonCredentials"/>
    <zosconnect_db2Connection id="db2Conn" host="${DB2_HOST}" port="${DB2_PORT}" credentialRef="commonCredentials" sslRef="sslCertificates"/>
    <ssl id="sslCertificates" keyStoreRef="clientKeyStore" trustStoreRef="clientTrustStore"/>
    <keyStore id="clientKeyStore" password="${DB2_CERT_PASSWORD}" location="${server.config.dir}/resources/security/clientKey.p12" />
    <keyStore id="clientTrustStore" password="${DB2_CERT_PASSWORD}" location="${server.config.dir}/resources/security/clientTrust.p12" />
</server>
    2. Save the file as db2.xml in the ZCWorkspace/EmployeesApi/src/main/liberty/config directory.
    3. Verify the db2.xml file and directories are listed correctly.
      The following screen image shows the resulting project structure.
      
        |-- ZCWorkspace
                |-- /certs
                |-- /logs
                |-- /EmployeesApi
                       |--src
                             |--main
                                     |--liberty
                                            --config  
                                                    |--db2.xml
        |-- docker-compose.yaml

Results

You successfully created the keystore and truststore that use a self-signed certificate. In the following topics, you verify that this connection is established.