Libreria client delle chiavi di Azure Key Vault per .NET - versione 4.5.0

Azure Key Vault è un servizio cloud che fornisce l'archiviazione sicura delle chiavi per crittografare i dati. È possibile conservare più chiavi e più versioni della stessa chiave nel Key Vault di Azure. Le chiavi crittografiche in Azure Key Vault sono rappresentate come oggetti JWK (JSON Web Key).

Il modulo di protezione hardware gestito di Azure Key Vault è un servizio cloud completamente gestito, a disponibilità elevata, a tenant singolo e conforme agli standard che consente di proteggere le chiavi crittografiche per le applicazioni cloud usando moduli di protezione hardware convalidati FIPS 140-2 livello 3.

Il client della libreria delle chiavi di Azure Key Vault supporta chiavi RSA e chiavi EC (Elliptic Curve), ognuna con il supporto corrispondente nei moduli di protezione hardware. Offre operazioni per creare, recuperare, aggiornare, eliminare, ripulire, eseguire il backup, ripristinare ed elencare le chiavi e le relative versioni.

Codice | sorgente Pacchetto (NuGet) | Documentazione | di riferimento sulle APIDocumentazione | del prodotto Campioni | Guida alla migrazione

Introduzione

Installare il pacchetto

Installare la libreria client delle chiavi di Azure Key Vault per .NET con NuGet:

dotnet add package Azure.Security.KeyVault.Keys

Prerequisiti

• Una sottoscrizione di Azure.
• Un Key Vault di Azure esistente. Se è necessario creare un Key Vault di Azure, è possibile usare il portale di Azure o l'interfaccia della riga di comando di Azure.
• Autorizzazione a un Key Vault di Azure esistente usando il controllo degli accessi in base al ruolo (scelta consigliata) o il controllo di accesso.

Se si crea una risorsa Key Vault standard, eseguire il comando dell'interfaccia della riga di comando seguente sostituendo <your-resource-group-name> e <your-key-vault-name> con nomi univoci personalizzati:

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

Se si sta creando una risorsa del modulo di protezione hardware gestito, eseguire il comando dell'interfaccia della riga di comando seguente:

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

Per ottenere l'esecuzione <your-user-object-id> del comando dell'interfaccia della riga di comando seguente:

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

Autenticare il client

Per interagire con il servizio Azure Key Vault, è necessario creare un'istanza della classe KeyClient. È necessario un URL dell'insieme di credenziali, che può essere visualizzato come "Nome DNS" nel portale e le credenziali per creare un'istanza di un oggetto client.

Gli esempi illustrati di seguito usano un DefaultAzureCredential, appropriato per la maggior parte degli scenari, tra cui gli ambienti di sviluppo locale e di produzione che usano l'autenticazione dell'identità gestita. È inoltre consigliabile usare un'identità gestita per l'autenticazione negli ambienti di produzione. Per altre informazioni sulle diverse modalità di autenticazione e sui relativi tipi di credenziali corrispondenti, vedere la documentazione di Identità di Azure .

Per usare il DefaultAzureCredential provider illustrato di seguito o altri provider di credenziali forniti con Azure SDK, è prima necessario installare il pacchetto Azure.Identity:

dotnet add package Azure.Identity

Attivare il modulo di protezione hardware gestito

Questa sezione si applica solo se si crea un modulo di protezione hardware gestito. Tutti i comandi del piano dati vengono disabilitati fino all'attivazione del modulo di protezione hardware. Non sarà possibile creare chiavi o assegnare ruoli. Solo gli amministratori designati assegnati durante il comando di creazione possono attivare il modulo di protezione hardware. Per attivare il modulo di protezione hardware, è necessario scaricare il dominio di sicurezza.

Per attivare il modulo di protezione hardware occorre:

• Almeno 3 coppie di chiavi RSA (al massimo 10)
• Specificare il numero minimo di chiavi necessarie per decrittografare il dominio di sicurezza (quorum)

Per attivare il modulo di protezione hardware è necessario inviare almeno 3 (al massimo 10) chiavi pubbliche RSA al modulo stesso. Il modulo di protezione hardware crittografa il dominio di sicurezza con queste chiavi e lo restituisce. Dopo il download di questo dominio di sicurezza, il modulo di protezione hardware è pronto per l'uso. Occorre anche specificare il quorum, ossia il numero minimo di chiavi private necessarie per decrittografare il dominio di sicurezza.

