// file included in the following:
//
// assembly-hashicorp-vault.adoc

[id='con-vault-setup-{context}']
= Enable the Transit Engine

The filter integrates with the {hashicorp-vault}/docs/secrets/transit[HashiCorp Vault *Transit
Engine*].
Vault does not enable the Transit Engine by default.
It must be {hashicorp-vault}/docs/secrets/transit#setup[enabled] before it can be used by the filter.

[#_vault_transit_engine_url]
== Vault Transit Engine URL

The Vault Transit Engine URL is required so the filter knows the location of the Transit Engine within the
Vault instance.

The URL is formed from the concatenation of the `Api Address` (reported by Vault reported by during
{hashicorp-vault}/tutorials/getting-started/getting-started-dev-server#starting-the-dev-server[starts up]) with the
complete path to Transit Engine, including the name of the engine itself. If
{hashicorp-vault}/docs/enterprise/namespaces[Namespacing] is used on the Vault instance, the path needs to include the
namespace(s). The URL will end with `/transit` unless the `-path` parameter was used when
{hashicorp-vault}/docs/secrets/transit#setup[enabling the engine].

If namespacing is not in use, the URL will look like this:

[source,shell]
----
https://myvaultinstance:8200/v1/transit
----

If namespacing is in use, the path must include the namespaces. For example, if there is a parent namespace is `a` and
a child namespace is `b`, the URL will look like this:

[source,shell]
----
https://myvaultinstance:8200/v1/a/b/transit
----

If the name of the Transit engine was changed (using the `-path` argument to the `vault secrets enable transit` command)
the URL will look like this:

[source,shell]
----
https://myvaultinstance:8200/v1/mytransit
----

== Establish the naming convention for keys within Vault hierarchy

Establish a naming convention for keys to keep the filter’s keys separate from those used by other systems.
Here, we use a prefix of KEK_ for filter key name.
Adjust the instructions if a different naming convention is used.

== Role of the administrator

To use the filter, an administrator (or administrative process) must create the encryption keys within Vault that will be used to encrypt the records.
The organization deploying the Record Encryption filter is responsible for managing this administrator or process.

The administrator must have permissions to create keys beneath `transit/keys/KEK_*` in the Vault hierarchy.

As a guideline, the minimal Vault policy required by the administrator is as follows:

[source,shell]
----
path "transit/keys/KEK_*" {
  capabilities = ["read", "write"]
}
----

== Establish an application identity for the filter

The filter must authenticate to Vault in order to perform envelope encryption operations, such as generating and decrypting DEKs
Therefore, a Vault identity with sufficient permissions must be created for the filter.

Create a Vault policy for the filter:

[source,shell]
----
vault policy write kroxylicious_encryption_filter_policy - << EOF
path "transit/keys/KEK_*" {
  capabilities = ["read"]
}
path "/transit/datakey/plaintext/KEK_*" {
  capabilities = ["update"]
}
path "transit/decrypt/KEK_*" {
  capabilities = ["update"]
}
EOF
----

Create a {hashicorp-vault}/docs/concepts/tokens#periodic-tokens[Periodic] (long-lived) Vault Token
for the filter:

[source,shell]
----
vault token create -display-name "kroxylicious record encryption" \
                   -policy=kroxylicious_encryption_filter_policy \
                   -period=768h \ # <1>
                   -no-default-policy \ # <2>
                   -orphan # <3>

----
<1> Causes the token to be periodic (with every renewal using the given period).
<2> Detach the "default" policy from the policy set for this token.  This is done so the token has least-privilege.
<3> Create the token with no parent. This is done so that expiration of a parent won't expire the token used by the filter.

NOTE: The example token create command illustrates the use of `-no-default-policy`
and `-orphan`. The use of these flags is not functionally important.  
You may adapt the configuration of the token to suit the standards required by your organization.

The `token create` command yields the `token`. The `token` value is required later when configuring the vault within the
filter.

[source]
----
token              hvs.CAESIFJ_HHo0VnnW6DSbioJ80NqmuYm2WlON-QxAPmiJScZUGh4KHGh2cy5KdkdFZUJMZmhDY0JCSVhnY2JrbUNEWnE
token_accessor     4uQZJbEnxW4YtbDBaW6yVzwP
token_policies     [kroxylicious_encryption_filter_policy]
----

The token must be {hashicorp-vault}/docs/concepts/tokens#token-time-to-live-periodic-tokens-and-explicit-max-ttls[renewed]
before expiration.  
It is the responsibility of the administrator to do this.

This can be done with a command like the following:

[source,shell]
----
vault token renew --accessor <token_accessor>
----

== Testing the application identity for the filter using the CLI

To test whether the application identity and the policy are working correctly, a
https://raw.githubusercontent.com/kroxylicious/kroxylicious/main/scripts/validate_vault_token.sh[script] can be used.

First, as the administrator, create a KEK in the hierarchy at this path `transit/keys/KEK_testkey`.

[source,shell]
----
VAULT_TOKEN=<kroxylicious encryption filter token> validate_vault_token.sh <kek path>
----

The script should respond `Ok`.  
If errors are reported check the policy/token configuration.

`transit/keys/KEK_testkey` can now be removed.

