Transform

Encode/Decode Example

hvac.api.secrets_engines.Transform.encode() hvac.api.secrets_engines.Transform.decode()

import hvac
client = hvac.Client(url='https://127.0.0.1:8200')

input_value = '1111-1111-1111-1111'

role_name = 'hvac-role'
transformation_name = 'hvac-fpe-credit-card'
transformations = [transformation_name]

# Create a role and a transformation
client.secrets.transform.create_or_update_role(
    name=role_name,
    transformations=transformations,
)
client.secrets.transform.create_or_update_transformation(
    name=transformation_name,
    transform_type='fpe',
    template='builtin/creditcardnumber',
    tweak_source='internal',
    allowed_roles=[role_name],
)

# Use the role/transformation combination to encode a value
encode_response = client.secrets.transform.encode(
    role_name=role_name,
    value=input_value,
    transformation=transformation_name,
)
print('The encoded value is: %s' % encode_response['data']['encoded_value'])

# Use the role/transformation combination to decode a value
decode_response = client.secrets.transform.decode(
    role_name=role_name,
    value=encode_response['data']['encoded_value'],
    transformation=transformation_name,
)
print('The decoded value is: %s' % decode_response['data']['decoded_value'])
The encoded value is: ...
The decoded value is: 1111-1111-1111-1111

Create/Update Role

hvac.api.secrets_engines.Transform.create_or_update_role()

import hvac
client = hvac.Client(url='https://127.0.0.1:8200')

client.secrets.transform.create_or_update_role(
    name='hvac-role',
    transformations=[
        'hvac-fpe-credit-card',
    ],
)

Read Role

hvac.api.secrets_engines.Transform.read_role()

import hvac
client = hvac.Client(url='https://127.0.0.1:8200')

role_name = 'hvac-role'
client.secrets.transform.create_or_update_role(
    name=role_name,
    transformations=[
        'hvac-fpe-credit-card',
    ],
)
read_response = client.secrets.transform.read_role(
    name=role_name,
)
print('Role "{}" has the following transformations configured: {}'.format(
    role_name,
    ', '.join(read_response['data']['transformations']),
))
Role "hvac-role" has the following transformations configured: hvac-fpe-credit-card

List Roles

hvac.api.secrets_engines.Transform.list_roles()

import hvac
client = hvac.Client(url='https://127.0.0.1:8200')

client.secrets.transform.create_or_update_role(
    name='hvac-role',
    transformations=[
        'hvac-fpe-credit-card',
    ],
)
list_response = client.secrets.transform.list_roles()
print('List of transform role names: {}'.format(
    ', '.join(list_response['data']['keys']),
))
List of transform role names: hvac-role

Delete Role

hvac.api.secrets_engines.Transform.delete_role()

import hvac
client = hvac.Client(url='https://127.0.0.1:8200')

role_name = 'hvac-role'

# Create a role
client.secrets.transform.create_or_update_role(
    name=role_name,
    transformations=[
        'hvac-fpe-credit-card',
    ],
)

# Subsequently delete it...
client.secrets.transform.delete_role(
    name=role_name,
)

Create/Update Transformation

hvac.api.secrets_engines.Transform.create_or_update_transformation()

import hvac
client = hvac.Client(url='https://127.0.0.1:8200')

transformation_name = 'hvac-fpe-credit-card'
template = 'builtin/creditcardnumber'
client.secrets.transform.create_or_update_transformation(
    name=transformation_name,
    transform_type='fpe',
    template=template,
    tweak_source='internal',
    allowed_roles=[
        'test-role'
    ],
)

Read Transformation

hvac.api.secrets_engines.Transform.read_transformation()

import hvac
client = hvac.Client(url='https://127.0.0.1:8200')

transformation_name = 'hvac-fpe-credit-card'
template = 'builtin/creditcardnumber'
client.secrets.transform.create_or_update_transformation(
    name=transformation_name,
    transform_type='fpe',
    template=template,
    tweak_source='internal',
    allowed_roles=[
        'hvac-role'
    ],
)
read_response = client.secrets.transform.read_transformation(
    name=transformation_name,
)
print('Transformation "{}" has the following type configured: {}'.format(
    transformation_name,
    read_response['data']['type'],
))
Transformation "hvac-fpe-credit-card" has the following type configured: fpe

