Bibliothèque de client Azure KeyVault Administration pour .NET - version 4.3.0

Azure Key Vault Managed HSM est un service cloud entièrement managé, hautement disponible et conforme aux normes qui vous permet de protéger les clés de chiffrement pour vos applications cloud à l’aide de HSM validés FIPS 140-2 Niveau 3.

Les clients de la bibliothèque d’administration Azure Key Vault prennent en charge les tâches administratives telles que la sauvegarde/restauration complète et le contrôle d’accès en fonction du rôle (RBAC) au niveau des clés.

| Code sourcePackage (NuGet) | | Documentation produitÉchantillons

Prise en main

Installer le package

Installez la bibliothèque de client d’administration Azure Key Vault pour .NET avec NuGet :

dotnet add package Azure.Security.KeyVault.Administration

Prérequis

• Un abonnement Azure.
• Un Key Vault Azure existant. Si vous devez créer un Key Vault Azure, vous pouvez utiliser Azure CLI.
• L’autorisation d’un Key Vault Azure existant à l’aide du RBAC (recommandé) ou du contrôle d’accès.

Pour créer une ressource HSM managée, exécutez la commande CLI suivante :

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

Pour obtenir, <your-user-object-id> vous pouvez exécuter la commande CLI suivante :

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

Authentifier le client

Pour interagir avec le service Azure Key Vault, vous devez créer une instance des classes clientes ci-dessous. Vous avez besoin d’une URL de coffre, que vous pouvez voir sous le nom « Nom DNS » dans le portail, et d’informations d’identification pour instancier un objet client.

Les exemples présentés ci-dessous utilisent un DefaultAzureCredential, qui convient à la plupart des scénarios, notamment aux environnements de développement et de production locaux. En outre, nous vous recommandons d’utiliser une identité managée pour l’authentification dans les environnements de production. Vous trouverez plus d’informations sur les différentes méthodes d’authentification et leurs types d’informations d’identification correspondants dans la documentation Azure Identity .

Pour utiliser le DefaultAzureCredential fournisseur indiqué ci-dessous ou d’autres fournisseurs d’informations d’identification fournis avec le Kit de développement logiciel (SDK) Azure, vous devez d’abord installer le package Azure.Identity :

dotnet add package Azure.Identity

Activer votre HSM managé

Toutes les commandes du plan de données sont désactivées tant que le HSM n’est pas activé. Vous ne pourrez pas créer de clés ou attribuer des rôles. Seuls les administrateurs désignés qui ont fait l’objet d’une attribution pendant l’exécution de la commande create peuvent activer le HSM. Pour activer le HSM, vous devez télécharger le domaine de sécurité.

Pour activer votre HSM, vous avez besoin de :

• Un minimum de 3 paires de clés RSA (maximum 10)
• Spécifier le nombre minimal de clés requises pour déchiffrer le domaine de sécurité (quorum)

Pour activer le HSM, vous devez envoyer au moins trois clés publiques RSA au HSM (10 au maximum). Le HSM chiffre le domaine de sécurité avec ces clés et le renvoie. Une fois ce domaine de sécurité correctement téléchargé, votre HSM est prêt à être utilisé. Vous devez aussi spécifier un quorum, qui est le nombre minimal de clés privées nécessaires au déchiffrement du domaine de sécurité.

L’exemple ci-dessous montre comment utiliser openssl pour générer 3 certificats auto-signés.

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

Utilisez la commande az keyvault security-domain download pour télécharger le domaine de sécurité et activer votre HSM managé. L’exemple ci-dessous utilise 3 paires de clés RSA (seules les clés publiques sont nécessaires pour cette commande) et définit le quorum sur 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

Contrôle de l’accès à votre HSM managé

Les administrateurs désignés affectés lors de la création sont automatiquement ajoutés au rôle intégré « Administrateurs HSM managés », qui sont en mesure de télécharger un domaine de sécurité et de gérer des rôles pour l’accès au plan de données, entre autres autorisations limitées.

Pour effectuer d’autres actions sur des clés, vous devez affecter des principaux à d’autres rôles, tels que « Utilisateur de chiffrement HSM managé », qui peut effectuer des opérations de clé non destructrices :

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>

Lisez les bonnes pratiques pour sécuriser correctement votre HSM managé.

Créer KeyVaultAccessControlClient

Instanciez un DefaultAzureCredential à passer au KeyVaultAccessControlClient. Les mêmes instance d’informations d’identification de jeton peuvent être utilisées avec plusieurs clients s’ils authentificationnt avec la même identité.

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

Créer KeyVaultBackupClient

Instanciez un DefaultAzureCredential à passer au KeyVaultBackupClient. Les mêmes instance d’informations d’identification de jeton peuvent être utilisées avec plusieurs clients s’ils authentificationnt avec la même identité.

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

