Add-AzKeyVaultKey

Syntax

Add-AzKeyVaultKey
   [-VaultName] <String>
   [-Name] <String>
   -Destination <String>
   [-Disable]
   [-KeyOps <String[]>]
   [-Expires <DateTime>]
   [-NotBefore <DateTime>]
   [-Tag <Hashtable>]
   [-Size <Int32>]
   [-KeyType <String>]
   [-CurveName <String>]
   [-Exportable]
   [-Immutable]
   [-ReleasePolicyPath <String>]
   [-UseDefaultCVMPolicy]
   [-DefaultProfile <IAzureContextContainer>]
   [-WhatIf]
   [-Confirm]
   [<CommonParameters>]

Add-AzKeyVaultKey
   [-VaultName] <String>
   [-Name] <String>
   -KeyFilePath <String>
   [-KeyFilePassword <SecureString>]
   [-Destination <String>]
   [-Disable]
   [-KeyOps <String[]>]
   [-Expires <DateTime>]
   [-NotBefore <DateTime>]
   [-Tag <Hashtable>]
   [-KeyType <String>]
   [-CurveName <String>]
   [-DefaultProfile <IAzureContextContainer>]
   [-WhatIf]
   [-Confirm]
   [<CommonParameters>]

Add-AzKeyVaultKey
   -HsmName <String>
   [-Name] <String>
   [-Disable]
   [-KeyOps <String[]>]
   [-Expires <DateTime>]
   [-NotBefore <DateTime>]
   [-Tag <Hashtable>]
   [-Size <Int32>]
   -KeyType <String>
   [-CurveName <String>]
   [-Exportable]
   [-Immutable]
   [-ReleasePolicyPath <String>]
   [-UseDefaultCVMPolicy]
   [-DefaultProfile <IAzureContextContainer>]
   [-WhatIf]
   [-Confirm]
   [<CommonParameters>]

Add-AzKeyVaultKey
   -HsmName <String>
   [-Name] <String>
   -KeyFilePath <String>
   [-KeyFilePassword <SecureString>]
   [-Disable]
   [-KeyOps <String[]>]
   [-Expires <DateTime>]
   [-NotBefore <DateTime>]
   [-Tag <Hashtable>]
   [-DefaultProfile <IAzureContextContainer>]
   [-WhatIf]
   [-Confirm]
   [<CommonParameters>]

Add-AzKeyVaultKey
   [-InputObject] <PSKeyVault>
   [-Name] <String>
   -Destination <String>
   [-Disable]
   [-KeyOps <String[]>]
   [-Expires <DateTime>]
   [-NotBefore <DateTime>]
   [-Tag <Hashtable>]
   [-Size <Int32>]
   [-KeyType <String>]
   [-CurveName <String>]
   [-Exportable]
   [-Immutable]
   [-ReleasePolicyPath <String>]
   [-UseDefaultCVMPolicy]
   [-DefaultProfile <IAzureContextContainer>]
   [-WhatIf]
   [-Confirm]
   [<CommonParameters>]

Add-AzKeyVaultKey
   [-InputObject] <PSKeyVault>
   [-Name] <String>
   -KeyFilePath <String>
   [-KeyFilePassword <SecureString>]
   [-Destination <String>]
   [-Disable]
   [-KeyOps <String[]>]
   [-Expires <DateTime>]
   [-NotBefore <DateTime>]
   [-Tag <Hashtable>]
   [-KeyType <String>]
   [-CurveName <String>]
   [-DefaultProfile <IAzureContextContainer>]
   [-WhatIf]
   [-Confirm]
   [<CommonParameters>]

Add-AzKeyVaultKey
   [-HsmObject] <PSManagedHsm>
   [-Name] <String>
   [-Disable]
   [-KeyOps <String[]>]
   [-Expires <DateTime>]
   [-NotBefore <DateTime>]
   [-Tag <Hashtable>]
   [-Size <Int32>]
   -KeyType <String>
   [-CurveName <String>]
   [-Exportable]
   [-Immutable]
   [-ReleasePolicyPath <String>]
   [-UseDefaultCVMPolicy]
   [-DefaultProfile <IAzureContextContainer>]
   [-WhatIf]
   [-Confirm]
   [<CommonParameters>]

Add-AzKeyVaultKey
   [-HsmObject] <PSManagedHsm>
   [-Name] <String>
   -KeyFilePath <String>
   [-KeyFilePassword <SecureString>]
   [-Disable]
   [-KeyOps <String[]>]
   [-Expires <DateTime>]
   [-NotBefore <DateTime>]
   [-Tag <Hashtable>]
   [-DefaultProfile <IAzureContextContainer>]
   [-WhatIf]
   [-Confirm]
   [<CommonParameters>]

