.NET için Azure Key Vault anahtar istemci kitaplığı - sürüm 4.5.0

  • Makale

Azure Key Vault, verilerinizi şifrelemek için anahtarların güvenli bir şekilde depolanmasını sağlayan bir bulut hizmetidir. Birden çok anahtar ve aynı anahtarın birden çok sürümü Azure Key Vault tutulabilir. Azure Key Vault'daki şifreleme anahtarları JSON Web Anahtarı (JWK) nesneleri olarak temsil edilir.

Azure Key Vault Yönetilen HSM, FIPS 140-2 Düzey 3 doğrulanmış HSM'leri kullanarak bulut uygulamalarınız için şifreleme anahtarlarını korumanızı sağlayan, tam olarak yönetilen, yüksek oranda kullanılabilir, tek kiracılı, standartlara uyumlu bir bulut hizmetidir.

Azure Key Vault anahtarları kitaplığı istemcisi, her birinde donanım güvenlik modülleri (HSM) desteği bulunan RSA anahtarlarını ve Elips Eğrisi (EC) anahtarlarını destekler. Anahtarları ve sürümlerini oluşturma, alma, güncelleştirme, silme, temizleme, yedekleme, geri yükleme ve listeleme işlemleri sunar.

Kaynak kodu | Paket (NuGet) | API başvuru belgeleri | Ürün belgeleri | Örnekleri | Geçiş kılavuzu

Başlarken

Paketi yükleme

NuGet ile .NET için Azure Key Vault anahtarları istemci kitaplığını yükleyin:

dotnet add package Azure.Security.KeyVault.Keys

Önkoşullar

Standart bir Key Vault kaynağı oluşturuyorsanız ve yerine kendi benzersiz adlarınızı koyarak <your-resource-group-name><your-key-vault-name> aşağıdaki CLI komutunu çalıştırın:

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

Yönetilen HSM kaynağı oluşturuyorsanız aşağıdaki CLI komutunu çalıştırın:

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

Almak <your-user-object-id> için aşağıdaki CLI komutunu çalıştırabilirsiniz:

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

İstemcinin kimliğini doğrulama

Azure Key Vault hizmetiyle etkileşim kurmak için KeyClient sınıfının bir örneğini oluşturmanız gerekir. Portalda "DNS Adı" olarak görebileceğiniz bir kasa URL'sine ve istemci nesnesinin örneğini oluşturmak için kimlik bilgilerine ihtiyacınız vardır.

Aşağıda gösterilen örneklerde, yönetilen kimlik kimlik doğrulaması kullanan yerel geliştirme ve üretim ortamları dahil olmak üzere çoğu senaryo için uygun olan bir DefaultAzureCredentialkullanılır. Ayrıca, üretim ortamlarında kimlik doğrulaması için yönetilen kimlik kullanmanızı öneririz. Farklı kimlik doğrulama yöntemleri ve bunların ilgili kimlik bilgileri türleri hakkında daha fazla bilgiyi Azure Kimliği belgelerinde bulabilirsiniz.

Aşağıda gösterilen sağlayıcıyı DefaultAzureCredential veya Azure SDK ile sağlanan diğer kimlik bilgisi sağlayıcılarını kullanmak için önce Azure.Identity paketini yüklemeniz gerekir:

dotnet add package Azure.Identity

Yönetilen HSM'nizi etkinleştirme

Bu bölüm yalnızca Yönetilen HSM oluşturuyorsanız geçerlidir. HSM etkinleştirilene kadar tüm veri düzlemi komutları devre dışı bırakılır. Anahtar oluşturamaz veya rol atayamazsınız. HSM'yi yalnızca oluşturma komutu sırasında atanan atanan yöneticiler etkinleştirebilir. HSM'yi etkinleştirmek için güvenlik etki alanını indirmeniz gerekir.

HSM'nizi etkinleştirmek için ihtiyacınız olan:

  • En az 3 RSA anahtar çifti (en fazla 10)
  • Güvenlik etki alanının şifresini çözmek için gereken en az anahtar sayısını belirtin (çekirdek)

HSM'yi etkinleştirmek için HSM'ye en az 3 (en fazla 10) RSA ortak anahtarı gönderirsiniz. HSM, güvenlik etki alanını bu anahtarlarla şifreler ve geri gönderir. Bu güvenlik etki alanı başarıyla indirildikten sonra HSM'niz kullanıma hazırdır. Güvenlik etki alanının şifresini çözmek için gereken en az özel anahtar sayısı olan çekirdeği de belirtmeniz gerekir.

