Edit

Share via

Backup-AzKeyVaultKey

Module:
Az.KeyVault Module

Backs up a key in a key vault.

Syntax

ByKeyName (Default) 

Backup-AzKeyVaultKey
    [-VaultName] <String>
    [-Name] <String>
    [[-OutputFile] <String>]
    [-Force]
    [-DefaultProfile <IAzureContextContainer>]
    [-WhatIf]
    [-Confirm]
    [<CommonParameters>]

HsmByKeyName 

Backup-AzKeyVaultKey
    [-Name] <String>
    [[-OutputFile] <String>]
    -HsmName <String>
    [-Force]
    [-DefaultProfile <IAzureContextContainer>]
    [-WhatIf]
    [-Confirm]
    [<CommonParameters>]

ByKey 

Backup-AzKeyVaultKey
    [-InputObject] <PSKeyVaultKeyIdentityItem>
    [[-OutputFile] <String>]
    [-Force]
    [-DefaultProfile <IAzureContextContainer>]
    [-WhatIf]
    [-Confirm]
    [<CommonParameters>]

Description

The Backup-AzKeyVaultKey cmdlet backs up a specified key in a key vault by downloading it and storing it in a file. If there are multiple versions of the key, all versions are included in the backup. Because the downloaded content is encrypted, it cannot be used outside of Azure Key Vault. You can restore a backed-up key to any key vault in the subscription that it was backed up from. Typical reasons to use this cmdlet are:

  • You want to escrow a copy of your key, so that you have an offline copy in case you accidentally delete your key in your key vault.

  • You created a key using Key Vault and now want to clone the key into a different Azure region, so that you can use it from all instances of your distributed application. Use the Backup-AzKeyVaultKey cmdlet to retrieve the key in encrypted format and then use the Restore-AzKeyVaultKey cmdlet and specify a key vault in the second region.

Examples

Example 1: Back up a key with an automatically generated file name

Backup-AzKeyVaultKey -VaultName 'MyKeyVault' -Name 'MyKey'

C:\Users\username\mykeyvault-mykey-1527029447.01191

This command retrieves the key named MyKey from the key vault named MyKeyVault and saves a backup of that key to a file that is automatically named for you, and displays the file name.

Example 2: Back up a key to a specified file name

Backup-AzKeyVaultKey -VaultName 'MyKeyVault' -Name 'MyKey' -OutputFile 'C:\Backup.blob'

C:\Backup.blob

This command retrieves the key named MyKey from the key vaultnamed MyKeyVault and saves a backup of that key to a file named Backup.blob.

Example 3: Back up a previously retrieved key to a specified file name, overwriting the destination file without prompting.

$key = Get-AzKeyVaultKey -VaultName 'MyKeyVault' -Name 'MyKey'
Backup-AzKeyVaultKey -Key $key -OutputFile 'C:\Backup.blob' -Force

C:\Backup.blob

This command creates a backup of the key named $key.Name in the vault named $key.VaultName to a file named Backup.blob, silently overwriting the file if it exists already.

Parameters

-Confirm

Prompts you for confirmation before running the cmdlet.

Parameter properties

Type:SwitchParameter
Default value:None
Supports wildcards:False
DontShow:False
Aliases:cf

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-DefaultProfile

The credentials, account, tenant, and subscription used for communication with azure

Parameter properties

Type:IAzureContextContainer
Default value:None
Supports wildcards:False
DontShow:False
Aliases:AzContext, AzureRmContext, AzureCredential

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-Force

Overwrite the given file if it exists

Parameter properties

Type:SwitchParameter
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-HsmName

HSM name. Cmdlet constructs the FQDN of a managed HSM based on the name and currently selected environment.

Parameter properties

Type:String
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

HsmByKeyName
Position:Named
Mandatory:True
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-InputObject

Key bundle to back up, pipelined in from the output of a retrieval call.

Parameter properties

Type:PSKeyVaultKeyIdentityItem
Default value:None
Supports wildcards:False
DontShow:False
Aliases:Key

Parameter sets

ByKey
Position:0
Mandatory:True
Value from pipeline:True
Value from pipeline by property name:False
Value from remaining arguments:False

-Name

Specifies the name of the key to back up.

Parameter properties

Type:String
Default value:None
Supports wildcards:False
DontShow:False
Aliases:KeyName

Parameter sets

ByKeyName
Position:1
Mandatory:True
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False
HsmByKeyName
Position:1
Mandatory:True
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-OutputFile

Specifies the output file in which the backup blob is stored. If you do not specify this parameter, this cmdlet generates a file name for you. If you specify the name of an existing output file, the operation will not complete and returns an error message that the backup file already exists.

Parameter properties

Type:String
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:2
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-VaultName

Specifies the name of the key vault that contains the key to back up.

Parameter properties

Type:String
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

ByKeyName
Position:0
Mandatory:True
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-WhatIf

Shows what would happen if the cmdlet runs. The cmdlet is not run.

Parameter properties

Type:SwitchParameter
Default value:None
Supports wildcards:False
DontShow:False
Aliases:wi

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

CommonParameters

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.

Inputs

PSKeyVaultKeyIdentityItem

Outputs

String