-->
Secure key management is essential to protect data in the cloud. Use Azure Key Vault to encrypt keys and small secrets like passwords that use keys stored in hardware security modules (HSMs). For more assurance, import or generate keys in HSMs, and Microsoft processes your keys in FIPS 140-2 Level 2 validated HSMs (hardware and firmware).
Creates a key in a key vault or imports a key into a key vault.
Syntax
Description
The Add-AzureKeyVaultKey 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, theoriginal key is updated with the values that you specify for the new key. You can access theprevious values by using the version-specific URI for that version of the key. To learn about keyversions and the URI structure, see About Keys and Secretsin the Key Vault REST API documentation.Note: To import a key from your own hardware security module, you must first generate a BYOKpackage (a file with a .byok file name extension) by using the Azure Key Vault BYOK toolset. Formore information, seeHow 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 theBackup-AzureKeyVaultKey cmdlet. There is no undelete functionality, so if you accidentally deleteyour key or delete it and then change your mind, the key is not recoverable unless you have abackup of it that you can restore.
Examples
Example 1: Create a key
This command creates a software-protected key named ITSoftware in the key vault named Contoso.
Example 2: Create an HSM-protected key
This command creates an HSM-protected key in the key vault named Contoso.
Example 3: Create a key with non-default values
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 $Expiresvariable. For more information, type
Get-Help Get-Date
.The third command creates a DateTime object by using the Get-Date cmdlet. That objectspecifies 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 commandspecifies values for allowed key operations stored $KeyOperations. The command specifies times forthe Expires and NotBefore parameters created in the previous commands, and tags for highseverity and IT. The new key is disabled. You can enable it by using the Set-AzureKeyVaultKeycmdlet.Example 4: Import an HSM-protected key
This command imports the key named ITByok from the location that the KeyFilePath parameterspecifies. 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, seeHow to Generate and Transfer HSM-Protected Keys for Azure Key Vault.
Example 5: Import a software-protected key
The first command converts a string into a secure string by using the ConvertTo-SecureStringcmdlet, 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 thelocation for the key and the password stored in $Password.Example 6: Import a key and assign attributes
The first command converts a string into a secure string by using the ConvertTo-SecureStringcmdlet, and then stores that string in the $Password variable.The second command creates a DateTime object by using the Get-Date cmdlet, and then storesthat 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 specifiesthe expiration time stored in $Expires and password stored in $Password, and applies the tagsstored in $tags.
Parameters
Prompts you for confirmation before running the cmdlet.
Type: | SwitchParameter |
Aliases: | cf |
Position: | Named |
Default value: | None |
Accept pipeline input: | False |
Accept wildcard characters: | False |
The credentials, account, tenant, and subscription used for communication with azure
Type: | Microsoft.Azure.Commands.Common.Authentication.Abstractions.IAzureContextContainer |
Aliases: | AzureRmContext, AzureCredential |
Position: | Named |
Default value: | None |
Accept pipeline input: | False |
Accept wildcard characters: | False |
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 moreinformation about the service tiers and capabilities for Azure Key Vault, see theAzure Key Vault Pricing website.This parameter is required when you create a new key. If you import a key by using theKeyFilePath parameter, this parameter is optional:
- If you do not specify this parameter, and this cmdlet imports a key that has .byok file nameextension, it imports that key as an HSM-protected key. The cmdlet cannot import that key assoftware-protected key.
- If you do not specify this parameter, and this cmdlet imports a key that has a .pfx file nameextension, it imports the key as a software-protected key.
Type: | String |
Accepted values: | HSM, Software, HSM, Software |
Position: | Named |
Default value: | None |
Accept pipeline input: | False |
Accept wildcard characters: | False |
Indicates that the key you are adding is set to an initial state of disabled. Any attempt to usethe key will fail. Use this parameter if you are preloading keys that you intend to enable later.
Type: | SwitchParameter |
Position: | Named |
Default value: | None |
Accept pipeline input: | False |
Accept wildcard characters: | False |
Specifies the expiration time, as a DateTime object, for the key that this cmdlet adds. Thisparameter uses Coordinated Universal Time (UTC). To obtain a DateTime object, use theGet-Date cmdlet. For more information, type
Get-Help Get-Date
. If you do not specify thisparameter, the key does not expire.Type: | System.Nullable`1[System.DateTime] |
Position: | Named |
Default value: | None |
Accept pipeline input: | False |
Accept wildcard characters: | False |
Vault object.
Type: | PSKeyVault |
Position: | 0 |
Default value: | None |
Accept pipeline input: | True (ByValue) |
Accept wildcard characters: | False |
Specifies a password for the imported file as a SecureString object. To obtain aSecureString 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 filename extension.Type: | SecureString |
Position: | Named |
Default value: | None |
Accept pipeline input: | False |
Accept wildcard characters: | False |
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 youcannot override this default.
- If the file is a .pfx file, the key is automatically protected by software after the import. Tooverride 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.
Type: | String |
Position: | Named |
Default value: | None |
Accept pipeline input: | False |
Accept wildcard characters: | False |
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 bythe JSON Web Key (JWK) specification:
- Encrypt
- Decrypt
- Wrap
- Unwrap
- Sign
- Verify
Type: | System.String[] |
Position: | Named |
Default value: | None |
Accept pipeline input: | False |
Accept wildcard characters: | False |
Specifies the name of the key to add to the key vault. This cmdlet constructs the fully qualifieddomain name (FQDN) of a key based on the name that this parameter specifies, the name of the keyvault, and your current environment. The name must be a string of 1 through 63 characters in lengththat contains only 0-9, a-z, A-Z, and - (the dash symbol).
Type: | String |
Aliases: | KeyName |
Position: | 1 |
Default value: | None |
Accept pipeline input: | False |
Accept wildcard characters: | False |
Specifies the time, as a DateTime object, before which the key cannot be used. This parameteruses UTC. To obtain a DateTime object, use the Get-Date cmdlet. If you do not specify thisparameter, the key can be used immediately.
Type: | System.Nullable`1[System.DateTime] |
Position: | Named |
Default value: | None |
Accept pipeline input: | False |
Accept wildcard characters: | False |
Vault Resource Id.
Type: | String |
Position: | 0 |
Default value: | None |
Accept pipeline input: | True (ByPropertyName) |
Accept wildcard characters: | False |
RSA key size, in bits. If not specified, the service will provide a safe default.
Type: | System.Nullable`1[System.Int32] |
Position: | Named |
Default value: | None |
Accept pipeline input: | False |
Accept wildcard characters: | False |
Key-value pairs in the form of a hash table. For example:@{key0='value0';key1=$null;key2='value2'}
Type: | Hashtable |
Aliases: | Tags |
Position: | Named |
Default value: | None |
Accept pipeline input: | False |
Accept wildcard characters: | False |
Specifies the name of the key vault to which this cmdlet adds the key. This cmdlet constructs theFQDN of a key vault based on the name that this parameter specifies and your current environment.
Type: | String |
Position: | 0 |
Default value: | None |
Accept pipeline input: | False |
Accept wildcard characters: | False |
Shows what would happen if the cmdlet runs.The cmdlet is not run.
Type: | SwitchParameter |
Aliases: | wi |
Position: | Named |
Default value: | None |
Accept pipeline input: | False |
Accept wildcard characters: | False |
Inputs
Parameters: InputObject (ByValue)
Outputs
Related Links
-->Azure Key Vault is a cloud service that provides a secure store for secrets. You can securely store keys, passwords, certificates, and other secrets. Azure key vaults may be created and managed through the Azure portal. In this quickstart, you create a key vault, then use it to store a secret. For more information on Key Vault, review the Overview.
If you don't have an Azure subscription, create a free account before you begin.
Sign in to Azure
Sign in to the Azure portal at https://portal.azure.com.
Create a vault
- From the Azure portal menu, or from the Home page, select Create a resource.
- In the Search box, enter Key Vault.
- From the results list, choose Key Vault.
- On the Key Vault section, choose Create.
- On the Create key vault section provide the following information:
- Name: A unique name is required. For this quickstart, we use Contoso-vault2.
- Subscription: Choose a subscription.
- Under Resource Group, choose Create new and enter a resource group name.
- In the Location pull-down menu, choose a location.
- Leave the other options to their defaults.
- After providing the information above, select Create.
Take note of the two properties listed below:
- Vault Name: In the example, this is Contoso-Vault2. You will use this name for other steps.
- Vault URI: In the example, this is https://contoso-vault2.vault.azure.net/. Applications that use your vault through its REST API must use this URI.
At this point, your Azure account is the only one authorized to perform operations on this new vault.
Add a secret to Key Vault
To add a secret to the vault, you just need to take a couple of additional steps. In this case, we add a password that could be used by an application. The password is called ExamplePassword and we store the value of hVFkk965BuUv in it.
- On the Key Vault properties pages, select Secrets.
- Click on Generate/Import.
- On the Create a secret screen choose the following values:
- Upload options: Manual.
- Name: ExamplePassword.
- Value: hVFkk965BuUv
- Leave the other values to their defaults. Click Create.
Once that you receive the message that the secret has been successfully created, you may click on it on the list. You can then see some of the properties. If you click on the current version, you can see the value you specified in the previous step.
By clicking 'Show Secret Value' button in the right pane, you can see the hidden value.
Clean up resources
Other Key Vault quickstarts and tutorials build upon this quickstart. If you plan to continue on to work with subsequent quickstarts and tutorials, you may wish to leave these resources in place.When no longer needed, delete the resource group, which deletes the Key Vault and related resources. To delete the resource group through the portal:
- Enter the name of your resource group in the Search box at the top of the portal. When you see the resource group used in this quickstart in the search results, select it.
- Select Delete resource group.
- In the TYPE THE RESOURCE GROUP NAME: box type in the name of the resource group and select Delete.
Next steps
In this quickstart, you created a Key Vault and stored a secret in it. To learn more about Key Vault and how to integrate it with your applications, continue on to the articles below.
Generate A New Key For Filevault 2 Free
- Read an Overview of Azure Key Vault
- See the Azure Key Vault developer's guide
- Review Azure Key Vault best practices