Biblioteca cliente de claves de Azure Key Vault para .NET: versión 4.5.0

  • Artículo

Azure Key Vault es un servicio en la nube que proporciona almacenamiento seguro de claves para cifrar los datos. Se pueden conservar varias claves y varias versiones de la misma clave en azure Key Vault. Las claves criptográficas de Azure Key Vault se representan como objetos JSON Web Key (JWK).

Azure Key Vault HSM administrado es un servicio en la nube totalmente administrado, de alta disponibilidad, de inquilino único y compatible con estándares que le permite proteger las claves criptográficas para las aplicaciones en la nube mediante HSM validados de nivel 3 de FIPS 140-2.

El cliente de la biblioteca de claves de Azure Key Vault admite claves RSA y claves de curva elíptica (EC), cada una con la compatibilidad correspondiente en módulos de seguridad de hardware (HSM). Ofrece operaciones para crear, recuperar, actualizar, eliminar, purgar, realizar copias de seguridad, restaurar y enumerar las claves y sus versiones.

Código | fuente Paquete (NuGet) | Documentación | de referencia de APIDocumentación | del producto Muestras | Guía de migración

Introducción

Instalar el paquete

Instale la biblioteca cliente de claves de Azure Key Vault para .NET con NuGet:

dotnet add package Azure.Security.KeyVault.Keys

Prerrequisitos

Si va a crear un recurso de Key Vault estándar, ejecute el siguiente comando de la CLI reemplazando <your-resource-group-name> y <your-key-vault-name> por sus propios nombres únicos:

az keyvault create --resource-group <your-resource-group-name> --name <your-key-vault-name>

Si va a crear un recurso de HSM administrado, ejecute el siguiente comando de la CLI:

az keyvault create --hsm-name <your-key-vault-name> --resource-group <your-resource-group-name> --administrators <your-user-object-id> --location <your-azure-location>

Para obtener <your-user-object-id> , puede ejecutar el siguiente comando de la CLI:

az ad user show --id <your-user-principal> --query id

Autenticar el cliente

Para interactuar con el servicio azure Key Vault, deberá crear una instancia de la clase KeyClient. Necesita una dirección URL del almacén, que puede ver como "Nombre DNS" en el portal y credenciales para crear instancias de un objeto de cliente.

Los ejemplos que se muestran a continuación usan , DefaultAzureCredentialque es adecuado para la mayoría de los escenarios, incluidos los entornos de desarrollo y producción locales que usan la autenticación de identidad administrada. Además, se recomienda usar una identidad administrada para la autenticación en entornos de producción. Puede encontrar más información sobre las distintas formas de autenticación y sus tipos de credenciales correspondientes en la documentación de Azure Identity .

Para usar el DefaultAzureCredential proveedor que se muestra a continuación u otros proveedores de credenciales proporcionados con el SDK de Azure, primero debe instalar el paquete Azure.Identity:

dotnet add package Azure.Identity

Activación de un HSM administrado

Esta sección solo se aplica si va a crear un HSM administrado. Todos los comandos de plano de datos estarán deshabilitados hasta que se active el HSM. No podrá crear claves ni asignar roles. El HSM solo pueden activarlo los administradores designados que se asignaron durante el comando create. Para activar el HSM, debe descargar el dominio de seguridad.

Para activar el HSM necesita:

  • Tres pares de claves RSA como mínimo (diez como máximo).
  • Especificar el número mínimo de claves necesarias para descifrar el dominio de seguridad (cuórum)

Para activar el HSM, envíe al menos tres claves públicas RSA (diez como máximo) al HSM. El HSM cifra el dominio de seguridad con estas claves y lo devuelve. Una vez descargado correctamente este dominio de seguridad, el HSM está listo para usarse. También debe especificar el cuórum, que es el número mínimo de claves privadas necesarias para descifrar el dominio de seguridad.

En el ejemplo siguiente se muestra cómo usar openssl para generar 3 certificados autofirmados.

openssl req -newkey rsa:2048 -nodes -keyout cert_0.key -x509 -days 365 -out cert_0.cer
openssl req -newkey rsa:2048 -nodes -keyout cert_1.key -x509 -days 365 -out cert_1.cer
openssl req -newkey rsa:2048 -nodes -keyout cert_2.key -x509 -days 365 -out cert_2.cer

Use el comando az keyvault security-domain download para descargar el dominio de seguridad y activar el HSM administrado. En el ejemplo siguiente se usan 3 pares de claves RSA (solo se necesitan claves públicas para este comando) y se establece el cuórum en 2.

