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

[id='con-fortanix-dsm-setup-{context}']
= Integrate with Fortanix DSM

The filter integrates with the {fortanix-dsm}[Fortanix Data Security Manager (DSM)].
Both Fortanix DSM software-as-a service (SaaS) or an on-premise installation are supported.

These instructions assume that you are using the
link:{fortanix-support}/docs/clients-command-line-interface-cli-for-fortanix-data-security-manager[Fortanix DSM CLI],
but you can use the Fortanix DSM user interface if preferred.

NOTE: The Fortanix KMS plugin for Record Encryption doesn't yet support keys in the
https://support.fortanix.com/docs/users-guide-key-undo-policy#50-deactivate-and-compromise-key-with-key-undo-policy[Deactivated state].
For more information, see the {github-issues}/1767[related issue^].

== Fortanix DSM Cluster URL

The Record Encryption filter requires the URL of the Fortanix DSM cluster.

If you are using SaaS, the URL looks like https://smartkey.io/[`https://<region>.smartkey.io`] where `region` is an identifier such as `amer`.
For more information, see the link: {fortanix-support}/docs/configure-api-client[Fortanix documentation].

If using an on-premises instance, talk to the group responsible for it within your organization to find out
the URL you should use.

== Establish a naming convention for keys within Fortanix DSM

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.

Choose the Fortanix DSM groups to keep the keys. Here, we assume a group name of `topic-keks`.

Adjust the instructions if a different naming convention is used.

== Role of the administrator

To use the filter, an administrator or an administrative process must create the encryption keys within Fortanix DSM,
which are used by the xref:con-topic-encryption-overview-{context}[envelope encryption] process.

The organization deploying the Record Encryption filter is responsible for managing this administrator or process.

The administrator must have permissions to create keys with Fortanix DSM.

== Establish an application identity for the filter

The filter must authenticate to Fortanix DSM in order to perform the encryption and decryption operations.

Create a Fortanix DSM App with sufficient permissions for the filter:

[source,shell]
----
sdkms-cli --api-endpoint https://<region>.smartkey.io create-app --name kroxylicious --default-group topic-keks --groups topic-keks
----

Retrieve the API key for the app:

[source,shell]
----
sdkms-cli --api-endpoint https://<region>.smartkey.io get-app-api-key --name kroxylicious
----

The Record Encryption filter uses the API Key in its KMS configuration to authenticate to Fortanix DSM.