List Transformations

hvac.api.secrets_engines.Transform.list_transformations()

import hvac
client = hvac.Client(url='https://127.0.0.1:8200')

transformation_name = 'hvac-fpe-credit-card'
template = 'builtin/creditcardnumber'
client.secrets.transform.create_or_update_transformation(
    name=transformation_name,
    transform_type='fpe',
    template=template,
    tweak_source='internal',
    allowed_roles=[
        'hvac-role'
    ],
)
list_response = client.secrets.transform.list_transformations()
print('List of transformations: {}'.format(
    ', '.join(list_response['data']['keys']),
))
List of transformations: hvac-fpe-credit-card

Delete Transformation

hvac.api.secrets_engines.Transform.delete_transformation()

import hvac
client = hvac.Client(url='https://127.0.0.1:8200')

transformation_name = 'hvac-fpe-credit-card'
template = 'builtin/creditcardnumber'

# Create a transformation
client.secrets.transform.create_or_update_transformation(
    name=transformation_name,
    transform_type='fpe',
    template=template,
    tweak_source='internal',
    allowed_roles=[
        'hvac-role'
    ],
)

# Subsequently delete it...
client.secrets.transform.delete_role(
    name=role_name,
)

Create/Update Template

hvac.api.secrets_engines.Transform.create_or_update_template()

import hvac
client = hvac.Client(url='https://127.0.0.1:8200')

template_name = 'hvac-template'
create_response = client.secrets.transform.create_or_update_template(
    name=template_name,
    template_type='regex',
    pattern='(\\d{9})',
    alphabet='builtin/numeric',
)

Read Template

hvac.api.secrets_engines.Transform.read_template()

import hvac
client = hvac.Client(url='https://127.0.0.1:8200')

template_name = 'hvac-template'
client.secrets.transform.create_or_update_template(
    name=template_name,
    template_type='regex',
    pattern='(\\d{9})',
    alphabet='builtin/numeric',
)
read_response = client.secrets.transform.read_template(
    name=template_name,
)
print('Template "{}" has the following type configured: {}'.format(
    template_name,
    read_response['data']['type'],
))
Template "hvac-template" has the following type configured: regex

List Templates

hvac.api.secrets_engines.Transform.list_templates()

import hvac
client = hvac.Client(url='https://127.0.0.1:8200')

template_name = 'hvac-template'
client.secrets.transform.create_or_update_template(
    name=template_name,
    template_type='regex',
    pattern='(\\d{9})',
    alphabet='builtin/numeric',
)
list_response = client.secrets.transform.list_templates()
print('List of templates: {}'.format(
    ', '.join(list_response['data']['keys']),
))
List of templates: builtin/creditcardnumber, builtin/socialsecuritynumber, hvac-template

Delete Template

hvac.api.secrets_engines.Transform.delete_template()

import hvac
client = hvac.Client(url='https://127.0.0.1:8200')

template_name = 'hvac-template'
client.secrets.transform.create_or_update_template(
    name=template_name,
    template_type='regex',
    pattern='(\\d{9})',
    alphabet='builtin/numeric',
)

# Subsequently delete it...
client.secrets.transform.delete_template(
    name=template_name,
)

Create/Update Alphabet

hvac.api.secrets_engines.Transform.create_or_update_alphabet()

import hvac
client = hvac.Client(url='https://127.0.0.1:8200')

alphabet_name = 'hvac-alphabet'
alphabet_value = 'abc'
client.secrets.transform.create_or_update_alphabet(
    name=alphabet_name,
    alphabet=alphabet_value,
)

Read Alphabet

hvac.api.secrets_engines.Transform.read_alphabet()

import hvac
client = hvac.Client(url='https://127.0.0.1:8200')

alphabet_name = 'hvac-alphabet'
alphabet_value = 'abc'
client.secrets.transform.create_or_update_alphabet(
    name=alphabet_name,
    alphabet=alphabet_value,
)
read_response = client.secrets.transform.read_alphabet(
    name=alphabet_name,
)
print('Alphabet "{}" has this jazz: {}'.format(
    alphabet_name,
    read_response['data']['alphabet'],
))
Alphabet "hvac-alphabet" has this jazz: abc

List Alphabets