az keyvault security-domain download --hsm-name <your-key-vault-name> --sd-wrapping-keys ./certs/cert_0.cer ./certs/cert_1.cer ./certs/cert_2.cer --sd-quorum 2 --security-domain-file ContosoMHSM-SD.json

Creación de KeyClient

Cree una instancia de para DefaultAzureCredential pasar al cliente. La misma instancia de una credencial de token se puede usar con varios clientes si se autenticarán con la misma identidad.

// Create a new key client using the default credential from Azure.Identity using environment variables previously set,
// including AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, and AZURE_TENANT_ID.
var client = new KeyClient(vaultUri: new Uri(vaultUrl), credential: new DefaultAzureCredential());

// Create a new key using the key client.
KeyVaultKey key = client.CreateKey("key-name", KeyType.Rsa);

// Retrieve a key using the key client.
key = client.GetKey("key-name");

Creación de CryptographyClient

Una vez que haya creado un KeyVaultKey elemento en azure Key Vault, también puede crear CryptographyClient:

// Create a new cryptography client using the same Key Vault or Managed HSM endpoint, service version,
// and options as the KeyClient created earlier.
CryptographyClient cryptoClient = client.GetCryptographyClient(key.Name, key.Properties.Version);

Conceptos clave

KeyVaultKey

Azure Key Vault admite varios tipos de clave y algoritmos, y permite el uso de módulos de seguridad de hardware (HSM) para claves de alto valor.

KeyClient

Existe una KeyClient provisión de operaciones sincrónicas y asincrónicas en el SDK que permite la selección de un cliente en función del caso de uso de una aplicación. Una vez que haya inicializado un KeyClient, puede interactuar con los tipos de recursos principales en Azure Key Vault.

CryptographyClient

Existe una CryptographyClient provisión de operaciones sincrónicas y asincrónicas en el SDK que permite la selección de un cliente en función del caso de uso de una aplicación. Una vez que haya inicializado un CryptographyClient, puede usarlo para realizar operaciones criptográficas con claves almacenadas en Azure Key Vault.

Seguridad para subprocesos

Garantizamos que todos los métodos de instancia de cliente sean seguros para subprocesos e independientes entre sí (guía). Esto garantiza que la recomendación de reutilizar instancias de cliente siempre es segura, incluso entre subprocesos.

Conceptos adicionales

Opciones | de cliente Acceso a la respuesta | Operaciones | de larga duraciónControl de errores | Diagnóstico | Burla | Duración del cliente

Ejemplos

El paquete Azure.Security.KeyVault.Keys admite API sincrónicas y asincrónicas.

En la sección siguiente se proporcionan varios fragmentos de código mediante el clientcreado anteriormente, que abarcan algunas de las tareas relacionadas con el servicio clave de Azure Key Vault más comunes:

Ejemplos de sincronización

Ejemplos asincrónicos

Crear una clave

Cree una clave que se almacenará en azure Key Vault. Si ya existe una clave con el mismo nombre, se crea una nueva versión de la clave.

// Create a key. Note that you can specify the type of key
// i.e. Elliptic curve, Hardware Elliptic Curve, RSA
KeyVaultKey key = client.CreateKey("key-name", KeyType.Rsa);

Console.WriteLine(key.Name);
Console.WriteLine(key.KeyType);

// Create a software RSA key
var rsaCreateKey = new CreateRsaKeyOptions("rsa-key-name", hardwareProtected: false);
KeyVaultKey rsaKey = client.CreateRsaKey(rsaCreateKey);

Console.WriteLine(rsaKey.Name);
Console.WriteLine(rsaKey.KeyType);

// Create a hardware Elliptic Curve key
// Because only premium Azure Key Vault supports HSM backed keys , please ensure your Azure Key Vault
// SKU is premium when you set "hardwareProtected" value to true
var echsmkey = new CreateEcKeyOptions("ec-key-name", hardwareProtected: true);
KeyVaultKey ecKey = client.CreateEcKey(echsmkey);

Console.WriteLine(ecKey.Name);
Console.WriteLine(ecKey.KeyType);

Recuperación de una clave

GetKeyrecupera una clave almacenada anteriormente en azure Key Vault.

KeyVaultKey key = client.GetKey("key-name");

Console.WriteLine(key.Name);
Console.WriteLine(key.KeyType);

Actualización de una clave existente

UpdateKeyPropertiesactualiza una clave almacenada anteriormente en azure Key Vault.

KeyVaultKey key = client.CreateKey("key-name", KeyType.Rsa);

// You can specify additional application-specific metadata in the form of tags.
key.Properties.Tags["foo"] = "updated tag";

