Configuration Reference

All Kryptonite for Kafka modules share the same set of core configuration parameters. The table below shows which parameters are available and supported by each module.

Core Parameters

key_source

Defines the origin and protection of the key material.

Default: CONFIG

cipher_data_keys

A JSON array of Tink keyset objects. Each entry has an identifier and a material field containing a Tink keyset specification.

Plain keyset example (when key_source=CONFIG):

[
  {
    "identifier": "my-demo-key",
    "material": {
      "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"
        }
      ]
    }
  }
]

Encrypted keyset example (when key_source=CONFIG_ENCRYPTED):

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

May be deliberately left empty [] when keysets are sourced from cloud secret managers (key_source=KMS or key_source=KMS_ENCRYPTED), or when using only KMS-backed envelope encryption (key_source=NONE).

cipher_data_key_identifier

The default key identifier used for encryption in case field settings do not specify their own key. For regular and keyset-based encryption this is the data-key identifier. It must match an identifier present in cipher_data_keys (or be resolvable from the used cloud KMS).

kms_type

The cloud secret manager to use when key_source=KMS or key_source=KMS_ENCRYPTED.

Default: NONE

kms_config

JSON object with authentication settings specific to the chosen cloud provider

{
  "clientId": "...",
  "tenantId": "...",
  "clientSecret": "...",
  "keyVaultUrl": "..."
}

{
  "accessKey": "...",
  "secretKey": "...",
  "region": "..."
}

{
  "credentials": "<GCP service account JSON contents>",
  "projectId": "..."
}

kek_type

The KMS provider holding the Key Encryption Key (KEK) used to encrypt/decrypt keysets at rest. Required when key_source=CONFIG_ENCRYPTED or key_source=KMS_ENCRYPTED.

Default: NONE

kek_config

JSON object with credentials for the KEK provider.

{
  "credentials": "<GCP service account JSON contents>",
  "projectId": "my-gcp-project"
}

{
  "accessKey": "...",
  "secretKey": "..."
}

{
  "clientId": "...",
  "tenantId": "...",
  "clientSecret": "...",
  "keyVaultUrl": "..."
}

kek_uri

URI referencing the Key Encryption Key in the chosen cloud KMS.

Encryption Parameters

cipher_algorithm

The default cipher algorithm used for encryption in case field settings do not specify their own cipher algorithm.

Default: TINK/AES_GCM

field_mode

Controls how complex fields (ARRAY, MAP, STRUCT, and ROW types) are processed.

Default: ELEMENT

Envelope Encryption Parameters

The parameters below are split into:

• parameters that apply only to KMS-based envelope encryption (TINK/AES_GCM_ENVELOPE_KMS)
• parameters that apply to both envelope encryption variants (TINK/AES_GCM_ENVELOPE_KEYSET, TINK/AES_GCM_ENVELOPE_KMS)

envelope_kek_configs

Applies to KMS-based envelope encryption only (TINK/AES_GCM_ENVELOPE_KMS). JSON array of KEK entries where each entry specifies a KEK identifier, type (cloud provider), uri, and provider-specific config credentials. Not used for keyset-based envelope encryption (TINK/AES_GCM_ENVELOPE_KEYSET).

[
  {
    "identifier": "my-kek",
    "type": "GCP",
    "uri": "gcp-kms://projects/<project>/locations/<location>/keyRings/<ring>/cryptoKeys/<key>",
    "config": {
      "credentials": "<GCP service account JSON>",
      "projectId": "<project>"
    }
  }
]

See Envelope Encryption / KEK configuration for examples for all supported providers.

Default: [] (disabled)

envelope_kek_identifier

Applies to KMS-based envelope encryption only (TINK/AES_GCM_ENVELOPE_KMS). The default KEK identifier used when field settings do not specify their own individual KEK. Must match an identifier present in envelope_kek_configs.

edek_store_config

Applies to KMS-based envelope encryption only (TINK/AES_GCM_ENVELOPE_KMS). JSON object configuring the backing EdekStore implementation. Currently, the default implementation is based on KCache/Kafka which persistently maps DEK fingerprints to wrapped DEKs. A minimal viable configuration is:

