Changing the data encryption key for IBM OpenPages for IBM Cloud Pak for Data

You can change the encryption key that is used to encrypt data in IBM® OpenPages® for IBM Cloud Pak for Data.

Before you begin

Before you do this task, review the following prerequisites:
  • You are familiar with encryption keys and how to manage them.
  • You know how to use the OpenPages GRC REST API or you have experience with other REST APIs.
  • You can log in to the OpenPages application as a super administrator, such as OpenPagesAdministrator.
  • You can log in to Red Hat® OpenShift® as a project administrator.

About this task

Do the following tasks in order:
  1. Backing up the current encryption key
  2. Backing up OpenPages
  3. Decrypting data with the current encryption key
  4. Generating a new secret key
  5. Updating Red Hat OpenShift with the new key
  6. Restarting the application servers
  7. Encrypting data with the new key
  8. Restarting the application servers again

Backing up the current encryption key

Back up your current encryption key.

Procedure

  1. Log in to your Red Hat OpenShift cluster as a project administrator: 
    oc login OpenShift_URL:port
  2. Change to the project where OpenPages is installed: 
    oc project <Project>
  3. Retrieve the current encryption key by running the following command: 
    oc get secret openpages-<instance name>-platform-secret -o jsonpath="{.data.encryption-key-pw}"

    The command returns the base64 encoded key that is used currently for data encryption in your instance.

    Save the key in a secure location. You might need it later, for example if you need to restore a backup.

Backing up OpenPages

Back up your OpenPages instance.

About this task

You can do an online backup or an offline backup. For more information, see .

Decrypting data with the current encryption key

After you complete the backups, decrypt the data by using the current encryption key so that you can encrypt the data later with a new key.

Before you begin

To do this task, the application pods must be in a Running state and their readiness status must be Ready.

About this task

Use the following OpenPages GRC REST API endpoint to decrypt the data: 
https://<op_app_server>:<op_port>/grc/api/configuration/decryptWithExternalKey
To call the API, send an https PUT request to the path by using an HTTPS client. You can use a curl command, for example:
curl -k --location --request PUT --header 'Content-Type: application/json' --header 'Accept: application/json' -u <op_super_user>:<op_super_user_password> 'https://<op_app_server>:<op_port>/grc/api/configuration/decryptWithExternalKey'

The API response includes the process ID of the decryption long running process, for example {"processId":"2927"}

Note the following details about the curl command:
  • The -u parameter requires an OpenPages username and password. This user must be an OpenPages super administrator, such as OpenPagesAdministrator.
  • The -k parameter allows connections to SSL sites without trusted certificates. This parameter is not needed if you replaced the default certificates with your own certificate authority (CA)-signed certificates.
You can check the status of the decryption process by using the following API:
https://<op_app_server>:<op_port>/grc/api/processes/<process_Id>

You can call the API by using your browser or by using an HTTPS client to send a GET request.

For example:
curl -k --location -u <op_super_user>:<op_super_user_password> --header 'Content-Type: application/json' --header 'Accept: application/json' --request GET 'https://<op_app_server>:<op_port>/ grc/api/processes/<process_Id>'

In the response, the status attribute indicates whether the process is finished or still in progress. You can repeat the check as needed. The process is complete when the status value is STATUS_FINISHED_SUCCESS.

The decryption process can take time, depending on the data volume. It takes longer especially if you have many file attachment records.

To check the logs for a process, you can send a GET request to the following endpoint:
https://<op_app_server>:<op_port>/grc/api/processes/<process_Id>/logs

Generating a new secret key

Generate a new encryption key.

About this task

IBM OpenPages for IBM Cloud Pak for Datauses AES256 for data encryption. The key must be 256 bits (32 bytes) in length and it must be encoded with base64. The key must meet these requirements so it can be stored in a Kubernetes secret.

Note: A 256-bit key that is encoded with base64 is 44 characters in length.

To generate a new random key, you can use a random generation tool or you can use openssl. The openssl command is available on the OpenPages application server pod:

Important: In either case, save the key value in a secure location. The key value will be stored only in Kubernetes Secrets. The key value is not persisted by OpenPages and the key value cannot be recovered if it's lost.

Procedure

  1. Log in to the application server pod and open a terminal window.
    Use one of the following methods:
    Using the web client
    In the Red Hat OpenShift console, go to an application server pod and open a terminal.
    Using the command line
    1. Log in to your Red Hat OpenShift cluster as a project administrator: 
      oc login OpenShift_URL:port
    2. Change to the project where the Cloud Pak for Data control plane is installed:
      oc project <Project>
    3. Log in to the application server pod and open a terminal:
      oc exec -it openpages-<instance_name>-sts-1 -- /bin/bash

      To find the pod name, run oc get sts and look for a name that starts with openpages-.

  2. Run the following command to create the key: 
    openssl rand -base64 32 | head -c24 | tr -d '\n' | base64
  3. Save the new key value in a secure location.

