Difficulty: beginner
Estimated Time: 10 minutes


Vault Enterprise 1.4 with Advanced Data Protection module introduced the Transform secrets engine which handles secure data transformation and tokenization against the provided secrets. Transformation methods encompass NIST vetted cryptographic standards such as format-preserving encryption (FPE) via FF3-1 to encode your secrets while maintaining the data format and length. In addition, it can also be pseudonymous transformations of the data through other means such as masking.

This prevents the need for change in the existing database schema.

Important Note: Without a valid license, Vault Enterprise server will be sealed after 30 minutes. In other words, you have 30 free minutes to explorer the Enterprise features. To explore Vault Enterprise further, you can sign up for a free 30-day trial.

[Enterprise] Transform Secrets Engine

Step 1 of 6

Setup the Transform secrets engine

Important Note: Without a valid license, Vault Enterprise server will be sealed after 30 minutes. To explore Vault Enterprise further, you can sign up for a free 30-day trial.

Transform secrets engine configuration workflow:

  1. Enable the transform secrets engine
  2. Create a role containing the transformations that it can perform
  3. Create an alphabet defining a set of characters to use for format-preserving encryption (FPE) if not using the built-in alphabets.
  4. Create a template defining the rules for value matching if not using the built-in template
  5. Create a transformation to specify the nature of the data manipulation


Alphabets define a set of valid input/output UTF-8 characters to be used when you perform FPE. In this step, you are going to leverage one of the built-in alphabets.

Data transformation templates are constructed of type (regex), pattern (regex expression) and allowed alphabet used in the input value. Currently, regex is the only supported type. The pattern defines the data format pattern. For example, the most credit card numbers would have a pattern that can be expressed as (\d{4})-(\d{4})-(\d{4})-(\d{4}) in regex.

Transformations define the transformation type (fpe or masking), template, tweak source or the masking character to be used to transform the secrets.

Tweak source types:

Source Description
supplied (default) User provide the tweak source which must be a base64-encoded string
generated Vault generates and returns the tweak source along with the encoded data. The user must securely store the tweak source which will be needed to decrypt the data
internal Vault generates a tweak source for the transformation and the same tweak source will be used for every request

NOTE: Tweak source is only applicable to the FPE transformation.

Let's begin! First, login with root token.

Click on the command () will automatically copy it into the terminal and execute it.

vault login root

Execute the following command to enable the transform secrets engine at transform/.

vault secrets enable transform

Create a role

Create a role named "payments" with "card-number" transformation attached which you will create next.

vault write transform/role/payments transformations=card-number

To list existing roles, execute the following command.

vault list transform/role

Create a transformation

Create a transformation named "card-number" which will be used to transform credit card numbers. This uses the built-in builtin/creditcardnumber template to perform format-preserving encryption (FPE). The allowed role to use this transformation is payments you just created.

vault write transform/transformation/card-number type=fpe \
        template="builtin/creditcardnumber" \
        tweak_source=internal \

NOTE: The allowed_roles parameter can be set to a wildcard (*) instead of listing role names. Also, the role name can be expressed using globs at the end for pattern matching (e.g. pay*).

To list the existing transformations, execute the following command.

vault list transform/transformation

To view the details of the newly created card-number transformation, execute the following command.

vault read transform/transformation/card-number

Creating Katacoda Scenarios

Thanks for creating Katacoda scenarios. This tab is designed to help you as an author have quick access the information you need when creating scenarios.

This tab will not be visible to users.

Here are some useful links to get you started.

Running Katacoda Workshops

If you are planning to use Katacoda for workshops, please contact [email protected] to arrange capacity.

Debugging Scenarios

Below is the response from any background scripts run or files uploaded. This stream can aid debugging scenarios.

If you still need assistance, please contact [email protected]