{
  "kafkacache.bootstrap.servers": "broker1:9092,...",
  "kafkacache.topic": "_k4k_edeks"
}

See Envelope Encryption / EdekStore configuration for the full list of supported keys.

Default: {} (disabled)

dek_max_encryptions

Applies to both envelope encryption variants (TINK/AES_GCM_ENVELOPE_KEYSET, TINK/AES_GCM_ENVELOPE_KMS). Upper limit for field encryptions before the current DEK session is rotated and a new DEK is generated.

Default: 100000

dek_ttl_minutes

Applies to both envelope encryption variants (TINK/AES_GCM_ENVELOPE_KEYSET, TINK/AES_GCM_ENVELOPE_KMS). Longest allowed age of a DEK session in minutes. The session is rotated when this threshold is reached, regardless of dek_max_encryptions.

Default: 720 (12 hours)

dek_key_bits

Applies to both envelope encryption variants (TINK/AES_GCM_ENVELOPE_KEYSET, TINK/AES_GCM_ENVELOPE_KMS). Size of the generated DEK in bits. Accepted values: 128 or 256.

Default: 128

FPE Settings

These settings apply if and only if you have configured a format-preserving encryption (FPE) cipher i.e. cipher_algorithm=CUSTOM/MYSTO_FPE_FF3_1.

cipher_fpe_tweak

A 7-bytes tweak value that adds cryptographic variation to FPE. Different tweaks produce different ciphertexts for the same plaintext input.

Default: 0000000

cipher_fpe_alphabet_type

The character set to which both plaintext and ciphertext characters are mapped.

Default: ALPHANUMERIC

cipher_fpe_alphabet_custom

The explicit character set when cipher_fpe_alphabet_type=CUSTOM. At least 2 unique characters are required. Example: 01 for binary strings.

Module Specific Parameters

dynamic_key_id_prefix

Supported by the Kafka Connect SMT, Quarkus HTTP Service, and the Kroxylicious Filter.

Marks a configured key identifier as dynamic. When the selected configured identifier starts with this prefix, the remaining suffix is interpreted as a field path and resolved from the input record. The extracted textual field value is then used verbatim as the effective runtime key identifier.

This applies to:

• field-level keyId
• default cipher_data_key_identifier
• for TINK/AES_GCM_ENVELOPE_KMS, default envelope_kek_identifier

Example: __#customer.country resolves the runtime key identifier from field path customer.country.

If the path cannot be resolved, resolves to a non-textual/non-string value, or resolves to a blank string, processing fails. The prefix itself must not be blank.

Default: __#

path_delimiter

Supported by the Kafka Connect SMT and the Quarkus HTTP Service.

Separator for nested field references used by dynamic key identifier resolution and field path matching. For the Kafka Connect SMT, this delimiter is also used for nested field names in field_config. For the Quarkus HTTP Service, the same delimiter is used for nested field names in request-body fieldConfig entries.

Default: .

cipher_mode

Supported by the Kafka Connect SMT. ENCRYPT or DECRYPT. Required. Determines the direction of the transformation.

field_config

Supported by the Kafka Connect SMT. JSON array listing the payload fields to process. Each entry must at least specify the field name. Optional per-field overrides for other settings influencing the encryption / decryption behaviour, including keyId.

• Example

[
  { "name": "ssn" },
  { "name": "creditCard", "algorithm": "CUSTOM/MYSTO_FPE_FF3_1", "fpeAlphabetType": "DIGITS" },
  { "name": "mySubDoc1.nestedField" }
]

The SMT also supports dynamic key identifiers for field-level keyId, the default cipher_data_key_identifier, and, for TINK/AES_GCM_ENVELOPE_KMS, the default envelope_kek_identifier. When one of those values starts with dynamic_key_id_prefix, the remaining suffix is resolved as a field path against the top-level record. This works for both schemaless Map records and schema-aware Struct records.

For decryption of schema-aware records, include the schema field to allow the SMT to reconstruct the original type.

• Example:

[
  { "name": "myArray1", "schema": { "type": "ARRAY", "valueSchema": { "type": "STRING" } } }
]