hvac.api.secrets_engines.Transform.list_alphabets()

import hvac
client = hvac.Client(url='https://127.0.0.1:8200')

alphabet_name = 'hvac-alphabet'
alphabet_value = 'abc'
client.secrets.transform.create_or_update_alphabet(
    name=alphabet_name,
    alphabet=alphabet_value,
)
list_response = client.secrets.transform.list_alphabets()
print('List of alphabets: {}'.format(
    ', '.join(list_response['data']['keys']),
))
List of alphabets: builtin/alphalower, ..., hvac-alphabet

Delete Alphabet

hvac.api.secrets_engines.Transform.delete_alphabet()

import hvac
client = hvac.Client(url='https://127.0.0.1:8200')

alphabet_name = 'hvac-alphabet'
alphabet_value = 'abc'

# Create an alphabet
client.secrets.transform.create_or_update_alphabet(
    name=alphabet_name,
    alphabet=alphabet_value,
)

# Subsequently delete it...
client.secrets.transform.delete_alphabet(
    name=alphabet_name,
)

Create Or Update FPE Transformation

hvac.api.secrets_engines.Transform.create_or_update_fpe_transformation()

Creates or update an FPE 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.

Supported methods:

POST: /{mount_point}/transformations/fpe/:name.

param name

The name of the transformation to create or update. This is part of the request URL.

type name

str

param template

The template name to use for matching value on encode and decode operations when using this transformation.

type template

str

param tweak_source

Specifies the source of where the tweak value comes from. Valid sources are: supplied, generated, and internal.

type tweak_source

str

param allowed_roles

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.

type allowed_roles

list

param mount_point

The “path” the method/backend was mounted on.

type mount_point

str

return

The response of the create_or_update_fpe_transformation request.

rtype

requests.Response

Create Or Update Masking Transformation

hvac.api.secrets_engines.Transform.create_or_update_masking_transformation()

Creates or update a masking 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.

Supported methods:

POST: /{mount_point}/transformations/masking/:name.

param name

The name of the transformation to create or update. This is part of the request URL.

type name

str

param template

The template name to use for matching value on encode and decode operations when using this transformation.

type template

str

param masking_character

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.

type masking_character

str

param allowed_roles

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.

type allowed_roles

list

param mount_point

The “path” the method/backend was mounted on.

type mount_point

str

return

The response of the create_or_update_masking_transformation request.

rtype

requests.Response

Create Or Update Tokenization Transformation

hvac.api.secrets_engines.Transform.create_or_update_tokenization_transformation()

This endpoint creates or updates a tokenization 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.

Supported methods:

POST: /{mount_point}/transformations/tokenization/:name.

param max_ttl

The maximum TTL of a token. If 0 or unspecified, tokens may have no expiration.

type max_ttl

str

param mapping_mode

Specifies the mapping mode for stored tokenization values.

  • default is strongly recommended for highest security

  • exportable exportable allows for all plaintexts to be decoded via the export-decoded endpoint in an emergency.

type mapping_mode

str

param allowed_roles

aAlist 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.

type allowed_roles

list

param stores

list of tokenization stores to use for tokenization state. Vault’s internal storage is used by default.

type stores

list

param mount_point

The “path” the method/backend was mounted on.

type mount_point

str

return

The response of the create_or_update_tokenization_transformation request.

rtype

requests.Response

Create Or Update Tokenization Store

hvac.api.secrets_engines.Transform.create_or_update_tokenization_store()

Create or update a storage configuration for use with tokenization. The database user configured here should only have permission to SELECT, INSERT, and UPDATE rows in the tables.

Supported methods:

POST: /{mount_point}/store/:name.

param name

The name of the store to create or update.

type name

str

param type

Specifies the type of store. Currently only sql is supported.

type type

str

param driver

Specifies the database driver to use, and thus which SQL database type. Currently the supported options are postgres or mysql

type driver

str

param supported_transformations

The types of transformations this store can host. Currently only tokenization is supported.

type supported_transformations

list(str)

param connection_string

database connection string with template slots for username and password that Vault will use for locating and connecting to a database. Each database driver type has a different syntax for its connection strings.

type connection_string

str

param username

username value to use when connecting to the database.

type username

str

param password

password value to use when connecting to the database.

type password

str

param schema

