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

[id='con-record-encryption-filter-config-{context}']
= Filter configuration

[role="_abstract"]
This procedure describes how to configure 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
{ProxyGuide} or {OperatorGuide}.
* 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]
----
kms: <kms_service_name> # <1>
kmsConfig:
  <kms_specific_config> # <2>
  # ...
selector: <KEK_selector_service_name> # <3>
selectorConfig:
  template: "KEK_$(topicName)" # <4>
unresolvedKeyPolicy: PASSTHROUGH_UNENCRYPTED # <5>
experimental:
  encryptionDekRefreshAfterWriteSeconds: 3600 # <6>
  encryptionDekExpireAfterWriteSeconds: 7200 # <7>
  maxEncryptionsPerDek: 5000000 # <8>
----
<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> Optional policy governing the behaviour when the KMS does not contain a key. The default is `PASSTHROUGH_UNENCRYPTED` which
causes the record to be forwarded, unencrypted, to the target cluster. Users can alternatively specify `REJECT` which
will cause the entire produce request to be rejected. This is a safer alternative if you know that all traffic sent
to the Virtual Cluster should be encrypted because unencrypted data will never be forwarded.
<6> 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.
<7> 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.
<8> 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.
+
`encryptionDekRefreshAfterWriteSeconds` and `encryptionDekExpireAfterWriteSeconds` properties govern the _originator usage period_ of the DEK, which is the amount of time the DEK remains valid for encrypting records.  Shortening this period helps limit the impact if the DEK key material is leaked. However, shorter periods increase the number of KMS API calls, which might affect produce and consume latency and raise 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.