Add-AzKeyVaultKey
   [-ResourceId] <String>
   [-Name] <String>
   -Destination <String>
   [-Disable]
   [-KeyOps <String[]>]
   [-Expires <DateTime>]
   [-NotBefore <DateTime>]
   [-Tag <Hashtable>]
   [-Size <Int32>]
   [-KeyType <String>]
   [-CurveName <String>]
   [-Exportable]
   [-Immutable]
   [-ReleasePolicyPath <String>]
   [-UseDefaultCVMPolicy]
   [-DefaultProfile <IAzureContextContainer>]
   [-WhatIf]
   [-Confirm]
   [<CommonParameters>]

Add-AzKeyVaultKey
   [-ResourceId] <String>
   [-Name] <String>
   -KeyFilePath <String>
   [-KeyFilePassword <SecureString>]
   [-Destination <String>]
   [-Disable]
   [-KeyOps <String[]>]
   [-Expires <DateTime>]
   [-NotBefore <DateTime>]
   [-Tag <Hashtable>]
   [-KeyType <String>]
   [-CurveName <String>]
   [-DefaultProfile <IAzureContextContainer>]
   [-WhatIf]
   [-Confirm]
   [<CommonParameters>]

Add-AzKeyVaultKey
   -HsmResourceId <String>
   [-Name] <String>
   [-Disable]
   [-KeyOps <String[]>]
   [-Expires <DateTime>]
   [-NotBefore <DateTime>]
   [-Tag <Hashtable>]
   [-Size <Int32>]
   -KeyType <String>
   [-CurveName <String>]
   [-Exportable]
   [-Immutable]
   [-ReleasePolicyPath <String>]
   [-UseDefaultCVMPolicy]
   [-DefaultProfile <IAzureContextContainer>]
   [-WhatIf]
   [-Confirm]
   [<CommonParameters>]

Add-AzKeyVaultKey
   -HsmResourceId <String>
   [-Name] <String>
   -KeyFilePath <String>
   [-KeyFilePassword <SecureString>]
   [-Disable]
   [-KeyOps <String[]>]
   [-Expires <DateTime>]
   [-NotBefore <DateTime>]
   [-Tag <Hashtable>]
   [-DefaultProfile <IAzureContextContainer>]
   [-WhatIf]
   [-Confirm]
   [<CommonParameters>]

Description

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.

Examples

Example 1: Create a key

Add-AzKeyVaultKey -VaultName 'contoso' -Name 'ITSoftware' -Destination 'Software'

Vault/HSM Name : contoso
Name           : ITSoftware
Key Type       : RSA
Key Size       : 2048
Curve Name     : 
Version        : 67da57e9cadf48a2ad8d366b115843ab
Id             : https://contoso.vault.azure.net:443/keys/ITSoftware/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 creates a software-protected key named ITSoftware in the key vault named Contoso.

Example 2: Create an EC key

Add-AzKeyVaultKey -VaultName test-kv -Name test-key -Destination Software -KeyType EC

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.

Example 3: Create an HSM-protected key

Add-AzKeyVaultKey -VaultName 'contoso' -Name 'ITHsm' -Destination 'HSM'

Vault Name     : contoso
Name           : ITHsm
Version        : 67da57e9cadf48a2ad8d366b115843ab
Id             : https://contoso.vault.azure.net:443/keys/ITSoftware/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 creates an HSM-protected key in the key vault named Contoso.

Example 4: Create a key with non-default values

$KeyOperations = 'decrypt', 'verify'
$Expires = (Get-Date).AddYears(2).ToUniversalTime()
$NotBefore = (Get-Date).ToUniversalTime()
$Tags = @{'Severity' = 'high'; 'Accounting' = "true"}
Add-AzKeyVaultKey -VaultName 'contoso' -Name 'ITHsmNonDefault' -Destination 'HSM' -Expires $Expires -NotBefore $NotBefore -KeyOps $KeyOperations -Disable -Tag $Tags

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.

Example 5: Import an HSM-protected key

Add-AzKeyVaultKey -VaultName 'contoso' -Name 'ITByok' -KeyFilePath 'C:\Contoso\ITByok.byok' -Destination 'HSM'

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.

Example 6: Import a software-protected key

