keys

Creates, updates, deletes, gets or lists a keys resource.

Overview

Name	keys
Type	Resource
Id	azure.key_vault_keys.keys

Fields

The following fields are returned by SELECT queries:

get_key

Name	Datatype	Description
attributes	object	The key management attributes.
key	object	The Json web key.
managed	boolean	True if the key's lifetime is managed by key vault. If this is a key backing a certificate, then managed will be true.
release_policy	object	The policy rules under which the key can be exported.
tags	object	Application specific metadata in the form of key-value pairs.

get_keys

Name	Datatype	Description
attributes	object	The key management attributes.
kid	string	Key identifier.
managed	boolean	True if the key's lifetime is managed by key vault. If this is a key backing a certificate, then managed will be true.
tags	object	Application specific metadata in the form of key-value pairs.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get_key	select	key_name, key_version, vault_name		Gets the public part of a stored key. The get key operation is applicable to all key types. If the requested key is symmetric, then no key material is released in the response. This operation requires the keys/get permission.
get_keys	select	vault_name	maxresults	List keys in the specified vault. Retrieves a list of the keys in the Key Vault as JSON Web Key structures that contain the public part of a stored key. The LIST operation is applicable to all key types, however only the base key identifier, attributes, and tags are provided in the response. Individual versions of a key are not listed in the response. This operation requires the keys/list permission.
create_key	insert	key_name, vault_name, kty		Creates a new key, stores it, then returns key parameters and attributes to the client. The create key operation can be used to create any key type in Azure Key Vault. If the named key already exists, Azure Key Vault creates a new version of the key. It requires the keys/create permission.
update_key	update	key_name, key_version, vault_name		The update key operation changes specified attributes of a stored key and can be applied to any key type and key version stored in Azure Key Vault. In order to perform this operation, the key must already exist in the Key Vault. Note: The cryptographic material of a key itself cannot be changed. This operation requires the keys/update permission.
delete_key	delete	key_name, vault_name		Deletes a key of any type from storage in Azure Key Vault. The delete key operation cannot be used to remove individual versions of a key. This operation removes the cryptographic material associated with the key, which means the key is not usable for Sign/Verify, Wrap/Unwrap or Encrypt/Decrypt operations. This operation requires the keys/delete permission.
backup_key	exec	key_name, vault_name		Requests that a backup of the specified key be downloaded to the client. The Key Backup operation exports a key from Azure Key Vault in a protected form. Note that this operation does NOT return key material in a form that can be used outside the Azure Key Vault system, the returned key material is either protected to a Azure Key Vault HSM or to Azure Key Vault itself. The intent of this operation is to allow a client to GENERATE a key in one Azure Key Vault instance, BACKUP the key, and then RESTORE it into another Azure Key Vault instance. The BACKUP operation may be used to export, in protected form, any key type from Azure Key Vault. Individual versions of a key cannot be backed up. BACKUP / RESTORE can be performed within geographical boundaries only; meaning that a BACKUP from one geographical area cannot be restored to another geographical area. For example, a backup from the US geographical area cannot be restored in an EU geographical area. This operation requires the key/backup permission.
restore_key	exec	vault_name, value		Restores a backed up key to a vault. Imports a previously backed up key into Azure Key Vault, restoring the key, its key identifier, attributes and access control policies. The RESTORE operation may be used to import a previously backed up key. Individual versions of a key cannot be restored. The key is restored in its entirety with the same key name as it had when it was backed up. If the key name is not available in the target Key Vault, the RESTORE operation will be rejected. While the key name is retained during restore, the final key identifier will change if the key is restored to a different vault. Restore will restore all versions and preserve version identifiers. The RESTORE operation is subject to security constraints: The target Key Vault must be owned by the same Microsoft Azure Subscription as the source Key Vault The user must have RESTORE permission in the target Key Vault. This operation requires the keys/restore permission.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
key_name	string	The name of the key. Required.
key_version	string	The version of the key to update. Required.
vault_name	string	Key vault name. (default: )
maxresults	integer	Maximum number of results to return in a page. If not specified the service will return up to 25 results. Default value is None.

SELECT examples

get_key

Gets the public part of a stored key. The get key operation is applicable to all key types. If the requested key is symmetric, then no key material is released in the response. This operation requires the keys/get permission.

SELECT
attributes,
key,
managed,
release_policy,
tags
FROM azure.key_vault_keys.keys
WHERE key_name = '{{ key_name }}' -- required
AND key_version = '{{ key_version }}' -- required
AND vault_name = '{{ vault_name }}' -- required
;

get_keys

List keys in the specified vault. Retrieves a list of the keys in the Key Vault as JSON Web Key structures that contain the public part of a stored key. The LIST operation is applicable to all key types, however only the base key identifier, attributes, and tags are provided in the response. Individual versions of a key are not listed in the response. This operation requires the keys/list permission.

SELECT
attributes,
kid,
managed,
tags
FROM azure.key_vault_keys.keys
WHERE vault_name = '{{ vault_name }}' -- required
AND maxresults = '{{ maxresults }}'
;

INSERT examples

create_key

Creates a new key, stores it, then returns key parameters and attributes to the client. The create key operation can be used to create any key type in Azure Key Vault. If the named key already exists, Azure Key Vault creates a new version of the key. It requires the keys/create permission.

INSERT INTO azure.key_vault_keys.keys (
kty,
key_size,
public_exponent,
key_ops,
attributes,
tags,
crv,
release_policy,
key_name,
vault_name
)
SELECT 
'{{ kty }}' /* required */,
{{ key_size }},
{{ public_exponent }},
'{{ key_ops }}',
'{{ attributes }}',
'{{ tags }}',
'{{ crv }}',
'{{ release_policy }}',
'{{ key_name }}',
'{{ vault_name }}'
RETURNING
attributes,
key,
managed,
release_policy,
tags
;

