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