L'esempio seguente illustra come usare openssl per generare 3 certificati autofirmato.

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

Usare il comando az keyvault security-domain download per scaricare il dominio di sicurezza e attivare il modulo di protezione hardware gestito. L'esempio seguente usa 3 coppie di chiavi RSA (sono necessarie solo chiavi pubbliche per questo comando) e imposta il quorum su 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

Creare KeyClient

Creare un'istanza DefaultAzureCredential di per passare al client. La stessa istanza di una credenziale del token può essere usata con più client se eseguirà l'autenticazione con la stessa 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");

Creare CryptographyClient

Dopo aver creato un KeyVaultKey in Azure Key Vault, è anche possibile creare 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);

Concetti chiave

KeyVaultKey

Azure Key Vault supporta più tipi di chiavi e algoritmi e consente l'uso di moduli di protezione hardware (HSM) per le chiavi con valori elevati.

KeyClient

Un KeyClient oggetto che fornisce sia operazioni sincrone che asincrone è presente nell'SDK che consente la selezione di un client in base al caso d'uso di un'applicazione. Dopo aver inizializzato un KeyClientoggetto , è possibile interagire con i tipi di risorse primari in Azure Key Vault.

CryptographyClient

Un CryptographyClient oggetto che fornisce sia operazioni sincrone che asincrone è presente nell'SDK che consente la selezione di un client in base al caso d'uso di un'applicazione. Dopo aver inizializzato un CryptographyClientoggetto , è possibile usarlo per eseguire operazioni di crittografia con chiavi archiviate in Azure Key Vault.

Thread safety

Microsoft garantisce che tutti i metodi di istanza client siano thread-safe e indipendenti l'uno dall'altro (linee guida). Ciò garantisce che la raccomandazione di riutilizzare le istanze client sia sempre sicura, anche tra thread.

Concetti aggiuntivi

Opzioni | client Accesso alla risposta | Operazioni | a esecuzione prolungataGestione degli errori | Diagnostica | Beffardo | Durata del client

Esempio

Il pacchetto Azure.Security.KeyVault.Keys supporta API sincrone e asincrone.

La sezione seguente fornisce diversi frammenti di codice che usano il clientcodice creato in precedenza, che illustra alcune delle attività più comuni correlate al servizio di Key Vault di Azure:

Esempi di sincronizzazione

• Creare una chiave
• Recuperare una chiave
• Aggiornare una chiave esistente
• Eliminare una chiave
• Eliminare ed eliminare una chiave
• List keys
• Crittografare e decrittografare

Esempi asincroni

• Creare una chiave in modo asincrono
• Elencare le chiavi in modo asincrono
• Eliminare una chiave in modo asincrono

Creare una chiave

Creare una chiave da archiviare nel Key Vault di Azure. Se esiste già una chiave con lo stesso nome, viene creata una nuova versione della chiave.

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

Recuperare una chiave

GetKeyrecupera una chiave archiviata in precedenza nel Key Vault di Azure.

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

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

Aggiornare una chiave esistente

UpdateKeyPropertiesaggiorna una chiave archiviata in precedenza nel Key Vault di 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);

Eliminare una chiave

StartDeleteKeyavvia un'operazione a esecuzione prolungata per eliminare una chiave archiviata in precedenza nel Key Vault di Azure. È possibile recuperare immediatamente la chiave senza attendere il completamento dell'operazione. Quando l'eliminazione temporanea non è abilitata per l'Key Vault di Azure, questa operazione elimina definitivamente la chiave.

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

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

Eliminare ed eliminare una chiave

È necessario attendere il completamento dell'operazione a esecuzione prolungata prima di tentare di ripulire o recuperare la chiave.

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

Elenco delle chiavi

Questo esempio elenca tutte le chiavi nel Key Vault di Azure specificato.

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

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

Crittografare e decrittografare

Questo esempio crea un oggetto CryptographyClient e lo usa per crittografare e decrittografare con una chiave in 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);

Creare una chiave in modo asincrono

Le API asincrone sono identiche alle rispettive controparti sincrone, ma restituiscono con il suffisso "Async" tipico per i metodi asincroni e restituiscono un'attività.

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

Elencare le chiavi in modo asincrono

