Transform sensitive data with Vault

1. Enable the transform secrets engine at transform/.

   $ vault secrets enable transformSuccess! Enabled the transform secrets engine at: transform/

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

   $ vault write transform/role/payments transformations=card-numberSuccess! Data written to: transform/role/payments

3. List the existing roles.

   $ vault list transform/roleKeys----payments

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

   $ vault write transform/transformations/fpe/card-number \    template="builtin/creditcardnumber" \    tweak_source=internal \    allowed_roles=payments

   Example Output:

   Success! Data written to: transform/transformations/fpe/card-number

   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*).

   You will learn how to define your own template in the Create custom templates section.

5. List the existing transformations.

   $ vault list transform/transformations/fpeKeys----card-number

6. View the details of the newly created card-number transformation.

   $ vault read transform/transformations/fpe/card-numberKey                 Value---                 -----allowed_roles       [payments]deletion_allowed    falsetemplate            builtin/creditcardnumbertemplates           [builtin/creditcardnumber]tweak_source        internaltype                fpe

1. Enable transform secrets engine using /sys/mounts endpoint.

   $ curl --header "X-Vault-Token: $VAULT_TOKEN" \     --header "X-Vault-Namespace: $VAULT_NAMESPACE" \     --request POST \     --data '{"type":"transform"}' \     $VAULT_ADDR/v1/sys/mounts/transform

2. Create a role named payments with a transformation named card-number.

   $ curl --header "X-Vault-Token: $VAULT_TOKEN" \     --header "X-Vault-Namespace: $VAULT_NAMESPACE" \     --request POST \     --data '{"transformations": ["card-number"]}' \     $VAULT_ADDR/v1/transform/role/payments

   The payments role is created.

3. Display all the roles.

   $ curl --header "X-Vault-Token: $VAULT_TOKEN" \     --header "X-Vault-Namespace: $VAULT_NAMESPACE" \     --request LIST \     $VAULT_ADDR/v1/transform/role | jq ".data"

   Example output:

   {  "keys": [    "payments"  ]}

4. Create a transformation API request payload.

   $ tee payload.json <<EOF{  "template": "builtin/creditcardnumber",  "tweak_source": "internal",  "allowed_roles": [ "payments" ]}EOF

   The template value specifies a built-in builtin/creditcardnumber template to perform format-preserving encryption (FPE). The allowed_roles is limited to the role named payments.

   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*).

   You will learn how to define your own template in the Create custom templates section.

5. Create a transformation named card-number.

   $ curl --header "X-Vault-Token: $VAULT_TOKEN" \     --header "X-Vault-Namespace: $VAULT_NAMESPACE" \     --request POST \     --data @payload.json \     $VAULT_ADDR/v1/transform/transformations/fpe/card-number

6. Display all the transformations.

   $ curl --header "X-Vault-Token: $VAULT_TOKEN" \     --header "X-Vault-Namespace: $VAULT_NAMESPACE" \     --request LIST \     $VAULT_ADDR/v1/transform/transformations/fpe | jq ".data"

   Example output:

   {  "keys": [    "card-number"  ]}

7. Display details about the card-number transformation

   $ curl --header "X-Vault-Token: $VAULT_TOKEN" \     --header "X-Vault-Namespace: $VAULT_NAMESPACE" \     $VAULT_ADDR/v1/transform/transformations/fpe/card-number \     | jq ".data"

   Example output:

   {  "allowed_roles": [    "payments"  ],  "deletion_allowed": false,  "template": "builtin/creditcardnumber",  "templates": [    "builtin/creditcardnumber"  ],  "tweak_source": "internal",  "type": "fpe"}

1. Open a web browser, then navigate to the Vault UI and login.

2. Click Enable new engine and select the Transform radio button.

   

3. Click Next.

4. Click Enable Engine to accept the default path, transform.

   

5. Click Create transformation from the Transformations tab.

6. Enter the following information:

   • Name - Enter card-number
   • Type - Select Format Preserving Encryption
   • Tweak - source Select internal
   • Template Name - Start typing creditcard and select builtin/creditcardnumber.
   • Allowed roles - Enter payments. This role does not exist yet, so Vault will create it and attach the transformation to it.

   

   You will learn how to define your own template in the Create custom templates section.

   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*).

7. Click Create Transformation. This displays the details page of the transformation including encode and decode commands that can copy to test the transformation.

   

1. Encode a value with the payments role.

   $ ENCODED_OUTPUT=$(vault write transform/encode/payments \     value=1111-2222-3333-4444 \     -format=json | jq -r '.data | .encoded_value') \     && echo encoded_value: $ENCODED_OUTPUT

   Example output:

   encoded_value: 9474-2096-7736-0783

2. Decode the value encoded with payments role where the value is set to the returned encoded_value.

   $ vault write transform/decode/payments \        value=$ENCODED_OUTPUT

   Example output:

   Key              Value---              -----decoded_value    1111-2222-3333-4444

