exec.azurerm.keyvault.key

Azure Resource Manager (ARM) Key Execution Module

New in version 2.0.0.

Changed in version 4.0.0.

maintainer:

<devops@eitr.tech>
configuration:

This module requires Azure Resource Manager credentials to be passed as keyword arguments to every function or via acct in order to work properly.

Required provider parameters:

if using username and password:
  • subscription_id
  • username
  • password
if using a service principal:
  • subscription_id
  • tenant
  • client_id
  • secret

Optional provider parameters:

cloud_environment: Used to point the cloud driver to different API endpoints, such as Azure GovCloud. Possible values:

  • AZURE_PUBLIC_CLOUD (default)
  • AZURE_CHINA_CLOUD
  • AZURE_US_GOV_CLOUD
  • AZURE_GERMAN_CLOUD
idem_azurerm.exec.azurerm.keyvault.key.backup_key(hub, ctx, name, vault_url, **kwargs)

New in version 2.0.0.

Back up a key in a protected form useable only by Azure Key Vault. Requires key/backup permission. This is intended to allow copying a key from one vault to another. Both vaults must be owned by the same Azure subscription. Also, backup / restore cannot be performed across geopolitical boundaries. For example, a backup from a vault in a USA region cannot be restored to a vault in an EU region.

Parameters:
  • name – The name of the key to back up.
  • vault_url – The URL of the vault that the client will access.

CLI Example:

azurerm.keyvault.key.backup_key test_name test_vault
idem_azurerm.exec.azurerm.keyvault.key.begin_delete_key(hub, ctx, name, vault_url, **kwargs)

New in version 2.0.0.

Delete all versions of a key and its cryptographic material. Requires keys/delete permission. If the vault has soft-delete enabled, deletion may take several seconds to complete.

Parameters:
  • name – The name of the key to delete.
  • vault_url – The URL of the vault that the client will access.

CLI Example:

azurerm.keyvault.key.begin_delete_key test_name test_vault
idem_azurerm.exec.azurerm.keyvault.key.begin_recover_deleted_key(hub, ctx, name, vault_url, **kwargs)

New in version 2.0.0.

Recover a deleted key to its latest version. Possible only in a vault with soft-delete enabled. Requires keys/recover permission. If the vault does not have soft-delete enabled, the begin_delete_key operation is permanent, and this method will raise an error. Attempting to recover a non-deleted key will also raise an error.

Parameters:
  • name – The name of the deleted key to recover.
  • vault_url – The URL of the vault that the client will access.

CLI Example:

azurerm.keyvault.key.begin_recover_deleted_key test_name test_vault
idem_azurerm.exec.azurerm.keyvault.key.create_ec_key(hub, ctx, name, vault_url, curve=None, key_operations=None, hardware_protected=None, enabled=None, expires_on=None, not_before=None, tags=None, **kwargs)

New in version 2.0.0.

Changed in version 4.0.0.

Create a new elliptic curve key or, if name is already in use, create a new version of the key. Requires the keys/create permission. Key properties can be specified as keyword arguments.

Parameters:
  • name – The name of the new key. Key names can only contain alphanumeric characters and dashes.
  • vault_url – The URL of the vault that the client will access.
  • curve – Elliptic curve name. Defaults to the NIST P-256 elliptic curve. Possible values include: “P-256”, “P-256K”, “P-384”, “P-521”.
  • key_operations – A list of permitted key operations. Possible values include: ‘decrypt’, ‘encrypt’, ‘sign’, ‘unwrap_key’, ‘verify’, ‘wrap_key’.
  • hardware_protected – A boolean value specifying whether the key should be created in a hardware security module. Defaults to False.
  • enabled – A boolean value specifying whether the key is enabled for use.
  • expires_on – When the key will expire, in UTC. This parameter should be a string representation of a Datetime object in ISO-8601 format.
  • not_before – The time before which the key can not be used, in UTC. This parameter should be a string representation of a Datetime object in ISO-8601 format.
  • tags – Application specific metadata in the form of key-value pairs.

CLI Example:

azurerm.keyvault.key.create_ec_key test_name test_vault
idem_azurerm.exec.azurerm.keyvault.key.create_key(hub, ctx, name, key_type, vault_url, key_operations=None, size=None, curve=None, enabled=None, expires_on=None, not_before=None, tags=None, **kwargs)

New in version 2.0.0.

Changed in version 4.0.0.

Create a key or, if name is already in use, create a new version of the key. Requires keys/create permission. Key properties can be specified as keyword arguments.

