Key Management

All Kryptonite for Kafka modules support four ways to source the required key material. You can define this by means of the key_source configuration parameter. The right choice primarly depends on your security posture and preferred operational model.

Overview

key_source=CONFIG              → plain keysets inline in config
key_source=CONFIG_ENCRYPTED    → KEK-encrypted keysets inline in config
key_source=KMS                 → plain keysets in cloud secret manager
key_source=KMS_ENCRYPTED       → KEK-encrypted keysets in cloud secret manager

Plain keysets in configuration

The simplest and least secure mode. Plain keysets are embedded directly in the cipher_data_keys configuration parameter.

Plain keyset example

  {
    "identifier": "my-key",
    "material": {
      "primaryKeyId": 10000,
      "key": [
        {
          "keyData": {
            "typeUrl": "type.googleapis.com/google.crypto.tink.AesGcmKey",
            "value": "<BASE64_ENCODED_KEY_HERE>",
            "keyMaterialType": "SYMMETRIC"
          },
          "status": "ENABLED",
          "keyId": 10000,
          "outputPrefixType": "TINK"
        }
      ]
    }
  }

Encrypted keysets in configuration

Encrypted keysets give you moderate security while still being able to directly reference keys inside the configuration. A cloud KMS key encryption key (KEK) is used to decrypt the keysets at runtime. The plain keysets are never stored anywhere.

Requires: key_source=CONFIG_ENCRYPTED, depends on kek_type, kek_uri, and kek_config in addition to cipher_data_keys.

Encrypted keyset example

Note, that the material field takes the encrypted keyset form:

  {
    "identifier": "my-key",
    "material": {
      "encryptedKeyset": "<ENCRYPTED_AND_BASE64_ENCODED_KEYSET_HERE>",
      "keysetInfo": {
        "primaryKeyId": 10000,
        "keyInfo": [
          {
            "typeUrl": "type.googleapis.com/google.crypto.tink.AesGcmKey",
            "status": "ENABLED",
            "keyId": 10000,
            "outputPrefixType": "TINK"
          }
        ]
      }
    }
  }

Plain keysets in cloud secret manager

Plain keysets are stored as secrets in a cloud secret manager which provides reasonable key material protection. These are either fetched lazily on-demand or eagerly loaded during module initialization using the configured cloud provider credentials.

Requires: key_source=KMS, depends on kms_type and kms_config. When using a cloud secret manager cipher_data_keys can be deliberately set to the empty JSON array [].

Plain keyset example

For cloud secret manager usage, plain keysets must be generated in RAW format with the keyset tool.

{
  "primaryKeyId": 10000,
  "key": [
    {
      "keyData": {
        "typeUrl": "type.googleapis.com/google.crypto.tink.AesGcmKey",
        "value": "<BASE64_ENCODED_KEY_HERE>",
        "keyMaterialType": "SYMMETRIC"
      },
      "status": "ENABLED",
      "keyId": 10000,
      "outputPrefixType": "TINK"
    }
  ]
}

Encrypted keysets in cloud secret manager

The most secure mode. Keysets are stored encrypted in a cloud secret manager, and a separate cloud KMS key encryption key is required to decrypt them at runtime.

Requires: key_source=KMS_ENCRYPTED, depends on kms_type,kms_config, kek_type, kek_uri, and kek_config. When using a cloud secret manager cipher_data_keys can be deliberately set to the empty JSON array [].

Encrypted keyset example

For cloud secret manager usage, encrypted keysets must be generated in RAW format with the keyset tool.

{
  "encryptedKeyset": "<ENCRYPTED_AND_BASE64_ENCODED_KEYSET_HERE>",
  "keysetInfo": {
    "primaryKeyId": 10000,
    "keyInfo": [
      {
        "typeUrl": "type.googleapis.com/google.crypto.tink.AesGcmKey",
        "status": "ENABLED",
        "keyId": 10000,
        "outputPrefixType": "TINK"
      }
    ]
  }
}

Secret naming conventions

Depending on which cloud secret manager is configured to store plain or encrypted keysets, the following secret name prefixes must be considered to distinguish plain from encrypted keysets:

Tink Keyset Format

All keyset material, regardless of the key source, must conform to Tink's plain or encrypted keyset specification.

Plain keyset examples

• AES-GCM (probabilistic encryption)

{
  "primaryKeyId": 123456789,
  "key": [
    {
      "keyData": {
        "typeUrl": "type.googleapis.com/google.crypto.tink.AesGcmKey",
        "value": "<BASE64_ENCODED_KEY_HERE>",
        "keyMaterialType": "SYMMETRIC"
      },
      "status": "ENABLED",
      "keyId": 123456789,
      "outputPrefixType": "TINK"
    }
  ]
}

• AES-GCM-SIV (deterministic encryption)

{
  "primaryKeyId": 123456789,
  "key": [
    {
      "keyData": {
        "typeUrl": "type.googleapis.com/google.crypto.tink.AesSivKey",
        "value": "<BASE64_ENCODED_KEY_HERE>",
        "keyMaterialType": "SYMMETRIC"
      },
      "status": "ENABLED",
      "keyId": 123456789,
      "outputPrefixType": "TINK"
    }
  ]
}

• FPE FF3-1 (format-preserving encryption)

{
  "primaryKeyId": 2000001,
  "key": [
    {
      "keyData": {
        "typeUrl": "io.github.hpgrahsl.kryptonite/crypto.custom.mysto.fpe.FpeKey",
        "value": "<BASE64_ENCODED_KEY_HERE>",
        "keyMaterialType": "SYMMETRIC"
      },
      "status": "ENABLED",
      "keyId": 2000001,
      "outputPrefixType": "RAW"
    }
  ]
}

Note the custom typeUrl and outputPrefixType: RAW for FPE keysets.

Key Rotation

Tink keysets natively support multiple keys. The primaryKeyId determines which key is used for new encryptions. Older keys are supposed to remain in the keyset for decryption of existing ciphertexts.

1. Generate a new keyset with multiple keys (e.g., -n 2 with the Keyset Tool)
2. One of the keys in the keyset must be the primary key, initially it's the first one
3. Any new encryption operations use the currently designated primary key
4. A different key in the keyset can be promoted to become the primary key at any time
5. Once the primary key changed, old ciphertexts remain decryptable so long as the previously used primary key is still resolvable within the configured keyset.

See Keyset Tool for examples of generating multi-key keysets.