// file included in the following:
//
// assembly-record-encryption-filter.adoc

[id='proc-configuring-record-encryption-filter-{context}']
= Setting up the Record Encryption filter

[role="_abstract"]
This procedure describes how to set up the Record Encryption filter.
Provide the filter configuration and the Key Encryption Key (KEK) selector to use. 
The KEK selector maps topic name to key names.  
The filter looks up the resulting key name in the KMS.

.Prerequisites

* An instance of Kroxylicious. 
For information on deploying Kroxylicious, see the link:{github}[samples and examples^].
* A config map for Kroxylicious that includes the configuration for creating virtual clusters and filters. 
* A KMS is installed and set up for the filter with KEKs to encrypt records set up for topics.

.Procedure

. Configure a `RecordEncryption` type filter.
+
.Example Record Encryption filter configuration
[source,yaml]
----
filters:
  - type: RecordEncryption
    config:
      kms: <kms_service_name> # <1>
      kmsConfig:
        <kms_specific_config> # <2>
        # ...
      selector: <KEK_selector_service_name> # <3>
      selectorConfig:
        template: "KEK_${topicName}" # <4>
      experimental:
        encryptionDekRefreshAfterWriteSeconds: 3600 # <5>
        encryptionDekExpireAfterWriteSeconds: 7200 # <6>
        maxEncryptionsPerDek: 5000000 # <7>
	 # ...
----
<1> The KMS service name.
<2> Configuration specific to the KMS provider.
<3> The Key Encryption Key (KEK) selector to use. The `${topicName}` is a literal understood by the proxy. 
For example, if using the `TemplateKekSelector` with the template `KEK_$\{topicName}`, create a key for every topic that
is to be encrypted with the key name matching the topic name, prefixed by the string `KEK_`.
<4> The template for deriving the KEK, based on a specific topic name.
<5> How long after creation of a DEK before it becomes eligible for rotation. On the **next** encryption request, the cache will asynchronously create a new DEK.  Encryption requests will continue to use the old DEK until the new DEK is ready.
<6> How long after creation of a DEK until it is removed from the cache. This setting puts an upper bound on how long a DEK can remain cached.
<7> The maximum number of records any DEK should be used to encrypt. After this limit is hit, that DEK will be destroyed and a new one created.

NOTE: `encryptionDekRefreshAfterWriteSeconds` and `encryptionDekExpireAfterWriteSeconds` help govern the "originator usage period" of the DEK. That is the period of time the DEK will be used to encrypt records.  Keeping the period short helps reduce the blast radius in the event that DEK key material is leaked. However, there is a trade-off. The additional KMS API calls will increase produce/consume latency and may increase your KMS provider costs. +
      +
      `maxEncryptionsPerDek` helps prevent key exhaustion by placing an upper limit of the amount of times that a DEK may be used to encrypt records.

. Verify that the encryption has been applied to the specified topics by producing messages through the proxy and then consuming directly and indirectly from the Kafka cluster.

NOTE: If the filter is unable to find the key in the KMS, the filter passes through the records belonging to that topic in the produce request without encrypting them.
