Partilhar via

Add-AzureKeyVaultKey

  • Referência
Módulo:
AzureRM.KeyVault

Cria uma chave em um cofre de chaves ou importa uma chave para um cofre de chaves.

Aviso

O módulo AzureRM do PowerShell foi oficialmente preterido a partir de 29 de fevereiro de 2024. Os usuários são aconselhados a migrar do AzureRM para o módulo Az PowerShell para garantir suporte e atualizações contínuos.

Embora o módulo AzureRM ainda possa funcionar, ele não é mais mantido ou suportado, colocando qualquer uso continuado a critério e risco do usuário. Consulte nossos recursos de migração para obter orientação sobre a transição para o módulo Az.

Sintaxe

Add-AzureKeyVaultKey
   [-VaultName] <String>
   [-Name] <String>
   -Destination <String>
   [-Disable]
   [-KeyOps <String[]>]
   [-Expires <DateTime>]
   [-NotBefore <DateTime>]
   [-Tag <Hashtable>]
   [-Size <Int32>]
   [-DefaultProfile <IAzureContextContainer>]
   [-WhatIf]
   [-Confirm]
   [<CommonParameters>]
Add-AzureKeyVaultKey
   [-VaultName] <String>
   [-Name] <String>
   -KeyFilePath <String>
   [-KeyFilePassword <SecureString>]
   [-Destination <String>]
   [-Disable]
   [-KeyOps <String[]>]
   [-Expires <DateTime>]
   [-NotBefore <DateTime>]
   [-Tag <Hashtable>]
   [-DefaultProfile <IAzureContextContainer>]
   [-WhatIf]
   [-Confirm]
   [<CommonParameters>]
Add-AzureKeyVaultKey
   [-InputObject] <PSKeyVault>
   [-Name] <String>
   -Destination <String>
   [-Disable]
   [-KeyOps <String[]>]
   [-Expires <DateTime>]
   [-NotBefore <DateTime>]
   [-Tag <Hashtable>]
   [-Size <Int32>]
   [-DefaultProfile <IAzureContextContainer>]
   [-WhatIf]
   [-Confirm]
   [<CommonParameters>]
Add-AzureKeyVaultKey
   [-InputObject] <PSKeyVault>
   [-Name] <String>
   -KeyFilePath <String>
   [-KeyFilePassword <SecureString>]
   [-Destination <String>]
   [-Disable]
   [-KeyOps <String[]>]
   [-Expires <DateTime>]
   [-NotBefore <DateTime>]
   [-Tag <Hashtable>]
   [-DefaultProfile <IAzureContextContainer>]
   [-WhatIf]
   [-Confirm]
   [<CommonParameters>]
Add-AzureKeyVaultKey
   [-ResourceId] <String>
   [-Name] <String>
   -Destination <String>
   [-Disable]
   [-KeyOps <String[]>]
   [-Expires <DateTime>]
   [-NotBefore <DateTime>]
   [-Tag <Hashtable>]
   [-Size <Int32>]
   [-DefaultProfile <IAzureContextContainer>]
   [-WhatIf]
   [-Confirm]
   [<CommonParameters>]
Add-AzureKeyVaultKey
   [-ResourceId] <String>
   [-Name] <String>
   -KeyFilePath <String>
   [-KeyFilePassword <SecureString>]
   [-Destination <String>]
   [-Disable]
   [-KeyOps <String[]>]
   [-Expires <DateTime>]
   [-NotBefore <DateTime>]
   [-Tag <Hashtable>]
   [-DefaultProfile <IAzureContextContainer>]
   [-WhatIf]
   [-Confirm]
   [<CommonParameters>]

Description

