The first provider in the list is used to encrypt resources going into storage.

5

Arbitrary name of the secret.

6

Base64 encoded random key. Different providers have different key lengths. See instructions
on how to generate the key.

When reading resources from storage, each provider that matches the stored data attempts to decrypt
the data in order. If no provider can read the stored data due to a mismatch in format or secret
key, an error is returned, which prevents clients from accessing that resource.

If any resource is not readable via the encryption configuration (because keys
were changed), the only recourse is to delete that key from the underlying etcd
directly. Calls attempting to read that resource will fail until it is deleted
or a valid decryption key is provided.

Available Providers

Name

Encryption

Strength

Speed

Key Length

Other Considerations

identity

None

N/A

N/A

N/A

Resources written as-is without encryption. When set as the first provider, the resource will be
decrypted as new values are written.

aescbc

AES-CBC with PKCS#7 padding

Strongest

Fast

32-byte

The recommended choice for encryption, but may be slightly slower than secretbox.

secretbox

XSalsa20 and Poly1305

Strong

Faster

32-byte

A newer standard and may not be considered acceptable in environments that
require high levels of review.

aesgcm

AES-GCM with a random initialization vector (IV)

Must be rotated every 200,000 writes

Fastest

16, 24, or 32-byte

Is not recommended for use except when an automated key rotation scheme is implemented.

Each provider supports multiple keys. The keys are tried in order for
decryption. If the provider is the first provider, the first key is used for
encryption.

Kubernetes has no proper nonce generator and uses a random IV as nonce for
AES-GCM. Since AES-GCM requires a proper nonce to be secure, AES-GCM is not
recommended. The 200,000 write limit just limits the possibility of a fatal
nonce misuse to a reasonable low margin.

Generate a 32-byte random key and base64 encode it. For example, on Linux and
macOS use:

$ head -c 32 /dev/urandom | base64

The encryption key must be generated with an appropriate cryptographically
secure random number generator like /dev/urandom. For example, math/random
from Golang or random.random() from Python are not suitable.

Place that value in the secret field.

Restart the API server:

# systemctl restart atomic-openshift-master-api

The encryption provider configuration file contains keys that can decrypt
content in etcd, so you must properly restrict permissions on masters so only
the user who runs the master API server can read it.

Verifying that Data is Encrypted

Data is encrypted when written to etcd. After restarting the API server, any newly created or
updated secrets should be encrypted when stored. To check, you can use the etcdctl command line
program to retrieve the contents of your secret.