Transit

Note

The following helper method is used various of the examples included here.

import sys


def base64ify(bytes_or_str):
    """Helper method to perform base64 encoding across Python 2.7 and Python 3.X"""
    if sys.version_info[0] >= 3 and isinstance(bytes_or_str, str):
        input_bytes = bytes_or_str.encode('utf8')
    else:
        input_bytes = bytes_or_str

    output_bytes = base64.urlsafe_b64encode(input_bytes)
    if sys.version_info[0] >= 3:
        return output_bytes.decode('ascii')
    else:
        return output_bytes

Create Key

Transit.create_key(name, convergent_encryption=None, derived=None, exportable=None, allow_plaintext_backup=None, key_type=None, mount_point='transit')[source]

Create a new named encryption key of the specified type.

The values set here cannot be changed after key creation.

Supported methods:
POST: /{mount_point}/keys/{name}. Produces: 204 (empty body)
Parameters:
  • name (str | unicode) – Specifies the name of the encryption key to create. This is specified as part of the URL.
  • convergent_encryption (bool) – If enabled, the key will support convergent encryption, where the same plaintext creates the same ciphertext. This requires derived to be set to true. When enabled, each encryption(/decryption/rewrap/datakey) operation will derive a nonce value rather than randomly generate it.
  • derived (bool) – Specifies if key derivation is to be used. If enabled, all encrypt/decrypt requests to this named key must provide a context which is used for key derivation.
  • exportable (bool) – Enables keys to be exportable. This allows for all the valid keys in the key ring to be exported. Once set, this cannot be disabled.
  • allow_plaintext_backup (bool) – If set, enables taking backup of named key in the plaintext format. Once set, this cannot be disabled.
  • key_type (str | unicode) –

    Specifies the type of key to create. The currently-supported types are:

    • aes256-gcm96: AES-256 wrapped with GCM using a 96-bit nonce size AEAD
    • chacha20-poly1305: ChaCha20-Poly1305 AEAD (symmetric, supports derivation and convergent encryption)
    • ed25519: ED25519 (asymmetric, supports derivation).
    • ecdsa-p256: ECDSA using the P-256 elliptic curve (asymmetric)
    • rsa-2048: RSA with bit size of 2048 (asymmetric)
    • rsa-4096: RSA with bit size of 4096 (asymmetric)
  • mount_point (str | unicode) – The “path” the method/backend was mounted on.
Returns:

The response of the request.

Return type:

requests.Response

Examples

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

client.secrets.transit.create_key(name='hvac-key')

Read Key

Transit.read_key(name, mount_point='transit')[source]

Read information about a named encryption key.

The keys object shows the creation time of each key version; the values are not the keys themselves. Depending on the type of key, different information may be returned, e.g. an asymmetric key will return its public key in a standard format for the type.

Supported methods:
GET: /{mount_point}/keys/{name}. Produces: 200 application/json
Parameters:
  • name (str | unicode) – Specifies the name of the encryption key to read. This is specified as part of the URL.
  • mount_point (str | unicode) – The “path” the method/backend was mounted on.
Returns:

The JSON response of the read_key request.

Return type:

requests.Response

Examples

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

read_key_response = client.secrets.transit.read_key(name='hvac-key')
latest_version = read_key_response['data']['latest_version']
print('Latest version for key "hvac-key" is: {ver}'.format(ver=latest_version))

Example output:

Latest version for key "hvac-key" is: 1

List Keys

Transit.list_keys(mount_point='transit')[source]

List keys.

Only the key names are returned (not the actual keys themselves).

Supported methods:
LIST: /{mount_point}/keys. Produces: 200 application/json
Parameters:mount_point (str | unicode) – The “path” the method/backend was mounted on.
Returns:The JSON response of the request.
Return type:requests.Response

Examples

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

list_keys_response = client.secrets.transit.read_key(name='hvac-key')
keys = list_keys_response['data']['keys']
print('Currently configured keys: {keys}'.format(keys=keys))

Example output:

Currently configured keys: {'1': ...}

Delete Key

Transit.delete_key(name, mount_point='transit')[source]

Delete a named encryption key.

