Compartir a través de

Add-AzureKeyVaultKey

  • Referencia
Módulo:
AzureRM.KeyVault

Crea una clave en un almacén de claves o importa una clave en un almacén de claves.

Advertencia

El módulo de PowerShell de AzureRM ha quedado en desuso oficialmente a partir del 29 de febrero de 2024. Se recomienda a los usuarios migrar de AzureRM al módulo Az PowerShell para seguir recibiendo soporte técnico y actualizaciones.

Aunque el módulo AzureRM puede seguir funcionando, ya no se mantiene ni se admite, colocando cualquier uso continuado a discreción y riesgo del usuario. Consulte nuestros recursos de migración para ver una guía sobre la transición al módulo Az.

Sintaxis

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

El cmdlet Add-AzureKeyVaultKey crea una clave en un almacén de claves de Azure Key Vault o importa una clave en un almacén de claves. Use este cmdlet para agregar claves mediante cualquiera de los métodos siguientes:

  • Cree una clave en un módulo de seguridad de hardware (HSM) en el servicio Key Vault.
  • Cree una clave en el software en el servicio Key Vault.
  • Importe una clave desde su propio módulo de seguridad de hardware (HSM) a HSM en el servicio Key Vault.
  • Importe una clave desde un archivo .pfx en el equipo.
  • Importe una clave de un archivo .pfx en el equipo a módulos de seguridad de hardware (HSM) en el servicio Key Vault. Para cualquiera de estas operaciones, puede proporcionar atributos clave o aceptar la configuración predeterminada. Si crea o importa una clave que tenga el mismo nombre que una clave existente en el almacén de claves, la clave original se actualiza con los valores que especifique para la nueva clave. Puede acceder a los valores anteriores mediante el URI específico de la versión para esa versión de la clave. Para obtener información sobre las versiones clave y la estructura de URI, consulte Acerca de las claves y los secretos en la documentación de la API rest de Key Vault. Nota: Para importar una clave desde su propio módulo de seguridad de hardware, primero debe generar un paquete BYOK (un archivo con una extensión de nombre de archivo .byok) mediante el conjunto de herramientas BYOK de Azure Key Vault. Para más información, consulte Generación y transferencia de claves protegidas con HSM para Azure Key Vault. Como procedimiento recomendado, realice una copia de seguridad de la clave después de crearla o actualizarla mediante el cmdlet Backup-AzureKeyVaultKey. No hay ninguna funcionalidad de recuperación, por lo que si elimina accidentalmente la clave o la elimina y, a continuación, cambia de opinión, la clave no se puede recuperar a menos que tenga una copia de seguridad de ella que pueda restaurar.

Ejemplos

Ejemplo 1: Creación de una clave

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 crea una clave protegida por software denominada ITSoftware en el almacén de claves denominado Contoso.

Ejemplo 2: Creación de una clave 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 crea una clave protegida por HSM en el almacén de claves denominado Contoso.

Ejemplo 3: Creación de una clave con valores no predeterminados

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

El primer comando almacena los valores descifrado y comprobación en la variable $KeyOperations. El segundo comando crea un objeto DateTime , definido en UTC, mediante el cmdlet Get-Date . Ese objeto especifica un tiempo de dos años en el futuro. El comando almacena esa fecha en la variable $Expires. Para obtener más información, escriba Get-Help Get-Date. El tercer comando crea un objeto DateTime mediante el cmdlet Get-Date . Ese objeto especifica la hora UTC actual. El comando almacena esa fecha en la variable $NotBefore. El comando final crea una clave denominada ITHsmNonDefault que es una clave protegida por HSM. El comando especifica valores para las operaciones de clave permitidas almacenadas $KeyOperations. El comando especifica horas para los parámetros Expires y NotBefore creados en los comandos anteriores y etiquetas para la gravedad alta y el equipo de TI. La nueva clave está deshabilitada. Puede habilitarlo mediante el cmdlet Set-AzureKeyVaultKey .

Ejemplo 4: Importación de una clave 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 la clave denominada ITByok desde la ubicación que especifica el parámetro KeyFilePath . La clave importada es una clave protegida por HSM. Para importar una clave desde su propio módulo de seguridad de hardware, primero debe generar un paquete BYOK (un archivo con una extensión de nombre de archivo .byok) mediante el conjunto de herramientas BYOK de Azure Key Vault. Para más información, consulte Generación y transferencia de claves protegidas con HSM para Azure Key Vault.

