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
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.
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, 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.
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:
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:
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.
Replace the default keys with new ones. In this example, all of the default keys are
replaced with keys:
When you first install Apigee hybrid, default encryption keys are used. If you were to
remove the encryption keys, you would
effectively disable encryption and subsequent values would be stored unencrypted.
If at a later
time you enable encryption by providing keys,
any existing unencrypted 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
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 below:
The following example command generates a suitable, randomly generated, 32 character,
Base64-encoded string:
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-08-26 UTC."],[[["\u003cp\u003eApigee hybrid encrypts Key Management System (KMS), Key-Value Map (KVM), and cache data by default, using AES-128 encryption, without requiring special configuration.\u003c/p\u003e\n"],["\u003cp\u003eKMS data encryption keys operate at the organization level, while KVM encryption keys can be scoped to either the organization or a specific environment, and cache keys are scoped only to the environment level.\u003c/p\u003e\n"],["\u003cp\u003eApigee hybrid provides default Base64-encoded keys stored as Kubernetes Secrets, which are used to encrypt data, but these keys are under your control and never exposed to the hybrid management plane.\u003c/p\u003e\n"],["\u003cp\u003eWhile the default encryption keys are sufficient for most cases, you can replace them during initial Apigee hybrid installation by generating new Base64-encoded keys that are 16, 24, or 32 bytes long.\u003c/p\u003e\n"],["\u003cp\u003eChanging encryption keys after the runtime is created will prevent the decryption of previously encrypted data, and only newly added data after the key change will be encrypted.\u003c/p\u003e\n"]]],[],null,["# Data encryption\n\n| You are currently viewing version 1.9 of the Apigee hybrid documentation. **This version is end of life.** You should upgrade to a newer version. For more information, see [Supported versions](/apigee/docs/hybrid/supported-platforms#supported-versions).\n\n\nBy default, the following data is stored *encrypted* in the hybrid\nruntime plane:\n\n- Key management system (KMS) data\n- Key-value map (KVM) data\n- Cache data\n\n\nData encryption does not require any special configuration on your part. However, if\nfor some reason you want to use your own encryption keys (replacing the default ones) you can\ndo so, as explained in this topic.\n\nEncryption key scope\n--------------------\n\n\nEncryption keys for KMS, KVM, and cache have scope. For example, KMS keys have *organization*\nscope. This means that the key is used to encrypt KMS data for the entire organization.\nThe following table lists the scope for\neach type of key:\n\nAbout the default encryption keys\n---------------------------------\n\n\nBy default, Apigee hybrid provides a set of Base64-encoded keys that are used to\nencrypt KVM, KMS, and cache data. The Apigee hybrid installer stores the keys in the\nruntime plane as\n[Kubernetes\nSecrets](https://kubernetes.io/docs/concepts/configuration/secret/), and uses them to encrypt your data with AES-128 standard encryption.\nThe keys are under your control;\nthe hybrid management plane is never aware of them at any time.\n| 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.\n\nChanging the default encryption keys\n------------------------------------\n\n\nAlthough not required, you can change any of the default encryption keys if you wish.\nTo replace one or more default keys, follow these steps:\n| 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.\n\n1. 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: \n\n ```actionscript-3\n defaults:\n org:\n kmsEncryptionKey: base64-encoded-key\n kvmEncryptionKey: base64-encoded-key\n env:\n kvmEncryptionKey: base64-encoded-key\n cacheEncryptionKey: base64-encoded-key\n ```\n2. 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\n key](#how-to-create-an-encoded-key).\n3. Replace the default keys with new ones. In this example, all of the default keys are replaced with keys: \n\n ```actionscript-3\n defaults:\n org:\n kmsEncryptionKey: \"JVpTb1FwI0otUHo2RUdRN3pnVyQqVGlMSEFAJXYmb1c=\"\n kvmEncryptionKey: \"T3VkRGM1U3cpOFgtNk9fMnNZU2NaSVA3I1BtZWxkaUU=\"\n env:\n kvmEncryptionKey: \"Q3h6M3R6OWdBeipxTURfKjQwQVdtTng2dU5mODFHcyE=\"\n cacheEncryptionKey: \"b2NTVXdKKjBzN0NORF9XSm9tWFlYKGJ6NUhpNystJVI=\"\n ```\n4. Apply the overrides file to your cluster as follows:\n - If you change KVM or Cache keys, update only the environment: \n\n ```\n $APIGEECTL_HOME/apigeectl apply -f overrides/overrides.yaml --env env_name\n ```\n - If you change KMS keys, update both the org and environment: \n\n ```\n $APIGEECTL_HOME/apigeectl apply -f overrides/overrides.yaml --env env_name --org org_name\n ```\n5. Restart the `apigee-runtime` and `apigee-mart` pods.\n\nA note about backward compatibility\n-----------------------------------\n\n\nWhen you first install Apigee hybrid, default encryption keys are used. If you were to\nremove the encryption keys, you would\neffectively disable encryption and subsequent values would be stored unencrypted.\nIf at a later\ntime you enable encryption by providing keys,\nany existing unencrypted data remains unencrypted; however, any future data that is added will\nbe encrypted. The system\nwill continue working normally with the unencrypted data and the new encrypted\ndata.\n\n\nAlso, note that\nyou cannot later change the encryption keys\nonce the runtime data is encrypted.\n\nHow to create an encoded key\n----------------------------\n\n\nA properly formatted Base-64-encoded key is required for KVM, KMS, and cache encryption.\nThe key used for any of these purposes must be Base-64 encoded from a string that is 16, 24, or\n32 bytes long, as explained below:\n| **Note:** If you are on Apigee hybrid version 1.9.0, then the generated key must include only printable characters. For example: \n|\n| ```\n| tr -dc 'A-Za-z0-9' \u003c /dev/urandom | head -c 32 | openssl base64\n| RjdJNmFGR2lFR0U5TmhvOWxFcTNYOGJsbm0wb3AzNXk=\n| ```\n| With version 1.9.1 and later, both printable and non-printable characters are allowed.\n| The key string length requirement exists because the [Advanced\n| 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).\n\n\nThe following example command generates a suitable, randomly generated, 32 character,\nBase64-encoded string: \n\n```\nhead -c 32 /dev/random | openssl base64\n```"]]