Parameters:
  • name – The name of the new key. Key names can only contain alphanumeric characters and dashes.
  • key_type – The type of key to create. Possible values include: ‘ec’, ‘ec_hsm’, ‘oct’, ‘rsa’, ‘rsa_hsm’.
  • vault_url – The URL of the vault that the client will access.
  • key_operations – A list of permitted key operations. Possible values include: ‘decrypt’, ‘encrypt’, ‘sign’, ‘unwrap_key’, ‘verify’, ‘wrap_key’.
  • size – RSA key size in bits, for example 2048, 3072, or 4096. Applies to RSA keys only.
  • curve – Elliptic curve name. Defaults to the NIST P-256 elliptic curve. Possible values include: “P-256”, “P-256K”, “P-384”, “P-521”.
  • enabled – Whether the key is enabled for use.
  • expires_on – When the key will expire, in UTC. This parameter should be a string representation of a Datetime object in ISO-8601 format.
  • not_before – The time before which the key can not be used, in UTC. This parameter should be a string representation of a Datetime object in ISO-8601 format.
  • tags – Application specific metadata in the form of key-value pairs.

CLI Example:

azurerm.keyvault.key.create_key test_name test_type test_vault
idem_azurerm.exec.azurerm.keyvault.key.create_rsa_key(hub, ctx, name, vault_url, size=None, key_operations=None, hardware_protected=None, enabled=None, expires_on=None, not_before=None, tags=None, **kwargs)

New in version 2.0.0.

Create a new RSA key or, if name is already in use, create a new version of the key. Requires the keys/create permission. Key properties can be specified as keyword arguments.

Parameters:
  • name – The name of the new key. Key names can only contain alphanumeric characters and dashes.
  • vault_url – The URL of the vault that the client will access.
  • size – Key size in bits, for example 2048, 3072, or 4096.
  • key_operations – A list of permitted key operations. Possible values include: ‘decrypt’, ‘encrypt’, ‘sign’, ‘unwrap_key’, ‘verify’, ‘wrap_key’.
  • hardware_protected – A boolean value specifying whether the key should be created in a hardware security module. Defaults to False.
  • enabled – Whether the key is enabled for use.
  • expires_on – When the key will expire, in UTC. This parameter should be a string representation of a Datetime object in ISO-8601 format.
  • not_before – The time before which the key can not be used, in UTC. This parameter should be a string representation of a Datetime object in ISO-8601 format.
  • tags – Application specific metadata in the form of key-value pairs.

CLI Example:

azurerm.keyvault.key.create_rsa_key test_name test_vault
idem_azurerm.exec.azurerm.keyvault.key.get_deleted_key(hub, ctx, name, vault_url, **kwargs)

New in version 2.0.0.

Get a deleted key. Possible only in a vault with soft-delete enabled. Requires keys/get permission.

Parameters:
  • name – The name of the key.
  • vault_url – The URL of the vault that the client will access.

CLI Example:

azurerm.keyvault.key.get_deleted_key test_name test_vault
idem_azurerm.exec.azurerm.keyvault.key.get_key(hub, ctx, name, vault_url, version=None, **kwargs)

New in version 2.0.0.

Get a key’s attributes and, if it’s an asymmetric key, its public material. Requires keys/get permission.

Parameters:
  • name – The name of the key to get.
  • vault_url – The URL of the vault that the client will access.
  • version – Used to specify the version of the key to get. If not specified, gets the latest version of the key.

CLI Example:

azurerm.keyvault.key.get_key test_name test_vault
idem_azurerm.exec.azurerm.keyvault.key.get_key_client(hub, ctx, vault_url, **kwargs)

New in version 2.0.0.

Load the key client and return a KeyClient object.

Parameters:vault_url – The URL of the vault that the client will access.
idem_azurerm.exec.azurerm.keyvault.key.import_key(hub, ctx, name, vault_url, hardware_protected=None, enabled=None, not_before=None, expires_on=None, tags=None, **kwargs)

New in version 2.0.0.

Changed in version 4.0.0.

Import a key created externally. Requires keys/import permission. If name is already in use, the key will be imported as a new version. Parameters used to build a JSONWebKey object will be passed to this module. More information about some of those parameters can be found at the following link: https://tools.ietf.org/html/draft-ietf-jose-json-web-key-18.

Parameters:
  • name – The name of the imported key.
  • vault_url – The URL of the vault that the client will access.
  • hardware_protected – A boolean value specifying whether the key should be created in a hardware security module. Defaults to False.
  • enabled – A boolean value specifying whether the key is enabled for use.
  • expires_on – When the key will expire, in UTC. This parameter should be a string representation of a Datetime object in ISO-8601 format.
  • not_before – The time before which the key can not be used, in UTC. This parameter should be a string representation of a Datetime object in ISO-8601 format.
  • tags – Application specific metadata in the form of key-value pairs.

Additional parameters passed as keyword arguments are used to build a JSONWebKey object will be passed to this module. Below some of those parameters are defined. More information about some of those parameters can be found at the following link: https://tools.ietf.org/html/draft-ietf-jose-json-web-key-18.

