Key

Read Root Generation Progress

Key.read_root_generation_progress()[source]

Read the configuration and process of the current root generation attempt.

Supported methods:
GET: /sys/generate-root/attempt. Produces: 200 application/json
Returns:The JSON response of the request.
Return type:dict

Examples

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

root_gen_progress = client.sys.read_root_generation_progress()
print('Root generation "started" status: %s' % root_gen_progress['started'])

Example output:

Root generation "started" status: ...

Start Root Token Generation

Key.start_root_token_generation(otp=None, pgp_key=None)[source]

Initialize a new root generation attempt.

Only a single root generation attempt can take place at a time. One (and only one) of otp or pgp_key are required.

Supported methods:
PUT: /sys/generate-root/attempt. Produces: 200 application/json
Parameters:
  • otp (str | unicode) – Specifies a base64-encoded 16-byte value. The raw bytes of the token will be XOR’d with this value before being returned to the final unseal key provider.
  • pgp_key (str | unicode) – Specifies a base64-encoded PGP public key. The raw bytes of the token will be encrypted with this value before being returned to the final unseal key provider.
Returns:

The JSON response of the request.

Return type:

dict

Examples

import hvac
from tests.utils import get_generate_root_otp

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

new_otp = get_generate_root_otp()
start_generate_root_response = client.sys.start_root_token_generation(
    otp=new_otp,
)
nonce = start_generate_root_response['nonce']
print('Nonce for root generation is: %s' % nonce)

Example output:

Nonce for root generation is: ...

Cancel Root Generation

Key.cancel_root_generation()[source]

Cancel any in-progress root generation attempt.

This clears any progress made. This must be called to change the OTP or PGP key being used.

Supported methods:
DELETE: /sys/generate-root/attempt. Produces: 204 (empty body)
Returns:The response of the request.
Return type:request.Response

Examples

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

client.sys.cancel_root_generation()

Generate Root

Key.generate_root(key, nonce)[source]

Enter a single master key share to progress the root generation attempt.

If the threshold number of master key shares is reached, Vault will complete the root generation and issue the new token. Otherwise, this API must be called multiple times until that threshold is met. The attempt nonce must be provided with each call.

Supported methods:
PUT: /sys/generate-root/update. Produces: 200 application/json
Parameters:
  • key (str | unicode) – Specifies a single master key share.
  • nonce (str | unicode) – The nonce of the attempt.
Returns:

The JSON response of the request.

Return type:

dict

Examples

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

client.sys.generate_root(
    key=key,
    nonce=nonce,
)

Get Encryption Key Status

Client.key_status

GET /sys/key-status

Returns:Information about the current encryption key used by Vault.
Return type:dict

Examples

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

print('Encryption key term is: %s' % client.key_status['term'])

Example output:

Encryption key term is: 1

Rotate Encryption Key

Key.rotate_encryption_key()[source]

Trigger a rotation of the backend encryption key.

This is the key that is used to encrypt data written to the storage backend, and is not provided to operators. This operation is done online. Future values are encrypted with the new key, while old values are decrypted with previous encryption keys.

This path requires sudo capability in addition to update.

Supported methods:
PUT: /sys/rorate. Produces: 204 (empty body)
Returns:The response of the request.
Return type:requests.Response

Examples

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

client.sys.rotate_encryption_key()

Read Rekey Progress

Key.read_rekey_progress(recovery_key=False)[source]

Read the configuration and progress of the current rekey attempt.

Supported methods:
GET: /sys/rekey-recovery-key/init. Produces: 200 application/json GET: /sys/rekey/init. Produces: 200 application/json
Parameters:recovery_key (bool) – If true, send requests to “rekey-recovery-key” instead of “rekey” api path.
Returns:The JSON response of the request.
Return type:requests.Response

Examples

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

print('Rekey "started" status is: %s' % client.sys.read_rekey_progress()['started'])

Example output:

Rekey "started" status is: False

Start Rekey

Key.start_rekey(secret_shares=5, secret_threshold=3, pgp_keys=None, backup=False, require_verification=False, recovery_key=False)[source]

Initializes a new rekey attempt.

Only a single recovery key rekeyattempt can take place at a time, and changing the parameters of a rekey requires canceling and starting a new rekey, which will also provide a new nonce.

