Add-AzureKeyVaultKey

  • Riferimento
Modulo:
AzureRM.KeyVault

Crea una chiave in un insieme di credenziali delle chiavi o importa una chiave in un insieme di credenziali delle chiavi.

Avviso

Il modulo AzureRM PowerShell è stato ufficialmente deprecato a partire dal 29 febbraio 2024. È consigliabile eseguire la migrazione da AzureRM al modulo Az PowerShell per garantire il supporto e gli aggiornamenti continui.

Anche se il modulo AzureRM può ancora funzionare, non è più gestito o supportato, posizionando qualsiasi uso continuo a discrezione e rischio dell'utente. Per indicazioni sulla transizione al modulo Az, vedere le risorse di migrazione.

Sintassi

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>]

Descrizione

Il cmdlet Add-AzureKeyVaultKey crea una chiave in un insieme di credenziali delle chiavi in Azure Key Vault o importa una chiave in un insieme di credenziali delle chiavi. Usare questo cmdlet per aggiungere chiavi usando uno dei metodi seguenti:

  • Creare una chiave in un modulo di protezione hardware (HSM) nel servizio Key Vault.
  • Creare una chiave nel software nel servizio Key Vault.
  • Importare una chiave dal proprio modulo di protezione hardware (HSM) ai moduli di protezione hardware nel servizio Key Vault.
  • Importare una chiave da un file pfx nel computer.
  • Importare una chiave da un file pfx nel computer in moduli di protezione hardware (HSM) nel servizio Key Vault. Per una di queste operazioni, è possibile fornire attributi chiave o accettare le impostazioni predefinite. Se si crea o si importa una chiave con lo stesso nome di una chiave esistente nell'insieme di credenziali delle chiavi, la chiave originale viene aggiornata con i valori specificati per la nuova chiave. È possibile accedere ai valori precedenti usando l'URI specifico della versione per tale versione della chiave. Per informazioni sulle versioni principali e sulla struttura URI, vedere Informazioni su chiavi e segreti nella documentazione dell'API REST di Key Vault. Nota: per importare una chiave dal proprio modulo di sicurezza hardware, è prima necessario generare un pacchetto BYOK (un file con estensione byok) usando il set di strumenti BYOK di Azure Key Vault. Per altre informazioni, vedere Come generare e trasferire chiavi protette dal modulo di protezione hardware per Azure Key Vault. Come procedura consigliata, eseguire il backup della chiave dopo la creazione o l'aggiornamento usando il cmdlet Backup-AzureKeyVaultKey. Non esiste alcuna funzionalità di annullamento, quindi se si elimina accidentalmente la chiave o la si elimina e quindi si cambia idea, la chiave non è recuperabile a meno che non si disponga di un backup di esso che è possibile ripristinare.

Esempio

Esempio 1: Creare una chiave

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           :

Questo comando crea una chiave protetta da software denominata ITSoftware nell'insieme di credenziali delle chiavi denominato Contoso.

Esempio 2: Creare una chiave protetta da modulo di protezione hardware

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           :

Questo comando crea una chiave protetta da HSM nell'insieme di credenziali delle chiavi denominato Contoso.

Esempio 3: Creare una chiave con valori non predefiniti

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

Il primo comando archivia i valori decrittografare e verificare nella variabile $KeyOperations. Il secondo comando crea un oggetto DateTime , definito in formato UTC, usando il cmdlet Get-Date . L'oggetto specifica un periodo di due anni in futuro. Il comando archivia tale data nella variabile $Expires. Per ulteriori informazioni, digitare Get-Help Get-Date. Il terzo comando crea un oggetto DateTime usando il cmdlet Get-Date . L'oggetto specifica l'ora UTC corrente. Il comando archivia tale data nella variabile $NotBefore. Il comando finale crea una chiave denominata ITHsmNonDefault che è una chiave protetta da HSM. Il comando specifica i valori per le operazioni chiave consentite archiviate $KeyOperations. Il comando specifica le ore per i parametri Expires e NotBefore creati nei comandi precedenti e tag per gravità elevata e IT. La nuova chiave è disabilitata. È possibile abilitarla usando il cmdlet Set-AzureKeyVaultKey .

Esempio 4: Importare una chiave protetta da 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           :

Questo comando importa la chiave denominata ITByok dal percorso specificato dal parametro KeyFilePath . La chiave importata è una chiave protetta da HSM. Per importare una chiave dal proprio modulo di sicurezza hardware, è prima necessario generare un pacchetto BYOK (un file con estensione byok) usando il set di strumenti BYOK di Azure Key Vault. Per altre informazioni, vedere Come generare e trasferire chiavi protette dal modulo di protezione hardware per Azure Key Vault.

Esempio 5: Importare una chiave protetta da 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           :

Il primo comando converte una stringa in una stringa protetta usando il cmdlet ConvertTo-SecureString e quindi archivia tale stringa nella variabile $Password. Per ulteriori informazioni, digitare Get-Help ConvertTo-SecureString. Il secondo comando crea una password software nell'insieme di credenziali delle chiavi contoso. Il comando specifica il percorso per la chiave e la password archiviata in $Password.

Esempio 6: Importare una chiave e assegnare attributi

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

Il primo comando converte una stringa in una stringa protetta usando il cmdlet ConvertTo-SecureString e quindi archivia tale stringa nella variabile $Password. Il secondo comando crea un oggetto DateTime usando il cmdlet Get-Date e quindi archivia tale oggetto nella variabile $Expires. Il terzo comando crea la variabile $tags per impostare i tag per la gravità elevata e l'IT. Il comando finale importa una chiave come chiave HSM dal percorso specificato. Il comando specifica l'ora di scadenza archiviata in $Expires e la password archiviata in $Password e applica i tag archiviati in $tags.