Ejemplo 5: Importación de una clave 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           :

El primer comando convierte una cadena en una cadena segura mediante el cmdlet ConvertTo-SecureString y, a continuación, almacena esa cadena en la variable $Password. Para obtener más información, escriba Get-Help ConvertTo-SecureString. El segundo comando crea una contraseña de software en el almacén de claves de Contoso. El comando especifica la ubicación de la clave y la contraseña almacenada en $Password.

Ejemplo 6: Importación de una clave y asignación de 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

El primer comando convierte una cadena en una cadena segura mediante el cmdlet ConvertTo-SecureString y, a continuación, almacena esa cadena en la variable $Password. El segundo comando crea un objeto DateTime mediante el cmdlet Get-Date y, a continuación, almacena ese objeto en la variable $Expires. El tercer comando crea la variable $tags para establecer etiquetas de gravedad alta y TI. El comando final importa una clave como una clave HSM desde la ubicación especificada. El comando especifica la hora de expiración almacenada en $Expires y la contraseña almacenadas en $Password y aplica las etiquetas almacenadas en $tags.

Parámetros

-Confirm

Le solicita su confirmación antes de ejecutar el cmdlet.

Tipo:SwitchParameter
Alias:cf
Posición:Named
Valor predeterminado:None
Requerido:False
Aceptar entrada de canalización:False
Aceptar caracteres comodín:False

-DefaultProfile

Las credenciales, la cuenta, el inquilino y la suscripción que se usan para la comunicación con Azure

Tipo:IAzureContextContainer
Alias:AzureRmContext, AzureCredential
Posición:Named
Valor predeterminado:None
Requerido:False
Aceptar entrada de canalización:False
Aceptar caracteres comodín:False

-Destination

Especifica si se va a agregar la clave como una clave protegida por software o una clave protegida por HSM en el servicio Key Vault. Los valores válidos son: HSM y Software. Nota: Para usar HSM como destino, debe tener un almacén de claves que admita HSM. Para obtener más información sobre los niveles de servicio y las funcionalidades de Azure Key Vault, consulte el sitio web Precios de Key Vault . Este parámetro es necesario cuando se crea una nueva clave. Si importa una clave mediante el parámetro KeyFilePath , este parámetro es opcional:

  • Si no especifica este parámetro y este cmdlet importa una clave que tiene la extensión de nombre de archivo .byok, importa esa clave como una clave protegida por HSM. El cmdlet no puede importar esa clave como clave protegida por software.
  • Si no especifica este parámetro y este cmdlet importa una clave que tiene una extensión de nombre de archivo .pfx, importa la clave como una clave protegida por software.
Tipo:String
Valores aceptados:HSM, Software, HSM, Software
Posición:Named
Valor predeterminado:None
Requerido:True
Aceptar entrada de canalización:False
Aceptar caracteres comodín:False

-Disable

Indica que la clave que va a agregar está establecida en un estado inicial de deshabilitado. Se producirá un error en cualquier intento de usar la clave. Use este parámetro si va a cargar previamente las claves que pretende habilitar más adelante.

Tipo:SwitchParameter
Posición:Named
Valor predeterminado:None
Requerido:False
Aceptar entrada de canalización:False
Aceptar caracteres comodín:False

-Expires

Especifica la hora de expiración, como un objeto DateTime , para la clave que agrega este cmdlet. Este parámetro usa la hora universal coordinada (UTC). Para obtener un objeto DateTime , use el cmdlet Get-Date . Para obtener más información, escriba Get-Help Get-Date. Si no especifica este parámetro, la clave no expira.

Tipo:Nullable<T>[DateTime]
Posición:Named
Valor predeterminado:None
Requerido:False
Aceptar entrada de canalización:False
Aceptar caracteres comodín:False

-InputObject

Objeto Vault.

Tipo:PSKeyVault
Posición:0
Valor predeterminado:None
Requerido:True
Aceptar entrada de canalización:True
Aceptar caracteres comodín:False

-KeyFilePassword

Especifica una contraseña para el archivo importado como un objeto SecureString . Para obtener un objeto SecureString , use el cmdlet ConvertTo-SecureString . Para obtener más información, escriba Get-Help ConvertTo-SecureString. Debe especificar esta contraseña para importar un archivo con una extensión de nombre de archivo .pfx.

