695 lines
16 KiB
Plaintext
695 lines
16 KiB
Plaintext
---
|
||
layout: api
|
||
page_title: Transform - Secrets Engines - HTTP API
|
||
sidebar_title: Transform <sup>ENTERPRISE</sup>
|
||
description: This is the API documentation for the Transform secrets engine.
|
||
---
|
||
|
||
# Transform Secrets Engine (API)
|
||
|
||
This is the API documentation for the Transform secrets engine. For general
|
||
information about the usage and operation of the secrets engine, please see the
|
||
[Transform secrets engine documentation](/docs/secrets/transform).
|
||
|
||
This documentation assumes the transform secrets engine is enabled at the
|
||
`/transform` path in Vault. Since it is possible to enable secrets engines at any
|
||
location, please update your API calls accordingly.
|
||
|
||
## Create/Update Role
|
||
|
||
This endpoint creates or updates the role with the given `name`. If a role with
|
||
the name does not exist, it will be created. If the role exists, it will be
|
||
updated with the new attributes.
|
||
|
||
| Method | Path |
|
||
| :----- | :---------------------- |
|
||
| `POST` | `/transform/role/:name` |
|
||
|
||
|
||
### Parameters
|
||
|
||
- `name` `(string: <required>)` –
|
||
Specifies the name of the role to create. This is part of the request URL.
|
||
|
||
- `transformations` (`list: []`) -
|
||
Specifies the transformations that can be used with this role.
|
||
|
||
### Sample Payload
|
||
|
||
```json
|
||
{
|
||
"transformations": [
|
||
"creditcard-fpe",
|
||
"creditcard-masking"
|
||
]
|
||
}
|
||
```
|
||
|
||
### Sample Request
|
||
|
||
```text
|
||
$ curl \
|
||
--header "X-Vault-Token: ..." \
|
||
--request POST \
|
||
--data @payload.json \
|
||
https://127.0.0.1:8200/v1/transform/role/example-role
|
||
```
|
||
|
||
## Read Role
|
||
|
||
This endpoint queries an existing role by the given name.
|
||
|
||
| Method | Path |
|
||
| :----- | :----------------------- |
|
||
| `GET` | `/transform/role/:name` |
|
||
|
||
### Parameters
|
||
|
||
- `name` `(string: <required>)` –
|
||
Specifies the name of the role to read. This is part of the request URL.
|
||
|
||
### Sample Request
|
||
|
||
```
|
||
$ curl \
|
||
--header "X-Vault-Token: ..." \
|
||
http://127.0.0.1:8200/v1/transform/role/example-role
|
||
```
|
||
|
||
### Sample Response
|
||
|
||
```json
|
||
{
|
||
"data": {
|
||
"transformations": [
|
||
"creditcard-fpe",
|
||
"creditcard-masking"
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
## List Roles
|
||
|
||
This endpoint lists all existing roles in the secrets engine.
|
||
|
||
| Method | Path |
|
||
| :----- | :----------------- |
|
||
| `LIST` | `/transform/role` |
|
||
|
||
### Sample Request
|
||
|
||
```shell
|
||
$ curl
|
||
--header "X-Vault-Token: ..." \
|
||
--request LIST \
|
||
http://127.0.0.1:8200/v1/transform/role
|
||
```
|
||
|
||
### Sample Response
|
||
|
||
```json
|
||
{
|
||
"data": {
|
||
"keys": [
|
||
"example-role"
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
## Delete Role
|
||
|
||
This endpoint deletes an existing role by the given name.
|
||
|
||
| Method | Path |
|
||
| :------- | :---------------------- |
|
||
| `DELETE` | `/transform/role/:name` |
|
||
|
||
### Parameters
|
||
|
||
- `name` `(string: <required>)` –
|
||
Specifies the name of the role to delete. This is part of the request URL.
|
||
|
||
### Sample Request
|
||
|
||
```shell
|
||
$ curl \
|
||
--header "X-Vault-Token: ..." \
|
||
--request DELETE \
|
||
http://127.0.0.1:8200/v1/transform/role/example-role
|
||
```
|
||
|
||
## Create/Update Transformation
|
||
|
||
This endpoint creates or updates a transformation with the given `name`. If a
|
||
transformation with the name does not exist, it will be created. If the
|
||
transformation exists, it will be updated with the new attributes.
|
||
|
||
| Method | Path |
|
||
| :----- | :-------------------------------- |
|
||
| `POST` | `/transform/transformation/:name` |
|
||
|
||
### Parameters
|
||
|
||
- `name` `(string: <required>)` –
|
||
Specifies the name of the transformation to create or update. This is part of
|
||
the request URL.
|
||
|
||
- `type` `(string: <required>)` -
|
||
Specifies the type of transformation to perform. The types currently supported
|
||
by this backend are `fpe` and `masking`. This value cannot be modified
|
||
by an update operation after creation.
|
||
|
||
- `template` `(string: <required>)` -
|
||
Specifies the template name to use for matching value on encode and decode
|
||
operations when using this transformation.
|
||
|
||
- `tweak_source` `(string: "supplied")` -
|
||
Specifies the source of where the tweak value comes from. Valid sources are
|
||
`supplied`, `generated`, and `internal`. Only used when the type is FPE.
|
||
|
||
- `masking_character` `(string: "*")` -
|
||
Specifies the character to use for masking. If multiple characters are
|
||
provided, only the first one is used and the rest is ignored. Only used when
|
||
the type is masking.
|
||
|
||
- `allowed_roles` `(list: [])` -
|
||
Specifies a list of allowed roles that this transformation can be assigned to.
|
||
A role using this transformation must exist in this list in order for
|
||
encode and decode operations to properly function.
|
||
|
||
### Sample Payload
|
||
|
||
```json
|
||
{
|
||
"type": "fpe",
|
||
"template": "builtin/creditcardnumber",
|
||
"tweak_source": "internal",
|
||
"allowed_roles": [
|
||
"example-role"
|
||
]
|
||
}
|
||
```
|
||
|
||
### Sample Request
|
||
|
||
```text
|
||
$ curl \
|
||
--header "X-Vault-Token: ..." \
|
||
--request POST \
|
||
--data @payload.json \
|
||
https://127.0.0.1:8200/v1/transform/transformation/example-transformation
|
||
```
|
||
|
||
## Read Transformation
|
||
|
||
This endpoint queries an existing transformation by the given name.
|
||
|
||
| Method | Path |
|
||
| :----- | :-------------------------------- |
|
||
| `GET` | `/transform/transformation/:name` |
|
||
|
||
- `name` `(string: <required>)` –
|
||
Specifies the name of the role to read. This is part of the request URL.
|
||
|
||
### Sample Request
|
||
|
||
```
|
||
$ curl \
|
||
--header "X-Vault-Token: ..." \
|
||
http://127.0.0.1:8200/v1/transform/transformation/example-transformation
|
||
```
|
||
|
||
### Sample Response
|
||
|
||
```json
|
||
{
|
||
"data": {
|
||
"allowed_roles": [
|
||
"example-role"
|
||
],
|
||
"templates": [
|
||
"builtin/creditcardnumber"
|
||
],
|
||
"tweak_source": "internal",
|
||
"type": "fpe"
|
||
}
|
||
}
|
||
```
|
||
|
||
## List Transformation
|
||
|
||
This endpoint lists all existing transformations in the secrets engine.
|
||
|
||
| Method | Path |
|
||
| :----- | :--------------------------- |
|
||
| `LIST` | `/transform/transformation` |
|
||
|
||
### Sample Request
|
||
|
||
```shell
|
||
$ curl
|
||
--header "X-Vault-Token: ..." \
|
||
--request LIST \
|
||
http://127.0.0.1:8200/v1/transform/transformation
|
||
```
|
||
|
||
### Sample Response
|
||
|
||
```json
|
||
{
|
||
"data": {
|
||
"keys": [
|
||
"example-transformation"
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
## Delete Transformation
|
||
|
||
This endpoint deletes an existing transformation by the given name.
|
||
|
||
| Method | Path |
|
||
| :------- | :-------------------------------- |
|
||
| `DELETE` | `/transform/transformation/:name` |
|
||
|
||
### Parameters
|
||
|
||
- `name` `(string: <required>)` –
|
||
Specifies the name of the transformation to delete. This is part of the
|
||
request URL.
|
||
|
||
### Sample Request
|
||
|
||
```shell
|
||
$ curl \
|
||
--header "X-Vault-Token: ..." \
|
||
--request DELETE \
|
||
http://127.0.0.1:8200/v1/transform/transformation/example-transformation
|
||
```
|
||
|
||
## Create/Update Template
|
||
|
||
This endpoint creates or updates a template with the given `name`. If a
|
||
template with the name does not exist, it will be created. If the
|
||
template exists, it will be updated with the new attributes.
|
||
|
||
| Method | Path |
|
||
| :----- | :-------------------------------- |
|
||
| `POST` | `/transform/template/:name` |
|
||
|
||
### Parameters
|
||
|
||
- `name` `(string: <required>)` –
|
||
Specifies the name of the template to create. This is part of the
|
||
request URL.
|
||
|
||
- `type` `(string: <required>)` -
|
||
Specifies the type of pattern matching to perform. The ony type currently supported
|
||
by this backend is `regex`.
|
||
|
||
- `pattern` `(string: <required>)` -
|
||
Specifies the pattern used to match a particular value. For regex type
|
||
matching, capture group determines the set of character that should be matched
|
||
against. Any matches outside of capture groups are retained
|
||
post-transformation.
|
||
|
||
- `alphabet` `(string)` -
|
||
Specifies the name of the alphabet to use when this template is used for FPE
|
||
encoding and decoding operations.
|
||
|
||
### Sample Payload
|
||
|
||
```json
|
||
{
|
||
"type": "regex",
|
||
"pattern": "(\\d{9})",
|
||
"alphabet": "builtin/numeric"
|
||
}
|
||
```
|
||
|
||
### Sample Request
|
||
|
||
```text
|
||
$ curl \
|
||
--header "X-Vault-Token: ..." \
|
||
--request POST \
|
||
--data @payload.json \
|
||
https://127.0.0.1:8200/v1/transform/template/example-template
|
||
```
|
||
|
||
## Read Template
|
||
|
||
This endpoint queries an existing template by the given name.
|
||
|
||
| Method | Path |
|
||
| :----- | :-------------------------------- |
|
||
| `GET` | `/transform/template/:name` |
|
||
|
||
- `name` `(string: <required>)` –
|
||
Specifies the name of the role to read. This is part of the request URL.
|
||
|
||
### Sample Request
|
||
|
||
```
|
||
$ curl \
|
||
--header "X-Vault-Token: ..." \
|
||
http://127.0.0.1:8200/v1/transform/template/example-template
|
||
```
|
||
|
||
### Sample Response
|
||
|
||
```json
|
||
{
|
||
"data": {
|
||
"alphabet": "builtin/numeric",
|
||
"pattern": "(\\d{9})",
|
||
"type": "regex"
|
||
}
|
||
}
|
||
```
|
||
|
||
## List Template
|
||
|
||
This endpoint lists all existing templates in the secrets engine.
|
||
|
||
| Method | Path |
|
||
| :----- | :--------------------------- |
|
||
| `LIST` | `/transform/transformation` |
|
||
|
||
### Sample Request
|
||
|
||
```shell
|
||
$ curl
|
||
--header "X-Vault-Token: ..." \
|
||
--request LIST \
|
||
http://127.0.0.1:8200/v1/transform/template
|
||
```
|
||
|
||
### Sample Response
|
||
|
||
```json
|
||
{
|
||
"data": {
|
||
"keys": [
|
||
"example-template"
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
## Delete Template
|
||
|
||
This endpoint deletes an existing template by the given name.
|
||
|
||
| Method | Path |
|
||
| :------- | :-------------------------------- |
|
||
| `DELETE` | `/transform/template/:name` |
|
||
|
||
### Parameters
|
||
|
||
- `name` `(string: <required>)` –
|
||
Specifies the name of the template to delete. This is part of the
|
||
request URL.
|
||
|
||
### Sample Request
|
||
|
||
```shell
|
||
$ curl \
|
||
--header "X-Vault-Token: ..." \
|
||
--request DELETE \
|
||
http://127.0.0.1:8200/v1/transform/template/example-template
|
||
```
|
||
|
||
## Create/Update Alphabet
|
||
|
||
This endpoint creates or updates an alphabet with the given `name`. If an
|
||
alphabet with the name does not exist, it will be created. If the
|
||
alphabet exists, it will be updated with the new attributes.
|
||
|
||
| Method | Path |
|
||
| :----- | :-------------------------------- |
|
||
| `POST` | `/transform/alphabet/:name` |
|
||
|
||
### Parameters
|
||
|
||
- `name` `(string: <required>)` –
|
||
Specifies the name of the transformation to create. This is part of the
|
||
request URL.
|
||
|
||
- `alphabet` `(string: <required>)` –
|
||
Specifies the set of characters that can exist within the provided value
|
||
and the encoded or decoded value for a FPE transformation.
|
||
|
||
### Sample Payload
|
||
|
||
```json
|
||
{
|
||
"alphabet": "abc"
|
||
}
|
||
```
|
||
|
||
### Sample Request
|
||
|
||
```text
|
||
$ curl \
|
||
--header "X-Vault-Token: ..." \
|
||
--request POST \
|
||
--data @payload.json \
|
||
https://127.0.0.1:8200/v1/transform/alphabet/example-alphabet
|
||
```
|
||
|
||
## Read Alphabet
|
||
|
||
This endpoint queries an existing alphabet by the given name.
|
||
|
||
| Method | Path |
|
||
| :----- | :-------------------------------- |
|
||
| `GET` | `/transform/alphabet/:name` |
|
||
|
||
- `name` `(string: <required>)` –
|
||
Specifies the name of the role to read. This is part of the request URL.
|
||
|
||
### Sample Request
|
||
|
||
```
|
||
$ curl \
|
||
--header "X-Vault-Token: ..." \
|
||
http://127.0.0.1:8200/v1/transform/alphabet/example-alphabet
|
||
```
|
||
|
||
### Sample Response
|
||
|
||
```json
|
||
{
|
||
"data": {
|
||
"alphabet": "abc"
|
||
}
|
||
}
|
||
```
|
||
|
||
## List Alphabets
|
||
|
||
This endpoint lists all existing alphabets in the secrets engine.
|
||
|
||
| Method | Path |
|
||
| :----- | :--------------------------- |
|
||
| `LIST` | `/transform/alphabet` |
|
||
|
||
### Sample Request
|
||
|
||
```shell
|
||
$ curl
|
||
--header "X-Vault-Token: ..." \
|
||
--request LIST \
|
||
http://127.0.0.1:8200/v1/transform/alphabet
|
||
```
|
||
|
||
### Sample Response
|
||
|
||
```json
|
||
{
|
||
"data": {
|
||
"keys": [
|
||
"example-alphabet"
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
## Delete Alphabet
|
||
|
||
This endpoint deletes an existing alphabet by the given name.
|
||
|
||
| Method | Path |
|
||
| :------- | :-------------------------------- |
|
||
| `DELETE` | `/transform/alphabet/:name` |
|
||
|
||
### Parameters
|
||
|
||
- `name` `(string: <required>)` –
|
||
Specifies the name of the alphabet to delete. This is part of the request URL.
|
||
|
||
### Sample Request
|
||
|
||
```shell
|
||
$ curl \
|
||
--header "X-Vault-Token: ..." \
|
||
--request DELETE \
|
||
http://127.0.0.1:8200/v1/transform/alphabet/example-alphabet
|
||
```
|
||
|
||
## Encode
|
||
|
||
This endpoint encodes the provided value using a named role.
|
||
|
||
| Method | Path |
|
||
| :----- | :----------------------------- |
|
||
| `POST` | `/transform/encode/:role_name` |
|
||
|
||
|
||
### Parameters
|
||
|
||
- `role_name` `(string: <required>)` –
|
||
Specifies the role name to use for this operation. This is specified as part
|
||
of the URL.
|
||
|
||
- `value` `(string: <required>)` –
|
||
Specifies the value to be encoded.
|
||
|
||
- `transformation` `(string)` –
|
||
Specifies the transformation within the role that should be used for this
|
||
encode operation. If a single transformation exists for role, this parameter
|
||
may be skipped and will be inferred. If multiple transformations exist, one
|
||
must be specified.
|
||
|
||
- `tweak` `(string)` –
|
||
Specifies the **base64 encoded** tweak to use. Only applicable for FPE
|
||
transformations with `supplied` as the tweak source.
|
||
|
||
- `batch_input` `(array<object>: nil)` -
|
||
Specifies a list of items to be encoded in a single batch. When this
|
||
parameter is set, the 'value', 'transformation' and 'tweak' parameters are
|
||
ignored. Instead, the aforementioned parameters should be provided within
|
||
each object in the list.
|
||
|
||
```json
|
||
[
|
||
{
|
||
"value": "1111-1111-1111-1111",
|
||
"transformation": "ccn-fpe"
|
||
},
|
||
{
|
||
"value": "2222-2222-2222-2222",
|
||
"transformation": "ccn-masking"
|
||
}
|
||
]
|
||
```
|
||
|
||
**NOTE:** The response payload may return a tweak along with the encoded value
|
||
if the `tweak_source` for the specified transformation is set to `generated`.
|
||
The resource owner should properly store this tweak, which must be supplied back
|
||
when decrypting the encoded value.
|
||
|
||
### Sample Payload
|
||
|
||
```json
|
||
{
|
||
"value": "1111-2222-3333-4444",
|
||
"transformation": "ccn-fpe"
|
||
}
|
||
```
|
||
|
||
### Sample Request
|
||
|
||
```
|
||
$ curl \
|
||
--header "X-Vault-Token: ..." \
|
||
--request POST \
|
||
--data @payload.json \
|
||
http://127.0.0.1:8200/v1/transform/encode/example-role
|
||
```
|
||
|
||
### Sample Response
|
||
|
||
```json
|
||
{
|
||
"data": {
|
||
"encoded_value": "5682-4613-6822-8064"
|
||
}
|
||
}
|
||
```
|
||
|
||
## Decode
|
||
|
||
This endpoint decodes the provided value using a named role.
|
||
|
||
| Method | Path |
|
||
| :----- | :----------------------------- |
|
||
| `POST` | `/transform/decode/:role_name` |
|
||
|
||
|
||
### Parameters
|
||
|
||
- `role_name` `(string: <required>)` –
|
||
Specifies the role name to use for this operation. This is specified as part
|
||
of the URL.
|
||
|
||
- `value` `(string: <required>)` –
|
||
Specifies the value to be decoded.
|
||
|
||
- `transformation` `(string)` –
|
||
Specifies the transformation within the role that should be used for this
|
||
decode operation. If a single transformation exists for role, this parameter
|
||
may be skipped and will be inferred. If multiple transformations exist, one
|
||
must be specified.
|
||
|
||
- `tweak` `(string)` –
|
||
Specifies the **base64 encoded** tweak to use. Only applicable for FPE
|
||
transformations with `supplied` or `generated` as the tweak source.
|
||
|
||
- `batch_input` `(array<object>: nil)` -
|
||
Specifies a list of items to be decoded in a single batch. When this
|
||
parameter is set, the 'value', 'transformation' and 'tweak' parameters are
|
||
ignored. Instead, the aforementioned parameters should be provided within
|
||
each object in the list.
|
||
|
||
```json
|
||
[
|
||
{
|
||
"value": "5682-4613-6822-8064",
|
||
"transformation": "ccn-fpe"
|
||
}
|
||
]
|
||
```
|
||
### Sample Payload
|
||
|
||
```json
|
||
{
|
||
"value": "5682-4613-6822-8064",
|
||
"transformation": "ccn-fpe"
|
||
}
|
||
```
|
||
|
||
### Sample Request
|
||
|
||
```
|
||
$ curl \
|
||
--header "X-Vault-Token: ..." \
|
||
--request POST \
|
||
--data @payload.json \
|
||
http://127.0.0.1:8200/v1/transform/encode/example-role
|
||
```
|
||
|
||
### Sample Response
|
||
|
||
```json
|
||
{
|
||
"data": {
|
||
"decoded_value": "1111-2222-3333-4444"
|
||
}
|
||
}
|
||
```
|