schema within the database to expect tokenization state tables.

type schema

str

param max_open_connections

maximum number of connections to the database at any given time.

type max_open_connections

int

param max_idle_connections

maximum number of idle connections to the database at any given time.

type max_idle_connections

int

param max_connection_lifetime

means no limit.

type max_connection_lifetime

duration

param mount_point

The “path” the method/backend was mounted on.

type mount_point

str

return

The response of the create_or_update_tokenization_store request.

rtype

requests.Response

Encode

hvac.api.secrets_engines.Transform.encode()

Encode the provided value using a named role.

Supported methods:

POST: /{mount_point}/encode/:role_name.

param role_name

the role name to use for this operation. This is specified as part of the URL.

type role_name

str | unicode

param value

the value to be encoded.

type value

str | unicode

param transformation

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.

type transformation

str | unicode

param tweak

the tweak source.

type tweak

str | unicode

param batch_input

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.

type batch_input

list

param mount_point

The “path” the secrets engine was mounted on.

type mount_point

str | unicode

return

The response of the encode request.

rtype

requests.Response

Validate Token

hvac.api.secrets_engines.Transform.validate_token()

Determine if a provided tokenized value is valid and unexpired. Only valid for tokenization transformations.

Supported methods:

POST: /{mount_point}/validate/:role_name.

param role_name

the role name to use for this operation. This is specified as part of the URL.

type role_name

str

param value

the token for which to check validity.

type value

str

param transformation

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.

type transformation

str

param batch_input

a list of items to be decoded in a single batch. When this parameter is set, the ‘value’ parameter is ignored. Instead, the aforementioned parameters should be provided within each object in the list.

type batch_input

list

param mount_point

The “path” the method/backend was mounted on.

type mount_point

str

return

The response of the validate_token request.

rtype

requests.Response

Check Tokenization

hvac.api.secrets_engines.Transform.check_tokenization()

Determine if a provided plaintext value has an valid, unexpired tokenized value. Note that this cannot return the token, just confirm that a tokenized value exists. This endpoint is only valid for tokenization transformations.

Supported methods:

POST: /{mount_point}/tokenized/:role_name.

param role_name

the role name to use for this operation. This is specified as part of the URL.

type role_name

str

param value

the token to test for whether it has a valid tokenization.

type value

str

param transformation

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.

type transformation

str

param batch_input

a list of items to be decoded in a single batch. When this parameter is set, the ‘value’ parameter is ignored. Instead, the aforementioned parameters should be provided within each object in the list.

type batch_input

list

param mount_point

The “path” the method/backend was mounted on.

type mount_point

str

return

The response of the check_tokenization request.

rtype

requests.Response

Retrieve Token Metadata

hvac.api.secrets_engines.Transform.retrieve_token_metadata()

This endpoint retrieves metadata for a tokenized value using a named role. Only valid for tokenization transformations.

Supported methods:

POST: /{mount_point}/metadata/:role_name.

param role_name

the role name to use for this operation. This is specified as part of the URL.

type role_name

str

param value

the token for which to retrieve metadata.

type value

str

param transformation

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.

type transformation

str

param batch_input

a list of items to be decoded in a single batch. When this parameter is set, the ‘value’ parameter is ignored. Instead, the aforementioned parameters should be provided within each object in the list.

type batch_input

list

param mount_point

The “path” the method/backend was mounted on.

type mount_point

str

return

The response of the retrieve_token_metadata request.

rtype

requests.Response

Snapshot Tokenization State

hvac.api.secrets_engines.Transform.snapshot_tokenization_state()

This endpoint starts or continues retrieving a snapshot of the stored state of a tokenization transform. This state is protected as it is in the underlying store, and so is safe for storage or transport. Snapshots may be used for backup purposes or to migrate from one store to another. If more than one store is configured for a tokenization transform, the snapshot data contains the contents of the first store.

Supported methods:

POST: /{mount_point}/transformations/tokenization/snapshot/:name.

param name

the name of the transformation to snapshot.

type name

str

param limit

maximum number of tokenized value states to return on this call.

type limit

int

param continuation

absent or empty, a new snapshot is started. If present, the snapshot should continue at the next available value.

type continuation

str

param mount_point

The “path” the method/backend was mounted on.

type mount_point