$Password = ConvertTo-SecureString -String "****" -AsPlainText -Force
Add-AzKeyVaultKey -VaultName 'contoso' -Name 'ITPfx' -KeyFilePath 'C:\Contoso\ITPfx.pfx' -KeyFilePassword $Password

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.

Example 7: Import a key and assign attributes

$Password = ConvertTo-SecureString -String "****" -AsPlainText -Force
$Expires = (Get-Date).AddYears(2).ToUniversalTime()
$Tags = @{ 'Severity' = 'high'; 'Accounting' = "true" }
Add-AzKeyVaultKey -VaultName 'contoso' -Name 'ITPfxToHSM' -Destination 'HSM' -KeyFilePath 'C:\Contoso\ITPfx.pfx' -KeyFilePassword $Password -Expires $Expires -Tag $Tags

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

$key = Add-AzKeyVaultKey -VaultName $vaultName -Name $keyName -Destination HSM -Size 2048 -KeyOps "import"

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://zcusa.951200.xyz/azure/key-vault/keys/hsm-protected-keys

Example 9: Create a secure key in managed hsm

<# release_policy_template.json
{
  "anyOf": [
    {
      "allOf": [
        {
          "claim": "<claim name>",
          "equals": "<value to match>"
        }
      ],
      "authority": "<issuer>"
    }
  ],
  "version": "1.0.0"
}
#>
Add-AzKeyVaultKey -HsmName testmhsm -Name test-key -KeyType RSA -Exportable -ReleasePolicyPath release_policy.json

Vault/HSM Name : testmhsm
Name           : test-key
Key Type       : RSA
Key Size       : 2048
Curve Name     : 
Version        : ed6b026bf0a605042006635713d33ef6
Id             : https://testmhsm.managedhsm.azure.net:443/keys/test-key/ed6b026bf0a605042006635713d33ef6
Enabled        : True
Expires        : 
Not Before     : 
Created        : 6/2/2022 7:14:37 AM
Updated        : 6/2/2022 7:14:37 AM
Recovery Level : Recoverable+Purgeable
Release Policy : 
                 Content Type   : application/json; charset=utf-8
                 Policy Content : {"anyOf":[{"allOf":[{"claim":"x-ms-sgx-is-debuggable","equals":"true"}],"authority":"htt 
                 ps://sharedeus.eus.attest.azure.net/"}],"version":"1.0.0"}
                 Immutable      : False


Tags           :

Create a secure key in managed hsm named testmhsm. Its name is test-key and type is RSA.

Example 10: Add a key for a Confidential VM to a key vault.

New-AzKeyVault -Name $keyVaultName -Location $location -ResourceGroupName $resourceGroupName -Sku Premium -EnablePurgeProtection -EnabledForDiskEncryption;
$cvmAgent = Get-AzADServicePrincipal -ApplicationId '00001111-aaaa-2222-bbbb-3333cccc4444';
Set-AzKeyVaultAccessPolicy -VaultName $keyVaultName -ResourceGroupName $resourceGroupName -ObjectId $cvmAgent.id -PermissionsToKeys get,release;

$keySize = 3072;
Add-AzKeyVaultKey -VaultName $keyVaultName -Name $keyName -Size $keySize -KeyOps wrapKey,unwrapKey -KeyType RSA -Destination HSM -Exportable -UseDefaultCVMPolicy;

Vault/HSM Name : <Vault Name>
Name           : <Key Name>
Key Type       : RSA
Key Size       : 3072
Curve Name     :
Version        : <Version>
Id             : <Id>
Enabled        : True
Expires        :
Not Before     :
Created        : 9/9/2022 8:36:00 PM
Updated        : 9/9/2022 8:36:00 PM
Recovery Level : Recoverable
Release Policy :
                 Content Type   : application/json; charset=utf-8
                 Policy Content : <Policy Content>
                 Immutable      : False
Tags           :

Parameters

-Confirm

-CurveName

-DefaultProfile

-Destination

-Disable

-Expires

-Exportable

-HsmName

-HsmObject

-HsmResourceId

-Immutable

-InputObject

-KeyFilePassword

-KeyFilePath

-KeyOps

-KeyType

-Name

-NotBefore

-ReleasePolicyPath

-ResourceId

-Size

-Tag

-UseDefaultCVMPolicy

-VaultName

-WhatIf

Inputs

PSKeyVault

PSManagedHsm

String

Outputs

PSKeyVaultKey

Related Links

• Backup-AzKeyVaultKey
• Get-AzKeyVaultKey
• Remove-AzKeyVaultKey