It will no longer be possible to decrypt any data encrypted with the named key. Because this is a potentially catastrophic operation, the deletion_allowed tunable must be set in the key’s /config endpoint.

Supported methods:
DELETE: /{mount_point}/keys/{name}. Produces: 204 (empty body)
Parameters:
  • name (str | unicode) – Specifies the name of the encryption key to delete. This is specified as part of the URL.
  • mount_point (str | unicode) – The “path” the method/backend was mounted on.
Returns:

The response of the request.

Return type:

requests.Response

Examples

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

key_name = 'gonna-delete-this-key'

client.secrets.transit.create_key(
    name=key_name,
)

# Update key subsequently to allow deletion...
client.secrets.transit.update_key_configuration(
    name=key_name,
    deletion_allowed=True,
)

# Finally, delete the key
client.secrets.transit.delete_key(name=key_name)

Update Key Configuration

Transit.update_key_configuration(name, min_decryption_version=None, min_encryption_version=None, deletion_allowed=None, exportable=None, allow_plaintext_backup=None, mount_point='transit')[source]

Tune configuration values for a given key.

These values are returned during a read operation on the named key.

Supported methods:
POST: /{mount_point}/keys/{name}/config. Produces: 204 (empty body)
Parameters:
  • name (str | unicode) – Specifies the name of the encryption key to update configuration for.
  • min_decryption_version (int) – Specifies the minimum version of ciphertext allowed to be decrypted. Adjusting this as part of a key rotation policy can prevent old copies of ciphertext from being decrypted, should they fall into the wrong hands. For signatures, this value controls the minimum version of signature that can be verified against. For HMACs, this controls the minimum version of a key allowed to be used as the key for verification.
  • min_encryption_version (int) – Specifies the minimum version of the key that can be used to encrypt plaintext, sign payloads, or generate HMACs. Must be 0 (which will use the latest version) or a value greater or equal to min_decryption_version.
  • deletion_allowed (bool) – Specifies if the key is allowed to be deleted.
  • exportable (bool) – Enables keys to be exportable. This allows for all the valid keys in the key ring to be exported. Once set, this cannot be disabled.
  • allow_plaintext_backup (bool) – If set, enables taking backup of named key in the plaintext format. Once set, this cannot be disabled.
  • mount_point (str | unicode) – The “path” the method/backend was mounted on.
Returns:

The response of the request.

Return type:

requests.Response

Examples

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

# allow key "hvac-key" to be exported in subsequent requests
client.secrets.transit.update_key_configuration(
    name='hvac-key',
    exportable=True,
)

Rotate Key

Transit.rotate_key(name, mount_point='transit')[source]

Rotate the version of the named key.

After rotation, new plaintext requests will be encrypted with the new version of the key. To upgrade ciphertext to be encrypted with the latest version of the key, use the rewrap endpoint. This is only supported with keys that support encryption and decryption operations.

Supported methods:
POST: /{mount_point}/keys/{name}/rotate. Produces: 204 (empty body)
Parameters:
  • name (str | unicode) – Specifies the name of the key to read information about. This is specified as part of the URL.
  • mount_point (str | unicode) – The “path” the method/backend was mounted on.
Returns:

The response of the request.

Return type:

requests.Response

Examples

import hvac
client = hvac.Client(url='https://127.0.0.1:8200')
client.secrets.transit.rotate_key(name='hvac-key')

Export Key

Transit.export_key(name, key_type, version=None, mount_point='transit')[source]

Return the named key.

The keys object shows the value of the key for each version. If version is specified, the specific version will be returned. If latest is provided as the version, the current key will be provided. Depending on the type of key, different information may be returned. The key must be exportable to support this operation and the version must still be valid.

Supported methods:
GET: /{mount_point}/export/{key_type}/{name}(/{version}). Produces: 200 application/json
Parameters:
  • name (str | unicode) – Specifies the name of the key to read information about. This is specified as part of the URL.
  • key_type (str | unicode) – Specifies the type of the key to export. This is specified as part of the URL. Valid values are: encryption-key signing-key hmac-key
  • version (str | unicode) – Specifies the version of the key to read. If omitted, all versions of the key will be returned. If the version is set to latest, the current key will be returned.
  • mount_point (str | unicode) – The “path” the method/backend was mounted on.