Parameters:
  • kid – Key identifier.
  • kty – Key type. Possible values inclide: ‘ec’, ‘ec_hsm’, ‘oct’, ‘rsa’, ‘rsa_hsm’.
  • key_ops – A list of allow operations for the key. Possible elements of the list include: ‘decrypt’, ‘encrypt’, ‘sign’, ‘unwrap_key’, ‘verify’, ‘wrap_key’
  • n – RSA modulus.
  • e – RSA public exponent.
  • d – RSA private exponent, or the D component of the EC private key.
  • dp – RSA private key parameter.
  • dq – RSA private key parameter.
  • qi – RSA private key parameter.
  • p – RSA secret prime.
  • q – RSA secret prime, with p < q.
  • k – Symmetric key.
  • t – HSM Token, used with ‘Bring Your Own Key’.
  • crv – Elliptic curve name. Posible values include: ‘p_256’, ‘p_256_k’, ‘p_384’, and ‘p_521’.
  • x – X component of an EC public key.
  • y – Y component of an EC public key.

CLI Example:

azurerm.keyvault.key.import_key test_name test_vault test_webkey_params
idem_azurerm.exec.azurerm.keyvault.key.list_(hub, ctx, vault_url, **kwargs)

New in version 2.0.0.

List identifiers and properties of all keys in the vault. Requires keys/list permission.

Parameters:vault_url – The URL of the vault that the client will access.

CLI Example:

azurerm.keyvault.key.list test_vault
idem_azurerm.exec.azurerm.keyvault.key.list_deleted_keys(hub, ctx, vault_url, **kwargs)

New in version 2.0.0.

List all deleted keys, including the public part of each. Possible only in a vault with soft-delete enabled. Requires keys/list permission.

Parameters:vault_url – The URL of the vault that the client will access.

CLI Example:

azurerm.keyvault.key.list_deleted_keys test_vault
idem_azurerm.exec.azurerm.keyvault.key.list_properties_of_key_versions(hub, ctx, name, vault_url, **kwargs)

New in version 2.0.0.

List the identifiers and properties of a key’s versions. Requires keys/list permission.

Parameters:
  • name – The name of the key.
  • vault_url – The URL of the vault that the client will access.

CLI Example:

azurerm.keyvault.key.list_properties_of_key_versions test_name test_vault
idem_azurerm.exec.azurerm.keyvault.key.purge_deleted_key(hub, ctx, name, vault_url, **kwargs)

New in version 2.0.0.

Permanently deletes a deleted key. Only possible in a vault with soft-delete enabled. Performs an irreversible deletion of the specified key, without possibility for recovery. The operation is not available if the recovery_level does not specify ‘Purgeable’. This method is only necessary for purging a key before its scheduled_purge_date. Requires keys/purge permission.

Parameters:
  • name – The name of the deleted key to purge.
  • vault_url – The URL of the vault that the client will access.

CLI Example:

azurerm.keyvault.key.purge_deleted_key test_name test_vault
idem_azurerm.exec.azurerm.keyvault.key.restore_key_backup(hub, ctx, backup, vault_url, **kwargs)

New in version 2.0.0.

Restore a key backup to the vault. This imports all versions of the key, with its name, attributes, and access control policies. If the key’s name is already in use, restoring it will fail. Also, the target vault must be owned by the same Microsoft Azure subscription as the source vault. Requires keys/restore permission.

Parameters:
  • backup – A key backup as returned by the backup_key operation.
  • vault_url – The URL of the vault that the client will access.

CLI Example:

azurerm.keyvault.key.restore_key_backup test_backup test_vault
idem_azurerm.exec.azurerm.keyvault.key.update_key_properties(hub, ctx, name, vault_url, version=None, key_operations=None, enabled=None, expires_on=None, not_before=None, tags=None, **kwargs)

New in version 2.0.0.

Changed in version 4.0.0.

Change a key’s properties (not its cryptographic material). Requires keys/update permission. Key properties that need to be updated can be specified as keyword arguments.

Parameters:
  • name – The name of the key to update.
  • vault_url – The URL of the vault that the client will access.
  • version – Used to specify the version of the key to update. If no version is specified, the latest version of the key will be updated.
  • key_operations – A list of permitted key operations. Possible values include: ‘decrypt’, ‘encrypt’, ‘sign’, ‘unwrap_key’, ‘verify’, ‘wrap_key’.
  • enabled – Whether the key is enabled for use.
  • expires_on – When the key will expire, in UTC. This parameter should be a string representation of a Datetime object in ISO-8601 format.
  • not_before – The time before which the key can not be used, in UTC. This parameter should be a string representation of a Datetime object in ISO-8601 format.
  • tags – Application specific metadata in the form of key-value pairs.

CLI Example:

azurerm.keyvault.key.update_key_properties test_name test_vault test_version