1. Encode a value with the payments role.

   $ ENCODED_OUTPUT=$(curl --header "X-Vault-Token: $VAULT_TOKEN" \     --header "X-Vault-Namespace: $VAULT_NAMESPACE" \     --request POST \     --data '{"value": "1111-2222-3333-4444"}' \     $VAULT_ADDR/v1/transform/encode/payments | jq -r ".data.encoded_value") \     && echo encoded_value: $ENCODED_OUTPUT

   Example output:

   encoded_value: "3330-9570-2888-3352"

2. Decode the value encoded with payments role.

   $ curl --header "X-Vault-Token: $VAULT_TOKEN" \     --header "X-Vault-Namespace: $VAULT_NAMESPACE" \     --request POST \     --data '{"value": '\"$ENCODED_OUTPUT\"'}' \     $VAULT_ADDR/v1/transform/decode/payments | jq ".data"

   Example output:

   {  "decoded_value": "1111-2222-3333-4444"}

   Note

   Refer to the batch input processing section for encoding and decoding multiple secrets in a single API call.

1. The transformation detail page displays a sample encode and decode commands.

   

   Copy the encode command.

2. Click the Vault CLI shell icon (>_) to open a command shell. Paste in the copied command with some test data.

   Example:

   $ vault write transform/encode/payments value="1111-2222-3333-4444"

   You can omit the transformation=card-number since the payments role only has one transformation attached.

   Press Enter to execute the command.

   

3. To decode the value, set the value to be the returned encoded_value and invoke the transform/decode/payments endpoint.

   Example:

   $ vault write transform/decode/payments value="3501-8042-9628-0343"

   

4. Close the Vault UI shell and click transform in the breadcrumb menu to return to the main Transform secrets engine configuration page.

1. Display all the exiting templates.

   $ vault list transform/template Keys----builtin/creditcardnumberbuiltin/socialsecuritynumber

2. Create a template named uk-passport-tmpl.

   $ vault write transform/template/uk-passport-tmpl \    type=regex \    pattern="(\d{9})" \    alphabet=builtin/numeric

   Example output:

   Success! Data written to: transform/template/uk-passport-tmpl

   This template uses the built-in alphabet, builtin/numeric.

3. Create a transformation named uk-passport with the uk-passport-tmpl template.

   $ vault write transform/transformations/fpe/uk-passport \    template=uk-passport-tmpl \    tweak_source=internal \    allowed_roles='*'

   Example output:

   Success! Data written to: transform/transformations/fpe/uk-passport

4. Update the payments role to include the uk-passport transformation.

   $ vault write transform/role/payments transformations=card-number,uk-passportSuccess! Data written to: transform/role/payments

   The payments role has two transformations. Future requests to encode/decode require that the specific transformation is provided.

5. Encode a value with the payments role with the uk-passport.

   $ ENCODED_OUTPUT=$(vault write transform/encode/payments value="123456789" \    transformation=uk-passport -format=json | jq -r '.data | .encoded_value') \    && echo encoded_value: $ENCODED_OUTPUT

   Example output:

   encoded_value: 128151714

1. Create an API request payload that describes the template.

   $ tee payload-template.json <<EOF{  "type": "regex",  "pattern": "(\\\d{9})",  "alphabet": "builtin/numeric"}EOF

   This template uses the built-in alphabet, builtin/numeric.

2. Create a template named uk-passport-tmpl.

   $ curl --header "X-Vault-Token: $VAULT_TOKEN" \     --header "X-Vault-Namespace: $VAULT_NAMESPACE" \     --request POST \     --data @payload-template.json \     $VAULT_ADDR/v1/transform/template/uk-passport-tmpl

   The transformation template is created.

3. Create an API request payload that describes a transformation.

   $ tee payload.json <<EOF{  "template": "uk-passport-tmpl",  "tweak_source": "internal",  "allowed_roles": ["*"]}EOF

   The payload uses the template uk-passport-tmpl.

4. Create a transformation named uk-passport.

   $ curl --header "X-Vault-Token: $VAULT_TOKEN" \     --header "X-Vault-Namespace: $VAULT_NAMESPACE" \     --request POST \     --data @payload.json \     $VAULT_ADDR/v1/transform/transformations/fpe/uk-passport

5. Update the payments role to include the uk-passport transformation.

   $ curl --header "X-Vault-Token: $VAULT_TOKEN" \     --header "X-Vault-Namespace: $VAULT_NAMESPACE" \     --request POST \     --data '{"transformations": ["uk-passport", "card-number"]}' \     $VAULT_ADDR/v1/transform/role/payments

   The payments role has two transformations. Future requests to encode/decode require that the specific transformation is provided.

6. Create an API request payload with a value and the uk-passport transformation.

   $ tee input.json <<EOF{  "value": "123456789",  "transformation": "uk-passport"}EOF

7. Encode a value with the payments role with the uk-passport transformation.

   $ curl --header "X-Vault-Token: $VAULT_TOKEN" \     --header "X-Vault-Namespace: $VAULT_NAMESPACE" \     --request POST \     --data @input.json \     $VAULT_ADDR/v1/transform/encode/payments | jq ".data"

   Example output:

   {  "encoded_value": "128151714"}