L'elenco delle chiavi non si basa sull'attesa del GetPropertiesOfKeysAsync metodo, ma restituisce un oggetto AsyncPageable<KeyProperties> che è possibile usare con l'istruzione await foreach :

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

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

Eliminare una chiave in modo asincrono

Quando si elimina una chiave in modo asincrono prima di eliminarla, è possibile attendere il WaitForCompletionAsync metodo sull'operazione. Per impostazione predefinita, questo ciclo viene eseguito per un periodo illimitato, ma è possibile annullarlo passando un oggetto 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);

Risoluzione dei problemi

Per informazioni dettagliate su come diagnosticare vari scenari di errore, vedere la guida alla risoluzione dei problemi .

Generale

Quando si interagisce con la libreria client delle chiavi di Azure Key Vault tramite .NET SDK, gli errori restituiti dal servizio corrispondono agli stessi codici di stato HTTP restituiti per le richieste api REST.

Ad esempio, se si tenta di recuperare una chiave che non esiste nel Key Vault di Azure, viene restituito un 404 errore che indica "Non trovato".

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

Si noterà che vengono registrate informazioni aggiuntive, ad esempio l'ID richiesta client dell'operazione.

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

Passaggi successivi

In questo repository GitHub sono disponibili diversi esempi di libreria client delle chiavi di Azure Key Vault. Questi esempi forniscono codice di esempio per scenari aggiuntivi comunemente rilevati durante l'uso di Azure Key Vault:

• Sample1_HelloWorld.md: per l'uso di Azure Key Vault, tra cui:

  • Creare una chiave
  • Ottenere una chiave esistente
  • Aggiornare una chiave esistente
  • Eliminare una chiave

• Sample2_BackupAndRestore.md: contiene i frammenti di codice che lavorano con le chiavi Key Vault di Azure, tra cui:

  • Eseguire il backup e il ripristino di una chiave

• Sample3_GetKeys.md - Codice di esempio per l'uso delle chiavi di Azure Key Vault, tra cui:

  • Creare chiavi
  • Elencare tutte le chiavi nel Key Vault
  • Aggiornare le chiavi nel Key Vault
  • Elencare le versioni di una chiave specificata
  • Eliminare le chiavi dal Key Vault
  • Elencare le chiavi eliminate nel Key Vault

• Sample4_EncryptDecrypt.md : codice di esempio per l'esecuzione di operazioni di crittografia con chiavi di Key Vault di Azure, tra cui:

  • Crittografare e decrittografare i dati con CryptographyClient

• Sample5_SignVerify.md : codice di esempio per l'uso delle chiavi di Azure Key Vault, tra cui:

  • Firmare un digest precalcolato e verificare la firma con Firma e verifica
  • Firmare i dati non elaborati e verificare la firma con SignData e VerifyData

• Sample6_WrapUnwrap.md : codice di esempio per l'uso delle chiavi di Azure Key Vault, tra cui:

  • Eseguire il wrapping e annullare il wrapping di una chiave simmetrica

Documentazione aggiuntiva

• Per una documentazione più completa su Azure Key Vault, vedere la documentazione di riferimento sulle API.
• Per la libreria client dei segreti, vedere Libreria client dei segreti.
• Per la libreria client certificati, vedere Libreria client dei certificati.

Contributo

Per informazioni dettagliate sulla compilazione, il test e il contributo a queste librerie, vedere la CONTRIBUTING.md .

In questo progetto sono benvenuti i contributi e i suggerimenti. Per la maggior parte dei contenuti è necessario sottoscrivere un contratto di licenza di collaborazione (CLA, Contributor License Agreement) che stabilisce che l'utente ha il diritto di concedere, e di fatto concede a Microsoft i diritti d'uso del suo contributo. Per informazioni dettagliate, vedere https://cla.microsoft.com.

Quando si invia una richiesta pull, un bot CLA determina automaticamente se è necessario specificare un contratto CLA e completare la richiesta pull in modo appropriato (ad esempio con un'etichetta e un commento). Seguire le istruzioni specificate dal bot. È sufficiente eseguire questa operazione una sola volta per tutti i repository che usano il contratto CLA Microsoft.

Questo progetto ha adottato il Codice di comportamento di Microsoft per l'open source. Per altre informazioni, vedere Code of Conduct FAQ (Domande frequenti sul Codice di comportamento Open Source di Microsoft) oppure contattare opencode@microsoft.com per eventuali altre domande o commenti.