Returns:

The JSON response of the request.

Return type:

requests.Response

Examples

import hvac
client = hvac.Client(url='https://127.0.0.1:8200')
export_key_response = client.secrets.transit.export_key(
    name='hvac-key',
    key_type='hmac-key',
)

print('Exported keys: %s' % export_key_response['data']['keys'])

Example output:

Exported keys: {...}

Encrypt Data

Transit.encrypt_data(name, plaintext, context=None, key_version=None, nonce=None, batch_input=None, type=None, convergent_encryption=None, mount_point='transit')[source]

Encrypt the provided plaintext using the named key.

This path supports the create and update policy capabilities as follows: if the user has the create capability for this endpoint in their policies, and the key does not exist, it will be upserted with default values (whether the key requires derivation depends on whether the context parameter is empty or not). If the user only has update capability and the key does not exist, an error will be returned.

Supported methods:
POST: /{mount_point}/encrypt/{name}. Produces: 200 application/json
Parameters:
  • name (str | unicode) – Specifies the name of the encryption key to encrypt against. This is specified as part of the URL.
  • plaintext (str | unicode) – Specifies base64 encoded plaintext to be encoded.
  • context (str | unicode) – Specifies the base64 encoded context for key derivation. This is required if key derivation is enabled for this key.
  • key_version (int) – Specifies the version of the key to use for encryption. If not set, uses the latest version. Must be greater than or equal to the key’s min_encryption_version, if set.
  • nonce (str | unicode) – Specifies the base64 encoded nonce value. This must be provided if convergent encryption is enabled for this key and the key was generated with Vault 0.6.1. Not required for keys created in 0.6.2+. The value must be exactly 96 bits (12 bytes) long and the user must ensure that for any given context (and thus, any given encryption key) this nonce value is never reused.
  • batch_input (List[dict]) – Specifies a list of items to be encrypted in a single batch. When this parameter is set, if the parameters ‘plaintext’, ‘context’ and ‘nonce’ are also set, they will be ignored. The format for the input is: [dict(context=”b64_context”, plaintext=”b64_plaintext”), …]
  • type (str | unicode) – This parameter is required when encryption key is expected to be created. When performing an upsert operation, the type of key to create.
  • convergent_encryption (str | unicode) – This parameter will only be used when a key is expected to be created. Whether to support convergent encryption. This is only supported when using a key with key derivation enabled and will require all requests to carry both a context and 96-bit (12-byte) nonce. The given nonce will be used in place of a randomly generated nonce. As a result, when the same context and nonce are supplied, the same ciphertext is generated. It is very important when using this mode that you ensure that all nonces are unique for a given context. Failing to do so will severely impact the ciphertext’s security.
  • mount_point (str | unicode) – The “path” the method/backend was mounted on.
Returns:

The JSON response of the request.

Return type:

requests.Response

Examples

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

encrypt_data_response = client.secrets.transit.encrypt_data(
    name='hvac-key',
    plaintext=base64ify('hi its me hvac'.encode()),
)
ciphertext = encrypt_data_response['data']['ciphertext']
print('Encrypted plaintext ciphertext is: {cipher}'.format(cipher=ciphertext))

Example output:

Encrypted plaintext ciphertext is: vault:...

Decrypt Data

Transit.decrypt_data(name, ciphertext, context=None, nonce=None, batch_input=None, mount_point='transit')[source]

Decrypt the provided ciphertext using the named key.

Supported methods:
POST: /{mount_point}/decrypt/{name}. Produces: 200 application/json
Parameters:
  • name (str | unicode) – Specifies the name of the encryption key to decrypt against. This is specified as part of the URL.
  • ciphertext (str | unicode) – the ciphertext to decrypt.
  • context (str | unicode) – Specifies the base64 encoded context for key derivation. This is required if key derivation is enabled.
  • nonce (str | unicode) – Specifies a base64 encoded nonce value used during encryption. Must be provided if convergent encryption is enabled for this key and the key was generated with Vault 0.6.1. Not required for keys created in 0.6.2+.
  • batch_input (List[dict]) – Specifies a list of items to be decrypted in a single batch. When this parameter is set, if the parameters ‘ciphertext’, ‘context’ and ‘nonce’ are also set, they will be ignored. Format for the input goes like this: [dict(context=”b64_context”, ciphertext=”b64_plaintext”), …]
  • mount_point (str | unicode) – The “path” the method/backend was mounted on.