KeyVaultKey updatedKey = client.UpdateKeyProperties(key.Properties);

Console.WriteLine(updatedKey.Name);
Console.WriteLine(updatedKey.Properties.Version);
Console.WriteLine(updatedKey.Properties.UpdatedOn);

Eliminación de una clave

StartDeleteKeyinicia una operación de ejecución prolongada para eliminar una clave almacenada anteriormente en Azure Key Vault. Puede recuperar la clave inmediatamente sin esperar a que se complete la operación. Cuando la eliminación temporal no está habilitada para Azure Key Vault, esta operación elimina permanentemente la clave.

DeleteKeyOperation operation = client.StartDeleteKey("key-name");

DeletedKey key = operation.Value;
Console.WriteLine(key.Name);
Console.WriteLine(key.DeletedOn);

Eliminar y purgar una clave

Tendrá que esperar a que se complete la operación de ejecución prolongada antes de intentar purgar o recuperar la clave.

DeleteKeyOperation operation = client.StartDeleteKey("key-name");

// You only need to wait for completion if you want to purge or recover the key.
while (!operation.HasCompleted)
{
    Thread.Sleep(2000);

    operation.UpdateStatus();
}

DeletedKey key = operation.Value;
client.PurgeDeletedKey(key.Name);

Enumera las claves

En este ejemplo se enumeran todas las claves de la Key Vault de Azure especificada.

Pageable<KeyProperties> allKeys = client.GetPropertiesOfKeys();

foreach (KeyProperties keyProperties in allKeys)
{
    Console.WriteLine(keyProperties.Name);
}

Cifrar y descifrar

En este ejemplo se crea y CryptographyClient se usa para cifrar y descifrar con una clave en Azure Key Vault.

// Create a new cryptography client using the same Key Vault or Managed HSM endpoint, service version,
// and options as the KeyClient created earlier.
var cryptoClient = client.GetCryptographyClient(key.Name, key.Properties.Version);

byte[] plaintext = Encoding.UTF8.GetBytes("A single block of plaintext");

// encrypt the data using the algorithm RSAOAEP
EncryptResult encryptResult = cryptoClient.Encrypt(EncryptionAlgorithm.RsaOaep, plaintext);

// decrypt the encrypted data.
DecryptResult decryptResult = cryptoClient.Decrypt(EncryptionAlgorithm.RsaOaep, encryptResult.Ciphertext);

Creación de una clave de forma asincrónica

Las API asincrónicas son idénticas a sus homólogos sincrónicos, pero devuelven con el sufijo "asincrónico" típico para los métodos asincrónicos y devuelven una tarea.

// Create a key of any type
KeyVaultKey key = await client.CreateKeyAsync("key-name", KeyType.Rsa);

Console.WriteLine(key.Name);
Console.WriteLine(key.KeyType);

// Create a software RSA key
var rsaCreateKey = new CreateRsaKeyOptions("rsa-key-name", hardwareProtected: false);
KeyVaultKey rsaKey = await client.CreateRsaKeyAsync(rsaCreateKey);

Console.WriteLine(rsaKey.Name);
Console.WriteLine(rsaKey.KeyType);

// Create a hardware Elliptic Curve key
// Because only premium Azure Key Vault supports HSM backed keys , please ensure your Azure Key Vault
// SKU is premium when you set "hardwareProtected" value to true
var echsmkey = new CreateEcKeyOptions("ec-key-name", hardwareProtected: true);
KeyVaultKey ecKey = await client.CreateEcKeyAsync(echsmkey);

Console.WriteLine(ecKey.Name);
Console.WriteLine(ecKey.KeyType);

Enumerar claves de forma asincrónica

La enumeración de claves no se basa en esperar el GetPropertiesOfKeysAsync método, pero devuelve un AsyncPageable<KeyProperties> valor que se puede usar con la await foreach instrucción :

AsyncPageable<KeyProperties> allKeys = client.GetPropertiesOfKeysAsync();

await foreach (KeyProperties keyProperties in allKeys)
{
    Console.WriteLine(keyProperties.Name);
}

Eliminar una clave de forma asincrónica

Al eliminar una clave de forma asincrónica antes de purgarla, puede esperar el WaitForCompletionAsync método en la operación. De forma predeterminada, este bucle se realiza indefinidamente, pero puede cancelarlo pasando un CancellationToken.

DeleteKeyOperation operation = await client.StartDeleteKeyAsync("key-name");

// You only need to wait for completion if you want to purge or recover the key.
await operation.WaitForCompletionAsync();

DeletedKey key = operation.Value;
await client.PurgeDeletedKeyAsync(key.Name);