1. Select the Templates tab. Existing templates are listed.

   

2. In the Templates tab, click Create template.

   

3. Enter the following information:

   • Name - Enter uk-passport-tmpl
   • Pattern - Enter (\d{9})
   • Alphabet - Select builtin/numeric

   

4. Click Create template to complete.

5. Click transform in the breadcrumb menu to return to the Templates configuration page.

6. Select the Transformations tab and click Create transformation.

7. Enter the following information:

   • Name - Enter uk-passport
   • Type - Select Format Preserving Encryption (FPE)
   • Tweak source - Select internal
   • Template Name - Choose the uk-passport-tmpl you created earlier
   • Allowed roles - Select payments

   

8. Click Create transformation. The payments role has two transformations. Future requests to encode/decode require that the specific transformation is provided by passing the transformation parameter.

9. Click the Vault CLI shell icon (>_) to open a command shell. Paste in the copied command with some test data and the transformation parameter.

   $ vault write transform/encode/payments value="123456789" transformation=uk-passport

10. Click transform in the breadcrumb menu to return to the main Transform secrets engine configuration page.

1. Create a template named us-ssn-tmpl.

   $  vault write transform/template/us-ssn-tmpl \     type=regex \     pattern='(?:SSN[: ]?|ssn[: ]?)?(\d{3})[- ]?(\d{2})[- ]?(\d{4})' \     encode_format='$1-$2-$3' \     alphabet=builtin/numeric

   Example output:

   Success! Data written to: transform/template/us-ssn-tmpl

2. Create a transformation named us-ssn with the us-ssn-tmpl template.

   $ vault write transform/transformations/fpe/us-ssn \    template=us-ssn-tmpl \    tweak_source=internal \    allowed_roles='*'

   Example output:

   Success! Data written to: transform/transformations/fpe/us-ssn

3. Update the payments role to include the us-ssn transformation.

   $ vault write transform/role/payments transformations=card-number,uk-passport,us-ssnSuccess! Data written to: transform/role/payments

Validation

1. Encode values with the payments role with the us-ssn transformation.

   $ ENCODED_OUTPUT=$(vault write transform/encode/payments value="123-45-6789" \    transformation=us-ssn \    -format=json | jq -r '.data | .encoded_value') \    && echo encoded_value: $ENCODED_OUTPUT

   Example output:

   encoded_value: 489-82-2140

2. Try encoding value that starts with SSN.

   $ vault write transform/encode/payments value="SSN:$ENCODED_OUTPUT" \    transformation=us-ssn

   Example output:

   Key              Value---              -----encoded_value    766-52-7759

3. Try encoding value that starts with ssn.

   $  vault write transform/encode/payments value="ssn:$ENCODED_OUTPUT" \     transformation=us-ssn

   Example output:

   Key              Value---              -----encoded_value    766-52-7759

4. Decode the value encoded with the payments role with the us-ssn transformation where the value is set to the encoded_value.

   $ vault write transform/decode/payments value="$ENCODED_OUTPUT" \    transformation=us-ssn

   Example output:

   Key              Value---              -----decoded_value    123-45-6789

1. Create an API request payload that describes the template.

   $ tee payload-template.json <<EOF{  "type": "regex",  "pattern": "(?:SSN[: ]?|ssn[: ]?)?(\\\\d{3})[- ]?(\\\\d{2})[- ]?(\\\\d{4})",  "encode_format": "\$1-\$2-\$3",  "alphabet": "builtin/numeric"}EOF

2. Create a template named us-ssn-tmpl.

   $ curl --header "X-Vault-Token: $VAULT_TOKEN" \     --header "X-Vault-Namespace: $VAULT_NAMESPACE" \     --request POST \     --data @payload-template.json \     $VAULT_ADDR/v1/transform/template/us-ssn-tmpl

3. Create an API request payload that describes a transformation.

   $ tee payload.json <<EOF{  "template":"us-ssn-tmpl",  "tweak_source":"internal",  "allowed_roles":"*"}EOF

4. Create a transformation named us-ssn with the us-ssn-tmpl template.

   $ curl --header "X-Vault-Token: $VAULT_TOKEN" \     --header "X-Vault-Namespace: $VAULT_NAMESPACE" \     --request POST \     --data @payload.json \     $VAULT_ADDR/v1/transform/transformations/fpe/us-ssn

5. Update the payments role to include the us-ssn transformation.

   $ curl --header "X-Vault-Token: $VAULT_TOKEN" \     --header "X-Vault-Namespace: $VAULT_NAMESPACE" \     --request POST \     --data '{"transformations": ["uk-passport", "card-number", "us-ssn"]}' \     $VAULT_ADDR/v1/transform/role/payments

Validation

