Keyring

A Keyring is a mechanism that encrypts sensitive data fields, such as consumer secrets, before storing them in the database. The Keyring stores keys used to encrypt and decrypt data.

This functionality provides transparent, symmetric encryption of sensitive data fields at rest. When enabled, encryption and decryption of data are done on-the-fly by Kong Gateway immediately before writing to the database and after reading from the database. Responses containing sensitive fields generated by the Admin API continue to show data as plain text. Kong Gateway runtime elements, such as plugins, can access sensitive fields transparently, without requiring additional configuration.

For wider stability, security, and more granular control over encrypted values, we recommend using Vaults and database encryption at rest for secret management:

• Whenever possible, use Vaults for any secret values. Vaults are supported in Konnect, have less performance impact on your Kong Gateway deployment, and support encrypting a wider range of values than Keyring.
• Use database encryption at rest for your PostgreSQL database. Cloud vendors such as Amazon RDS normally enable this by default.

The following sections describe how Keyring encryption works.

Encrypted fields

The Keyring encrypts the following fields:

• The key fields in a certificate object, which is the private key for a TLS certificate.
• Certain configuration parameters in plugins and plugin-related authentication objects. These parameters have an encrypted label in the plugin’s configuration reference.

Encryption and decryption

Kong Gateway uses 256-bit AES encryption in Galois/Counter Mode (GCM mode). Cryptographic nonce values for each encryption routine execution are derived from the kernel CSPRNG (/dev/urandom). The AES routines used by Kong Gateway are provided by the OpenSSL library bundled with the Kong Gateway package.

Once you’ve enabled Keyring with the cluster strategy on all Kong Gateway nodes in your cluster, the encryption process will work like this:

1. You generate a key using the /keyring/generate Admin API endpoint.
2. Kong Gateway stores this key and its ID in a shared memory zone in the data store, which is accessible to all nodes in your cluster.
3. You create a plugin that contains an encrypted field. For example, a plugin with an API key field.
4. Using the key you generated, Kong Gateway encrypts the value of the encrypted fields and writes the data to the Kong Gateway database.
5. If any Kong Gateway node in the cluster receives a request, through the /plugins API endpoint for example, it uses the key you generated to decrypt the sensitive fields and returns the data in plain text.

If you generate a new key:

• New data is encrypted using the new key
• Older keys remain in the Keyring to decrypt previously-encrypted data, but are no longer used for encryption

To automatically back up your Keyring material, make sure to configure the keyring_recovery_public_key parameter to point to your cert.pem file. See Enable Keyring for more details.

The Keyring material is then encrypted with the public RSA key defined with the keyring_recovery_public_key value in the database. The corresponding private key can be used to decrypt the Keyring material in the database:

curl -X POST localhost:8001/keyring/recover -F recovery_private_key=@./key.pem

The response contains a list of keys that were successfully recovered and a list of keys that could not be recovered. The Kong Gateway error log will contain the detailed reason why the keys could not be recovered.

To allow Kong Gateway to use a recovered key, you need to activate it:

curl -X POST localhost:8001/keyring/activate -d key=$KEY_ID

1. Generate an RSA key pair

Use the openssl CLI to generate an RSA key pair that can be used to export and recover Keyring material:

openssl genrsa -out key.pem 2048
openssl rsa -in key.pem -pubout -out cert.pem

2. Configure Kong Gateway

To enable data encryption, you must modify the Kong Gateway configuration. You can either update kong.conf or use environment variables:

keyring_enabled = on
keyring_strategy = cluster
keyring_recovery_public_key = /path/to/generated/cert.pem

export KONG_KEYRING_ENABLED=on
export KONG_KEYRING_STRATEGY=cluster
export KONG_KEYRING_RECOVERY_PUBLIC_KEY=./cert.pem

3. Start Kong Gateway and generate a key

Once the configuration is updated, you can start your Kong Gateway instance and use the following request to make create a new key in the Keyring:

curl -X POST localhost:8001/keyring/generate

This key will then be used to encrypt sensitive fields in the database. To validate that it’s working, you can create a plugin with data in an encrypted field, and then check the database to make sure the data is encrypted.