Solución de problemas

Consulte nuestra guía de solución de problemas para obtener más información sobre cómo diagnosticar varios escenarios de error.

General

Al interactuar con la biblioteca cliente de claves de Azure Key Vault mediante el SDK de .NET, los errores devueltos por el servicio corresponden a los mismos códigos de estado HTTP devueltos para las solicitudes de la API REST.

Por ejemplo, si intenta recuperar una clave que no existe en azure Key Vault, se devuelve un 404 error que indica "No encontrado".

try
{
    KeyVaultKey key = client.GetKey("some_key");
}
catch (RequestFailedException ex)
{
    Console.WriteLine(ex.ToString());
}

Observará que se registra información adicional, como el identificador de solicitud de cliente de la operación.

Message:
    Azure.RequestFailedException : Service request failed.
    Status: 404 (Not Found)
Content:
    {"error":{"code":"KeyNotFound","message":"Key not found: some_key"}}

Headers:
    Cache-Control: no-cache
    Pragma: no-cache
    Server: Microsoft-IIS/10.0
    x-ms-keyvault-region: westus
    x-ms-request-id: 625f870e-10ea-41e5-8380-282e5cf768f2
    x-ms-keyvault-service-version: 1.1.0.866
    x-ms-keyvault-network-info: addr=131.107.174.199;act_addr_fam=InterNetwork;
    X-AspNet-Version: 4.0.30319
    X-Powered-By: ASP.NET
    Strict-Transport-Security: max-age=31536000;includeSubDomains
    X-Content-Type-Options: nosniff
    Date: Tue, 18 Jun 2019 16:02:11 GMT
    Content-Length: 75
    Content-Type: application/json; charset=utf-8
    Expires: -1

Pasos siguientes

Hay varios ejemplos de biblioteca cliente de claves de Azure Key Vault disponibles en este repositorio de GitHub. Estos ejemplos proporcionan código de ejemplo para escenarios adicionales que se suelen encontrar al trabajar con Azure Key Vault:

  • Sample1_HelloWorld.md: para trabajar con Azure Key Vault, entre los que se incluyen:

    • Crear una clave
    • Obtención de una clave existente
    • Actualización de una clave existente
    • Eliminación de una clave

  • Sample2_BackupAndRestore.md: contiene los fragmentos de código que funcionan con claves de Azure Key Vault, entre las que se incluyen:

    • Copia de seguridad y recuperación de una clave

  • Sample3_GetKeys.md: código de ejemplo para trabajar con claves de Azure Key Vault, entre las que se incluyen:

    • Crear claves
    • Enumerar todas las claves del Key Vault
    • Actualización de claves en el Key Vault
    • Enumeración de versiones de una clave especificada
    • Eliminación de claves del Key Vault
    • Enumerar las claves eliminadas en el Key Vault

  • Sample4_EncryptDecrypt.md: código de ejemplo para realizar operaciones criptográficas con claves de Azure Key Vault, entre las que se incluyen:

    • Cifrado y descifrado de datos con CryptographyClient

  • Sample5_SignVerify.md: código de ejemplo para trabajar con claves de Azure Key Vault, entre las que se incluyen:

    • Firmar un resumen precalculado y comprobar la firma con Firmar y comprobar
    • Firmar datos sin procesar y comprobar la firma con SignData y VerifyData

  • Sample6_WrapUnwrap.md: código de ejemplo para trabajar con claves de Azure Key Vault, entre las que se incluyen:

    • Encapsular y desencapsular una clave simétrica

Documentación adicional

Contribuir

Consulte el CONTRIBUTING.md para obtener más información sobre la compilación, las pruebas y la contribución a estas bibliotecas.

Este proyecto agradece las contribuciones y sugerencias. La mayoría de las contribuciones requieren que acepte un Contrato de licencia para el colaborador (CLA) que declara que tiene el derecho a concedernos y nos concede los derechos para usar su contribución. Para más detalles, visite https://cla.microsoft.com.

Cuando se envía una solicitud de incorporación de cambios, un bot de CLA determinará de forma automática si tiene que aportar un CLA y completar la PR adecuadamente (por ejemplo, la etiqueta, el comentario). Solo siga las instrucciones que le dará el bot. Solo será necesario que lo haga una vez en todos los repositorios con nuestro CLA.

Este proyecto ha adoptado el Código de conducta de Microsoft Open Source. Para más información, consulte las preguntas más frecuentes del código de conducta o póngase en contacto con opencode@microsoft.com si tiene cualquier otra pregunta o comentario.

Impresiones