str

return

The response of the snapshot_tokenization_state request.

rtype

requests.Response

Restore Tokenization State

hvac.api.secrets_engines.Transform.restore_tokenization_state()

This endpoint restores previously snapshotted tokenization state values to the underlying store(s) of a tokenization transform. Calls to this endpoint are idempotent, so multiple outputs from a snapshot run can be applied via restore in any order and duplicates will not cause a problem.

Supported methods:

POST: /{mount_point}/transformations/tokenization/restore/:name.

param name

the name of the transformation to restore.

type name

str

param values

number of tokenization state values from a previous snapshot call.

type values

str

param mount_point

The “path” the method/backend was mounted on.

type mount_point

str

return

The response of the restore_tokenization_state request.

rtype

requests.Response

Export Decoded Tokenization State

hvac.api.secrets_engines.Transform.export_decoded_tokenization_state()

Start or continue retrieving an export of tokenization state, including the tokens and their decoded values. This call is only supported on tokenization stores configured with the exportable mapping mode. Refer to the Tokenization documentation for when to use the exportable mapping mode. Decoded values are in Base64 representation.

Supported methods:

POST: /{mount_point}/transformations/tokenization/export-decoded/:name.

param name

the name of the transformation to export.

type name

str

param limit

maximum number of tokenized value states to return on this call.

type limit

int

param continuation

absent or empty, a new export is started. If present, the export should continue at the next available value.

type continuation

str

param mount_point

The “path” the method/backend was mounted on.

type mount_point

str

return

The response of the export_decoded_tokenization_state request.

rtype

requests.Response

Rotate Tokenization Key

hvac.api.secrets_engines.Transform.rotate_tokenization_key()

Rotate the version of the named key. After rotation, new requests will be encoded with the new version of the key.

Supported methods:

POST: /{mount_point}/tokenization/keys/{transform_name}/rotate.

param transform_name

the transform name to use for this operation. This is specified as part of the URL.

type transform_name

str

param mount_point

The “path” the method/backend was mounted on.

type mount_point

str

return

The response of the rotate_tokenization_key request.

rtype

requests.Response

Update Tokenization Key Config

hvac.api.secrets_engines.Transform.update_tokenization_key_config()

Allow the minimum key version to be set for decode operations. Only valid for tokenization transformations.

Supported methods:

POST: /{mount_point}/tokenization/keys/{transform_name}/config.

param transform_name

the transform name to use for this operation. This is specified as part of the URL.

type transform_name

str

param min_decryption_version

the minimum key version that vault can use to decode values for the corresponding transform.

type min_decryption_version

int

param mount_point

The “path” the method/backend was mounted on.

type mount_point

str

return

The response of the update_tokenization_key_config request.

rtype

requests.Response

List Tokenization Key Configuration

hvac.api.secrets_engines.Transform.list_tokenization_key_configuration()

List all tokenization keys. Only valid for tokenization transformations.

Supported methods:

LIST: /{mount_point}/tokenization/keys/.

param mount_point

The “path” the method/backend was mounted on.

type mount_point

str

return

The response of the list_tokenization_key_configuration request.

rtype

requests.Response

Read Tokenization Key Configuration

hvac.api.secrets_engines.Transform.read_tokenization_key_configuration()

Read tokenization key configuration for a particular transform. Only valid for tokenization transformations.

Supported methods:

GET: /{mount_point}/tokenization/keys/:{mount_point}_name.

param transform_name

the transform name to use for this operation. This is specified as part of the URL.

type transform_name

str

param mount_point

The “path” the method/backend was mounted on.

type mount_point

str

return

The response of the read_tokenization_key_configuration request.

rtype

requests.Response

Trim Tokenization Key Version

hvac.api.secrets_engines.Transform.trim_tokenization_key_version()

Trim older key versions setting a minimum version for the keyring. Once trimmed, previous versions of the key cannot be recovered.

Supported methods:

POST: /{mount_point}/tokenization/keys/{transform_name}/trim.

param transform_name

the transform name to use for this operation. This is specified as part of the URL.

type transform_name

str

param min_available_version

type min_available_version

int

param mount_point

The “path” the method/backend was mounted on.

type mount_point

str

return

The response of the trim_tokenization_key_version request.

rtype

requests.Response