O cmdlet Add-AzureKeyVaultKey cria uma chave em um cofre de chaves no Cofre de Chaves do Azure ou importa uma chave para um cofre de chaves. Use este cmdlet para adicionar chaves usando qualquer um dos seguintes métodos:

  • Crie uma chave em um módulo de segurança de hardware (HSM) no serviço Cofre de Chaves.
  • Crie uma chave no software no serviço Cofre de Chaves.
  • Importe uma chave do seu próprio módulo de segurança de hardware (HSM) para HSMs no serviço Cofre de Chaves.
  • Importe uma chave de um ficheiro .pfx no seu computador.
  • Importe uma chave de um arquivo .pfx em seu computador para módulos de segurança de hardware (HSMs) no serviço Cofre de Chaves. Para qualquer uma dessas operações, você pode fornecer atributos de chave ou aceitar configurações padrão. Se você criar ou importar uma chave que tenha o mesmo nome de uma chave existente no cofre de chaves, a chave original será atualizada com os valores especificados para a nova chave. Você pode acessar os valores anteriores usando o URI específico da versão para essa versão da chave. Para saber mais sobre as versões das chaves e a estrutura do URI, consulte Sobre chaves e segredos na documentação da API REST do Cofre de Chaves. Observação: para importar uma chave do seu próprio módulo de segurança de hardware, você deve primeiro gerar um pacote BYOK (um arquivo com uma extensão de nome de arquivo .byok) usando o conjunto de ferramentas BYOK do Cofre da Chave do Azure. Para obter mais informações, consulte Como gerar e transferir chaves protegidas por HSM para o Cofre de Chaves do Azure. Como prática recomendada, faça backup de sua chave depois que ela for criada ou atualizada, usando o cmdlet Backup-AzureKeyVaultKey. Não há nenhuma funcionalidade de undelete, por isso, se você acidentalmente excluir sua chave ou excluí-la e, em seguida, mudar de ideia, a chave não é recuperável, a menos que você tenha um backup dela que você pode restaurar.

Exemplos

Exemplo 1: Criar uma chave

PS C:\> Add-AzureKeyVaultKey -VaultName 'contoso' -Name 'ITSoftware' -Destination 'Software'

Vault Name     : contoso
Name           : ITSoftware
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           :

Este comando cria uma chave protegida por software chamada ITSoftware no cofre de chaves chamado Contoso.

Exemplo 2: Criar uma chave protegida por HSM

PS C:\> Add-AzureKeyVaultKey -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           :

Este comando cria uma chave protegida por HSM no cofre de chaves chamado Contoso.

Exemplo 3: Criar uma chave com valores não padrão

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

Vault Name     : contoso
Name           : ITHsmNonDefault
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

O primeiro comando armazena os valores, desencripta e verifica na variável $KeyOperations. O segundo comando cria um objeto DateTime , definido em UTC, usando o cmdlet Get-Date . Esse objeto especifica um prazo de dois anos no futuro. O comando armazena essa data na variável $Expires. Para obter mais informações, digite Get-Help Get-Date. O terceiro comando cria um objeto DateTime usando o cmdlet Get-Date . Esse objeto especifica a hora UTC atual. O comando armazena essa data na variável $NotBefore. O comando final cria uma chave chamada ITHsmNonDefault que é uma chave protegida por HSM. O comando especifica valores para operações de chave permitidas armazenadas $KeyOperations. O comando especifica tempos para os parâmetros Expires e NotBefore criados nos comandos anteriores e tags para alta severidade e TI. A nova chave está desativada. Você pode habilitá-lo usando o cmdlet Set-AzureKeyVaultKey .

Exemplo 4: Importar uma chave protegida por HSM

PS C:\> Add-AzureKeyVaultKey -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           :

Este comando importa a chave chamada ITByok do local especificado pelo parâmetro KeyFilePath . A chave importada é uma chave protegida por HSM. Para importar uma chave do seu próprio módulo de segurança de hardware, você deve primeiro gerar um pacote BYOK (um arquivo com uma extensão de nome de arquivo .byok) usando o conjunto de ferramentas BYOK do Cofre da Chave do Azure. Para obter mais informações, consulte Como gerar e transferir chaves protegidas por HSM para o Cofre de Chaves do Azure.