Returns:

The JSON response of the request.

Return type:

requests.Response

Examples

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

decrypt_data_response = client.secrets.transit.decrypt_data(
    name='hvac-key',
    ciphertext=ciphertext,
)
plaintext = decrypt_data_response['data']['plaintext']
print('Decrypted plaintext is: {text}'.format(text=plaintext))

Example output:

Decrypted plaintext is: ...

Rewrap Data

Transit.rewrap_data(name, ciphertext, context=None, key_version=None, nonce=None, batch_input=None, mount_point='transit')[source]

Rewrap the provided ciphertext using the latest version of the named key.

Because this never returns plaintext, it is possible to delegate this functionality to untrusted users or scripts.

Supported methods:
POST: /{mount_point}/rewrap/{name}. Produces: 200 application/json
Parameters:
  • name (str | unicode) – Specifies the name of the encryption key to re-encrypt against. This is specified as part of the URL.
  • ciphertext (str | unicode) – Specifies the ciphertext to re-encrypt.
  • context (str | unicode) – Specifies the base64 encoded context for key derivation. This is required if key derivation is enabled.
  • key_version (int) – Specifies the version of the key to use for the operation. If not set, uses the latest version. Must be greater than or equal to the key’s min_encryption_version, if set.
  • nonce (str | unicode) – Specifies a base64 encoded nonce value used during encryption. Must be provided if convergent encryption is enabled for this key and the key was generated with Vault 0.6.1. Not required for keys created in 0.6.2+.
  • batch_input (List[dict]) – Specifies a list of items to be decrypted in a single batch. When this parameter is set, if the parameters ‘ciphertext’, ‘context’ and ‘nonce’ are also set, they will be ignored. Format for the input goes like this: [dict(context=”b64_context”, ciphertext=”b64_plaintext”), …]
  • mount_point (str | unicode) – The “path” the method/backend was mounted on.
Returns:

The JSON response of the request.

Return type:

requests.Response

Examples

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

encrypt_data_response = client.secrets.transit.rewrap_data(
    name='hvac-key',
    ciphertext=ciphertext,
)
rewrapped_ciphertext = encrypt_data_response['data']['ciphertext']
print('Rewrapped ciphertext is: {cipher}'.format(cipher=rewrapped_ciphertext))

Example output:

Rewrapped ciphertext is: vault:...

Generate Data Key

Transit.generate_data_key(name, key_type, context=None, nonce=None, bits=None, mount_point='transit')[source]

Generates a new high-entropy key and the value encrypted with the named key.

Optionally return the plaintext of the key as well. Whether plaintext is returned depends on the path; as a result, you can use Vault ACL policies to control whether a user is allowed to retrieve the plaintext value of a key. This is useful if you want an untrusted user or operation to generate keys that are then made available to trusted users.

Supported methods:
POST: /{mount_point}/datakey/{key_type}/{name}. Produces: 200 application/json
Parameters:
  • name (str | unicode) – Specifies the name of the encryption key to use to encrypt the datakey. This is specified as part of the URL.
  • key_type (str | unicode) – Specifies the type of key to generate. If plaintext, the plaintext key will be returned along with the ciphertext. If wrapped, only the ciphertext value will be returned. This is specified as part of the URL.
  • context (str | unicode) – Specifies the key derivation context, provided as a base64-encoded string. This must be provided if derivation is enabled.
  • nonce (str | unicode) – Specifies a nonce value, provided as base64 encoded. Must be provided if convergent encryption is enabled for this key and the key was generated with Vault 0.6.1. Not required for keys created in 0.6.2+. The value must be exactly 96 bits (12 bytes) long and the user must ensure that for any given context (and thus, any given encryption key) this nonce value is never reused.
  • bits (int) – Specifies the number of bits in the desired key. Can be 128, 256, or 512.
  • mount_point (str | unicode) – The “path” the method/backend was mounted on.
