Changing the data encryption key for OpenPages

You can change the encryption key that is used to encrypt data in OpenPages.

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 instance administrator.

About this task

Backing up the current encryption key

Back up your current encryption key.

Procedure

  1. Log in to your Red Hat OpenShift cluster as an instance administrator:
    ${CPDM_OC_LOGIN}
  2. 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.

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.

To authenticate to the API, you pass an access token or platform API key token in an Authorization header. For more information, see Generating an API authorization token.

About this task

Use the following OpenPages GRC REST API endpoint to decrypt the data:
https://<cloud_pak_url>/openpages-<openpages_instance_name>-opgrc/api/v2/configuration/decrypt_with_external_key

To call the API, send an https PUT request to the path by using an HTTPS client with an access token or platform API key token in an Authorization header.

  • The following curl command shows an example of an https PUT request to the path using an access token to authenticate:
    curl -k --location --request PUT --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'Authorization: Bearer <token>' 'https://<cloud_pak_url>/openpages-<openpages_instance_name>-opgrc/api/v2/configuration/decrypt_with_external_key' 
  • The following curl command shows an example of an https PUT request using a platform API key token to authenticate:
    curl -k --location --request PUT --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'Authorization: ZenApiKey <token>' 'https://<cloud_pak_url>/openpages-<openpages_instance_name>-opgrc/api/v2/configuration/decrypt_with_external_key' 

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

In the curl commands, replace <cloud_pak_url> with the URL of Cloud Pak for Data. Replace <openpages_instance_name> with the name of the OpenPages instance. 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://<cloud_pak_url>/openpages-<openpages_instance_name>-opgrc/api/v2/processes/<process_Id>

You can call the API by using your browser or by using an HTTPS client to send a GET request with an access token or platform API key token in an Authorization header.

  • The following curl command shows an example of an https GET request to the path using an access token to authenticate:
    curl -k --location --request GET --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'Authorization: Bearer <token>' 'https://<cloud_pak_url>/openpages-<openpages_instance_name>-opgrc/api/v2/processes/<process_Id>' 
  • The following curl command shows an example of an https GET request using a platform API key token to authenticate:
    curl -k --location --request GET --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'Authorization: ZenApiKey <token>' 'https://<cloud_pak_url>/openpages-<openpages_instance_name>-opgrc/api/v2/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://<cloud_pak_url>/openpages-<openpages_instance_name>-opgrc/api/v2/processes/<process_Id>/logs

Generating a new secret key

Generate a new encryption key.

About this task

OpenPages uses 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 an instance administrator:
      ${CPDM_OC_LOGIN}
    2. 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.

To authenticate to the API, you pass an access token or platform API key token in an Authorization header.

About this task

Use the following OpenPages GRC REST API endpoint to encrypt the data:
https://<cloud_pak_url>/openpages-<openpages_instance_name>-opgrc/api/v2/configuration/encrypt_with_external_key

To call the API, send an https PUT request to the path by using an HTTPS client with an access token or platform API key token in an Authorization header.

  • The following curl command shows an example of an https PUT request to the path using an access token to authenticate:
    curl -k --location --request PUT --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'Authorization: Bearer <token>' 'https://<cloud_pak_url>/openpages-<openpages_instance_name>-opgrc/api/v2/configuration/encrypt_with_external_key' 
  • The following curl command shows an example of an https PUT request using a platform API key token to authenticate:
    curl -k --location --request PUT --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'Authorization: ZenApiKey <token>' 'https://<cloud_pak_url>/openpages-<openpages_instance_name>-opgrc/api/v2/configuration/encrypt_with_external_key' 

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

In the curl commands, replace <cloud_pak_url> with the URL of Cloud Pak for Data. Replace <openpages_instance_name> with the name of the OpenPages instance. 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://<cloud_pak_url>/openpages-<openpages_instance_name>-opgrc/api/v2/processes/<process_Id>

You can call the API by using your browser or by using an HTTPS client to send a GET request with an access token or platform API key token in an Authorization header.

  • The following curl command shows an example of an https GET request to the path using an access token to authenticate:
    curl -k --location --request GET --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'Authorization: Bearer <token>' 'https://<cloud_pak_url>/openpages-<openpages_instance_name>-opgrc/api/v2/processes/<process_Id>' 
  • The following curl command shows an example of an https GET request using a platform API key token to authenticate:
    curl -k --location --request GET --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'Authorization: ZenApiKey <token>' 'https://<cloud_pak_url>/openpages-<openpages_instance_name>-opgrc/api/v2/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://<cloud_pak_url>/openpages-<openpages_instance_name>-opgrc/api/v2/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