> [!CAUTION]
> You are currently viewing version 1.4 of the Apigee hybrid documentation. **This version is end of life.** You should upgrade to a newer version. For more information, see [Supported versions](https://docs.cloud.google.com/apigee/docs/hybrid/supported-platforms.md.txt#supported-versions).

<button class="button button-with-icon cloud-select-dropdown__button button-primary" aria-haspopup="true">Version 1.4 (unsupported)</button>

- Supported versions:
- [v1.17 (latest)](https://docs.cloud.google.com/apigee/docs/hybrid/v1.17/key-encryption.md.txt)
- [v1.16](https://docs.cloud.google.com/apigee/docs/hybrid/v1.16/key-encryption.md.txt)
- [v1.15](https://docs.cloud.google.com/apigee/docs/hybrid/v1.15/key-encryption.md.txt)
- [v1.14](https://docs.cloud.google.com/apigee/docs/hybrid/v1.14/key-encryption.md.txt)
- [List of supported versions](https://docs.cloud.google.com/apigee/docs/hybrid/supported-platforms.md.txt#supported-versions)
- Unsupported versions:
- [v1.13](https://docs.cloud.google.com/apigee/docs/hybrid/v1.13/key-encryption.md.txt)
- [v1.12](https://docs.cloud.google.com/apigee/docs/hybrid/v1.12/key-encryption.md.txt)
- [v1.11](https://docs.cloud.google.com/apigee/docs/hybrid/v1.11/key-encryption.md.txt)
- [v1.10](https://docs.cloud.google.com/apigee/docs/hybrid/v1.10/key-encryption.md.txt)
- [v1.9](https://docs.cloud.google.com/apigee/docs/hybrid/v1.9/key-encryption.md.txt)
- [v1.8](https://docs.cloud.google.com/apigee/docs/hybrid/v1.8/key-encryption.md.txt)
- [v1.7](https://docs.cloud.google.com/apigee/docs/hybrid/v1.7/key-encryption.md.txt)
- [v1.6](https://docs.cloud.google.com/apigee/docs/hybrid/v1.6/key-encryption.md.txt)
- [v1.5](https://docs.cloud.google.com/apigee/docs/hybrid/v1.5/key-encryption.md.txt)
- [v1.4](https://docs.cloud.google.com/apigee/docs/hybrid/v1.4/key-encryption.md.txt)
- [v1.3](https://docs.cloud.google.com/apigee/docs/hybrid/v1.3/key-encryption.md.txt)
- [v1.2](https://docs.cloud.google.com/apigee/docs/hybrid/v1.2/key-encryption.md.txt)
- [v1.1](https://docs.cloud.google.com/apigee/docs/hybrid/v1.1/key-encryption.md.txt)


By default, the following data is stored *encrypted* in the hybrid
runtime plane:

- Key management system (KMS) data
- Key-value map (KVM) data
- Cache data


Data encryption does not require any special configuration on your part. However, if
for some reason you want to use your own encryption keys (replacing the default ones) you can
do so, as explained in this topic.

## Encryption key scope


Encryption keys for KMS, KVM, and cache have scope. For example, KMS keys have *organization*
scope. This means that the key is used to encrypt KMS data for the entire organization.
The following table lists the scope for
each type of key:

| Encryption key | Scope |
|---|---|
| KMS | Organization only |
| KVM | Organization or environment If a [KVM policy](https://docs.cloud.google.com/apigee/docs/api-platform/reference/policies/key-value-map-operations-policy.md.txt#ScopeElement) specifies `apiproxy` or `policy` (API proxy revision) scope, the organization level key is used to encrypt the data. For a general overview of how KVMs are used in Apigee Edge, see [Working with key-value maps](https://docs.cloud.google.com/apigee/docs/api-platform/cache/key-value-maps.md.txt). |
| Cache | Environment only |

## About the default encryption keys


By default, Apigee hybrid provides a set of Base64-encoded keys that are used to
encrypt KVM, KMS, and cache data. The Apigee hybrid installer stores the keys in the
runtime plane as
[Kubernetes
Secrets](https://kubernetes.io/docs/concepts/configuration/secret/), and uses them to encrypt your data with AES-128 standard encryption.
The keys are under your control;
the hybrid management plane is never aware of them at any time.

> [!WARNING]
> The default keys will work for most use cases. If you want to change the default encryption keys, do so when you initially install Apigee hybrid into a new cluster. If you change the encryption keys after the runtime is created in your cluster, previously encrypted data can no longer work (it cannot be decrypted); only new data added after the change will be encrypted and function as expected.

## Changing the default encryption keys


Although not required, you can change any of the default encryption keys if you wish.
To replace one or more default keys, follow these steps:

> [!WARNING]
> If you change the encryption keys after the runtime is created in your cluster, previously encrypted data can no longer work (it cannot be decrypted); only new data added after the change will be encrypted and function as expected.

1. Copy the following stanzas into your overrides file. This configuration lets you change the KMS and KVM encryption keys for the organization level and the KVM and cache encryption keys for the environment level:

   ```
   defaults:
     org:
       kmsEncryptionKey: base64-encoded-key
       kvmEncryptionKey: base64-encoded-key
     env:
       kvmEncryptionKey: base64-encoded-key
       cacheEncryptionKey: base64-encoded-key
   ```
2. Generate a new key for each key you wish to replace. Each key must be a Base64-encoded string that is exactly **16, 24, or 32 bytes long** . See also [How to create an encoded
   key](https://docs.cloud.google.com/apigee/docs/hybrid/v1.4/key-encryption#how-to-create-an-encoded-key).
3. Replace the default keys with new ones. In this example, all of the default keys are replaced with keys:

   ```
   defaults:
     org:
       kmsEncryptionKey: "JVpTb1FwI0otUHo2RUdRN3pnVyQqVGlMSEFAJXYmb1c="
       kvmEncryptionKey: "T3VkRGM1U3cpOFgtNk9fMnNZU2NaSVA3I1BtZWxkaUU="
     env:
       kvmEncryptionKey: "Q3h6M3R6OWdBeipxTURfKjQwQVdtTng2dU5mODFHcyE="
       cacheEncryptionKey: "b2NTVXdKKjBzN0NORF9XSm9tWFlYKGJ6NUhpNystJVI="
   ```
4. Apply the overrides file to your cluster as follows:
   - If you change KVM or Cache keys, update only the environment:

     ```
     $APIGEECTL_HOME/apigeectl apply -f overrides/overrides.yaml --env env_name
     ```
   - If you change KMS keys, update both the org and environment:

     ```
     $APIGEECTL_HOME/apigeectl apply -f overrides/overrides.yaml --env env_name --org org_name
     ```

## A note about backward compatibility


If you were to remove the encryption keys in your overrides file the first
time you install Apigee hybrid, you would
effectively disable encryption and values would be stored unencrypted.
If at a later
time you enable encryption by providing keys,
exiting data remains unencrypted; however, any future data that is added will
be encrypted. The system
will continue working normally with the unencrypted data and the new encrypted
data.


Also, note that
you cannot later change the encryption keys
once the runtime data is encrypted.

## How to create an encoded key

> [!NOTE]
> NOTE: You must generate your key from ASCII characters. Apigee hybrid does not support using non-printable characters, such as characters generated using the openssl random command.


A properly formatted Base-64-encoded key is required for KVM, KMS, and cache encryption.
The key used for any of these purposes must be Base-64 encoded from a string that is 16, 24, or
32 bytes long, as explained in the following steps:

> [!NOTE]
> The key string length requirement exists because the [Advanced
> Encryption Standard](https://en.wikipedia.org/wiki/Advanced_Encryption_Standard) (AES) cipher works on a block size of 128 bits, but can take three different key lengths: 128, 192, and 256 bits (16, 24, or 32 bytes).


The following example commands generate suitable, randomly generated, 32 character,
Base64-encoded strings that do not include non-printable characters:

```
LC_ALL=C tr -dc A-Za-z0-9_\!\@\#\$\%\^\&\*\(\)\\-+= < /dev/urandom | head -c 32  | openssl base64
PSFvX0BPc1Z2NVklcXdxcF8xR0N4MV4temFveStITU4=
```


or

```
LC_ALL=C tr -dc "[:print:]" < /dev/urandom | head -c 32 | openssl base64
```