Configuring custom encryption for access tokens

If you have projects that are integrated with Git, you can optionally use custom encryption keys to encrypt the Git access tokens that are associated with the projects. Using custom encryption allows you to manage the encryption process and control how your tokens are securely stored.

About this task

You can add additional key values to update encryption regularly. Whenever you add a key value, that value is placed at the top of a list of values and is used to encrypt new tokens. Older key values can stay in the list and are used for decrypting tokens that have already been encrypted.

Before you begin

To provide custom encryption keys, you must:

  1. Be logged in as admin. This feature is not available if you disabled the default admin user.
  2. Have vaults enabled in the Cloud Pak for Data web client.

Procedure

To configure custom encryption keys, complete the following steps.

  1. Open the Secrets page and add a secret:
    1. From the navigation menu, select Administration > Configurations.
    2. On the Secrets and vaults tab, select the Secrets page.
    3. Click Add secret.
  2. Specify the display name for the secret, a vault, and the secret type:
    1. Enter ccs-encryption-keychain as the name. This secret must be unique across all vaults.
    2. Select the vault. You can select either internal vaults or external vaults such as CyberArk or HashiCorp.
    3. Select Custom for Secret type. In the Name field, type keychain.

  3. Specify the encryption key name and value. In the Value field, add your encryption key using the following format: [{“keyname”:“encryption_value”}]. Keyname is an identifier for the key, and encryption_value is the encryption key. Replace keyname and encryption_value with the correct values.

    The Value field is an ordered list. You can update the values regularly by adding additional keys to the list. The first key will be used for encrypting new tokens and subsequent keys in the list are only used for decrypting previously encrypted tokens. If a token was encrypted with a key that is removed from the list, it can no longer be decrypted.

    For example, if you plan to manually update the encryption every month, your list of encryption keys would look similar to the following:

    [{"march_2022_key":"H9$Qj#8l14T4"},{"february_2022_key":"L%db2g7e^T6p"}]

    On April 1st, you would like to add a new key. The value would become:

    [{"april_2022_key":"EvVUt35X&%94"},{"march_2022_key":"H9$Qj#8l14T4"},{"february_2022_key":"L%db2g7e^T6p"}]

    After that value is saved, EvVUt35X&%94 will be the key used to encrypt any new values.

Important: If you change the ccs-encryption-keychain secret and want the process to take effect immediately, the pods asset-files-api and portal-common-api need to be restarted. Otherwise, it will take up to 30 minutes for the process to take effect since the secret is cached. If you delete the ccs-encryption-keychain secret, Cloud Pak for Data can no longer retrieve your tokens and they will have to be deleted.

Parent topic: Creating a project