Returns:

The JSON response of the request.

Return type:

requests.Response

Examples

import hvac
client = hvac.Client(url='https://127.0.0.1:8200')
gen_key_response = client.secrets.transit.generate_data_key(
    name='hvac-key',
    key_type='plaintext',
)
ciphertext = gen_key_response['data']['ciphertext']
print('Generated data key ciphertext is: {cipher}'.format(cipher=ciphertext))

Example output:

Generated data key ciphertext is: vault:...

Generate Random Bytes

Transit.generate_random_bytes(n_bytes=None, output_format=None, mount_point='transit')[source]

Return high-quality random bytes of the specified length.

Supported methods:
POST: /{mount_point}/random(/{bytes}). Produces: 200 application/json
Parameters:
  • n_bytes (int) – Specifies the number of bytes to return. This value can be specified either in the request body, or as a part of the URL.
  • output_format (str | unicode) – Specifies the output encoding. Valid options are hex or base64.
  • mount_point (str | unicode) – The “path” the method/backend was mounted on.
Returns:

The JSON response of the request.

Return type:

requests.Response

Examples

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

gen_bytes_response = client.secrets.transit.generate_random_bytes(n_bytes=32)
random_bytes = gen_bytes_response['data']['random_bytes']
print('Here are some random bytes: {bytes}'.format(bytes=random_bytes))

Example output:

Here are some random bytes: ...

Hash Data

Transit.hash_data(hash_input, algorithm=None, output_format=None, mount_point='transit')[source]

Return the cryptographic hash of given data using the specified algorithm.

Supported methods:
POST: /{mount_point}/hash(/{algorithm}). Produces: 200 application/json
Parameters:
  • hash_input (str | unicode) – Specifies the base64 encoded input data.
  • algorithm (str | unicode) – Specifies the hash algorithm to use. This can also be specified as part of the URL. Currently-supported algorithms are: sha2-224, sha2-256, sha2-384, sha2-512
  • output_format (str | unicode) – Specifies the output encoding. This can be either hex or base64.
  • mount_point (str | unicode) – The “path” the method/backend was mounted on.
Returns:

The JSON response of the request.

Return type:

requests.Response

Examples

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

hash_data_response = client.secrets.transit.hash_data(
    hash_input=base64ify('hi its me hvac'),
    algorithm='sha2-256',
)
sum = hash_data_response['data']['sum']
print('Hashed data is: {sum}'.format(sum=sum))

Example output:

Hashed data is: ...

Generate Hmac

Transit.generate_hmac(name, hash_input, key_version=None, algorithm=None, mount_point='transit')[source]

Return the digest of given data using the specified hash algorithm and the named key.

The key can be of any type supported by transit; the raw key will be marshaled into bytes to be used for the HMAC function. If the key is of a type that supports rotation, the latest (current) version will be used.

Supported methods:
POST: /{mount_point}/hmac/{name}(/{algorithm}). Produces: 200 application/json
Parameters:
  • name (str | unicode) – Specifies the name of the encryption key to generate hmac against. This is specified as part of the URL.
  • hash_input – Specifies the base64 encoded input data.
  • key_version (int) – Specifies the version of the key to use for the operation. If not set, uses the latest version. Must be greater than or equal to the key’s min_encryption_version, if set.
  • algorithm (str | unicode) – Specifies the hash algorithm to use. This can also be specified as part of the URL. Currently-supported algorithms are: sha2-224, sha2-256, sha2-384, sha2-512
  • mount_point (str | unicode) – The “path” the method/backend was mounted on.
Returns:

The JSON response of the request.

Return type:

requests.Response

Examples

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

generate_hmac_response = client.secrets.transit.generate_hmac(
    name='hvac-key',
    hash_input=base64ify('hi its me hvac'),
    algorithm='sha2-256',
)
hmac = generate_hmac_response['data']
print("HMAC'd data is: {hmac}".format(hmac=hmac))

