Contract data encryption

In addition contract data that is downloaded from the management plane to the runtime plane is encrypted by default. Contract data includes proxy bundles and other data that the runtime plane needs to process API proxies. You must provide an encryption key for this data in your overrides file, as explained below.

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

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

To enable KMS, KVM, or cache encryption, you must provide Base64-encoded keys in your overrides file. hybrid 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.

This topic explains how to enable encryption for KMS, KVM, and cache data.

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
Cache Environment only

A note about backward compatibility

If you do not provide encryption keys when you initially install hybrid, data entries for KMS, KVM, and cache are not encrypted when they are stored in the runtime plane. 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.

Encrypting KMS data

You can choose to encrypt the consumer secrets stored in your organization. By default, consumer secrets are stored unencrypted. You can elect to encrypt consumer secrets by adding the kmsEncryptionKey property to your overrides file and supplying a Base64-encoded string that is 16, 24, or 32 bytes in length. Consumer secrets are the only KMS values that can be encrypted; all other KMS data is stored unencrypted.

Scope of KMS encryption keys

KMS encryption keys have organization scope. This means the keys are used to encrypt all of the consumer secrets that exist within an organization.

Enabling KMS encryption

To enable KMS encryption, you must Base64-encode a string that is 16, 24, or 32 bytes in length and add the encoded key to your overrides file, as explained below.

If you add or change the key at some point after installing hybrid, you must recreate both the runtime and mart components for the change to take effect.

  1. Create a Base64-encoded key. To learn how, see How to create an encoded key.
  2. Add the encoded key to your overrides file as shown below. Note that the kmsEncryptionKey property is an organization-scoped property. In the YAML file, it is a top-level entity and should not be indented.
    org: hybrid
    
    kmsEncryptionKey: YXo0UyRuRSg1dUVnPTU7Rwo=
    ...
    
  3. After adding the kvmEncryptionKey property, be sure to apply your change to the cluster using apigeectl apply.

KVM encryption

By default, KVM data is stored unencrypted. To encrypt it, you must add the kvmEncryptionKey property to your overrides file and supply a Base64-encoded string that is 16, 24, or 32 bytes in length. For a general overview of how KVMs are used in Apigee Edge, see Working with key-value maps.

Scope of KVM encryption keys

The key used to encrypt KVM data is stored at the scope of the KVM. For example, to encrypt all KVM data within an organization using one key, store that key at the organization level. To encrypt KVM data for environment-scoped KVMs, store the key within an environment, as explained below.

Enabling KVM encryption

To enable KVM encryption, you must Base64-encode a string that is 16, 24, or 32 bytes in length and add the encoded key to your overrides file, as explained below. For KVM, you can add the key at either the organization or environment scope.

If you add or change the key at some point after installing hybrid, you must recreate both the runtime and mart components for the change to take effect.

  • Create a Base64-encoded key. To learn how, see How to create an encoded key.
  • Add the encoded key to your overrides file as shown below. Note that the kvmEncryptionKey property can be organization or environment-scoped.

    Org-level example: In the following example, the KVM encryption key is added at the organization level. Note that the kvmEncryptionKey property is not indented:

    org: hybrid
    
    kvmEncryptionKey: YXo0UyRuRSg1dUVnPTU7Rwo=
    ...

    Env-level example: To enable environment-scoped KVM encryption, add the kvmEncryptionKey property to your overrides file to one or more environment definitions (that is, under envs). If you have multiple environments, each one should have its own key. For example:

    envs:
      - name: test
        sslCertPath: /Users/myhome/ingress.crt
        sslKeyPath: /Users/myhome/ingress.key
        hostAlias: foo-test.mydomain.net
        kvmEncryptionKey: YXo0UyRuRSg1dUVnPTU7Rwo=
      - name: prod
        sslCertPath: /Users/myhome/ingress.crt
        sslKeyPath: /Users/myhome/ingress.key
        hostAlias: foo-test.mydomain.net
        kvmEncryptionKey: ekt5U3YkQFpje0d1KVg5Iwo=

  • After adding the kvmEncryptionKey property, be sure to apply your change to the cluster using apigeectl apply.
  • Cache encryption

    Scope of cache encryption keys

    The key used to encrypt cache data is always stored at the environment scope. All proxies deployed to an environment will encrypt cache data using the same key.

    Enabling cache encryption

    To enable cache encryption, you must Base64-encode a string that is 16, 24, or 32 bytes in length and add the encoded key to your overrides file, as explained below.

    If you add or change the key at some point after installing hybrid, you must recreate both the runtime and mart components for the change to take effect.

  • Create a Base64-encoded key. To learn how, see How to create an encoded key.
  • Add the encoded key to your overrides file as shown below. Note that the cacheEncryptionKey property must be environment-scoped (placed under envs). If you have multiple environments, each one should have its own key. For example:
    envs:
      - name: test
        sslCertPath: /Users/myhome/ingress.crt
        sslKeyPath: /Users/myhome/ingress.key
        hostAlias: foo-test.mydomain.net
        cacheEncryptionKey: YXo0UyRuRSg1dUVnPTU7Rwo=
      - name: prod
        sslCertPath: /Users/myhome/ingress.crt
        sslKeyPath: /Users/myhome/ingress.key
        hostAlias: foo-test.mydomain.net
        cacheEncryptionKey: ekt5U3YkQFpje0d1KVg5Iwo=
  • After adding the cacheEncryptionKey property, be sure to apply your change to the cluster using apigeectl apply.
  • Example

    Encrypt KMS data (organization scope), and encrypt KVM and cache data in the test environment:

    org: hybrid
    
    kvmEncryptionKey: YXo0UyRuRSg1dUVnPTU7Rwo=
    
    envs:
      - name: test
        sslCertPath: /Users/myhome/ingress.crt
        sslKeyPath: /Users/myhome/ingress.key
        hostAlias: foo-test.mydomain.net
        cacheEncryptionKey: YXo0UyRuRSg1dUVnPTU7Rwo=
        kvmEncryptionKey: YXo0UyRuRSg1dUVnPTU7Rwo=
        

    How to create an encoded key

    A properly formatted Base-64-encoded key is required for KVM, KMS, and cache encryption. A key of the same format is also required to configure contract encryption, as explained in Add a contract encryption key. 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:

    1. Create a random string that is 16, 24, or 32 bytes in length. For example, the following is a randomly generated 16 byte string:
      az4S$nE(5uEg=5;G
    2. Put the string into a file. For example:
      printf '%s' 'az4S$nE(5uEg=5;G' > mystring.txt
    3. Base64-encode the string. For example:
      openssl base64 -in mystring.txt -out my-key.txt
      cat my-key.txt
        YXo0UyRuRSg1dUVnPTU7Rwo=
    4. Use this key in your KMS, KVM, cache, or contract encryption configuration in your overrides file.