Key¶

Read Root Generation Progress
Start Root Token Generation
Cancel Root Generation
Generate Root
Get Encryption Key Status
Rotate Encryption Key
Read Rekey Progress
Start Rekey
Cancel Rekey
Rekey
Rekey Multi
Read Rekey Verify Progress
Cancel Rekey Verify
Rekey Verify
Rekey Verify Multi
Read Backup Keys

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 Rekey Verify Progress ¶

Key.read_rekey_verify_progress()[source]

Read the configuration and progress of the current rekey verify attempt.

Supported methods:: GET: /sys/rekey/verify. Produces: 200 application/json

Returns: The JSON response of the request.
Return type: requests.Response

Examples¶

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

response = client.sys.read_rekey_verify_progress()

print(
    'Rekey verify progress is %d out of %d' % (
        response['progress'],
        response['t'],
    )
)

Example output:

Rekey verify progress is 0 out of 3

Cancel Rekey Verify ¶

Key.cancel_rekey_verify()[source]

Cancel any in-progress rekey verification. This clears any progress made and resets the nonce. Unlike cancel_rekey, this only resets the current verification operation, not the entire rekey atttempt. The return value is the same as GET along with the new nonce.

Supported methods:: DELETE: /sys/rekey/verify. 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.cancel_rekey_verify()

Rekey Verify ¶

Key.rekey_verify(key, nonce)[source]

Enter a single new recovery key share to progress the rekey verification of the Vault. If the threshold number of new 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 verification nonce must be provided with each call.

Supported methods:: PUT: /sys/rekey/verify. Produces: 200 application/json

Parameters

key (str | unicode) – Specifies multiple recovery share keys.
nonce (str | unicode) – Specifies the nonce of the rekey verify operation.

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_verify(
    key,
    nonce=verify_nonce,
)

Rekey Verify Multi ¶

Key.rekey_verify_multi(keys, nonce)[source]

Enter multiple new recovery key shares to progress the rekey verification of the Vault. If the threshold number of new 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 verification nonce must be provided with each call.

Supported methods:: PUT: /sys/rekey/verify. Produces: 200 application/json

Parameters

keys (list) – Specifies multiple recovery share keys.
nonce (str | unicode) – Specifies the nonce of the rekey verify operation.

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_verify_multi(
    keys,
    nonce=verify_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: {'...': [...]}