Aşağıdaki örnekte, otomatik olarak imzalanan 3 sertifika oluşturmak için openssl'nin nasıl kullanılacağı gösterilmektedir.

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

az keyvault security-domain download Güvenlik etki alanını indirmek ve yönetilen HSM'nizi etkinleştirmek için komutunu kullanın. Aşağıdaki örnekte 3 RSA anahtar çifti kullanılır (bu komut için yalnızca ortak anahtarlar gereklidir) ve çekirdeği 2 olarak ayarlar.

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

KeyClient Oluşturma

İstemciye geçirmek için bir DefaultAzureCredential örneği oluşturun. Aynı kimlikle kimlik doğrulaması yapacaklarsa, belirteç kimlik bilgilerinin aynı örneği birden çok istemcide kullanılabilir.

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

CryptographyClient Oluşturma

Azure Key Vault oluşturduktan KeyVaultKey sonra CryptographyClient'ı da oluşturabilirsiniz:

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

Önemli kavramlar

KeyVaultKey

Azure Key Vault birden çok anahtar türünü ve algoritmayı destekler ve yüksek değerli anahtarlar için donanım güvenlik modüllerinin (HSM) kullanılmasını sağlar.

KeyClient

SDK'da KeyClient hem zaman uyumlu hem de zaman uyumsuz işlemler sağlayan ve bir uygulamanın kullanım örneğine göre istemci seçimine olanak sağlayan bir. bir KeyClientuygulamasını başlatdıktan sonra Azure Key Vault'daki birincil kaynak türleriyle etkileşim kurabilirsiniz.

CryptographyClient

SDK'da CryptographyClient hem zaman uyumlu hem de zaman uyumsuz işlemler sağlayan ve bir uygulamanın kullanım örneğine göre istemci seçimine olanak sağlayan bir. bir CryptographyClient'i başlatdıktan sonra, Azure Key Vault'de depolanan anahtarlarla şifreleme işlemleri gerçekleştirmek için bunu kullanabilirsiniz.

İş parçacığı güvenliği

Tüm istemci örneği yöntemlerinin iş parçacığı açısından güvenli ve birbirinden bağımsız olduğunu garanti ediyoruz (kılavuz). Bu, istemci örneklerini yeniden kullanma önerisinin iş parçacıkları arasında bile her zaman güvenli olmasını sağlar.

Ek kavramlar

İstemci seçenekleri | Yanıta | erişme Uzun süre çalışan işlemler | | Hataları işlemeTanılama | Alaycı | İstemci ömrü

Örnekler

Azure.Security.KeyVault.Keys paketi zaman uyumlu ve zaman uyumsuz API'leri destekler.

Aşağıdaki bölümde, yukarıda oluşturulan kullanılarak client azure Key Vault temel hizmetle ilgili en yaygın görevlerden bazılarını kapsayan birkaç kod parçacığı verilmiştir:

Eşitleme örnekleri

Zaman uyumsuz örnekler

Bir anahtar oluşturma

Azure Key Vault depolanacak bir anahtar oluşturun. Aynı ada sahip bir anahtar zaten varsa, anahtarın yeni bir sürümü oluşturulur.

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

Anahtar alma

GetKeydaha önce Azure Key Vault depolanan bir anahtarı alır.

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

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

Mevcut anahtarı güncelleştirme

UpdateKeyPropertiesdaha önce Azure Key Vault depolanan bir anahtarı güncelleştirir.

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

Bir anahtarı silme

StartDeleteKeydaha önce Azure Key Vault depolanan bir anahtarı silmek için uzun süre çalışan bir işlem başlatır. İşlemin tamamlanmasını beklemeden anahtarı hemen alabilirsiniz. Azure Key Vault için geçici silme etkinleştirilmediğinde, bu işlem anahtarı kalıcı olarak siler.

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

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

Anahtarı silme ve temizleme

Anahtarı temizlemeye veya kurtarmaya çalışmadan önce uzun süre çalışan işlemin tamamlanmasını beklemeniz gerekir.

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

Liste Anahtarları

Bu örnek, belirtilen Azure Key Vault tüm anahtarları listeler.

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

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

Şifreleme ve Şifre Çözme

Bu örnek, CryptographyClient azure Key Vault bir anahtarla şifrelemek ve şifresini çözmek için bir oluşturur ve kullanır.

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

Zaman uyumsuz olarak anahtar oluşturma

Zaman uyumsuz API'ler, zaman uyumlu karşılıklarıyla aynıdır, ancak zaman uyumsuz yöntemler için tipik "Zaman uyumsuz" soneki ile geri döner ve bir Görev döndürür.

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

Anahtarları zaman uyumsuz olarak listeleme

