Enabling secret key encryption

This document explains how to enable the encryption of developer app consumer secrets (client credentials) stored in the Cassandra database.

Overview

Traditionally, Apigee Edge for Private Cloud has provided optional encryption for key value map (KVM) data and OAuth access tokens.

The following table describes the encryption options for data at rest in Apigee for Private Cloud:

To enable encryption of client credentials, you need to perform the following tasks on all message processor and management server nodes:

• Create a keystore to store a Key encryption key (KEK). Apigee uses this encrypted key to encrypt the secret keys needed to encrypt your data.
• Edit configuration properties on all management server and message processor nodes.
• Create a developer app to trigger key creation.
• Restart the nodes.

These tasks are explained in this document.

What you need to know about the key encryption feature

The steps in this document explain how to enable the KEK feature, which allows Apigee to encrypt the secret keys used to encrypt developer app consumer secrets when they are stored at rest in the Cassandra database.

By default, any existing values in the database will remain unchanged (in plain text) and will continue to work as before.

If you perform any write operation on an unencrypted entity, it will be encrypted when the operation is saved. For example, if you revoke an unencrypted token and then later approve it, the newly approved token will be encrypted.

Keeping keys safe

Be sure to store a copy of the keystore in which the KEK is stored in a safe location. We recommend using your own secure mechanism to save a copy of the keystore. As the instructions in this document explain, a keystore must be placed on each message processor and management server node where the local configuration file can reference it. But it is also important to store a copy of the keystore somewhere else for safekeeping and as a backup.

Enabling key encryption

Follow these steps to consumer secret key encryption:

Prerequisites

You must meet these requirements before performing the steps in this document:

• You must install or upgrade to Apigee Edge for Private Cloud 4.50.00.10 or later.
• You must be an Apigee Edge for Private Cloud administrator.

Step 1: Generate a keystore

Follow these steps to create a keystore to hold the key encryption key (KEK):

1. Execute the following command to generate a keystore to store a key that will be used to encrypt the KEK. Enter the command exactly as shown. (You can provide any keystore name you wish):
   

   keytool -genseckey -alias KEYSTORE_NAME -keyalg AES -keysize 256 \
   -keystore kekstore.p12 -storetype PKCS12

   When prompted, enter a password. You will use this password in later sections when you configure the management server and message processor.

   This command generates a kekstore.p12 keystore file containing a key with alias KEYSTORE_NAME.

2. (Optional) Verify the file was generated correctly with the following command. If the file is correct, the command returns a key with the alias KEYSTORE_NAME:

   keytool -list -keystore kekstore.p12

Step 2: Configure the management server

Next, configure the management server. If you have management servers installed on multiple nodes, you must repeat these steps on each node.

1. Copy the keystore file you generated in Step 1 to a directory on the management server node, such as /opt/apigee/customer/application. For example:

   cp certs/kekstore.p12 /opt/apigee/customer/application

2. Ensure the file is readable by the apigee user:

   chown apigee:apigee /opt/apigee/customer/application/kekstore.p12

   chmod 400 /opt/apigee/customer/application/kekstore.p12

3. Add the following properties to /opt/apigee/customer/application/management-server.properties. If the file does not exist, create it. See also Property file reference.
   

   conf_keymanagement_kmscred.encryption.enabled=true
   
   # Fallback is true to ensure your existing plaintext credentials continue to work
   conf_keymanagement_kmscred.encryption.allowFallback=true
   
   conf_keymanagement_kmscred.encryption.keystore.path=PATH_TO_KEYSTORE_FILE
   conf_keymanagement_kmscred.encryption.kek.alias=KEYSTORE_NAME
   
   # These could alternately be set as environment variables. These variables should be
   # accessible to Apigee user during bootup of the Java process. If environment
   # variables are specified, you can skip the password configs below.
   # KMSCRED_ENCRYPTION_KEYSTORE_PASS=
   # KMSCRED_ENCRYPTION_KEK_PASS=
   See also Using environment variables for configuration properties.
   
   conf_keymanagement_kmscred.encryption.keystore.pass=KEYSTORE_PASSWORD
   conf_keymanagement_kmscred.encryption.kek.pass=KEK_PASSWORD

   Note that the KEK_PASSWORD may be the same as the KEYSTORE_PASSWORD depending on the tool used to generate the keystore.

