Bibliothèque de client de clé Azure Key Vault pour .NET - version 4.5.0

  • Article

Azure Key Vault est un service cloud qui fournit un stockage sécurisé des clés pour le chiffrement de vos données. Plusieurs clés, et plusieurs versions de la même clé, peuvent être conservées dans le Key Vault Azure. Les clés de chiffrement dans Azure Key Vault sont représentées en tant qu’objets JWK (JSON Web Key).

Azure Key Vault HSM managé est un service cloud entièrement managé, hautement disponible, monolocataire 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 De niveau 3.

Le client de bibliothèque de clés Azure Key Vault prend en charge les clés RSA et les clés de courbe elliptique (EC), chacune avec la prise en charge correspondante dans les modules de sécurité matériels (HSM). Il offre des opérations pour créer, récupérer, mettre à jour, supprimer, vider, sauvegarder, restaurer et répertorier les clés et leurs versions.

| Code sourcePackage (NuGet) | Documentation de référence sur les | API | Documentation produitÉchantillons | Guide de migration

Prise en main

Installer le package

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

dotnet add package Azure.Security.KeyVault.Keys

Prérequis

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

Si vous créez une ressource Key Vault standard, exécutez la commande CLI suivante en <your-resource-group-name> remplaçant et <your-key-vault-name> par vos propres noms uniques :

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

Si vous créez 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 un instance de la classe KeyClient. Vous avez besoin d’une URL de coffre, que vous pouvez voir sous la forme « Nom DNS » dans le portail, ainsi que des 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, y compris les environnements de développement et de production locaux utilisant l’authentification d’identité managée. 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é

Cette section s’applique uniquement si vous créez un 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 :

  • Trois paires de clés RSA au minimum (10 au maximum)
  • Spécifier le nombre minimal de clés nécessaires au déchiffrement du 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é 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-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

Créer un KeyClient

Instanciez un DefaultAzureCredential à passer au client. La même instance d’informations d’identification de jeton peut être utilisée avec plusieurs clients s’ils s’authentifient avec la même identité.

// 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");

Créer un chiffrementClient

Une fois que vous avez créé un KeyVaultKey dans l’Key Vault Azure, vous pouvez également créer l’objet 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);

Concepts clés

KeyVaultKey

Azure Key Vault prend en charge plusieurs types de clés et algorithmes, et permet l’utilisation de modules de sécurité matériels (HSM) pour les clés à valeur élevée.

KeyClient

Il KeyClient existe des opérations synchrones et asynchrones dans le Kit de développement logiciel (SDK) qui permet de sélectionner un client en fonction du cas d’usage d’une application. Une fois que vous avez initialisé un KeyClient, vous pouvez interagir avec les types de ressources principaux dans Azure Key Vault.

CryptographyClient

Il CryptographyClient existe des opérations synchrones et asynchrones dans le Kit de développement logiciel (SDK) qui permet de sélectionner un client en fonction du cas d’usage d’une application. Une fois que vous avez initialisé un , vous pouvez l’utiliser pour effectuer des CryptographyClientopérations de chiffrement avec des clés stockées dans Azure Key Vault.

Sécurité des threads

Nous garantissons que toutes les méthodes de instance client sont thread-safe et indépendantes les unes des autres (instructions). 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 | du client Accès à la réponse | Opérations | de longue duréeGestion des défaillances | Diagnostics | Moqueur | Durée de vie du client

Exemples

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

La section suivante fournit plusieurs extraits de code à l’aide client du créé ci-dessus, couvrant certaines des tâches les plus courantes liées au service azure Key Vault clés :

Exemples de synchronisation

Exemples asynchrones

Créer une clé

Créez une clé à stocker dans le Key Vault Azure. Si une clé portant le même nom existe déjà, une nouvelle version de la clé est créée.

// 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);

Récupérer une clé

GetKeyrécupère une clé précédemment stockée dans le Key Vault Azure.

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

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

Mettre à jour une clé existante

UpdateKeyPropertiesmet à jour une clé précédemment stockée dans le Key Vault Azure.

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);

Supprimer une clé