Supported methods:
PUT: /sys/rekey/init. Produces: 204 (empty body) PUT: /sys/rekey-recovery-key/init. Produces: 204 (empty body)
Parameters:
  • secret_shares (int) – Specifies the number of shares to split the master key into.
  • secret_threshold (int) – Specifies the number of shares required to reconstruct the master key. This must be less than or equal to secret_shares.
  • pgp_keys (list) – Specifies an array of PGP public keys used to encrypt the output unseal keys. Ordering is preserved. The keys must be base64-encoded from their original binary representation. The size of this array must be the same as secret_shares.
  • backup (bool) – Specifies if using PGP-encrypted keys, whether Vault should also store a plaintext backup of the PGP-encrypted keys at core/unseal-keys-backup in the physical storage backend. These can then be retrieved and removed via the sys/rekey/backup endpoint.
  • require_verification (bool) – This turns on verification functionality. When verification is turned on, after successful authorization with the current unseal keys, the new unseal keys are returned but the master key is not actually rotated. The new keys must be provided to authorize the actual rotation of the master key. This ensures that the new keys have been successfully saved and protects against a risk of the keys being lost after rotation but before they can be persisted. This can be used with without pgp_keys, and when used with it, it allows ensuring that the returned keys can be successfully decrypted before committing to the new shares, which the backup functionality does not provide.
  • recovery_key (bool) – If true, send requests to “rekey-recovery-key” instead of “rekey” api path.
Returns:

The JSON dict of the response.

Return type:

dict | request.Response

Examples

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

rekey_response = client.sys.start_rekey()
nonce = rekey_response['nonce']
print('Nonce for rekey is: %s' % nonce)

Example output:

Nonce for rekey is: ...

Cancel Rekey

Key.cancel_rekey(recovery_key=False)[source]

Cancel any in-progress rekey.

This clears the rekey settings as well as any progress made. This must be called to change the parameters of the rekey.

Note: Verification is still a part of a rekey. If rekeying is canceled during the verification flow, the current unseal keys remain valid.

Supported methods:
DELETE: /sys/rekey/init. Produces: 204 (empty body) DELETE: /sys/rekey-recovery-key/init. Produces: 204 (empty body)
Parameters:recovery_key (bool) – If true, send requests to “rekey-recovery-key” instead of “rekey” api path.
Returns:The response of the request.
Return type:requests.Response

Examples

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

client.sys.cancel_rekey()

Rekey

Key.rekey(key, nonce=None, recovery_key=False)[source]

Enter a single recovery key share to progress the rekey of the Vault.

If the threshold number of recovery key shares is reached, Vault will complete the rekey. Otherwise, this API must be called multiple times until that threshold is met. The rekey nonce operation must be provided with each call.

Supported methods:
PUT: /sys/rekey/update. Produces: 200 application/json PUT: /sys/rekey-recovery-key/update. Produces: 200 application/json
Parameters:
  • key (str | unicode) – Specifies a single recovery share key.
  • nonce (str | unicode) – Specifies the nonce of the rekey operation.
  • recovery_key (bool) – If true, send requests to “rekey-recovery-key” instead of “rekey” api path.
Returns:

The JSON response of the request.

Return type:

dict

Examples

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

client.sys.rekey(
    key=key,
    nonce=nonce,
)

Rekey Multi

Key.rekey_multi(keys, nonce=None, recovery_key=False)[source]

Enter multiple recovery key shares to progress the rekey of the Vault.

If the threshold number of recovery key shares is reached, Vault will complete the rekey.

Parameters:
  • keys (list) – Specifies multiple recovery share keys.
  • nonce (str | unicode) – Specifies the nonce of the rekey operation.
  • recovery_key (bool) – If true, send requests to “rekey-recovery-key” instead of “rekey” api path.
Returns:

The last response of the rekey request.

Return type:

response.Request

Examples

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

client.sys.rekey_multi(
    keys,
    nonce=nonce,
)

Read Backup Keys

Key.read_backup_keys(recovery_key=False)[source]

Retrieve the backup copy of PGP-encrypted unseal keys.

The returned value is the nonce of the rekey operation and a map of PGP key fingerprint to hex-encoded PGP-encrypted key.

Supported methods:
PUT: /sys/rekey/backup. Produces: 200 application/json PUT: /sys/rekey-recovery-key/backup. Produces: 200 application/json
Parameters:recovery_key (bool) – If true, send requests to “rekey-recovery-key” instead of “rekey” api path.
Returns:The JSON response of the request.
Return type:dict

Examples

import hvac
client = hvac.Client(url='https://127.0.0.1:8200')
rekey_response = client.sys.start_rekey(
    secret_shares=1,
    secret_threshold=1,
    pgp_keys=pgp_keys,
    backup=True,
)
nonce = rekey_response['nonce']

client.sys.rekey_multi(
    keys,
    nonce=nonce,
)

print('Backup keys are: %s' % client.sys.read_backup_keys()['data']['keys'])

Example output:

Backup keys are: {'...': [...]}