4. Restart the management server by using the following commands:

   /opt/apigee/apigee-service/bin/apigee-service edge-management-server restart

   /opt/apigee/apigee-service/bin/apigee-service edge-management-server wait_for_ready

   The wait_for_ready command returns the following message when the management server is ready:

   Checking if management-server is up: management-server is up.

5. If you have management servers installed on multiple nodes, repeat steps 1-4 above on each management server node.

Step 3: Create a developer app

Now that the management servers are updated, you must create a developer app to trigger generation of the key used to encrypt the client credentials data:

1. Create a Developer app to trigger the creation of a data encryption key (KEK). For steps, see Registering an app.
2. Delete the developer app if you wish. You do not need to keep it around once the encryption key is generated.

Step 4: Configure message processors

Until encryption is enabled in the message processors, runtime requests will not be able to process any encrypted credentials.

1. Copy the keystore file you generated in Step 1 to a directory on the message processor node, such as /opt/apigee/customer/application. For example:

   cp certs/kekstore.p12 /opt/apigee/customer/application

2. Ensure the file is readable by the apigee user:

   chown apigee:apigee /opt/apigee/customer/application/kekstore.p12

3. Add the following properties to /opt/apigee/customer/application/message-processor.properties. If the file does not exist, create it. See also Property file reference.

   conf_keymanagement_kmscred.encryption.enabled=true
   
   # Fallback is true to ensure your existing plaintext credentials continue to work
   conf_keymanagement_kmscred.encryption.allowFallback=true
   
   conf_keymanagement_kmscred.encryption.keystore.path=PATH_TO_KEYSTORE_FILE
   conf_keymanagement_kmscred.encryption.kek.alias=KEYSTORE_NAME
   
   # These could alternately be set as environment variables. These variables should be
   # accessible to Apigee user during bootup of the Java process. If environment
   # variables are specified, you can skip the password configs below.
   # KMSCRED_ENCRYPTION_KEYSTORE_PASS=
   # KMSCRED_ENCRYPTION_KEK_PASS=
   See also Using environment variables for configuration properties.
   
   
   conf_keymanagement_kmscred.encryption.keystore.pass=KEYSTORE_PASSWORD
   conf_keymanagement_kmscred.encryption.kek.pass=KEK_PASSWORD

   Note that the KEK_PASSWORD may be the same as the KEYSTORE_PASSWORD depending on the tool used to generate the keystore.

4. Restart the message processor by using the following commands:

   /opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart

   /opt/apigee/apigee-service/bin/apigee-service edge-message-processor wait_for_ready

   The wait_for_ready command returns the following message when the message processor is ready to process messages:

   Checking if message-processor is up: message-processor is up.

5. If you have message processors installed on multiple nodes, repeat steps 1-4 on each message processor node.

Summary

Any developer apps that you create from now on will have their credential secret encrypted at rest in the Cassandra database.

Using environment variables for configuration properties

You can alternatively set the following message processor and management server configuration properties using environment variables. If set, the environment variables override the properties set in the message processor or management server configuration file.

conf_keymanagement_kmscred.encryption.keystore.pass=
conf_keymanagement_kmscred.encryption.kek.pass=

The corresponding environment variables are:

export KMSCRED_ENCRYPTION_KEYSTORE_PASS=KEYSTORE_PASSWORD

export KMSCRED_ENCRYPTION_KEK_PASS=KEK_PASSWORD

If you set these environment variables, you can omit these configuration properties from the configuration files on the message processor and management server nodes, as they will be ignored:

conf_keymanagement_kmscred.encryption.keystore.pass
conf_keymanagement_kmscred.encryption.kek.pass

Property file reference

This section describes the configuration properties that you must set on all message processor and management server nodes, as explained previously in this document.