Biblioteca cliente de administración de Azure KeyVault para .NET, versión 4.3.0

  • Artículo

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

Los clientes de la biblioteca de administración de Azure Key Vault admiten tareas administrativas, como la copia de seguridad completa o restauración y el control de acceso basado en rol (RBAC) de nivel de clave.

Código | fuente Paquete (NuGet) | | Documentación del productoMuestras

Introducción

Instalar el paquete

Instale la biblioteca cliente de administración de Azure Key Vault para .NET con NuGet:

dotnet add package Azure.Security.KeyVault.Administration

Prerrequisitos

Para 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 las clases de cliente siguientes. 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. 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

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:

  • Un mínimo de 3 pares de claves RSA (máximo 10)
  • Especifique 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 que este dominio de seguridad se haya descargado correctamente, el HSM estará 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-managed-hsm-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

Control del acceso al HSM administrado

Los administradores designados asignados durante la creación se agregan automáticamente al rol integrado "Administradores de HSM administrados", que pueden descargar un dominio de seguridad y administrar roles para el acceso al plano de datos, entre otros permisos limitados.

Para realizar otras acciones en las claves, debe asignar entidades de seguridad a otros roles, como "Managed HSM Crypto User", que puede realizar operaciones de clave no destructivas:

az keyvault role assignment create --hsm-name <your-managed-hsm-name> --role "Managed HSM Crypto User" --scope / --assignee-object-id <principal-or-user-object-ID> --assignee-principal-type <principal-type>

Lea los procedimientos recomendados para proteger correctamente el HSM administrado.

Creación de KeyVaultAccessControlClient

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

KeyVaultAccessControlClient client = new KeyVaultAccessControlClient(new Uri(managedHsmUrl), new DefaultAzureCredential());

Creación de KeyVaultBackupClient

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

KeyVaultBackupClient client = new KeyVaultBackupClient(new Uri(managedHsmUrl), new DefaultAzureCredential());

Creación de KeyVaultSettingClient

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

KeyVaultSettingsClient client = new KeyVaultSettingsClient(new Uri(managedHsmUrl), new DefaultAzureCredential());

Conceptos clave

KeyVaultRoleDefinition

es KeyVaultRoleDefinition una colección de permisos. Una definición de rol define las operaciones que se pueden realizar, como lectura, escritura y eliminación. También puede definir las operaciones que se excluyen de las operaciones permitidas.

KeyVaultRoleDefinitions se puede enumerar y especificar como parte de .KeyVaultRoleAssignment

KeyVaultRoleAssignment

A KeyVaultRoleAssignment es la asociación de keyVaultRoleDefinition a una entidad de servicio. Se pueden crear, enumerar, capturar individualmente y eliminar.

KeyVaultAccessControlClient

A KeyVaultAccessControlClient proporciona operaciones sincrónicas y asincrónicas que permiten la administración de KeyVaultRoleDefinition objetos y KeyVaultRoleAssignment .

KeyVaultBackupClient

A KeyVaultBackupClient proporciona operaciones sincrónicas y asincrónicas para realizar copias de seguridad de clave completa, restauraciones de claves completas y restauraciones selectivas de claves.

BackupOperation

BackupOperation representa una operación de larga duración para una copia de seguridad de clave completa.

RestoreOperation

RestoreOperation representa una operación de larga duración para una restauración de clave completa y de clave selectiva.

Seguridad para subprocesos

Garantizamos que todos los métodos de instancia de cliente son seguros para subprocesos e independientes entre sí (instrucciones). 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.Administration admite API sincrónicas y asincrónicas.

En la siguiente sección se proporcionan varios fragmentos de código mediante el client creado anteriormente para los clientes de control de acceso o de copia de seguridad, que abarcan algunas de las tareas relacionadas con el control de acceso de Azure Key Vault más comunes:

Ejemplos de sincronización

Ejemplos asincrónicos

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 de administración 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 asignación de roles que no existe en azure Key Vault, se devuelve un 404 error que indica "No encontrado".

try
{
    KeyVaultRoleAssignment roleAssignment = client.GetRoleAssignment(KeyVaultRoleScope.Global, "example-name");
}
catch (RequestFailedException ex)
{
    Console.WriteLine(ex.ToString());
}

Azure.RequestFailedException: Service request failed.
Status: 404 (Not Found)

Content:
{"error":{"code":"RoleAssignmentNotFound","message":"Requested role assignment not found (Activity ID: a67f09f4-b68e-11ea-bd6d-0242ac120006)"}}

Headers:
X-Content-Type-Options: REDACTED
x-ms-request-id: a67f09f4-b68e-11ea-bd6d-0242ac120006
Content-Length: 143
Content-Type: application/json

Configuración del registro de la consola

La manera más sencilla de ver los registros es habilitar el registro de la consola. Para crear un agente de escucha de registro del SDK de Azure que envía mensajes a la consola, use el AzureEventSourceListener.CreateConsoleLogger método .

// Setup a listener to monitor logged events.
using AzureEventSourceListener listener = AzureEventSourceListener.CreateConsoleLogger();

Para más información sobre otros mecanismos de registro, consulte aquí.

Pasos siguientes

Comience a trabajar con nuestros ejemplos.

Contribuciones

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.

El proyecto ha adoptado el Código de conducta de código abierto de Microsoft. 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