Updating Red Hat OpenShift with the new key

Update the Kubernetes Secret in Red Hat OpenShift with the new key value.

Procedure

  1. Open the Red Hat OpenShift web client.
  2. Click Workload > Secrets, and then click openpages-<instance_name>-platform-secret.
  3. Click Actions > Edit Secret.
  4. Update encryption-key-pw with the new base64 encoded key value.
    Tip: You can also update the key value by using the command line. Run oc edit secrets openpages-<instance name>-platform-secret. In the yaml file, update encryption-key-pw with the new base64 encoded key value.

Restarting the application servers

Restart the application server pods and scale up to the number of replicas you want to use.

Procedure

  1. Scale down to 0 replicas. 
    oc scale --replicas=0 sts/openpages-<instance_name>-sts

    To find the name of the StatefulSet (sts), run oc get sts and look for a name that starts with openpages-. For example, openpages-instance_name-sts

  2. Wait until all application server pods are deleted.
  3. Scale up to the number of replicas you want to use for the application server by running the following command: 
    oc scale --replicas=<#_of_replicas> sts/openpages-<instance_name>-sts

    Replace the following values:

    Variable Replace with
    <#_of_replicas> Specify the number of replicas.

    Can be 1 or more.
    <StatefulSet_name> Specify the name of the StatefulSet for the application.

    To find the name of the StatefulSet, run oc get sts and look for a name that starts with openpages-.

    For example, openpages-opinst-sts

Encrypting data with the new key

You are now ready to encrypt the data with the new encryption key.

Before you begin

To do this task, the application pods must be in a Running state and their readiness status must be Ready.

About this task

Use the following OpenPages GRC REST API endpoint to encrypt the data: 
https://<op_app_server>:<op_port>/grc/api/configuration/encryptWithExternalKey
To call the API, send an https PUT request to this path by using an HTTPS client. You can use a curl command, for example:
curl -k --location --request PUT --header 'Content-Type: application/json' --header 'Accept: application/json' -u <super user>:<password> --cookie-jar cookie-jar.txt --cookie cookie-jar.txt 'https://<op_app_server>:<op_port>/grc/api/configuration/encryptWithExternalKey'

The API response includes the process ID of the encryption long running process, for example {"processId":"2928"}

Note the following details about the curl command:
  • The -u parameter requires an OpenPages username and password. This user must be an OpenPages super administrator, such as OpenPagesAdministrator.
  • The -k parameter allows connections to SSL sites without trusted certificates. This parameter is not needed if you replaced the default certificates with your own certificate authority (CA)-signed certificates.
You can check the status of the encryption process by using the following API:
https://<op_app_server>:<op_port>/grc/api/processes/<process_Id>

You can call the API by using your browser or by using an HTTPS client to send a GET request.

For example:
curl -k --location -u <op_super_user>:<op_super_user_password> --header 'Content-Type: application/json' --header 'Accept: application/json' --cookie-jar cookie-jar.txt --cookie cookie-jar.txt --request GET 'https://<op_app_server>:<op_port>/ grc/api/processes/<process_Id>'

In the response, the status attribute indicates whether the process is finished or still in progress. You can repeat the check as needed. The process is complete when the status value is STATUS_FINISHED_SUCCESS.

The encryption process can take time, depending on the data volume, especially if you have many file attachment records.

To check the logs for a process, you can send a GET request to the following endpoint:
https://<op_app_server>:<op_port>/grc/api/processes/<process_Id>/logs

Restarting the application servers again

Restart the application server pods again.

Procedure

  1. Scale down to 0 replicas. 
    oc scale --replicas=0 sts/openpages-<instance_name>-sts

    To find the name of the StatefulSet (sts), run oc get sts and look for a name that starts with openpages-. For example, openpages-instance_name-sts

  2. Wait until all application server pods are deleted.
  3. Scale up to the number of replicas you want to use for the application server by running the following command: 
    oc scale --replicas=<#_of_replicas> sts/openpages-<instance_name>-sts

    Replace the following values:

    Variable Replace with
    <#_of_replicas> Specify the number of replicas.

    Can be 1 or more.
    <StatefulSet_name> Specify the name of the StatefulSet for the application.

    To find the name of the StatefulSet, run oc get sts and look for a name that starts with openpages-.

    For example, openpages-opinst-sts