Parametri

-Confirm

Richiede conferma prima di eseguire il cmdlet.

Type:SwitchParameter
Aliases:cf
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-DefaultProfile

Credenziali, account, tenant e sottoscrizione usati per la comunicazione con Azure

Type:IAzureContextContainer
Aliases:AzureRmContext, AzureCredential
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Destination

Specifica se aggiungere la chiave come chiave protetta da software o come chiave protetta da HSM nel servizio Key Vault. I valori validi sono: HSM e Software. Nota: per usare HSM come destinazione, è necessario disporre di un insieme di credenziali delle chiavi che supporta i moduli di protezione hardware. Per altre informazioni su livelli di servizio e funzionalità per l'insieme di credenziali delle chiavi di Azure, vedere il sito Web relativo ai prezzi dell'insieme di credenziali delle chiavi di Azure. Questo parametro è obbligatorio quando si crea una nuova chiave. Se si importa una chiave usando il parametro KeyFilePath , questo parametro è facoltativo:

  • Se non si specifica questo parametro e questo cmdlet importa una chiave con estensione byok, importa tale chiave come chiave protetta da HSM. Il cmdlet non può importare tale chiave come chiave protetta da software.
  • Se non si specifica questo parametro e questo cmdlet importa una chiave con estensione pfx, importa la chiave come chiave protetta da software.
Type:String
Accepted values:HSM, Software, HSM, Software
Position:Named
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-Disable

Indica che la chiave da aggiungere è impostata su uno stato iniziale disabilitato. Qualsiasi tentativo di usare la chiave avrà esito negativo. Usare questo parametro se si precaricano le chiavi che si intende abilitare in un secondo momento.

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Expires

Specifica l'ora di scadenza, come oggetto DateTime , per la chiave aggiunta da questo cmdlet. Questo parametro usa l'ora UTC (Coordinated Universal Time). Per ottenere un oggetto DateTime , utilizzare il cmdlet Get-Date . Per ulteriori informazioni, digitare Get-Help Get-Date. Se non si specifica questo parametro, la chiave non scade.

Type:Nullable<T>[DateTime]
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-InputObject

Oggetto Insieme di credenziali.

Type:PSKeyVault
Position:0
Default value:None
Required:True
Accept pipeline input:True
Accept wildcard characters:False

-KeyFilePassword

Specifica una password per il file importato come oggetto SecureString . Per ottenere un oggetto SecureString , utilizzare il cmdlet ConvertTo-SecureString . Per ulteriori informazioni, digitare Get-Help ConvertTo-SecureString. È necessario specificare questa password per importare un file con estensione pfx.

Type:SecureString
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-KeyFilePath

Specifica il percorso di un file locale contenente il materiale della chiave importato da questo cmdlet. Le estensioni di file valide sono byok e pfx.

  • Se il file è un file con estensione byok, la chiave viene protetta automaticamente dai moduli di protezione hardware dopo l'importazione e non è possibile eseguire l'override di questa impostazione predefinita.
  • Se il file è un file pfx, la chiave viene protetta automaticamente dal software dopo l'importazione. Per eseguire l'override di questa impostazione predefinita, impostare il parametro Destination su HSM in modo che la chiave sia protetta da HSM. Quando si specifica questo parametro, il parametro Destination è facoltativo.
Type:String
Position:Named
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-KeyOps

Specifica una matrice di operazioni che è possibile eseguire usando la chiave aggiunta da questo cmdlet. Se non si specifica questo parametro, è possibile eseguire tutte le operazioni. I valori accettabili per questo parametro sono un elenco delimitato da virgole di operazioni chiave come definito dalla specifica JWK (JSON Web Key):

  • Encrypt
  • Decrypt
  • Wrapping
  • Unwrap
  • Segno
  • Verificare
Type:String[]
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Name

Specifica il nome della chiave da aggiungere all'insieme di credenziali delle chiavi. Questo cmdlet costruisce il nome di dominio completo (FQDN) di una chiave in base al nome specificato da questo parametro, al nome dell'insieme di credenziali delle chiavi e all'ambiente corrente. Il nome deve essere una stringa di lunghezza da 1 a 63 caratteri che contiene solo 0-9, a-z, A-Z e - (simbolo trattino).

Type:String
Aliases:KeyName
Position:1
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-NotBefore

Specifica l'ora, come oggetto DateTime , prima della quale non è possibile utilizzare la chiave. Questo parametro usa l'ora UTC. Per ottenere un oggetto DateTime , utilizzare il cmdlet Get-Date . Se non si specifica questo parametro, la chiave può essere usata immediatamente.

Type:Nullable<T>[DateTime]
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-ResourceId

ID risorsa dell'insieme di credenziali.

Type:String
Position:0
Default value:None
Required:True
Accept pipeline input:True
Accept wildcard characters:False

-Size

Dimensioni della chiave RSA, in bit. Se non specificato, il servizio fornirà un valore predefinito sicuro.

Type:Nullable<T>[Int32]
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Tag

Coppie chiave-valore sotto forma di tabella hash. Ad esempio: @{key0="value0"; key1=$null; key2="value2"}

Type:Hashtable
Aliases:Tags
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-VaultName

Specifica il nome dell'insieme di credenziali delle chiavi a cui questo cmdlet aggiunge la chiave. Questo cmdlet costruisce il nome di dominio completo di un insieme di credenziali delle chiavi in base al nome specificato da questo parametro e all'ambiente corrente.

Type:String
Position:0
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-WhatIf

Mostra gli effetti dell'esecuzione del cmdlet. Il cmdlet non viene eseguito.

Type:SwitchParameter
Aliases:wi
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

Input

PSKeyVault

Parametri: InputObject (ByValue)

String

Output

PSKeyVaultKey