Installing on IBM zCX environment with Db2 for z/OS

Use the instructions in this topic to install IBM Security Guardium Key Lifecycle Manager on IBM® zCX environment with Db2 for z/OS®.

Before you begin

Prepare the database system
  • Install Db2 for z/OS. For more information, see Installing and migrating Db2®.
  • Ensure that function level 501 or later is activated in Db2 for z/OS. For more information, see https://www.ibm.com/docs/en/db2-for-zos/12?topic=12-db2-function-levels.
    To verify whether the required function level is activated, run the following command:
    SELECT LISTAGG(id, ', ') as ids FROM ( VALUES (1),(2), (5), (6)) AS X(id)
    The following output indicates that the required function level is activated:
    "1, 2, 5, 6"
  • Create a buffer pool set with the following configuration:
    ALTER BUFFERPOOL (BP8K4) VPSIZE(1000)
    ALTER BUFFERPOOL (BP16K4) VPSIZE(1000)
    ALTER BUFFERPOOL (BP32K4) VPSIZE(1000)
  • Create databases in the following sequence:
    create database KLMSMM BUFFERPOOL BP8K4 INDEXBP BP8K4;				
    create database KLMLGG BUFFERPOOL BP16K4 INDEXBP BP16K4;			
    create database KLM32KLH BUFFERPOOL BP32K4 INDEXBP BP32K4;
    Note: The database names that are specified here are examples. You can specify the database names of your choice. Ensure that the database names are up to 8 characters long.
  • Grant the DBADM permission for the databases and buffer pools to the IBM Security Guardium Key Lifecycle Manager database user.
    GRANT DBADM with dataaccess with accessctrl TO DB_USER; 
    GRANT USE OF BUFFERPOOL BP8K4 TO DB_USER;
    GRANT USE OF BUFFERPOOL BP16K4 TO DB_USER;
    GRANT USE OF BUFFERPOOL BP32K4 TO DB_USER;

    Where, DB_USER is the database user for IBM Security Guardium Key Lifecycle Manager. For example, USER0001.

Prepare the host system with the IBM zCX environment
  • Ensure that your host system meets the minimum system requirements. For more information, see the Support matrix.
  • Provision an IBM z/OS Container Extension (zCX) instance on the host system. For more information, see What is z/OS Container Extension? .
Obtain the container installation files
Obtain the container installation files (eImages) for IBM Security Guardium Key Lifecycle Manager from IBM Passport Advantage. For more information, see Installation images for containerized platforms.
Obtain the license files
Obtain the license file for Db2 for z/OS, db2jcc_license_cisuz.jar. This file is used by the Guardium Key Lifecycle Manager container to connect to the Db2 for z/OS database.
Save these license files to the host system.
Create a Docker file
Create a file (Dockerfile) with the following content and save the file in the same directory where you saved the license file for Db2 for z/OS, db2jcc_license_cisuz.jar on the host system.
# Extend from GKLM Application Repository
ARG LATEST_IMAGE
FROM ${LATEST_IMAGE}
ARG DB2_LICENSE_FILE=${DB2_LICENSE_FILE}


#Copy license file to SKLM
COPY $DB2_LICENSE_FILE /opt/ibm/wlp/usr/sklm/custom

# Set Environment variable
ENV DB2_LICENSE_FILE=$DB2_LICENSE_FILE