Exemplo 5: Importar uma chave protegida por software

PS C:\> $Password = ConvertTo-SecureString -String 'Password' -AsPlainText -Force
PS C:\> Add-AzureKeyVaultKey -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           :

O primeiro comando converte uma cadeia de caracteres em uma cadeia de caracteres segura usando o cmdlet ConvertTo-SecureString e, em seguida, armazena essa cadeia de caracteres na variável $Password. Para obter mais informações, digite Get-Help ConvertTo-SecureString. O segundo comando cria uma senha de software no cofre de chaves da Contoso. O comando especifica o local da chave e da senha armazenada no $Password.

Exemplo 6: Importar uma chave e atribuir atributos

PS C:\> $Password = ConvertTo-SecureString -String 'password' -AsPlainText -Force
PS C:\> $Expires = (Get-Date).AddYears(2).ToUniversalTime()
PS C:\> $Tags = @{ 'Severity' = 'high'; 'Accounting' = "true" }
PS C:\> Add-AzureKeyVaultKey -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

O primeiro comando converte uma cadeia de caracteres em uma cadeia de caracteres segura usando o cmdlet ConvertTo-SecureString e, em seguida, armazena essa cadeia de caracteres na variável $Password. O segundo comando cria um objeto DateTime usando o cmdlet Get-Date e, em seguida, armazena esse objeto na variável $Expires. O terceiro comando cria a variável $tags para definir tags para alta severidade e TI. O comando final importa uma chave como uma chave HSM do local especificado. O comando especifica o tempo de expiração armazenado no $Expires e a senha armazenada no $Password e aplica as tags armazenadas no $tags.

Parâmetros

-Confirm

Solicita a sua confirmação antes de executar o cmdlet.

Tipo:SwitchParameter
Aliases:cf
Position:Named
Default value:None
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

-DefaultProfile

As credenciais, a conta, o locatário e a assinatura usados para comunicação com o azure

Tipo:IAzureContextContainer
Aliases:AzureRmContext, AzureCredential
Position:Named
Default value:None
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

-Destination

Especifica se a chave deve ser adicionada como uma chave protegida por software ou uma chave protegida por HSM no serviço Cofre de Chaves. Os valores válidos são: HSM e Software. Nota: Para usar o HSM como destino, você deve ter um cofre de chaves que suporte HSMs. Para obter mais informações sobre as camadas de serviço e os recursos do Azure Key Vault, consulte o site de Preços do Azure Key Vault. Esse parâmetro é necessário quando você cria uma nova chave. Se você importar uma chave usando o parâmetro KeyFilePath , esse parâmetro será opcional:

  • Se você não especificar esse parâmetro e esse cmdlet importar uma chave que tenha a extensão de nome de arquivo .byok, ele importará essa chave como uma chave protegida por HSM. O cmdlet não pode importar essa chave como chave protegida por software.
  • Se você não especificar esse parâmetro e esse cmdlet importar uma chave que tenha uma extensão de nome de arquivo .pfx, ele importará a chave como uma chave protegida por software.
Tipo:String
Valores aceites:HSM, Software, HSM, Software
Position:Named
Default value:None
Necessário:True
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

-Disable

Indica que a chave que você está adicionando está definida como um estado inicial de desabilitado. Qualquer tentativa de usar a chave falhará. Use este parâmetro se estiver pré-carregando chaves que pretende habilitar mais tarde.

Tipo:SwitchParameter
Position:Named
Default value:None
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

-Expires

Especifica o tempo de expiração, como um objeto DateTime , para a chave adicionada por esse cmdlet. Este parâmetro usa o Tempo Universal Coordenado (UTC). Para obter um objeto DateTime , use o cmdlet Get-Date . Para obter mais informações, digite Get-Help Get-Date. Se você não especificar esse parâmetro, a chave não expirará.

Tipo:Nullable<T>[DateTime]
Position:Named
Default value:None
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

