luxolus
/
open-vault
2
0
Fork 0
Code Issues 1 Pull Requests Releases Activity

Update docs with Transform FPE advanced I/O handling features (#12744)

This commit is contained in:
Victor Rodriguez 2021-10-15 14:51:53 -04:00 committed by GitHub
parent 66369469d9
commit 70a9636575
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 127 additions and 49 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

155
website/content/api-docs/secret/transform.mdx
View File

@ -455,8 +455,8 @@ template exists, it will be updated with the new attributes.
request URL. request URL.
- `type` `(string: <required>)` - - `type` `(string: <required>)` -
Specifies the type of pattern matching to perform. The ony type currently supported Specifies the type of pattern matching to perform. The only type currently
by this backend is `regex`. supported by this backend is `regex`.
- `pattern` `(string: <required>)` - - `pattern` `(string: <required>)` -
Specifies the pattern used to match a particular value. For regex type Specifies the pattern used to match a particular value. For regex type
@ -468,13 +468,28 @@ template exists, it will be updated with the new attributes.
Specifies the name of the alphabet to use when this template is used for FPE Specifies the name of the alphabet to use when this template is used for FPE
encoding and decoding operations. encoding and decoding operations.
- `encode_format` `(string)` -
The regular expression template to use to format encoded values. This can be
used to normalize the encoded output. This is only used during FPE
transformations.
- `decode_formats` `(key-value-map: {})` -
An optional map of regular expression templates that can be used to customize
decoded output. For example, this can be used to decode only the last four
digits of a credit card number. This is only used during FPE transformations.
### Sample Payload ### Sample Payload
```json ```json
{ {
"type": "regex", "type": "regex",
"pattern": "(\\d{9})", "alphabet": "builtin/numeric",
"alphabet": "builtin/numeric" "pattern": "(\\d{3})[-/](\\d{2})[-/](\\d{4})",
"encode_format": "$1-$2-$3",
"decode_formats": {
"first-three": "$1",
"last-four": "$3"
}
} }
``` ```
@ -513,7 +528,12 @@ $ curl \
{ {
"data": { "data": {
"alphabet": "builtin/numeric", "alphabet": "builtin/numeric",
"pattern": "(\\d{9})", "decode_formats": {
"first-three": "$1",
"last-four": "$3"
},
"encode_format": "$1-$2-$3",
"pattern": "(\\d{3})[-/](\\d{2})[-/](\\d{4})",
"type": "regex" "type": "regex"
} }
} }
@ -708,9 +728,6 @@ The database user configured here should only have permission to `SELECT`,
Specifies the database driver to use, and thus which SQL database type. Specifies the database driver to use, and thus which SQL database type.
Currently the supported options are `postgres` or `mysql` Currently the supported options are `postgres` or `mysql`
- `supported_transformations: `(list: ["tokenization"])` The types of transformations this store can host. Currently only`tokenization`
is supported.
- `connection_string` `(string: <required>)` - - `connection_string` `(string: <required>)` -
A database connection string with template slots for username and password that A database connection string with template slots for username and password that
Vault will use for locating and connecting to a database. Each Vault will use for locating and connecting to a database. Each
@ -724,6 +741,9 @@ The database user configured here should only have permission to `SELECT`,
- `password`: `(string: <required>)` - - `password`: `(string: <required>)` -
The password value to use when connecting to the database. The password value to use when connecting to the database.
- `supported_transformations: `(list: ["tokenization"])` The types of transformations this store can host. Currently only`tokenization`
is supported.
- `schema`: `(string: "public")` - - `schema`: `(string: "public")` -
The schema within the database to expect tokenization state tables. The schema within the database to expect tokenization state tables.
@ -734,7 +754,7 @@ The database user configured here should only have permission to `SELECT`,
The maximum number of idle connections to the database at any given time. The maximum number of idle connections to the database at any given time.
- `max_connection_lifetime` `(duration: 0)` - - `max_connection_lifetime` `(duration: 0)` -
The maximum amount of time a connection can be open before closing it. The maximum amount of time a connection can be open before closing it.
0 means no limit. 0 means no limit.
### Sample Payloads ### Sample Payloads
@ -787,15 +807,15 @@ operation.
Specifies the name of the store to create or update. This is part of Specifies the name of the store to create or update. This is part of
the request URL. the request URL.
- `transformation_type`: `(string: "tokenization")` -
The transformation type. Currently only tokenization is supported.
- `username`: `(string: <required>)` - - `username`: `(string: <required>)` -
The username value to use when connecting to the database. The username value to use when connecting to the database.
- `password`: `(string: <required>)` - - `password`: `(string: <required>)` -
The password value to use when connecting to the database. The password value to use when connecting to the database.
- `transformation_type`: `(string: "tokenization")` -
The transformation type. Currently only `tokenization` is supported.
### Sample Payload ### Sample Payload
```json ```json
@ -934,16 +954,17 @@ This endpoint encodes the provided value using a named role.
transformations with `supplied` as the tweak source. The tweak must be a transformations with `supplied` as the tweak source. The tweak must be a
7-byte value that is then base64 encoded. 7-byte value that is then base64 encoded.
- `reference` `(string: "")` - - `reference` `(string: "")` -
Only valid on batch requests using 'batch_input' below. A user supplied A user-supplied string that will be present in the `reference` field on the
string that will be present on the corresponding item in the batch corresponding `batch_results` item in the response, to assist in understanding
response, to assist in correlating inputs with outputs. which result corresponds to a particular input. Only valid on batch requests
when using ‘batch_input’ below.
- `batch_input` `(array<object>: nil)` - - `batch_input` `(array<object>: nil)` -
Specifies a list of items to be encoded in a single batch. When this Specifies a list of items to be encoded in a single batch. When this
parameter is set, the 'value', 'transformation', 'ttl', 'tweak' and parameter is set, the 'value', 'transformation', 'ttl', 'tweak' and
'reference' parameters are ignored. Instead, the aforementioned parameters 'reference' parameters are ignored. Instead, the aforementioned parameters
should be provided within each object in the list. should be provided within each object in the list.
```json ```json
[ [
@ -1048,9 +1069,9 @@ $ curl \
This endpoint decodes the provided value using a named role. This endpoint decodes the provided value using a named role.
| Method | Path | | Method | Path |
| :----- | :----------------------------- | | :----- | :---------------------------------------------- |
| `POST` | `/transform/decode/:role_name` | | `POST` | `/transform/decode/:role_name(/:decode_format)` |
### Parameters ### Parameters
@ -1061,6 +1082,13 @@ This endpoint decodes the provided value using a named role.
- `value` `(string: <required>)` – - `value` `(string: <required>)` –
Specifies the value to be decoded. Specifies the value to be decoded.
- `decode_format` `(string)` -
The name of the decode format to use for decoding. These are defined in
`decode_formats` when creating the transformation's template, and can be used
to selectively decode or format the output. If one is not defined or
specified, the template's pattern will be used. Only applicable for FPE
transformations.
- `transformation` `(string)` – - `transformation` `(string)` –
Specifies the transformation within the role that should be used for this Specifies the transformation within the role that should be used for this
decode operation. If a single transformation exists for role, this parameter decode operation. If a single transformation exists for role, this parameter
@ -1071,16 +1099,17 @@ This endpoint decodes the provided value using a named role.
applicable for FPE transformations with `supplied` or `generated` as the tweak applicable for FPE transformations with `supplied` or `generated` as the tweak
source. The tweak must be a 7-byte value that is then base64 encoded. source. The tweak must be a 7-byte value that is then base64 encoded.
- `reference` `(string: "")` - - `reference` `(string: "")` -
Only valid on batch requests using 'batch_input' below. A user supplied A user-supplied string that will be present in the `reference` field on the
string that will be present on the corresponding item in the batch corresponding `batch_results` item in the response, to assist in understanding
response, to assist in correlating inputs with outputs. which result corresponds to a particular input. Only valid on batch requests
when using ‘batch_input’ below.
- `batch_input` `(array<object>: nil)` - - `batch_input` `(array<object>: nil)` -
Specifies a list of items to be encoded in a single batch. When this Specifies a list of items to be decoded in a single batch. When this
parameter is set, the 'value', 'transformation', 'tweak' and parameter is set, the 'value', 'transformation', 'tweak' and
'reference' parameters are ignored. Instead, the aforementioned parameters 'reference' parameters are ignored. Instead, the aforementioned parameters
should be provided within each object in the list. should be provided within each object in the list.
```json ```json
[ [
@ -1093,10 +1122,10 @@ This endpoint decodes the provided value using a named role.
### Sample Payload ### Sample Payload
```json ```json
{ {
"value": "5682-4613-6822-8064", "value": "418-56-4374",
"transformation": "ccn-fpe" "transformation": "example-transformation"
} }
``` ```
@ -1107,7 +1136,7 @@ $ curl \
--header "X-Vault-Token: ..." \ --header "X-Vault-Token: ..." \
--request POST \ --request POST \
--data @payload.json \ --data @payload.json \
http://127.0.0.1:8200/v1/transform/encode/example-role http://127.0.0.1:8200/v1/transform/decode/example-role
``` ```
### Sample Response ### Sample Response
@ -1115,7 +1144,36 @@ $ curl \
```json ```json
{ {
"data": { "data": {
"decoded_value": "1111-2222-3333-4444" "decoded_value": "111-22-3333"
}
}
```
### Sample Payload
```json
{
"value": "418-56-4374",
"transformation": "example-transformation"
}
```
### Sample Request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/transform/decode/example-role/last-four
```
### Sample Response
```json
{
"data": {
"decoded_value": "4444"
} }
} }
``` ```
@ -1190,16 +1248,17 @@ Only valid for tokenization transformations.
may be skipped and will be inferred. If multiple transformations exist, one may be skipped and will be inferred. If multiple transformations exist, one
must be specified. must be specified.
- `reference` `(string: "")` - - `reference` `(string: "")` -
Only valid on batch requests using 'batch_input' below. A user supplied A user-supplied string that will be present in the `reference` field on the
string that will be present on the corresponding item in the batch corresponding `batch_results` item in the response, to assist in understanding
response, to assist in correlating inputs with outputs. which result corresponds to a particular input. Only valid on batch requests
when using ‘batch_input’ below.
- `batch_input` `(array<object>: nil)` - - `batch_input` `(array<object>: nil)` -
Specifies a list of items to be validated in a single batch. When this Specifies a list of items to be validated in a single batch. When this
parameter is set, the 'value', 'transformation' and parameter is set, the 'value', 'transformation' and
'reference' parameters are ignored. Instead, the aforementioned parameters 'reference' parameters are ignored. Instead, the aforementioned parameters
should be provided within each object in the list. should be provided within each object in the list.
```json ```json
[ [
@ -1265,10 +1324,11 @@ transformations.
may be skipped and will be inferred. If multiple transformations exist, one may be skipped and will be inferred. If multiple transformations exist, one
must be specified. must be specified.
- `reference` `(string: "")` - - `reference` `(string: "")` -
Only valid on batch requests using 'batch_input' below. A user supplied A user-supplied string that will be present in the `reference` field on the
string that will be present on the corresponding item in the batch corresponding `batch_results` item in the response, to assist in understanding
response, to assist in correlating inputs with outputs. which result corresponds to a particular input. Only valid on batch requests
when using ‘batch_input’ below.
- `batch_input` `(array<object>: nil)` - - `batch_input` `(array<object>: nil)` -
Specifies a list of items to be decoded in a single batch. When this Specifies a list of items to be decoded in a single batch. When this
@ -1339,10 +1399,11 @@ Only valid for tokenization transformations.
may be skipped and will be inferred. If multiple transformations exist, one may be skipped and will be inferred. If multiple transformations exist, one
must be specified. must be specified.
- `reference` `(string: "")` - - `reference` `(string: "")` -
Only valid on batch requests using 'batch_input' below. A user supplied A user-supplied string that will be present in the `reference` field on the
string that will be present on the corresponding item in the batch corresponding `batch_results` item in the response, to assist in understanding
response, to assist in correlating inputs with outputs. which result corresponds to a particular input. Only valid on batch requests
when using ‘batch_input’ below.
- `batch_input` `(array<object>: nil)` - - `batch_input` `(array<object>: nil)` -
Specifies a list of items to be decoded in a single batch. When this Specifies a list of items to be decoded in a single batch. When this

21
website/content/docs/secrets/transform/index.mdx
View File

@ -61,7 +61,9 @@ management tool.
```text ```text
$ vault write transform/template/ccn \ $ vault write transform/template/ccn \
type=regex \ type=regex \
pattern='(\d{4})-(\d{4})-(\d{4})-(\d{4})' \ pattern='(\d{4})[- ](\d{4})[- ](\d{4})[- ](\d{4})' \
encode_format='$1-$2-$3-$4' \
decode_formats=last-four='$4' \
alphabet=numerics alphabet=numerics
Success! Data written to: transform/template/ccn Success! Data written to: transform/template/ccn
``` ```
@ -106,6 +108,21 @@ values.
transformation. A tweak must be provided if the tweak source for the transformation. A tweak must be provided if the tweak source for the
transformation is "supplied" or "generated". transformation is "supplied" or "generated".
1. Decode some input value using the `/decode` endpoint with a named role and decode format:
```text
$ vault write transform/decode/payments/last-four value=9300-3376-4943-8903
Key Value
--- -----
decoded_value 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". A decode format can optionally
be provided. If one isn't provided, the decoded output will be formatted to
match the template's pattern as in the previous example.
## Roles, Transformations, Templates, and Alphabets ## Roles, Transformations, Templates, and Alphabets
The Transform secrets engine contains several types of resources that The Transform secrets engine contains several types of resources that
@ -250,7 +267,7 @@ for external storage.
#### Mapping Modes #### Mapping Modes
[Tokenization](transform/tokenization) stores the results of an encode operation [Tokenization](transform/tokenization) stores the results of an encode operation
in storage using a cryptographic construct that enhances the safety of its values. in storage using a cryptographic construct that enhances the safety of its values.
In the `default` mapping mode, the token itself is transformed via a one way In the `default` mapping mode, the token itself is transformed via a one way
function involving the transform key and elements of the token. As Vault does function involving the transform key and elements of the token. As Vault does
not store the token, the values in Vault storage themselves cannot be used to not store the token, the values in Vault storage themselves cannot be used to