Example output:

HMAC'd data is: {'hmac': 'vault:...'}

Sign Data

Transit.sign_data(name, hash_input, key_version=None, hash_algorithm=None, context=None, prehashed=None, signature_algorithm=None, marshaling_algorithm=None, mount_point='transit')[source]

Return the cryptographic signature of the given data using the named key and the specified hash algorithm.

The key must be of a type that supports signing.

Supported methods:
POST: /{mount_point}/sign/{name}(/{hash_algorithm}). Produces: 200 application/json
Parameters:
  • name (str | unicode) – Specifies the name of the encryption key to use for signing. This is specified as part of the URL.
  • hash_input (str | unicode) – Specifies the base64 encoded input data.
  • key_version (int) – Specifies the version of the key to use for signing. If not set, uses the latest version. Must be greater than or equal to the key’s min_encryption_version, if set.
  • hash_algorithm (str | unicode) – Specifies the hash algorithm to use for supporting key types (notably, not including ed25519 which specifies its own hash algorithm). This can also be specified as part of the URL. Currently-supported algorithms are: sha2-224, sha2-256, sha2-384, sha2-512
  • context (str | unicode) – Base64 encoded context for key derivation. Required if key derivation is enabled; currently only available with ed25519 keys.
  • prehashed (bool) – Set to true when the input is already hashed. If the key type is rsa-2048 or rsa-4096, then the algorithm used to hash the input should be indicated by the hash_algorithm parameter. Just as the value to sign should be the base64-encoded representation of the exact binary data you want signed, when set, input is expected to be base64-encoded binary hashed data, not hex-formatted. (As an example, on the command line, you could generate a suitable input via openssl dgst -sha256 -binary | base64.)
  • signature_algorithm (str | unicode) – When using a RSA key, specifies the RSA signature algorithm to use for signing. Supported signature types are: pss, pkcs1v15
  • marshaling_algorithm (str | unicode) – Specifies the way in which the signature should be marshaled. This currently only applies to ECDSA keys. Supported types are: asn1, jws
  • mount_point (str | unicode) – The “path” the method/backend was mounted on.
Returns:

The JSON response of the request.

Return type:

requests.Response

Examples

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

key_name = 'hvac-signing-key'

# Note: some key types do no support signing...
# E.g., "key type aes256-gcm96 does not support verification"
client.secrets.transit.create_key(
    name=key_name,
    key_type='ed25519',
)

sign_data_response = client.secrets.transit.sign_data(
    name=key_name,
    hash_input=base64ify('hi its me hvac'),
)
signature = sign_data_response['data']['signature']
print('Signature is: {signature}'.format(signature=signature))

Example output:

Signature is: vault:...

Verify Signed Data

Transit.verify_signed_data(name, hash_input, signature=None, hmac=None, hash_algorithm=None, context=None, prehashed=None, signature_algorithm=None, marshaling_algorithm=None, mount_point='transit')[source]

Return whether the provided signature is valid for the given data.

Supported methods:
POST: /{mount_point}/verify/{name}(/{hash_algorithm}). Produces: 200 application/json
Parameters:
  • name (str | unicode) – Specifies the name of the encryption key that was used to generate the signature or HMAC.
  • hash_input – Specifies the base64 encoded input data.
  • signature (str | unicode) – Specifies the signature output from the /transit/sign function. Either this must be supplied or hmac must be supplied.
  • hmac (str | unicode) – Specifies the signature output from the /transit/hmac function. Either this must be supplied or signature must be supplied.
  • hash_algorithm (str | unicode) – Specifies the hash algorithm to use. This can also be specified as part of the URL. Currently-supported algorithms are: sha2-224, sha2-256, sha2-384, sha2-512
  • context (str | unicode) – Base64 encoded context for key derivation. Required if key derivation is enabled; currently only available with ed25519 keys.
  • prehashed (bool) – Set to true when the input is already hashed. If the key type is rsa-2048 or rsa-4096, then the algorithm used to hash the input should be indicated by the hash_algorithm parameter.
  • signature_algorithm (str | unicode) – When using a RSA key, specifies the RSA signature algorithm to use for signature verification. Supported signature types are: pss, pkcs1v15
  • marshaling_algorithm (str | unicode) – Specifies the way in which the signature should be marshaled. This currently only applies to ECDSA keys. Supported types are: asn1, jws
  • mount_point (str | unicode) – The “path” the method/backend was mounted on.