Manifest

# Description fields are for documentation purposes
- name: keys
props:
  - name: key_name
    value: "{{ key_name }}"
    description: Required parameter for the keys resource.
  - name: vault_name
    value: "{{ vault_name }}"
    description: Required parameter for the keys resource.
  - name: kty
    value: "{{ kty }}"
    description: |
      The type of key to create. For valid values, see JsonWebKeyType. Required. Known values are: "EC", "EC-HSM", "RSA", "RSA-HSM", "oct", and "oct-HSM".
    valid_values: ['EC', 'EC-HSM', 'RSA', 'RSA-HSM', 'oct', 'oct-HSM']
  - name: key_size
    value: {{ key_size }}
    description: |
      The key size in bits. For example: 2048, 3072, or 4096 for RSA.
  - name: public_exponent
    value: {{ public_exponent }}
    description: |
      The public exponent for a RSA key.
  - name: key_ops
    value:
      - "{{ key_ops }}"
    description: |
      Json web key operations. For more information on possible key operations, see JsonWebKeyOperation.
  - name: attributes
    description: |
      The attributes of a key managed by the key vault service.
    value:
      enabled: {{ enabled }}
      nbf: "{{ nbf }}"
      exp: "{{ exp }}"
      created: "{{ created }}"
      updated: "{{ updated }}"
      recoverableDays: {{ recoverableDays }}
      recoveryLevel: "{{ recoveryLevel }}"
      exportable: {{ exportable }}
      hsmPlatform: "{{ hsmPlatform }}"
      attestation:
        certificatePemFile: "{{ certificatePemFile }}"
        privateKeyAttestation: "{{ privateKeyAttestation }}"
        publicKeyAttestation: "{{ publicKeyAttestation }}"
        version: "{{ version }}"
      external_key:
        id: "{{ id }}"
      key_size: {{ key_size }}
  - name: tags
    value: "{{ tags }}"
    description: |
      Application specific metadata in the form of key-value pairs.
  - name: crv
    value: "{{ crv }}"
    description: |
      Elliptic curve name. For valid values, see JsonWebKeyCurveName. Known values are: "P-256", "P-384", "P-521", and "P-256K".
    valid_values: ['P-256', 'P-384', 'P-521', 'P-256K']
  - name: release_policy
    description: |
      The policy rules under which the key can be exported.
    value:
      contentType: "{{ contentType }}"
      immutable: {{ immutable }}
      data: "{{ data }}"

UPDATE examples

update_key

The update key operation changes specified attributes of a stored key and can be applied to any key type and key version stored in Azure Key Vault. In order to perform this operation, the key must already exist in the Key Vault. Note: The cryptographic material of a key itself cannot be changed. This operation requires the keys/update permission.

UPDATE azure.key_vault_keys.keys
SET 
key_ops = '{{ key_ops }}',
attributes = '{{ attributes }}',
tags = '{{ tags }}',
release_policy = '{{ release_policy }}'
WHERE 
key_name = '{{ key_name }}' --required
AND key_version = '{{ key_version }}' --required
AND vault_name = '{{ vault_name }}' --required
RETURNING
attributes,
key,
managed,
release_policy,
tags;

DELETE examples

delete_key

Deletes a key of any type from storage in Azure Key Vault. The delete key operation cannot be used to remove individual versions of a key. This operation removes the cryptographic material associated with the key, which means the key is not usable for Sign/Verify, Wrap/Unwrap or Encrypt/Decrypt operations. This operation requires the keys/delete permission.

DELETE FROM azure.key_vault_keys.keys
WHERE key_name = '{{ key_name }}' --required
AND vault_name = '{{ vault_name }}' --required
;

Lifecycle Methods

backup_key

Requests that a backup of the specified key be downloaded to the client. The Key Backup operation exports a key from Azure Key Vault in a protected form. Note that this operation does NOT return key material in a form that can be used outside the Azure Key Vault system, the returned key material is either protected to a Azure Key Vault HSM or to Azure Key Vault itself. The intent of this operation is to allow a client to GENERATE a key in one Azure Key Vault instance, BACKUP the key, and then RESTORE it into another Azure Key Vault instance. The BACKUP operation may be used to export, in protected form, any key type from Azure Key Vault. Individual versions of a key cannot be backed up. BACKUP / RESTORE can be performed within geographical boundaries only; meaning that a BACKUP from one geographical area cannot be restored to another geographical area. For example, a backup from the US geographical area cannot be restored in an EU geographical area. This operation requires the key/backup permission.

EXEC azure.key_vault_keys.keys.backup_key 
@key_name='{{ key_name }}' --required, 
@vault_name='{{ vault_name }}' --required
;

restore_key

Restores a backed up key to a vault. Imports a previously backed up key into Azure Key Vault, restoring the key, its key identifier, attributes and access control policies. The RESTORE operation may be used to import a previously backed up key. Individual versions of a key cannot be restored. The key is restored in its entirety with the same key name as it had when it was backed up. If the key name is not available in the target Key Vault, the RESTORE operation will be rejected. While the key name is retained during restore, the final key identifier will change if the key is restored to a different vault. Restore will restore all versions and preserve version identifiers. The RESTORE operation is subject to security constraints: The target Key Vault must be owned by the same Microsoft Azure Subscription as the source Key Vault The user must have RESTORE permission in the target Key Vault. This operation requires the keys/restore permission.

EXEC azure.key_vault_keys.keys.restore_key 
@vault_name='{{ vault_name }}' --required 
@@json=
'{
"value": "{{ value }}"
}'
;