Data encryption

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

  • Cache data
  • Contract key data
  • Key management system (KMS) data
  • Key-value map (KVM) 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.

Apigee hybrid encryption keys 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
Contract Organization only
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 contract, 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.

The default keys are applied to all new Apigee hybrid components when you create them.

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:

  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
        contractEncryptionKey: 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.
  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="
        contractEncryptionKey: "RDEyMzQ1Njc4OTAxMjM0NQ=="
      env:
        kvmEncryptionKey: "Q3h6M3R6OWdBeipxTURfKjQwQVdtTng2dU5mODFHcyE="
        cacheEncryptionKey: "b2NTVXdKKjBzN0NORF9XSm9tWFlYKGJ6NUhpNystJVI="

Override the default keys

You can override the keys for the org or specific envs named in your overrides file. When you create the components, keys you specify for the org or individual envs will be override the defaults.

  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:
    org:YOUR_ORG_NAME
    
    kmsEncryptionKey: base64-encoded-key
    kvmEncryptionKey: base64-encoded-key
    contractEncryptionKey: base64-encoded-key
    
    envs
      - name: ENV_NAME
        kvmEncryptionKey: base64-encoded-key
        kmsEncryptionKey: base64-encoded-key
        cacheEncryptionKey: base64-encoded-key
    
      - name: 2ND_ENV_NAME
        kvmEncryptionKey: base64-encoded-key
        kmsEncryptionKey: base64-encoded-key
        cacheEncryptionKey: base64-encoded-key
  2. Generate a new key for each key you wish to override. 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.
  3. Specify the keys you want to override. In this example, all of the default keys are replaced with keys:
    org:hybrid-org
    
    kmsEncryptionKey: "QTEyMz1b2jc4OTAxMjM0NQ=="
    kvmEncryptionKey: "QzEyM2c3Njc4OTAxMjM0NQ=="
    contractEncryptionKey: "RDEyMzQ1Njc4OTAxMjM0NQ=="
    
    envs:
      - name: prod
        kvmEncryptionKey: "QzEyM2c3Njc4OTAxMjM0NQ=="
        kmsEncryptionKey: "QTEyMz1b2jc4OTAxMjM0NQ=="
        cacheEncryptionKey: "QjEyAvC1Njc4OTAxMjM0NQ=="
    
    envs:
      - name: test
        kvmEncryptionKey: "A1b2C3d4E5f6G7h8I9j10K=="
        kmsEncryptionKey: "QTEyMz1b2jc4OTAxMjM0NQ=="
        cacheEncryptionKey: "B1c2D3e4F5f6H7i8J9k10L=="

Apply the key changes

Apply the overrides file to your cluster as with the following Helm commands:
  • If you change the contract key or the KVM key for the org, update the org:
    helm upgrade ORG_NAME apigee-org/ \
      --namespace apigee \
      --atomic \
      -f OVERRIDES_FILE.yaml
    
  • If you change Cache key or the KVM key for an environment, update the environment:
    helm upgrade ENV_NAME apigee-env/ \
      --namespace apigee \
      --atomic \
      --set env=ENV_NAME \
      -f OVERRIDES_FILE.yaml
    
  • If you change KMS key, update both the org and environment:
    helm upgrade ORG_NAME apigee-org/ \
      --namespace apigee \
      --atomic \
      -f OVERRIDES_FILE.yaml
    
    helm upgrade ENV_NAME apigee-env/ \
      --namespace apigee \
      --set env=ENV_NAME \
      --atomic \
      -f OVERRIDES_FILE.yaml
    

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

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:

head -c 32 /dev/random | openssl base64