1. Encode values with the payments role with the us-ssn transformation.

   $ ENCODED_OUTPUT=$(curl --header "X-Vault-Token: $VAULT_TOKEN" \     --header "X-Vault-Namespace: $VAULT_NAMESPACE" \     --request POST \     --data '{"value": "123-45-6789", "transformation": "us-ssn"}' \     $VAULT_ADDR/v1/transform/encode/payments | jq ".data.encoded_value") \     && echo encoded_value: $ENCODED_OUTPUT

   Example output:

   encoded_value: "766-52-7759"

2. Try encoding value that starts with SSN.

   $ curl --header "X-Vault-Token: $VAULT_TOKEN" \     --header "X-Vault-Namespace: $VAULT_NAMESPACE" \     --request POST \     --data '{"value": "SSN:123 45 6789", "transformation": "us-ssn"}' \     $VAULT_ADDR/v1/transform/encode/payments | jq ".data"

   Example output:

   {  "encoded_value": "766-52-7759"}

3. Try encoding value that starts with ssn.

   $ curl --header "X-Vault-Token: $VAULT_TOKEN" \     --header "X-Vault-Namespace: $VAULT_NAMESPACE" \     --request POST \     --data '{"value": "ssn:123456789", "transformation": "us-ssn"}' \     $VAULT_ADDR/v1/transform/encode/payments | jq ".data"

   Example output:

   {  "encoded_value": "766-52-7759"}

4. Decode the value encoded with the payments role with the us-ssn transformation where value is set to the encoded_value.

   $ curl --header "X-Vault-Token: $VAULT_TOKEN" \     --header "X-Vault-Namespace: $VAULT_NAMESPACE" \     --request POST \     --data '{"value": '"$ENCODED_OUTPUT"', "transformation": "us-ssn"}' \     $VAULT_ADDR/v1/transform/decode/payments | jq ".data"

   Example output:

   {  "decoded_value": "123-45-6789"}

1. Create a template named us-ssn-tmpl.

   $  vault write transform/template/us-ssn-tmpl \     type=regex \     pattern='(?:SSN[: ]?|ssn[: ]?)?(\d{3})[- ]?(\d{2})[- ]?(\d{4})' \     encode_format='$1-$2-$3' \     decode_formats=space-separated='$1 $2 $3' \     decode_formats=last-four='*** ** $3' \     alphabet=builtin/numeric

   Example output:

   Success! Data written to: transform/template/us-ssn-tmpl

2. Create a transformation named us-ssn with the us-ssn-tmpl template.

   $ vault write transform/transformations/fpe/us-ssn \    template=us-ssn-tmpl \    tweak_source=internal \    allowed_roles='*'

   Example output:

   Success! Data written to: transform/transformations/fpe/us-ssn

3. Update the payments role to include the us-ssn transformation.

   $ vault write transform/role/payments transformations=card-number,uk-passport,us-ssnSuccess! Data written to: transform/role/payments

4. Encode values with the payments role with the us-ssn transformation.

   $ ENCODED_OUTPUT=$(vault write transform/encode/payments value="123-45-6789" \    transformation=us-ssn \    -format=json | jq -r '.data | .encoded_value') \    && echo encoded_value: $ENCODED_OUTPUT

   Example output:

   encoded_value: 489-82-2140

5. Decode values with the payments role, the us-ssn transformation and the space-separated decoding format.

   $ vault write transform/decode/payments/space-separated value="$ENCODED_OUTPUT" \     transformation=us-ssn

   Example output:

   Key              Value---              -----decoded_value    123 45 6789

6. Decode values with the payments role, the us-ssn transformation and the last-four decoding format.

   $ vault write transform/decode/payments/last-four value="$ENCODED_OUTPUT" \     transformation=us-ssn

   Example output:

   Key              Value---              -----decoded_value    *** ** 6789

1. Create an API request payload that describes the template.

   $ tee payload-template.json <<EOF{  "type": "regex",  "pattern": "(?:SSN[: ]?|ssn[: ]?)?(\\\\d{3})[- ]?(\\\\d{2})[- ]?(\\\\d{4})",  "encode_format": "\$1-\$2-\$3",  "decode_formats": {    "space-separated": "\$1 \$2 \$3",    "last-four": "*** ** \$3"  },  "alphabet": "builtin/numeric"}EOF

2. Create a template named us-ssn-tmpl.

   $ curl --header "X-Vault-Token: $VAULT_TOKEN" \     --header "X-Vault-Namespace: $VAULT_NAMESPACE" \     --request POST \     --data @payload-template.json \     $VAULT_ADDR/v1/transform/template/us-ssn-tmpl

3. Create an API request payload that describes a transformation.

   $ tee payload.json <<EOF{  "template":"us-ssn-tmpl",  "tweak_source":"internal",  "allowed_roles":"*"}EOF

4. Create a transformation named us-ssn with the us-ssn-tmpl template.

   $ curl --header "X-Vault-Token: $VAULT_TOKEN" \     --header "X-Vault-Namespace: $VAULT_NAMESPACE" \     --request POST \     --data @payload.json \     $VAULT_ADDR/v1/transform/transformations/fpe/us-ssn

