hvac.api.secrets_engines¶
Vault secrets engines endpoints
-
class
hvac.api.secrets_engines.
Kv
(adapter, default_kv_version='2')[source]¶ Bases:
hvac.api.vault_api_base.VaultApiBase
Class containing methods for the key/value secrets_engines backend API routes. Reference: https://www.vaultproject.io/docs/secrets/kv/index.html
-
__init__
(adapter, default_kv_version='2')[source]¶ Create a new Kv instnace.
Parameters: - adapter (hvac.adapters.Adapter) – Instance of
hvac.adapters.Adapter
; used for performing HTTP requests. - default_kv_version (str | unicode) – KV version number (e.g., ‘1’) to use as the default when accessing attributes/methods under this class.
- adapter (hvac.adapters.Adapter) – Instance of
-
allowed_kv_versions
= ['1', '2']¶
-
default_kv_version
¶
-
v1
¶ Accessor for kv version 1 class / method. Provided via the
hvac.api.secrets_engines.kv_v1.KvV1
class.Returns: This Kv instance’s associated KvV1 instance. Return type: hvac.api.secrets_engines.kv_v1.KvV1
-
v2
¶ Accessor for kv version 2 class / method. Provided via the
hvac.api.secrets_engines.kv_v2.KvV2
class.Returns: This Kv instance’s associated KvV2 instance. Return type: hvac.api.secrets_engines.kv_v2.KvV2
-
-
class
hvac.api.secrets_engines.
KvV1
(adapter)[source]¶ Bases:
hvac.api.vault_api_base.VaultApiBase
KV Secrets Engine - Version 1 (API).
Reference: https://www.vaultproject.io/api/secrets/kv/kv-v1.html
-
create_or_update_secret
(path, secret, method=None, mount_point='secret')[source]¶ Store a secret at the specified location.
If the value does not yet exist, the calling token must have an ACL policy granting the create capability. If the value already exists, the calling token must have an ACL policy granting the update capability.
- Supported methods:
- POST: /{mount_point}/{path}. Produces: 204 (empty body) PUT: /{mount_point}/{path}. Produces: 204 (empty body)
Parameters: - path (str | unicode) – Specifies the path of the secrets to create/update. This is specified as part of the URL.
- secret (dict) – Specifies keys, paired with associated values, to be held at the given location. Multiple key/value pairs can be specified, and all will be returned on a read operation. A key called ttl will trigger some special behavior. See the Vault KV secrets engine documentation for details.
- method (str | unicode) – Optional parameter to explicitly request a POST (create) or PUT (update) request to the selected kv secret engine. If no argument is provided for this parameter, hvac attempts to intelligently determine which method is appropriate.
- mount_point (str | unicode) – The “path” the secret engine was mounted on.
Returns: The response of the create_or_update_secret request.
Return type: requests.Response
-
delete_secret
(path, mount_point='secret')[source]¶ Delete the secret at the specified location.
- Supported methods:
- DELETE: /{mount_point}/{path}. Produces: 204 (empty body)
Parameters: - path (str | unicode) – Specifies the path of the secret to delete. This is specified as part of the URL.
- mount_point (str | unicode) – The “path” the secret engine was mounted on.
Returns: The response of the delete_secret request.
Return type: requests.Response
-
list_secrets
(path, mount_point='secret')[source]¶ Return a list of key names at the specified location.
Folders are suffixed with /. The input must be a folder; list on a file will not return a value. Note that no policy-based filtering is performed on keys; do not encode sensitive information in key names. The values themselves are not accessible via this command.
- Supported methods:
- LIST: /{mount_point}/{path}. Produces: 200 application/json
Parameters: - path (str | unicode) – Specifies the path of the secrets to list. This is specified as part of the URL.
- mount_point (str | unicode) – The “path” the secret engine was mounted on.
Returns: The JSON response of the list_secrets request.
Return type: dict
-
read_secret
(path, mount_point='secret')[source]¶ Retrieve the secret at the specified location.
- Supported methods:
- GET: /{mount_point}/{path}. Produces: 200 application/json
Parameters: - path (str | unicode) – Specifies the path of the secret to read. This is specified as part of the URL.
- mount_point (str | unicode) – The “path” the secret engine was mounted on.
Returns: The JSON response of the read_secret request.
Return type: dict
-
-
class
hvac.api.secrets_engines.
KvV2
(adapter)[source]¶ Bases:
hvac.api.vault_api_base.VaultApiBase
KV Secrets Engine - Version 2 (API).
Reference: https://www.vaultproject.io/api/secret/kv/kv-v2.html
-
configure
(max_versions=10, cas_required=None, mount_point='secret')[source]¶ Configure backend level settings that are applied to every key in the key-value store.
- Supported methods:
- POST: /{mount_point}/config. Produces: 204 (empty body)
Parameters: - max_versions (int) – The number of versions to keep per key. This value applies to all keys, but a key’s metadata setting can overwrite this value. Once a key has more than the configured allowed versions the oldest version will be permanently deleted. Defaults to 10.
- cas_required (bool) – If true all keys will require the cas parameter to be set on all write requests.
- mount_point (str | unicode) – The “path” the secret engine was mounted on.
Returns: The response of the request.
Return type: requests.Response
-
create_or_update_secret
(path, secret, cas=None, mount_point='secret')[source]¶ Create a new version of a secret at the specified location.
If the value does not yet exist, the calling token must have an ACL policy granting the create capability. If the value already exists, the calling token must have an ACL policy granting the update capability.
- Supported methods:
- POST: /{mount_point}/data/{path}. Produces: 200 application/json
Parameters: - path (str | unicode) – Path
- cas (int) – Set the “cas” value to use a Check-And-Set operation. If not set the write will be allowed. If set to 0 a write will only be allowed if the key doesn’t exist. If the index is non-zero the write will only be allowed if the key’s current version matches the version specified in the cas parameter.
- secret (dict) – The contents of the “secret” dict will be stored and returned on read.
- mount_point (str | unicode) – The “path” the secret engine was mounted on.
Returns: The JSON response of the request.
Return type: dict
-
delete_latest_version_of_secret
(path, mount_point='secret')[source]¶ Issue a soft delete of the secret’s latest version at the specified location.
This marks the version as deleted and will stop it from being returned from reads, but the underlying data will not be removed. A delete can be undone using the undelete path.
- Supported methods:
- DELETE: /{mount_point}/data/{path}. Produces: 204 (empty body)
Parameters: - path (str | unicode) – Specifies the path of the secret to delete. This is specified as part of the URL.
- mount_point (str | unicode) – The “path” the secret engine was mounted on.
Returns: The response of the request.
Return type: requests.Response
-
delete_metadata_and_all_versions
(path, mount_point='secret')[source]¶ Delete (permanently) the key metadata and all version data for the specified key.
All version history will be removed.
- Supported methods:
- DELETE: /{mount_point}/metadata/{path}. Produces: 204 (empty body)
Parameters: - path (str | unicode) – Specifies the path of the secret to delete. This is specified as part of the URL.
- mount_point (str | unicode) – The “path” the secret engine was mounted on.
Returns: The response of the request.
Return type: requests.Response
-
delete_secret_versions
(path, versions, mount_point='secret')[source]¶ Issue a soft delete of the specified versions of the secret.
This marks the versions as deleted and will stop them from being returned from reads, but the underlying data will not be removed. A delete can be undone using the undelete path.
- Supported methods:
- POST: /{mount_point}/delete/{path}. Produces: 204 (empty body)
Parameters: - path (str | unicode) – Specifies the path of the secret to delete. This is specified as part of the URL.
- versions (int) – The versions to be deleted. The versioned data will not be deleted, but it will no longer be returned in normal get requests.
- mount_point (str | unicode) – The “path” the secret engine was mounted on.
Returns: The response of the request.
Return type: requests.Response
-
destroy_secret_versions
(path, versions, mount_point='secret')[source]¶ Permanently remove the specified version data and numbers for the provided path from the key-value store.
- Supported methods:
- POST: /{mount_point}/destroy/{path}. Produces: 204 (empty body)
Parameters: - path (str | unicode) – Specifies the path of the secret to destroy. This is specified as part of the URL.
- versions (list of int) – The versions to destroy. Their data will be permanently deleted.
- mount_point (str | unicode) – The “path” the secret engine was mounted on.
Returns: The response of the request.
Return type: requests.Response
-
list_secrets
(path, mount_point='secret')[source]¶ Return a list of key names at the specified location.
Folders are suffixed with /. The input must be a folder; list on a file will not return a value. Note that no policy-based filtering is performed on keys; do not encode sensitive information in key names. The values themselves are not accessible via this command.
- Supported methods:
- LIST: /{mount_point}/metadata/{path}. Produces: 200 application/json
Parameters: - path (str | unicode) – Specifies the path of the secrets to list. This is specified as part of the URL.
- mount_point (str | unicode) – The “path” the secret engine was mounted on.
Returns: The JSON response of the request.
Return type: dict
-
read_configuration
(mount_point='secret')[source]¶ Read the KV Version 2 configuration.
- Supported methods:
- GET: /auth/{mount_point}/config. Produces: 200 application/json
Parameters: mount_point (str | unicode) – The “path” the secret engine was mounted on. Returns: The JSON response of the request. Return type: dict
-
read_secret_metadata
(path, mount_point='secret')[source]¶ Retrieve the metadata and versions for the secret at the specified path.
- Supported methods:
- GET: /{mount_point}/metadata/{path}. Produces: 200 application/json
Parameters: - path (str | unicode) – Specifies the path of the secret to read. This is specified as part of the URL.
- mount_point (str | unicode) – The “path” the secret engine was mounted on.
Returns: The JSON response of the request.
Return type: dict
-
read_secret_version
(path, version=None, mount_point='secret')[source]¶ Retrieve the secret at the specified location.
- Supported methods:
- GET: /{mount_point}/data/{path}. Produces: 200 application/json
Parameters: - path (str | unicode) – Specifies the path of the secret to read. This is specified as part of the URL.
- version (int) – Specifies the version to return. If not set the latest version is returned.
- mount_point (str | unicode) – The “path” the secret engine was mounted on.
Returns: The JSON response of the request.
Return type: dict
-
undelete_secret_versions
(path, versions, mount_point='secret')[source]¶ Undelete the data for the provided version and path in the key-value store.
This restores the data, allowing it to be returned on get requests.
- Supported methods:
- POST: /{mount_point}/undelete/{path}. Produces: 204 (empty body)
Parameters: - path (str | unicode) – Specifies the path of the secret to undelete. This is specified as part of the URL.
- versions (list of int) – The versions to undelete. The versions will be restored and their data will be returned on normal get requests.
- mount_point (str | unicode) – The “path” the secret engine was mounted on.
Returns: The response of the request.
Return type: requests.Response
-
update_metadata
(path, max_versions=None, cas_required=None, mount_point='secret')[source]¶ Updates the max_versions of cas_required setting on an existing path.
- Supported methods:
- POST: /{mount_point}/metadata/{path}. Produces: 204 (empty body)
Parameters: - path (str | unicode) – Path
- max_versions (int) – The number of versions to keep per key. If not set, the backend’s configured max version is used. Once a key has more than the configured allowed versions the oldest version will be permanently deleted.
- cas_required (bool) – If true the key will require the cas parameter to be set on all write requests. If false, the backend’s configuration will be used.
- mount_point (str | unicode) – The “path” the secret engine was mounted on.
Returns: The response of the request.
Return type: requests.Response
-