StartDeleteKeydémarre une opération de longue durée pour supprimer une clé précédemment stockée dans le Key Vault Azure. Vous pouvez récupérer la clé immédiatement sans attendre la fin de l’opération. Lorsque la suppression réversible n’est pas activée pour azure Key Vault, cette opération supprime définitivement la clé.

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

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

Supprimer et vider une clé

Vous devez attendre la fin de l’opération de longue durée avant d’essayer de vider ou de récupérer la clé.

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);

Afficher la liste des clés

Cet exemple répertorie toutes les clés dans le Key Vault Azure spécifié.

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

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

Chiffrer et déchiffrer

Cet exemple crée un CryptographyClient et l’utilise pour le chiffrer et le déchiffrer avec une clé dans 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);

Créer une clé de manière asynchrone

Les API asynchrones sont identiques à leurs équivalents synchrones, mais retournent avec le suffixe « Async » classique pour les méthodes asynchrones et retournent une tâche.

// 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);

Répertorier les clés de façon asynchrone

La liste des clés ne repose pas sur l’attente de la GetPropertiesOfKeysAsync méthode, mais retourne un AsyncPageable<KeyProperties> que vous pouvez utiliser avec l’instruction await foreach :

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

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

Supprimer une clé de façon asynchrone

Lors de la suppression asynchrone d’une clé avant de la vider, vous pouvez attendre la WaitForCompletionAsync méthode sur l’opération. Par défaut, cette boucle s’exécute indéfiniment, mais vous pouvez l’annuler en passant 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);

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 de client de clé Azure Key Vault à 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 clé qui n’existe pas dans votre Key Vault Azure, une 404 erreur est retournée, indiquant « Introuvable ».

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

Vous remarquerez que des informations supplémentaires sont enregistrées, comme l’ID de demande client de l’opération.

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

Étapes suivantes

Plusieurs exemples de bibliothèque de client de clés Azure Key Vault sont disponibles dans ce dépôt GitHub. Ces exemples fournissent un exemple de code pour des scénarios supplémentaires couramment rencontrés lors de l’utilisation d’Azure Key Vault :

  • Sample1_HelloWorld.md : pour utiliser Azure Key Vault, notamment :

    • Créer une clé
    • Obtenir une clé existante
    • Mettre à jour une clé existante
    • Supprimer une clé

  • Sample2_BackupAndRestore.md : contient les extraits de code qui fonctionnent avec des clés Key Vault Azure, notamment :

    • Sauvegarder et récupérer une clé

  • Sample3_GetKeys.md : exemple de code permettant d’utiliser des clés de Key Vault Azure, notamment :

    • Créer des clés
    • Répertorier toutes les clés dans le Key Vault
    • Mettre à jour les clés dans le Key Vault
    • Répertorier les versions d’une clé spécifiée
    • Supprimer des clés du Key Vault
    • Répertorier les clés supprimées dans le Key Vault

  • Sample4_EncryptDecrypt.md : exemple de code pour effectuer des opérations de chiffrement avec des clés Key Vault Azure, notamment :

    • Chiffrer et déchiffrer des données avec CryptographyClient

  • Sample5_SignVerify.md : exemple de code permettant d’utiliser des clés Key Vault Azure, notamment :

    • Signer un condensé précalculé et vérifier la signature avec Sign et Verify
    • Signer des données brutes et vérifier la signature avec SignData et VerifyData

  • Sample6_WrapUnwrap.md : exemple de code permettant d’utiliser des clés Key Vault Azure, notamment :

    • Encapsuler et désencapsuler une clé symétrique

Documentation complémentaire

Contribution

Consultez la CONTRIBUTING.md pour plus d’informations sur la création, le test et la contribution à ces bibliothèques.

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.

Quand vous envoyez une demande de tirage (pull request), un bot CLA détermine automatiquement si vous devez fournir un contrat CLA et agrémenter la demande de tirage de façon appropriée (par exemple, avec une étiquette ou un commentaire). Suivez simplement les instructions fournies par le bot. Vous ne devez effectuer cette opération qu’une seule fois sur tous les dépôts utilisant notre contrat CLA.

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.

Impressions