186 lines
6.1 KiB
Plaintext
186 lines
6.1 KiB
Plaintext
---
|
|
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.
|