The Add-AzKeyVaultKey cmdlet creates a key in a key vault in Azure Key Vault, or imports a key into a key vault.
Use this cmdlet to add keys by using any of the following methods:
Create a key in a hardware security module (HSM) in the Key Vault service.
Create a key in software in the Key Vault service.
Import a key from your own hardware security module (HSM) to HSMs in the Key Vault service.
Import a key from a .pfx file on your computer.
Import a key from a .pfx file on your computer to hardware security modules (HSMs) in the Key Vault service.
For any of these operations, you can provide key attributes or accept default settings.
If you create or import a key that has the same name as an existing key in your key vault, the
original key is updated with the values that you specify for the new key. You can access the
previous values by using the version-specific URI for that version of the key. To learn about key
versions and the URI structure, see About Keys and Secrets
in the Key Vault REST API documentation.
Note: To import a key from your own hardware security module, you must first generate a BYOK
package (a file with a .byok file name extension) by using the Azure Key Vault BYOK toolset. For
more information, see
How to Generate and Transfer HSM-Protected Keys for Azure Key Vault.
As a best practice, back up your key after it is created or updated, by using the
Backup-AzKeyVaultKey cmdlet. There is no undelete functionality, so if you accidentally delete
your key or delete it and then change your mind, the key is not recoverable unless you have a
backup of it that you can restore.
Vault/HSM Name : test-kv
Name : test-key
Key Type : EC
Key Size :
Curve Name : P-256
Version : 4da74af2b4fd47d6b1aa0b05c9a2ed13
Id : https://test-kv.vault.azure.net:443/keys/test-key/4da74af2b4fd47d6b1aa0b05c9a2ed13
Enabled : True
Expires :
Not Before :
Created : 8/24/2021 6:38:34 AM
Updated : 8/24/2021 6:38:34 AM
Recovery Level : Recoverable+Purgeable
Tags :
This command creates a software-protected EC key named test-key in the key vault named test-kv. Its curve name is P-256 by default.
Vault/HSM Name : contoso
Name : ITHsmNonDefault
Key Type : RSA
Key Size : 2048
Version : 929bfc14db84439b823ffd1bedadaf5f
Id : https://contoso.vault.azure.net:443/keys/ITHsmNonDefault/929bfc14db84439b823ffd1bedadaf5f
Enabled : False
Expires : 5/21/2020 11:12:43 PM
Not Before : 5/21/2018 11:12:50 PM
Created : 5/21/2018 11:13:17 PM
Updated : 5/21/2018 11:13:17 PM
Purge Disabled : False
Tags : Name Value
Severity high
Accounting true
The first command stores the values decrypt and verify in the $KeyOperations variable.
The second command creates a DateTime object, defined in UTC, by using the Get-Date cmdlet.
That object specifies a time two years in the future. The command stores that date in the $Expires
variable. For more information, type Get-Help Get-Date.
The third command creates a DateTime object by using the Get-Date cmdlet. That object
specifies current UTC time. The command stores that date in the $NotBefore variable.
The final command creates a key named ITHsmNonDefault that is an HSM-protected key. The command
specifies values for allowed key operations stored $KeyOperations. The command specifies times for
the Expires and NotBefore parameters created in the previous commands, and tags for high
severity and IT. The new key is disabled. You can enable it by using the Set-AzKeyVaultKey
cmdlet.
Vault Name : contoso
Name : ITByok
Version : 67da57e9cadf48a2ad8d366b115843ab
Id : https://contoso.vault.azure.net:443/keys/ITByok/67da57e9cadf48a2ad8d366b115843ab
Enabled : True
Expires :
Not Before :
Created : 5/21/2018 11:10:58 PM
Updated : 5/21/2018 11:10:58 PM
Purge Disabled : False
Tags :
This command imports the key named ITByok from the location that the KeyFilePath parameter
specifies. The imported key is an HSM-protected key.
To import a key from your own hardware security module, you must first generate a BYOK package (a file with a .byok file name extension) by using the Azure Key Vault BYOK toolset.
For more information, see
How to Generate and Transfer HSM-Protected Keys for Azure Key Vault.
Vault Name : contoso
Name : ITPfx
Version : 67da57e9cadf48a2ad8d366b115843ab
Id : https://contoso.vault.azure.net:443/keys/ITPfx/67da57e9cadf48a2ad8d366b115843ab
Enabled : True
Expires :
Not Before :
Created : 5/21/2018 11:10:58 PM
Updated : 5/21/2018 11:10:58 PM
Purge Disabled : False
Tags :
The first command converts a string into a secure string by using the ConvertTo-SecureString
cmdlet, and then stores that string in the $Password variable. For more information, type Get-Help ConvertTo-SecureString.
The second command creates a software password in the Contoso key vault. The command specifies the
location for the key and the password stored in $Password.
Vault Name : contoso
Name : ITPfxToHSM
Version : 929bfc14db84439b823ffd1bedadaf5f
Id : https://contoso.vault.azure.net:443/keys/ITPfxToHSM/929bfc14db84439b823ffd1bedadaf5f
Enabled : True
Expires : 5/21/2020 11:12:43 PM
Not Before :
Created : 5/21/2018 11:13:17 PM
Updated : 5/21/2018 11:13:17 PM
Purge Disabled : False
Tags : Name Value
Severity high
Accounting true
The first command converts a string into a secure string by using the ConvertTo-SecureString
cmdlet, and then stores that string in the $Password variable.
The second command creates a DateTime object by using the Get-Date cmdlet, and then stores
that object in the $Expires variable.
The third command creates the $tags variable to set tags for high severity and IT.
The final command imports a key as an HSM key from the specified location. The command specifies
the expiration time stored in $Expires and password stored in $Password, and applies the tags
stored in $tags.
Example 8: Generate a Key Exchange Key (KEK) for "bring your own key" (BYOK) feature
Generates a key (referred to as a Key Exchange Key (KEK)). The KEK must be an RSA-HSM key that has only the import key operation. Only Key Vault Premium SKU supports RSA-HSM keys.
For more details please refer to https://learn.microsoft.com/azure/key-vault/keys/hsm-protected-keys
Specifies whether to add the key as a software-protected key or an HSM-protected key in the Key Vault service.
Valid values are: HSM and Software.
Note: To use HSM as your destination, you must have a key vault that supports HSMs. For more
information about the service tiers and capabilities for Azure Key Vault, see the
Azure Key Vault Pricing website.
This parameter is required when you create a new key. If you import a key by using the
KeyFilePath parameter, this parameter is optional:
If you do not specify this parameter, and this cmdlet imports a key that has .byok file name
extension, it imports that key as an HSM-protected key. The cmdlet cannot import that key as
software-protected key.
If you do not specify this parameter, and this cmdlet imports a key that has a .pfx file name
extension, it imports the key as a software-protected key.
Indicates that the key you are adding is set to an initial state of disabled. Any attempt to use
the key will fail. Use this parameter if you are preloading keys that you intend to enable later.
Specifies the expiration time of the key in UTC, as a DateTime object, for the key that this cmdlet adds. If not specified, key will not expire. To obtain a DateTime object, use the Get-Date cmdlet. For more information, type Get-Help Get-Date. Please notice that expires is ignored for Key Exchange Key used in BYOK process.
Specifies a password for the imported file as a SecureString object. To obtain a
SecureString object, use the ConvertTo-SecureString cmdlet. For more information, type
Get-Help ConvertTo-SecureString. You must specify this password to import a file with a .pfx file
name extension.
Specifies the path of a local file that contains key material that this cmdlet imports.
The valid file name extensions are .byok and .pfx.
If the file is a .byok file, the key is automatically protected by HSMs after the import and you
cannot override this default.
If the file is a .pfx file, the key is automatically protected by software after the import. To
override this default, set the Destination parameter to HSM so that the key is HSM-protected.
When you specify this parameter, the Destination parameter is optional.
Specifies an array of operations that can be performed by using the key that this cmdlet adds.
If you do not specify this parameter, all operations can be performed.
The acceptable values for this parameter are a comma-separated list of key operations as defined by
the JSON Web Key (JWK) specification:
Specifies the name of the key to add to the key vault. This cmdlet constructs the fully qualified
domain name (FQDN) of a key based on the name that this parameter specifies, the name of the key
vault, and your current environment. The name must be a string of 1 through 63 characters in length
that contains only 0-9, a-z, A-Z, and - (the dash symbol).
Specifies the time, as a DateTime object, before which the key cannot be used. This parameter
uses UTC. To obtain a DateTime object, use the Get-Date cmdlet. If you do not specify this
parameter, the key can be used immediately.
Specifies the name of the key vault to which this cmdlet adds the key. This cmdlet constructs the
FQDN of a key vault based on the name that this parameter specifies and your current environment.
This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable,
-InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable,
-ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see
about_CommonParameters.
