luxolus/open-vault
2
0
Fork 0
Code Issues 1 Pull requests Releases Activity
open-vault/website/pages/api-docs/secret/transform/index.mdx

695 lines
16 KiB
Plaintext
Raw Normal View History

Transform docs
2020-04-07 16:59:49 +00:00
---
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"
}
}
```
Reference in a new issue Copy permalink