-InputObject

Objeto do Vault.

Tipo:PSKeyVault
Position:0
Default value:None
Necessário:True
Aceitar entrada de pipeline:True
Aceitar carateres universais:False

-KeyFilePassword

Especifica uma senha para o arquivo importado como um objeto SecureString . Para obter um objeto SecureString , use o cmdlet ConvertTo-SecureString . Para obter mais informações, digite Get-Help ConvertTo-SecureString. Você deve especificar essa senha para importar um arquivo com uma extensão de nome de arquivo .pfx.

Tipo:SecureString
Position:Named
Default value:None
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

-KeyFilePath

Especifica o caminho de um arquivo local que contém material de chave importado por esse cmdlet. As extensões de nome de arquivo válidas são .byok e .pfx.

  • Se o arquivo for um arquivo .byok, a chave será automaticamente protegida por HSMs após a importação e você não poderá substituir esse padrão.
  • Se o ficheiro for um ficheiro .pfx, a chave é automaticamente protegida por software após a importação. Para substituir esse padrão, defina o parâmetro Destination como HSM para que a chave seja protegida por HSM. Quando você especifica esse parâmetro, o parâmetro Destination é opcional.
Tipo:String
Position:Named
Default value:None
Necessário:True
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

-KeyOps

Especifica uma matriz de operações que podem ser executadas usando a chave adicionada por esse cmdlet. Se você não especificar esse parâmetro, todas as operações poderão ser executadas. Os valores aceitáveis para este parâmetro são uma lista separada por vírgulas de operações de chave, conforme definido pela especificação JSON Web Key (JWK):

  • Encriptar
  • Desencriptar
  • Moldar
  • Desembrulhar
  • Assinar
  • Verificar
Tipo:String[]
Position:Named
Default value:None
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

-Name

Especifica o nome da chave a ser adicionada ao cofre de chaves. Este cmdlet constrói o FQDN (nome de domínio totalmente qualificado) de uma chave com base no nome especificado por esse parâmetro, no nome do cofre de chaves e no seu ambiente atual. O nome deve ser uma cadeia de 1 a 63 caracteres de comprimento que contenha apenas 0-9, a-z, A-Z e - (o símbolo do traço).

Tipo:String
Aliases:KeyName
Position:1
Default value:None
Necessário:True
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

-NotBefore

Especifica a hora, como um objeto DateTime , antes da qual a chave não pode ser usada. Este parâmetro usa UTC. Para obter um objeto DateTime , use o cmdlet Get-Date . Se você não especificar esse parâmetro, a chave poderá ser usada imediatamente.

Tipo:Nullable<T>[DateTime]
Position:Named
Default value:None
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

-ResourceId

ID do recurso do Vault.

Tipo:String
Position:0
Default value:None
Necessário:True
Aceitar entrada de pipeline:True
Aceitar carateres universais:False

-Size

Tamanho da chave RSA, em bits. Se não for especificado, o serviço fornecerá um padrão seguro.

Tipo:Nullable<T>[Int32]
Position:Named
Default value:None
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

-Tag

Pares chave-valor na forma de uma tabela de hash. Por exemplo: @{key0="value0"; chave1=$null; key2="valor2"}

Tipo:Hashtable
Aliases:Tags
Position:Named
Default value:None
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

-VaultName

Especifica o nome do cofre de chaves ao qual esse cmdlet adiciona a chave. Este cmdlet constrói o FQDN de um cofre de chaves com base no nome especificado por esse parâmetro e no seu ambiente atual.

Tipo:String
Position:0
Default value:None
Necessário:True
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

-WhatIf

Apresenta o que aconteceria mediante a execução do cmdlet. O cmdlet não é executado.

Tipo:SwitchParameter
Aliases:wi
Position:Named
Default value:None
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

Entradas

PSKeyVault

Parâmetros: InputObject (ByValue)

String

Saídas

PSKeyVaultKey