Procedure

  • Scenario 1 - Installing on IBM zCX environment with a clean Db2 for z/OS with AT-TLS support.
    Complete the following steps on the host system with the IBM zCX environment:
    1. Ensure that the databases (KLMSMM, KLMLGG, KLM32KLH) are running and ready to accept connections.
    2. To configure SSL/TLS on Db2 for z/OS, follow the instructions here: Configuring the Db2 server for SSL.

      To configure Db2 to use the AT-TLS support, follow the instructions here: AT-TLS configuration.

    3. Obtain the container installation file (eImage) from IBM Passport Advantage and save it in the same directory where you saved the license and Docker files. For more information, see Installation images for containerized platforms.
    4. Log in to the host system and go to the directory where you saved the eImage, license, and Docker files.
    5. Extract the Docker image of the Guardium Key Lifecycle Manager application from the image file.
      Sample command:
      docker load -i sklm:Rel_4200_155.s390x.tar
    6. Build the Docker image of the Guardium Key Lifecycle Manager application by using the Docker file to include the Db2 license file.
      Sample command:
      docker build -t gklmzos --build-arg LATEST_IMAGE=sklm:Rel_4200_155.s390x --build-arg DB2_LICENSE_FILE=db2jcc_license_cisuz.jar --no-cache .
    7. Initialize the docker swarm. To do so, run the following command:
      docker swarm init
    8. Define the docker secrets.
      echo DB_PWD | docker secret create sklmdb_password -
      echo DB_USR | docker secret create sklmdb_username -
      echo 68d95f0081f1dbfc0b06de9b0916df1c | docker secret create sklmapp_seed -
      echo your_sklmadmin_password | docker secret create sklmadmin_password -
      echo your_sklmadmin_password | docker secret create liberty_key_store_password -
    9. Define a Docker secret from the Db2 SSL/TLS certificate.
      
      docker secret create db2_ssl_cert Db2_SSL_CERT_FILE
      docker secret create db_client_ssl_cert Db2_CLIENT_SSL_CERT_FILE
      docker secret create db_client_ssl_key Db2_CLIENT_SSL_KEY_FILE
      docker secret create db_client_ssl_key_password Db2_CLIENT_SSL_KEY_PASSWORD

      Where,

      • db2_ssl_cert is the secret name.
      • Db2_SSL_CERT_FILE is the Db2 SSL/TLS certificate file name.
      • db_client_ssl_cert is the secret name for client certificate.
      • Db2_CLIENT_SSL_CERT_FILE is the Db2 client SSL/TLS certificate file name.
      • db_client_ssl_key is the secret name for the encrypted private key file for client.
      • Db2_CLIENT_SSL_KEY_FILE is the Db2 client encrypted private key file name.
      • db_client_ssl_key_password is the secret name for the password for the encrypted private key file.
    10. Spin the Guardium Key Lifecycle Manager container by using the docker service command.
      docker service create -p 3801:3801 -p 1111:1111 -p 2222:2222 -p 9443:9443 -p 5696:5696 -p 1441:1441 -e DB_HOST=9.xx.xx.xx -e DB_PORT=446 -e DB_TYPE=zos_db2 -e ZOS_DB_NAMES=KLMSMM,KLMLGG,KLM32KLH -e LICENSE=accept -e ZOS_DB_LOCATION=db_location --mount src=klmappvolume,dst=/opt/ibm/wlp/products --secret sklmapp_seed --secret sklmadmin_password --secret liberty_key_store_password --secret db_client_ssl_cert --secret db_client_ssl_key --secret db_client_ssl_key_password --secret db_ssl_cert -e DB_SSL_ADD=true gklmzos
      Note: Ensure that the database names that you specify in the ZOS_DB_NAMES parameter are in the same sequence in which they were created.
      For more information about the parameters, see Parameters to install the IBM Security Guardium Key Lifecycle Manager container.
    11. To monitor the progress, run the following command.
      docker service logs -f gklm_service
      After you see the following message in the logs, proceed to the next step:
      IBM Security Guardium Key Lifecycle Manager server started.
    12. Start the IBM Security Guardium Key Lifecycle Manager graphical user interface.
      https://IP_address:port/ibm/SKLM/login.jsp

      Where, IP_address is the IP address or FQDN of the IBM Security Guardium Key Lifecycle Manager server, and port is the port number that the IBM Security Guardium Key Lifecycle Manager server listens on for requests.

    13. Log in to the IBM Security Guardium Key Lifecycle Manager graphical user interface with the Administrator user credentials (For example, sklmadmin).
    14. Activate the IBM Security Guardium Key Lifecycle Manager license. For instructions, see Trying IBM Security Guardium Key Lifecycle Manager trial version and activating a purchased license.
  • Scenario 2 - Upgrading the previous Guardium Key Lifecycle Manager version on zCX from one-way SSL (Db2 server-side TLS) to version 4.2.1 on Db2 for z/OS with AT-TLS (secure connection on both server and client side).

    If the earlier version of Guardium Key Lifecycle Manager is already running only with the database certificate, and if you want to upgrade version 4.2.1 with database and client certificates, complete the following steps.

    1. Remove the Guardium Key Lifecycle Manager service that is running on the zCX platform (do not remove the volume).
    2. Configure Db2 for z/OS with additional client certificates.
    3. Create the following secrets.
      docker secret create db_client_ssl_cert Db2_CLIENT_SSL_CERT_FILE
      docker secret create db_client_ssl_key Db2_CLIENT_SSL_KEY_FILE
      docker secret create db_client_ssl_key_password Db2_CLIENT_SSL_KEY_PASSWORD
    4. Deploy Guardium Key Lifecycle Manager container with regular command by using the same volume, which was used for earlier version of Guardium Key Lifecycle Manager deployment.
  • Scenario 3 - Update the database server/client certificates on the existing zCX environment with Db2 for z/OS with AT-TLS support.

    If the database certificates are expired or the existing database certificates are to be replaced, complete the following steps to update those certificates in Guardium Key Lifecycle Manager container.

    1. Remove the Guardium Key Lifecycle Manager service that is running on the zCX platform (do not remove the volume).
    2. Update the certificates in Db2 for z/OS.
    3. Delete the following existing secrets, and re-create them with the new certificate values.
      db_ssl_cert
      db_client_ssl_cert
      db_client_ssl_key
      db_client_ssl_key_password
      Note:

      If only the Db2 certificate is changed (db_ssl_cert), then re-create only the db_ssl_cert secret with the changed certificate file. No need to re-create the other secrets.

      If only the client certificate is changed, then re-create only the client-related secrets with the changed certificate files.

    4. Deploy Guardium Key Lifecycle Manager on zCX container with regular command by using the same volume, which was used for earlier version of Guardium Key Lifecycle Manager deployment.

What to do next

  • From the Welcome page, configure the drive types, keys, and certificates that your organization requires, or get started with using the product. See Administering.
  • (Optional) Enhance secure communication between the client and the IBM Security Guardium Key Lifecycle Manager server by using a CA-signed certificate. See Importing a server certificate.