.NET için Azure KeyVault Yönetim istemci kitaplığı - sürüm 4.3.0

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ıza olanak tanıyan, tam olarak yönetilen, yüksek oranda kullanılabilir, tek kiracılı, standartlara uyumlu bir bulut hizmetidir.

Azure Key Vault yönetim kitaplığı istemcileri tam yedekleme/geri yükleme ve anahtar düzeyinde rol tabanlı erişim denetimi (RBAC) gibi yönetim görevlerini destekler.

Kaynak kodu | Paket (NuGet) | Ürün belgeleri | Örnekleri

Başlarken

Paketi yükleme

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

dotnet add package Azure.Security.KeyVault.Administration

Önkoşullar

• Bir Azure aboneliği.
• Mevcut bir Azure Key Vault. Azure Key Vault oluşturmanız gerekiyorsa Azure CLI'yi kullanabilirsiniz.
• RBAC (önerilir) veya erişim denetimi kullanarak mevcut bir Azure Key Vault yetkilendirme.

Yönetilen HSM kaynağı oluşturmak için 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 aşağıdaki istemci sınıfları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, 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. Kimlik doğrulamanın farklı yolları 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 bilgileri 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

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 gerekenler:

• 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, 3 otomatik olarak imzalanan 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-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

Yönetilen HSM'nize erişimi denetleme

Oluşturma sırasında atanan atanan yöneticiler otomatik olarak "Yönetilen HSM Yöneticileri" yerleşik rolüne eklenir. Bu rol güvenlik etki alanını indirebilir ve veri düzlemi erişimi rollerini yönetebilir ve diğer sınırlı izinlere sahiptir.

Anahtarlar üzerinde başka eylemler gerçekleştirmek için, yıkıcı olmayan anahtar işlemleri gerçekleştirebilen "Yönetilen HSM Şifreleme Kullanıcısı" gibi diğer rollere sorumlular atamanız gerekir:

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>

Yönetilen HSM'nizin güvenliğini sağlamak için lütfen en iyi yöntemleri okuyun.

KeyVaultAccessControlClient Oluşturma

öğesine geçirmek için bir DefaultAzureCredential örneği KeyVaultAccessControlClientoluşturma. Aynı kimlikle kimlik doğrulaması yapacaklarsa, belirteç kimlik bilgilerinin aynı örneği birden çok istemciyle kullanılabilir.

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

KeyVaultBackupClient Oluşturma

öğesine geçirmek için bir DefaultAzureCredential örneği KeyVaultBackupClientoluşturma. Aynı kimlikle kimlik doğrulaması yapacaklarsa, belirteç kimlik bilgilerinin aynı örneği birden çok istemciyle kullanılabilir.

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

KeyVaultSettingClient Oluşturma

öğesine geçirmek için bir DefaultAzureCredential örneği KeyVaultSettingsClientoluşturma. Aynı kimlikle kimlik doğrulaması yapacaklarsa, belirteç kimlik bilgilerinin aynı örneği birden çok istemciyle kullanılabilir.

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

Önemli kavramlar

KeyVaultRoleDefinition

A KeyVaultRoleDefinition , bir izin koleksiyonudur. Rol tanımı okuma, yazma ve silme gibi gerçekleştirilebilecek işlemleri tanımlar. İzin verilen işlemlerin dışında tutulan işlemleri de tanımlayabilir.

KeyVaultRoleDefinitions bir KeyVaultRoleAssignmentöğesinin parçası olarak listelenebilir ve belirtilebilir.

KeyVaultRoleAssignment

A KeyVaultRoleAssignment , KeyVaultRoleDefinition öğesinin hizmet sorumlusuyla ilişkisidir. Bunlar oluşturulabilir, listelenebilir, tek tek getirilebilir ve silinebilir.

KeyVaultAccessControlClient

AKeyVaultAccessControlClient, ve KeyVaultRoleAssignment nesnelerinin yönetimine KeyVaultRoleDefinition olanak sağlayan hem zaman uyumlu hem de zaman uyumsuz işlemler sağlar.

KeyVaultBackupClient

A KeyVaultBackupClient , tam anahtar yedeklemeleri, tam anahtar geri yüklemeleri ve seçmeli anahtar geri yüklemeleri gerçekleştirmek için hem zaman uyumlu hem de zaman uyumsuz işlemler sağlar.

BackupOperation

A BackupOperation , tam anahtar yedeklemesi için uzun süre çalışan bir işlemi temsil eder.

RestoreOperation

A RestoreOperation , hem tam anahtar hem de seçmeli anahtar geri yükleme için uzun süre çalışan bir işlemi temsil eder.

İş 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şleme Tanılama | Alaycı | İstemci ömrü

Örnekler

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

Aşağıdaki bölümde, erişim denetimi veya yedekleme istemcileri için yukarıda oluşturulan kullanılarak, en yaygın Azure Key Vault erişim denetimiyle ilgili görevlerden bazılarını kapsayan çeşitli kod parçacıkları client sağlanır:

Eşitleme örnekleri

• Erişim denetimi
  • Tüm Rol Tanımlarını Listeleme
  • Tüm Rol Atamalarını Listeleme
  • Rol Ataması Oluşturma
  • Rol Ataması Alma
  • Rol Ataması Silme
• Yedekleme ve geri yükleme
  • Tam anahtar yedeklemesi gerçekleştirme
  • Tam anahtar geri yükleme gerçekleştirme

Zaman uyumsuz örnekler

• Erişim denetimi
  • Tüm Rol Tanımlarını Listeleme
  • Tüm Rol Atamalarını Listeleme
  • Rol Ataması Oluşturma
  • Rol Ataması Alma
  • Rol Ataması Silme
• Yedekleme ve geri yükleme
  • Tam anahtar yedeklemesi gerçekleştirme
  • Tam anahtar geri yükleme gerçekleştirme

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 Yönetim kitaplığıyla etkileşimde bulunursanız, 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 rol atamasını almaya çalışırsanız, "Bulunamadı" hatasını gösteren bir 404 hata döndürülür.

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

Konsol günlüğünü ayarlama

Günlükleri görmenin en basit yolu konsol günlüğünü etkinleştirmektir. Konsola ileti çıkışı veren bir Azure SDK günlük dinleyicisi oluşturmak için yöntemini kullanın AzureEventSourceListener.CreateConsoleLogger .

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

Diğer günlüğe kaydetme mekanizmaları hakkında daha fazla bilgi edinmek için buraya bakın.

Sonraki adımlar

Örneklerimizi kullanmaya başlayın.

Katkıda bulunma

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.

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ınız veya yorumlarınızla iletişime geçin opencode@microsoft.com .