Returns:

The JSON response of the request.

Return type:

requests.Response

Examples

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

verify_signed_data_response = client.secrets.transit.verify_signed_data(
    name='hvac-signing-key',
    hash_input=base64ify('hi its me hvac'),
    signature=signature,
)
valid = verify_signed_data_response['data']['valid']
print('Signature is valid?: {valid}'.format(valid=valid))

Example output:

Signature is valid?: True

Backup Key

Transit.backup_key(name, mount_point='transit')[source]

Return a plaintext backup of a named key.

The backup contains all the configuration data and keys of all the versions along with the HMAC key. The response from this endpoint can be used with the /restore endpoint to restore the key.

Supported methods:
GET: /{mount_point}/backup/{name}. Produces: 200 application/json
Parameters:
  • name (str | unicode) – Name of the key.
  • mount_point (str | unicode) – The “path” the method/backend was mounted on.
Returns:

The JSON response of the request.

Return type:

requests.Response

Examples

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

key_name = 'hvac-key'

# Update the key configuration to allow exporting
client.secrets.transit.update_key_configuration(
    name=key_name,
    exportable=True,
    allow_plaintext_backup=True,
)

backup_key_response = client.secrets.transit.backup_key(
    name=key_name,
)

backed_up_key = backup_key_response['data']['backup']
print('Backed up key: %s' % backed_up_key)

Example output:

Backed up key: ...

Restore Key

Transit.restore_key(backup, name=None, force=None, mount_point='transit')[source]

Restore the backup as a named key.

This will restore the key configurations and all the versions of the named key along with HMAC keys. The input to this endpoint should be the output of /backup endpoint. For safety, by default the backend will refuse to restore to an existing key. If you want to reuse a key name, it is recommended you delete the key before restoring. It is a good idea to attempt restoring to a different key name first to verify that the operation successfully completes.

Supported methods:
POST: /{mount_point}/restore(/name). Produces: 204 (empty body)
Parameters:
  • backup (str | unicode) – Backed up key data to be restored. This should be the output from the /backup endpoint.
  • name (str | unicode) – If set, this will be the name of the restored key.
  • force (bool) – If set, force the restore to proceed even if a key by this name already exists.
  • mount_point (str | unicode) – The “path” the method/backend was mounted on.
Returns:

The response of the request.

Return type:

requests.Response

Examples

import hvac

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

client.secrets.transit.update_key_configuration(
    name=key_name,
    deletion_allowed=True,
)
delete_resp = client.secrets.transit.delete_key(name=key_name)

# Restore a key after deletion
client.secrets.transit.restore_key(backup=backed_up_key)

Trim Key

Transit.trim_key(name, min_version, mount_point='transit')[source]

Trims 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}/keys/{name}/trim. Produces: 200 application/json
Parameters:
  • name (str | unicode) – Specifies the name of the key to be trimmed.
  • min_version (int) – The minimum version for the key ring. All versions before this version will be permanently deleted. This value can at most be equal to the lesser of min_decryption_version and min_encryption_version. This is not allowed to be set when either min_encryption_version or min_decryption_version is set to zero.
  • mount_point (str | unicode) – The “path” the method/backend was mounted on.
Returns:

The response of the request.

Return type:

requests.Response

Examples

Note

Transit key trimming was added for Vault versions >=0.11.4.

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

key_name = 'hvac-key'

for _ in range(0, 10):
    # Rotate the key a bunch...
    client.secrets.transit.rotate_key(
        name=key_name,
    )

# Set a minimum encryption version
client.secrets.transit.update_key_configuration(
    name=key_name,
    min_decryption_version=3,
    min_encryption_version=5,
)

# Trim any unneeded versions remaining of the key...
client.secrets.transit.trim_key(
    name='hvac-key',
    min_version=3,
)