> [!CAUTION]
> **Caution:** This documentation covers Edge for Private Cloud 4.50.00, which is no longer supported. Google does not provide security patches, bug fixes, or technical support for this version. The current supported version is 4.54.00. See the [Edge for Private Cloud documentation](https://docs.apigee.com/private-cloud/latest/overview) for the current version, or [All versions](https://docs.apigee.com/private-cloud/versions) to compare releases.

This document explains how to enable the encryption of
[developer app](https://docs.apigee.com/api-platform/publish/creating-apps-surface-your-api) consumer secrets (client credentials) stored
in the Cassandra database.

> [!NOTE]
> **Note:**We recommend that you implement the steps described in this document in a test environment and do suitable testing before deploying the changes to a production environment.

## 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:

|---|---|---|---|
| **Entity** | **Encryption enabled by default** | **Encryption optionally available** | **Related documentation** |
| KVMs | No | Yes | See [About encrypted KVMs](https://docs.apigee.com/api-platform/cache/key-value-maps#aboutencrypted). |
| OAuth access tokens | No | Yes | See [Hashing tokens for extra security](https://docs.apigee.com/api-platform/security/oauth/hashing-tokens). |
| Developer app consumer secrets | No | Yes | To enable, perform the configuration steps in this document. |


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](https://en.wikipedia.org/wiki/Glossary_of_cryptographic_keys) (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.

> [!NOTE]
> **Note:** Apigee provides a "fallback" option that is disabled by default. This means that, by default, unencrypted consumer secrets will fail. If the `allowFallback` flag is set to `true`, as explained in the steps that follow, then unencrypted entities will succeed. For example, if `allowFallback` is `false`, unencrypted developer app consumer secrets will no longer work, causing API key verification to fail.


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):

> [!CAUTION]
> **Important** : It is your responsibility to keep the keystore safe. See [Keeping keys safe](https://docs.apigee.com/private-cloud/v4.50.00/key-encryption#keeping-keys-safe).

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 <var translate="no">KEYSTORE_NAME</var>.
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 <var translate="no">KEYSTORE_NAME</var>:

   ```
   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](https://docs.apigee.com/private-cloud/v4.50.00/key-encryption#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](https://docs.apigee.com/api-platform/publish/creating-apps-surface-your-api#register).
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](https://docs.apigee.com/private-cloud/v4.50.00/key-encryption#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.

|---|---|---|
| Property | Default | Description |
| `conf_keymanagement_kmscred.encryption.enabled` | `false` | Must be `true` to enable key encryption. |
| `conf_keymanagement_kmscred.encryption.allowFallback` | `false` | Set allowFallback to `true` to ensure your existing plaintext credentials continue to work. |
| `conf_keymanagement_kmscred.encryption.keystore.path` | N/A | Provide the path to the KEK keystore on the message processor or management server node. See [Step 2: Configure the management server](https://docs.apigee.com/private-cloud/v4.50.00/key-encryption#step-2-configure-the-management-server) and [Step 3: Configure message processors](https://docs.apigee.com/private-cloud/v4.50.00/key-encryption#step-5-configure-message-processors). |
| `conf_keymanagement_kmscred.encryption.kek.alias` | N/A | Alias against which the KEK is stored in the keystore. |
| `conf_keymanagement_kmscred.encryption.keystore.pass` | N/A | Optional if you use environment variables to set these properties. See also [Using environment variables for configuration properties](https://docs.apigee.com/private-cloud/v4.50.00/key-encryption#using-environment-variables-for-configuration-properties). |
| `conf_keymanagement_kmscred.encryption.kek.pass` | N/A | Optional if you use environment variables to set these properties. See also [Using environment variables for configuration properties](https://docs.apigee.com/private-cloud/v4.50.00/key-encryption#using-environment-variables-for-configuration-properties). |