Listeleme anahtarları yöntemini beklemeye GetPropertiesOfKeysAsync dayanmaz, ancak deyimiyle await foreach kullanabileceğiniz bir AsyncPageable<KeyProperties> döndürür:

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

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

Anahtarı zaman uyumsuz olarak silme

Temizlemeden önce bir anahtarı zaman uyumsuz olarak silerken, işlemde WaitForCompletionAsync yöntemini bekleyebilirsiniz. Varsayılan olarak, bu döngü süresiz olarak döngüye geçer, ancak bir CancellationTokengeçirerek iptal edebilirsiniz.

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

Sorun giderme

Çeşitli hata senaryolarını tanılama hakkında ayrıntılı bilgi için sorun giderme kılavuzumuza bakın.

Genel

.NET SDK'sını kullanarak Azure Key Vault anahtar istemci kitaplığıyla etkileşime geçtiğiniz zaman, hizmet tarafından döndürülen hatalar REST API istekleri için döndürülen aynı HTTP durum kodlarına karşılık gelir.

Örneğin, Azure Key Vault'nizde bulunmayan bir anahtarı almaya çalışırsanız, "Bulunamadı" hatasını belirten bir 404 hata döndürülür.

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

İşlemin istemci istek kimliği gibi ek bilgilerin günlüğe kaydedildiğini fark edeceksiniz.

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

Sonraki adımlar

Bu GitHub deposunda çeşitli Azure Key Vault anahtarları istemci kitaplığı örnekleri sağlanır. Bu örnekler, Azure Key Vault çalışırken yaygın olarak karşılaşılan ek senaryolar için örnek kod sağlar:

  • Sample1_HelloWorld.md - Azure Key Vault ile çalışmak için:

    • Bir anahtar oluşturma
    • Var olan bir anahtarı alma
    • Mevcut anahtarı güncelleştirme
    • Bir anahtarı silme

  • Sample2_BackupAndRestore.md - Azure Key Vault anahtarlarıyla çalışan kod parçacıklarını içerir; örneğin:

    • Anahtarı yedekleme ve kurtarma

  • Sample3_GetKeys.md - Azure Key Vault anahtarlarıyla çalışmaya yönelik örnek kod:

    • Anahtar oluşturma
    • Key Vault tüm anahtarları listeleme
    • Key Vault anahtarları güncelleştirme
    • Belirtilen anahtarın sürümlerini listeleme
    • anahtarları Key Vault silme
    • Key Vault silinen anahtarları listeleme

  • Sample4_EncryptDecrypt.md - Azure Key Vault anahtarlarıyla şifreleme işlemleri gerçekleştirmeye yönelik örnek kod:

    • CryptographyClient ile verileri şifreleme ve şifre çözme

  • Sample5_SignVerify.md - Azure Key Vault anahtarlarıyla çalışmaya yönelik örnek kod:

    • Önceden hesaplanmış özet imzalama ve İmzala ve Doğrula ile imzayı doğrulama
    • Ham verileri imzalama ve SignData ve VerifyData ile imzayı doğrulama

  • Sample6_WrapUnwrap.md - Azure Key Vault anahtarlarıyla çalışmaya yönelik örnek kod:

    • Simetrik anahtarı sarmalama ve sarmalama

Diğer Belgeler

Katkıda bulunma

Bu kitaplıkları oluşturma, test etme ve bunlara katkıda bulunma hakkında ayrıntılı bilgi için CONTRIBUTING.md bakın.

Bu proje, katkı ve önerilere açıktır. Çoğu durumda, sağladığınız katkıyı kullanmamız için bize hak tanıma hakkına sahip olduğunuzu ve bu hakkı bize tanıdığınızı bildiren bir Katkıda Bulunan Lisans Sözleşmesi’ni (CLA) kabul etmeniz gerekir. Ayrıntılar için bkz. https://cla.microsoft.com.

Bir çekme isteği gönderdiğinizde, CLA robotu bir CLA sağlamanız gerekip gerekmediğini otomatik olarak belirler ve çekme isteğini uygun şekilde donatır (örn. etiket, açıklama). Robot tarafından sağlanan yönergeleri izlemeniz yeterlidir. Bu işlemi, CLA’mızı kullanarak tüm depolarda yalnızca bir kere yapmanız gerekir.

Bu proje Microsoft Open Source Code of Conduct (Microsoft Açık Kaynak Kullanım Kuralları) belgesinde listelenen kurallara uygundur. Daha fazla bilgi için Kullanım Kuralları SSS bölümüne bakın veya ek sorular veya yorumlarla iletişime geçin opencode@microsoft.com .

İzlenimler