5. Update the payments role to include the us-ssn transformation.

   $ curl --header "X-Vault-Token: $VAULT_TOKEN" \     --header "X-Vault-Namespace: $VAULT_NAMESPACE" \     --request POST \     --data '{"transformations": ["uk-passport", "card-number", "us-ssn"]}' \     $VAULT_ADDR/v1/transform/role/payments

6. Encode values with the payments role with the us-ssn transformation.

   $ ENCODED_OUTPUT=$(curl --header "X-Vault-Token: $VAULT_TOKEN" \     --header "X-Vault-Namespace: $VAULT_NAMESPACE" \     --request POST \     --data '{"value": "123-45-6789", "transformation": "us-ssn"}' \     $VAULT_ADDR/v1/transform/encode/payments | jq ".data.encoded_value") \     && echo encoded_value: $ENCODED_OUTPUT

   Example output:

   encoded_value: "766-52-7759"

7. Decode values with the payments role, the us-ssn transformation and the space-separated decoding format.

   $ curl --header "X-Vault-Token: $VAULT_TOKEN" \     --header "X-Vault-Namespace: $VAULT_NAMESPACE" \     --request POST \     --data '{"value": '"$ENCODED_OUTPUT"', "transformation": "us-ssn"}' \     $VAULT_ADDR/v1/transform/decode/payments/space-separated | jq ".data"

   Example output:

   {  "encoded_value": "123 45 6789"}

8. Decode values with the payments role, the us-ssn transformation and the last-four decoding format.

   $ curl --header "X-Vault-Token: $VAULT_TOKEN" \     --header "X-Vault-Namespace: $VAULT_NAMESPACE" \     --request POST \     --data '{"value": '"$ENCODED_OUTPUT"', "transformation": "us-ssn"}' \     $VAULT_ADDR/v1/transform/decode/payments/last-four | jq ".data"

   Example output:

   {  "encoded_value": "*** ** 6789"}

1. Define the policy in the file named last-four.hcl.

   $ tee last-four.hcl <<EOF# Allow decoding using only the last-four decode formatpath "transform/decode/payments/last-four"{    capabilities = ["update"]}EOF

2. Create the last-four with the policy defined in last-four.hcl.

   $ vault policy write last-four last-four.hclSuccess! Uploaded policy: us-ssn-last-four

3. Create a token with the last-four policy attached and store the token in the variable $LAST_FOUR_TOKEN.

   $ LAST_FOUR_TOKEN=$(vault token create -format=json -policy="last-four" | jq -r ".auth.client_token")

4. Using the token, decode values with the payments role, the us-ssn transformation and the last-four decoding format.

   $ VAULT_TOKEN=$LAST_FOUR_TOKEN vault write transform/decode/payments/last-four \     value="766-52-7759" \     transformation=us-ssn

   Example output:

   Key              Value---              -----decoded_value    *** ** 6789

5. Trying to use the token to decode with the payments role with the us-ssn transformation with the space-separated decode format, or without specifying a decode format will fail.

   $ VAULT_TOKEN=$LAST_FOUR_TOKEN vault write transform/decode/payments \     value="766-52-7759" \     transformation=us-ssn

   Example output:

   Error writing data to transform/decode/payments: Error making API request.URL: PUT http://localhost:8200/v1/transform/decode/paymentsCode: 403. Errors:* 1 error occurred:    * permission denied

1. Define the policy in the file named last-four.hcl.

   $ tee last-four.json <<EOF{  "policy": "# Allow decoding using only the last-four decode format\npath \"transform/decode/payments/last-four\"\n{\n    capabilities = [\"update\"]\n}\n"}EOF

2. Create the last-four with the policy defined in last-four.hcl.

   $ curl --header "X-Vault-Token: $VAULT_TOKEN" \     --header "X-Vault-Namespace: $VAULT_NAMESPACE" \     --request POST \     --data @last-four.json \     $VAULT_ADDR/v1/sys/policies/acl/last-four

3. Create a token with the last-four policy attached and store the token in the variable $LAST_FOUR_TOKEN.

   $ LAST_FOUR_TOKEN=$(curl --request POST --header "X-Vault-Token: $VAULT_TOKEN" \     --header "X-Vault-Namespace: $VAULT_NAMESPACE" \     --data '{ "policies":"last-four" }' \     $VAULT_ADDR/v1/auth/token/create | jq -r ".auth.client_token")

4. Using the token, decode values with the payments role, the us-ssn transformation and the last-four decoding format.

   $ curl --header "X-Vault-Token: $LAST_FOUR_TOKEN" \     --header "X-Vault-Namespace: $VAULT_NAMESPACE" \     --request POST \     --data '{"value": '"$ENCODED_OUTPUT"', "transformation": "us-ssn"}' \     $VAULT_ADDR/v1/transform/decode/payments/last-four | jq ".data"

   Example output:

   {  "decoded_value": "*** ** 6789"}

