Keyring

Uses: Kong Gateway Admin API

What is a 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.

How Keyring encryption works

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.

Key generation and lifecycle

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

You generate a key using the /keyring/generate Admin API endpoint.
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.
You create a plugin that contains an encrypted field. For example, a plugin with an API key field.
Using the key you generated, Kong Gateway encrypts the value of the encrypted fields and writes the data to the Kong Gateway database.
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

Disaster recovery

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.

Enable Keyring

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:

Set the following values in kong.conf:

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

Create the following environment variables:

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.

FAQs

What is the difference between a Vault and a Keyring?

A Keyring and a Vault are both used to secure secrets, but they use different approaches. The Keyring contains encryption keys used to encrypt sensitive data fields before they’re written to the database. The same key is then used to decrypt the data when reading from the database. A Vault is a container that securely stores secrets. You can then reference these secrets in other Kong Gateway entities.

The Keyring is configured for the whole Kong Gateway instance and will automatically encrypt a list of fields defined by Kong Gateway. In a Vault, each secret needs to be added and then referenced. However, a Vault supports storing some fields not supported by the Keyring.

You may choose a Vault if you want to secure certain fields that are not encrypted by the Keyring. If all the fields you want to secure are encrypted, the Keyring may be a quicker solution to implement.

Where does Kong Gateway store the contents of the Keyring?

Kong Gateway stores Keyring material in a shared memory zone that all Kong Gateway worker processes access. To prevent keys from being written to disk as part of memory paging operations, we recommend disabling memory swapping on systems running Kong Gateway.

What happens to the keys if a Kong Gateway node fails?

In cluster mode, the contents of the Keyring propagate automatically among all nodes in the Kong Gateway cluster. One node failing does not impact the Keyring. However, at least one node must be running at all times within the cluster; a failure of all nodes requires manually re-importing the Keyring to one node during an outage recovery.