Créer KeyVaultSettingClient

Instanciez un DefaultAzureCredential à passer au KeyVaultSettingsClient. Les mêmes instance d’informations d’identification de jeton peuvent être utilisées avec plusieurs clients s’ils authentificationnt avec la même identité.

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

Concepts clés

KeyVaultRoleDefinition

A KeyVaultRoleDefinition est une collection d’autorisations. Une définition de rôle définit les opérations qui peuvent être effectuées, telles que la lecture, l’écriture et la suppression. Il peut également définir les opérations qui sont exclues des opérations autorisées.

KeyVaultRoleDefinitions peut être listé et spécifié dans le cadre d’un KeyVaultRoleAssignment.

KeyVaultRoleAssignment

A KeyVaultRoleAssignment est l’association d’un KeyVaultRoleDefinition à un principal de service. Ils peuvent être créés, répertoriés, extraits individuellement et supprimés.

KeyVaultAccessControlClient

Un KeyVaultAccessControlClient fournit des opérations synchrones et asynchrones permettant la gestion des KeyVaultRoleDefinition objets et KeyVaultRoleAssignment .

KeyVaultBackupClient

Un KeyVaultBackupClient fournit des opérations synchrones et asynchrones pour effectuer des sauvegardes de clés complètes, des restaurations de clés complètes et des restaurations de clés sélectives.

BackupOperation

Représente BackupOperation une opération de longue durée pour une sauvegarde de clé complète.

RestoreOperation

Un RestoreOperation représente une opération de longue durée pour une restauration de clé complète et de clé sélective.

Sécurité des threads

Nous garantissons que toutes les méthodes de instance client sont sécurisées pour les threads et indépendantes les unes des autres (recommandations). Cela garantit que la recommandation de réutilisation des instances clientes est toujours sécurisée, même entre les threads.

Concepts supplémentaires

Options clientes | Accès à la réponse | Opérations de longue durée | Gestion des défaillances | Diagnostics | Moqueur | Durée de vie du client

Exemples

Le package Azure.Security.KeyVault.Administration prend en charge les API synchrones et asynchrones.

La section suivante fournit plusieurs extraits de code à l’aide de ce client qui a été créé ci-dessus pour les clients de contrôle d’accès ou de sauvegarde, couvrant certaines des tâches les plus courantes liées au contrôle d’accès Azure Key Vault :

Exemples de synchronisation

• Contrôle d’accès
  • Liste de toutes les définitions de rôle
  • Liste de toutes les attributions de rôles
  • Création d’une attribution de rôle
  • Obtention d’une attribution de rôle
  • Suppression d'une attribution de rôle
• Sauvegarde et restauration
  • Exécution d’une sauvegarde de clé complète
  • Exécution d’une restauration de clé complète

Exemples asynchrones

• Contrôle d’accès
  • Liste de toutes les définitions de rôle
  • Liste de toutes les attributions de rôles
  • Création d’une attribution de rôle
  • Obtention d’une attribution de rôle
  • Suppression d'une attribution de rôle
• Sauvegarde et restauration
  • Exécution d’une sauvegarde de clé complète
  • Exécution d’une restauration de clé complète

Résolution des problèmes

Consultez notre guide de résolution des problèmes pour plus d’informations sur la façon de diagnostiquer différents scénarios d’échec.

Général

Lorsque vous interagissez avec la bibliothèque Azure Key Vault Administration à l’aide du KIT de développement logiciel (SDK) .NET, les erreurs retournées par le service correspondent aux mêmes codes de status HTTP retournés pour les demandes d’API REST.

Par exemple, si vous essayez de récupérer une attribution de rôle qui n’existe pas dans votre Key Vault Azure, une 404 erreur est retournée, indiquant « Introuvable ».

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

Configuration de la journalisation de la console

Le moyen le plus simple de voir les journaux consiste à activer la journalisation de la console. Pour créer un écouteur de journal du SDK Azure qui génère des messages vers la console, utilisez la AzureEventSourceListener.CreateConsoleLogger méthode .

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

Pour en savoir plus sur les autres mécanismes de journalisation , consultez ici.

Étapes suivantes

Bien commencer avec nos exemples.

Contribution

Ce projet accepte les contributions et les suggestions. La plupart des contributions vous demandent d’accepter un contrat de licence de contribution (CLA) déclarant que vous avez le droit de nous accorder, et que vous nous accordez réellement, les droits d’utilisation de votre contribution. Pour plus d’informations, visitez https://cla.microsoft.com.

Ce projet a adopté le Code de conduite Open Source de Microsoft. Pour plus d’informations, consultez les Questions fréquentes (FAQ) sur le code de conduite ou envoyez vos questions ou vos commentaires à opencode@microsoft.com.