5. Try to use the token to decode with the payments role with the us-ssn transformation with the space-separated decode format, or without specifying a decode format will fail.

   $ curl --header "X-Vault-Token: $LAST_FOUR_TOKEN" \     --header "X-Vault-Namespace: $VAULT_NAMESPACE" \     --request POST \     --data '{"value": '"$ENCODED_OUTPUT"', "transformation": "us-ssn"}' \     $VAULT_ADDR/v1/transform/decode/payments

   Example output:

   {"errors":["1 error occurred:\n\t* permission denied\n\n"]}

Display existing alphabets.

$ vault list transform/alphabet Keys----builtin/alphalowerbuiltin/alphanumericbuiltin/alphanumericlowerbuiltin/alphanumericupperbuiltin/alphaupperbuiltin/numeric

Create an alphabet named non-zero-numeric.

$ vault write transform/alphabet/non-zero-numeric alphabet="123456789"Success! Data written to: transform/alphabet/non-zero-numeric

This new alphabet consists of only characters from the provided set 123456789.

Create an alphabet named non-zero-numeric.

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \     --header "X-Vault-Namespace: $VAULT_NAMESPACE" \     --request POST \     --data '{"alphabet": "123456789"}' \     $VAULT_ADDR/v1/transform/alphabet/non-zero-numeric

This new alphabet consists of only characters from the provided set 123456789.

1. Select the Alphabets tab to display existing alphabets.

   

2. Click Create alphabet.

3. Enter the following information:

   • Name - Enter non-zero-numeric
   • Alphabet - Enter 123456789

   

4. Click Create alphabet to complete. Once created, it is available for use in other templates and transformations.

5. Click transform in the breadcrumb menu to return to the transform configuration page.

1. Create a template named "phone-number-tmpl" with country code.

   $ vault write transform/template/phone-number-tmpl type=regex \    pattern="\+\d{1,2} (\d{3})-(\d{3})-(\d{4})" \    alphabet=builtin/numeric

   Example output:

   Success! Data written to: transform/template/phone-number-tmpl

2. Create a transformation named "phone-number" with the phone-number-tmpl template and allow all roles to use it.

   $ vault write transform/transformations/masking/phone-number \    template=phone-number-tmpl \    masking_character=# \    allowed_roles='*'

   Example output:

   Success! Data written to: transform/transformations/masking/phone-number

   The type is set to masking and specifies the masking_character value instead of tweak_source. The default masking character is * if you don't specify one.

3. Test and verify the newly created phone-number mask transformation by adding the phone-number transformation to the payments role.

   $ vault write transform/role/payments \    transformations=card-number,uk-passport,phone-number

   Example output:

   Success! Data written to: transform/role/payments

4. Encode a value with the payments role with the phone-number transformation.

   $ vault write transform/encode/payments value="+1 123-345-5678" \    transformation=phone-number

   Example output:

   Key              Value---              -----encoded_value    +1 ###-###-####

Create a template named "phone-number-tmpl" with country code.

1. Create an API request payload.

   $ tee payload-template.json <<EOF{  "type": "regex",  "pattern": "\\\+\\\d{1,2} (\\\d{3})-(\\\d{3})-(\\\d{4})",  "alphabet": "builtin/numeric"}EOF

2. Create a new template named phone-number-tmpl.

   $ curl --header "X-Vault-Token: $VAULT_TOKEN" \     --header "X-Vault-Namespace: $VAULT_NAMESPACE" \     --request POST \     --data @payload-template.json \     $VAULT_ADDR/v1/transform/template/phone-number-tmpl

3. Create an API request payload for the transformation named phone-number with the phone-number-tmpl template and allow all roles to use it.

   $ tee payload.json <<EOF{  "template": "phone-number-tmpl",  "masking_character": "#",  "allowed_roles": ["*"]}EOF

4. Create a transformation named phone-number.

   $ curl --header "X-Vault-Token: $VAULT_TOKEN" \     --header "X-Vault-Namespace: $VAULT_NAMESPACE" \     --request POST \     --data @payload.json \     $VAULT_ADDR/v1/transform/transformations/masking/phone-number

5. Verify the newly created phone-number mask transformation by adding the phone-number transformation to the payments role.

   $ curl --header "X-Vault-Token: $VAULT_TOKEN" \     --header "X-Vault-Namespace: $VAULT_NAMESPACE" \     --request POST \     --data '{"transformations": ["uk-passport","card-number","phone-number"]}' \     $VAULT_ADDR/v1/transform/role/payments

6. Create an API request payload with a value and the phone-number transformation.

   $ tee input.json <<EOF{  "value": "+1 123-345-5678",  "transformation": "phone-number"}EOF

7. Encode a value with the payments role with the phone-number transformation.

   $ curl --header "X-Vault-Token: $VAULT_TOKEN" \     --header "X-Vault-Namespace: $VAULT_NAMESPACE" \     --request POST \     --data @input.json \     $VAULT_ADDR/v1/transform/encode/payments | jq ".data"

   Example output:

   {  "encoded_value": "+1 ###-###-####"}

   Note

   Refer to the batch input processing section for encoding and decoding multiple secrets in a single API call.

