--- layout: docs page_title: Transform - Secrets Engines sidebar_title: Transform ENTERPRISE 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.