Tipo:SecureString
Posición:Named
Valor predeterminado:None
Requerido:False
Aceptar entrada de canalización:False
Aceptar caracteres comodín:False

-KeyFilePath

Especifica la ruta de acceso de un archivo local que contiene material de clave que importa este cmdlet. Las extensiones de nombre de archivo válidas son .byok y .pfx.

  • Si el archivo es un archivo .byok, la clave se protege automáticamente mediante HSM después de la importación y no puede invalidar este valor predeterminado.
  • Si el archivo es un archivo .pfx, la clave se protege automáticamente mediante software después de la importación. Para invalidar este valor predeterminado, establezca el parámetro Destination en HSM para que la clave esté protegida por HSM. Al especificar este parámetro, el parámetro Destination es opcional.
Tipo:String
Posición:Named
Valor predeterminado:None
Requerido:True
Aceptar entrada de canalización:False
Aceptar caracteres comodín:False

-KeyOps

Especifica una matriz de operaciones que se pueden realizar mediante la clave que agrega este cmdlet. Si no se especifica este parámetro, se pueden realizar todas las operaciones. Los valores aceptables para este parámetro son una lista separada por comas de las operaciones con clave, tal y como se define en la especificación JSON Web Key (JWK):

  • Cifrado
  • Descifrado
  • Encapsulado
  • Desencapsulado
  • Firma
  • Verify
Tipo:String[]
Posición:Named
Valor predeterminado:None
Requerido:False
Aceptar entrada de canalización:False
Aceptar caracteres comodín:False

-Name

Especifica el nombre de la clave que se va a agregar al almacén de claves. Este cmdlet construye el nombre de dominio completo (FQDN) de una clave en función del nombre que especifica este parámetro, el nombre del almacén de claves y el entorno actual. El nombre debe ser una cadena de 1 a 63 caracteres de longitud que solo contiene 0-9, a-z, A-Z y - (el símbolo de guión).

Tipo:String
Alias:KeyName
Posición:1
Valor predeterminado:None
Requerido:True
Aceptar entrada de canalización:False
Aceptar caracteres comodín:False

-NotBefore

Especifica la hora, como un objeto DateTime , antes del cual no se puede usar la clave. Este parámetro usa UTC. Para obtener un objeto DateTime , use el cmdlet Get-Date . Si no especifica este parámetro, la clave se puede usar inmediatamente.

Tipo:Nullable<T>[DateTime]
Posición:Named
Valor predeterminado:None
Requerido:False
Aceptar entrada de canalización:False
Aceptar caracteres comodín:False

-ResourceId

Identificador de recurso del almacén.

Tipo:String
Posición:0
Valor predeterminado:None
Requerido:True
Aceptar entrada de canalización:True
Aceptar caracteres comodín:False

-Size

Tamaño de clave RSA, en bits. Si no se especifica, el servicio proporcionará un valor predeterminado seguro.

Tipo:Nullable<T>[Int32]
Posición:Named
Valor predeterminado:None
Requerido:False
Aceptar entrada de canalización:False
Aceptar caracteres comodín:False

-Tag

Pares clave-valor en forma de tabla hash. Por ejemplo: @{key0="value0"; key1=$null; key2="value2"}

Tipo:Hashtable
Alias:Tags
Posición:Named
Valor predeterminado:None
Requerido:False
Aceptar entrada de canalización:False
Aceptar caracteres comodín:False

-VaultName

Especifica el nombre del almacén de claves al que este cmdlet agrega la clave. Este cmdlet construye el FQDN de un almacén de claves en función del nombre que especifica este parámetro y el entorno actual.

Tipo:String
Posición:0
Valor predeterminado:None
Requerido:True
Aceptar entrada de canalización:False
Aceptar caracteres comodín:False

-WhatIf

Muestra lo que sucedería si se ejecutara el cmdlet. El cmdlet no se ejecuta.

Tipo:SwitchParameter
Alias:wi
Posición:Named
Valor predeterminado:None
Requerido:False
Aceptar entrada de canalización:False
Aceptar caracteres comodín:False

Entradas

PSKeyVault

Parámetros: InputObject (ByValue)

String

Salidas

PSKeyVaultKey