1. Click the Templates tab and click Create template.

   

2. Enter the following information:

   • Name - Enter phone-number-tmpl
   • Pattern - Enter \+\d{1,2} (\d{3})-(\d{3})-(\d{4})
   • Alphabet - Select builtin/numeric

   

3. Click Create template to complete.

4. Click transform in the breadcrumb menu to return to the Templates configuration page.

5. Click the Transformations tab and click Create transformation.

6. Enter the following information:

   • Name - Enter phone-number
   • Type - Select Masking
   • Masking Character - Enter #
   • Template Choose the phone-number-tmpl you created earlier
   • Allowed roles - Enter * to allow all roles to use this transformation

   

7. Click Create transformation to complete.

$ vault read -field=public_key transform/wrapping_key-----BEGIN PUBLIC KEY-----MIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEA0aBVXa1Z8X1n1z3smBjUJ+Vm16AznaIrDxWrMAEsQt8xqh33gNMdzsdhNGy0+UzF2mxs9lUbp3uXJxqSaJDBB+yeSqB4svgcQneg5pZnpZ1Af1s8X6uHTjZZxlHpJ0wumA//zWwg+0TtDij16C5oQpep7+UqA9qEcVheCP4puyQXssGH6vwbV4nspNTd1E5RgXe9xpdUKW+ih0pJWbNNwiW1L6YP8F6dQ4adr6Nm/UUoTpKnvdippT980SLFrkl7v6xh+UKC51bS5fxtQ4XldFCZYWO+Z7HCu3dWEte0Q5vhvbDLCJYKQ/avsQ8EXJtBYzKS7rtvDOYZLOFAgGs4yeUgVOaIEHXmp+r7CdXnMlo9/5qN02i16HavTgQvaBbPclgH2NWE2JP4sKNsFfyFDIL9btnUjjgTl6/KaxlVBmZyx96A0V1UTEphziFgeUVw2Rc7PkyOX9lXdAu34A3i0kgjZC1Y8x/TnGWJ4ofyFBM8RmSaoe4e9C2i2VjHFzJX3ya53Rewy/e+MdvG3tlItIEXoanXtTAPbpBJw9tY4FLO8WFsQuBiYg/ovO3ZcYzK5tZwdPnWLjgiXitFchUss0lEYFARLap6i/nXxmJnE8jJeAoZ6QSOpNf9ss4rIM9liFvHy+O5Fb3qRLg4zu9MERqkZVYfyxp4bChyZwOJD+ECAwEAAQ==-----END PUBLIC KEY-----

The output is the (4096-bit RSA) wrapping key.

$ curl --header "X-Vault-Token: $VAULT_TOKEN" \     --header "X-Vault-Namespace: $VAULT_NAMESPACE" \     --request GET --silent \     $VAULT_ADDR/v1/transform/wrapping_key | jq

Example output:

{  "request_id": "03f42f4b-c216-fb54-50f9-a8b2683ba8f6",  "lease_id": "",  "renewable": false,  "lease_duration": 0,  "data": {    "public_key": "-----BEGIN PUBLIC KEY-----\nMIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEA0aBVXa1Z8X1n1z3smBjU\nJ+Vm16AznaIrDxWrMAEsQt8xqh33gNMdzsdhNGy0+UzF2mxs9lUbp3uXJxqSaJDB\nB+yeSqB4svgcQneg5pZnpZ1Af1s8X6uHTjZZxlHpJ0wumA//zWwg+0TtDij16C5o\nQpep7+UqA9qEcVheCP4puyQXssGH6vwbV4nspNTd1E5RgXe9xpdUKW+ih0pJWbNN\nwiW1L6YP8F6dQ4adr6Nm/UUoTpKnvdippT980SLFrkl7v6xh+UKC51bS5fxtQ4Xl\ndFCZYWO+Z7HCu3dWEte0Q5vhvbDLCJYKQ/avsQ8EXJtBYzKS7rtvDOYZLOFAgGs4\nyeUgVOaIEHXmp+r7CdXnMlo9/5qN02i16HavTgQvaBbPclgH2NWE2JP4sKNsFfyF\nDIL9btnUjjgTl6/KaxlVBmZyx96A0V1UTEphziFgeUVw2Rc7PkyOX9lXdAu34A3i\n0kgjZC1Y8x/TnGWJ4ofyFBM8RmSaoe4e9C2i2VjHFzJX3ya53Rewy/e+MdvG3tlI\ntIEXoanXtTAPbpBJw9tY4FLO8WFsQuBiYg/ovO3ZcYzK5tZwdPnWLjgiXitFchUs\ns0lEYFARLap6i/nXxmJnE8jJeAoZ6QSOpNf9ss4rIM9liFvHy+O5Fb3qRLg4zu9M\nERqkZVYfyxp4bChyZwOJD+ECAwEAAQ==\n-----END PUBLIC KEY-----\n"  },  "wrap_info": null,  "warnings": null,  "auth": null}

