---
layout: docs
page_title: Transform - Secrets Engines
sidebar_title: Transform <sup>ENTERPRISE</sup>
description: >-
  The Transform secrets engine for Vault performs secure data transformation.
---

# Transform Secrets Engine

-> **Note**: This secret engine requires [Vault
Enterprise](https://www.hashicorp.com/products/vault/) with the Advanced Data
Protection Module.

The Transform secrets engine handles secure data transformation and tokenization
against provided input value. Transformation methods may encompass NIST vetted
cryptographic standards such as [format-preserving encryption
(FPE)](https://en.wikipedia.org/wiki/Format-preserving_encryption) via
[FF3-1](https://csrc.nist.gov/publications/detail/sp/800-38g/rev-1/draft), but
can also be pseudonymous transformations of the data through other means, such
as masking.

The secret engine currently supports `fpe` and `masking` as data transformation
types.

## Setup

Most secrets engines must be configured in advance before they can perform their
functions. These steps are usually completed by an operator or configuration
management tool.

1. Enable the Transform secrets engine:

    ```text
    $ vault secrets enable transform
   Success! Enabled the transform secrets engine at: transform/
    ```

    By default, the secrets engine will mount at the name of the engine. To enable
    the secrets engine at a different path, use the -path argument.

1. Create a named role:

    ```text
    $ vault write transform/role/payments transformations=ccn-fpe
    Success! Data written to: transform/role/payments
    ```

1. Create a transformation:

    ```text
    $ vault write transform/transformation/ccn-fpe \
      type=fpe \
      template=ccn \
      tweak_source=internal \
      allowed_roles=payments
    Success! Data written to: transform/transformation/ccn-fpe
    ```

1. Optionally, create a template:

    ```text
    $ vault write transform/template/ccn \
      type=regex \
      pattern='(\d{4})-(\d{4})-(\d{4})-(\d{4})' \
      alphabet=numerics
    Success! Data written to: transform/template/ccn
    ```

1. Optionally, create an alphabet:

    ```text
    $ vault write transform/alphabet/numerics \
        alphabet="0123456789"
    Success! Data written to: transform/alphabet/numerics
    ```

## Usage

After the secrets engine is configured and a user/machine has a Vault token with
the proper permission, it can use this secrets engine to encode and decode input
values.

1. Encode some input value using the `/encode` endpoint with a named role:

    ```text
    $ vault write transform/encode/payments value=1111-2222-3333-4444
    Key              Value
    ---              -----
    encoded_value    9300-3376-4943-8903
    ```

   A transformation must be provided if the role contains more than one
   transformation. A tweak must be provided if the tweak source for the
   transformation is "supplied".

1. Decode some input value using the `/decode` endpoint with a named role:

    ```text
    $ vault write transform/decode/payments value=9300-3376-4943-8903
    Key              Value
    ---              -----
    decoded_value    1111-2222-3333-4444
    ```

   A transformation must be provided if the role contains more than one
   transformation. A tweak must be provided if the tweak source for the
   transformation is "supplied" or "generated".

## Roles, Transformations, Templates, and Alphabets

The Transform secrets engine contains several types of resources that
encapsulate different aspects of the information required in order to perform
data transformation.

- **Roles** are the basic high-level construct that holds the set of
transformation that it is allowed to performed. The role name is provided when
performing encode and decode operations.

- **Transformations** hold information about a particular transformation. It
contains information about the type of transformation that we want to perform,
the template that it should use for value detection, and other
transformation-specific values such as the tweak source or the masking character
to use.

- **Templates** allow us to determine what and how to capture the value that we
want to transform.

- **Alphabets** provide the set of valid UTF-8 character contained within both
the input and transformed value on FPE transformations.

## Deletion Behavior

The deletion of resources, aside from roles, is guarded by checking whether any
other related resources are currently using it in order to avoid accidental data
loss of any encoded value that may depend on these bits of information to
decode and reconstruct the original value. Role deletion can be safely done
since the information related to the transformation itself is contained within
transformation object and its related resources.

The following rules applies when it comes to deleting a resource:

- A transformation cannot be deleted if it's in use by a role
- A template cannot be deleted if it's in use by a transformation
- An alphabet cannot be deleted if it's in use by a template

## Provided Builtin Resources

The secret engine provides a set of builtin templates and alphabets that are
considered common. Builtin templates cannot be deleted, and the prefix
"builtin/" on template and alphabet names is a reserved keyword.

### Templates

The following builtin templates are available for use in the secret engine:

- builtin/creditcardnumber
- builtin/socialsecuritynumber

Note that these templates only check for the matching pattern(s), and not the
validity of the value itself. For instance, the builtin credit card number
template can determine whether the provided value is in the format of commonly
issued credit cards, but not whether the credit card is a valid number from a
particular issuer.

### Alphabets

The following builtin alphabets are available for use in the secret engine:

- builtin/numeric
- builtin/alphalower
- builtin/alphaupper
- builtin/alphanumericlower
- builtin/alphanumericupper
- builtin/alphanumeric

## Learn

Refer to the [Transform Secrets Engine](https://learn.hashicorp.com/vault/adp/transform) guide for a step-by-step tutorial.

## API

The Transform secrets engine has a full HTTP API. Please see the
[Transform secrets engine API](/api/secret/transform) for more
details.