The output is a JSON object with a data.public_key field containing the (4096-bit RSA) wrapping key.

$ vault write transform/template/identifier \    type=regex \    pattern="(\b[A-Z\d]{8}\b)[-/](\b[A-Z\d]{4}\b)[-/](\b[A-Z\d]{4}\b)[-/](\b[A-Z\d]{4}\b)[-/](\b[A-Z\d]{12}\b)" \    alphabet=builtin/alphanumericupper

Example output:

Success! Data written to: transit/template/identifier

Create a JSON payload containing the template configuration; because the regular expression used will result in invalid JSON errors unless stringified, you can base64 encode the entire JSON payload, assign it to the environment variable JSON_PAYLOAD_B64, and supply the environment variable for the data in the template creation step.

$ export JSON_PAYLOAD_B64=$(base64 - << EOF{  "type": "regex",  "alphabet": "builtin/alphanumericupper",  "pattern": "(\b[A-Z\d]{8}\b)[-/](\b[A-Z\d]{4}\b)[-/](\b[A-Z\d]{4}\b)[-/](\b[A-Z\d]{4}\b)[-/](\b[A-Z\d]{12}\b)"}EOF)

Create the template.

$ curl \    --silent \    --header "X-Vault-Token: $VAULT_TOKEN" \    --header "X-Vault-Namespace: $VAULT_NAMESPACE" \    --request POST \    --data $JSON_PAYLOAD_B64 \    $VAULT_ADDR/v1/transform/template/identifier

$ vault write transform/transformations/fpe/proximity-card/import \    ciphertext=$IMPORT_CIPHERTEXT \    allowed_roles=physical-access \    template=identifier \    tweak_source=internal

Example output:

Success! Data written to: transform/transformations/fpe/proximity-card/import

Create a JSON payload containing ciphertext value and any additional parameters.

$ cat > payload.json << EOF{  "ciphertext": "XQiDLXkoN2nE3UXIUnNb4joUSUDyB0OsD/U0T3WpSGuatB2Rd89yj57v1eDb2RDq8tt904iCftDY1c4fJXBlNhvZtRgS45zV+hZZA806YZ2a2ha3rFFEEobRLxs0aCoyq+iqBsOxG4pHG5irtzqfPz5IJRtN0SXxcoOodRm0hGU69++iZO5GkJ8k6Y4513Y/Qwnm/4rBToE9E6toQSTf7exF3yp0wxe/GSfFKCr2aVvYnyK0j+UYNbDeK0M7JOSQ38JmC62oPEfYdI+onyzQxQJsXec/5GOZWsuNnhZtvDNeslnAoC20HiMxl2aMQn4PAvWO+HtlhleXKjaWgDuopgj+qjsSny72pKo2hSntGsamaPqVZQHDmYpIQP4aBsqQeq5bXtDc407cAEPl+MA5huzazdNgMeZqCYZNYFPlUVtZ2dJ6A9ogFE7B8RLAEf4t717kTvlQ0qsXwXOGtoFuw/AQGMTF1CNmCVEJWZBPkxH6GXT6N3QAgwRMYVP6r//IAZ4FKmZ8V4nwmp2uBN0H49XekH1yULa3lWGSXx3CGGy3hYuUHGi6B7mWEH7B0jQgk3EtU1JlgtpTk/jlnL7mpa8VRZefAZqFDX6DoEjioXtqbQAA1Vvkke/PDN3OL6a5aj9kr2UJvlRPfwYsSHw+l8oyazrLs8aKHiaVJAfsVD5y02ipMIGFwaUjswYeW1LxtXg4FVfINzUAoq7z9mvQDby1mvh0Mtr9", "allowed_roles": "physical-access", "template": "identifier", "tweak_source": "internal"}EOF

Import the key.

$ curl \    --header "X-Vault-Token: $VAULT_TOKEN" \    --header "X-Vault-Namespace: $VAULT_NAMESPACE" \    --request POST \    --data @payload.json \    $VAULT_ADDR/v1/transform/transformations/fpe/proximity-card/import

Create a JSON payload.

$ cat > payload.json << EOF{  "value": "19742EC3-3C8A-B0C2-23C0-A039ECA9DD23",  "transformation": "proximity-card"}EOF

Encode the values.

$ curl \    --silent \    --header "X-Vault-Token: $VAULT_TOKEN" \    --header "X-Vault-Namespace: $VAULT_NAMESPACE" \    --request POST \    --data @payload.json \    $VAULT_ADDR/v1/transform/encode/physical-access | jq

Example output:

{  "request_id": "b7c8af19-2437-4a8f-ea44-c481fba254c6",  "lease_id": "",  "renewable": false,  "lease_duration": 0,  "data": {    "encoded_value": "OGCIWU8A-RBW0-R7FJ-8IZZ-VZZRIWZQ3P5Z"  },  "wrap_info": null,  "warnings": null,  "auth": null}