Клиентская библиотека ключей Azure Key Vault для .NET версии 4.5.0

Azure Key Vault — это облачная служба, которая обеспечивает безопасное хранение ключей для шифрования данных. В Key Vault Azure можно хранить несколько ключей и несколько версий одного ключа. Криптографические ключи в Azure Key Vault представлены в виде объектов веб-ключа JSON (JWK).

Управляемый модуль HSM Azure Key Vault — это полностью управляемая высокодоступная облачная служба с одним клиентом, соответствующая стандартам, которая позволяет защищать криптографические ключи для облачных приложений с помощью модулей HSM уровня 3, проверенных FIPS 140-2.

Клиент библиотеки ключей azure Key Vault поддерживает ключи RSA и ключи с эллиптической кривой (EC), каждый из которых поддерживает аппаратные модули безопасности (HSM). Он предлагает операции по созданию, извлечению, обновлению, удалению, очистке, резервному копированию, восстановлению и перечислению ключей и их версий.

Исходный код | Пакет (NuGet) | Справочная документация по | API Документация по продукту | Образцы | Руководство по миграции

Начало работы

Установка пакета

Установите клиентную библиотеку ключей Key Vault Azure для .NET с помощью NuGet:

dotnet add package Azure.Security.KeyVault.Keys

Предварительные требования

• Подписка Azure.
• Существующий Key Vault Azure. Если вам нужно создать Key Vault Azure, можно использовать портал Azure или Azure CLI.
• Авторизация в существующей Key Vault Azure с помощью RBAC (рекомендуется) или управления доступом.

Если вы создаете стандартный ресурс Key Vault, выполните следующую команду CLI, заменив <your-resource-group-name> и <your-key-vault-name> собственными уникальными именами:

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

Если вы создаете управляемый ресурс HSM, выполните следующую команду CLI:

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

Чтобы получить, <your-user-object-id> выполните следующую команду CLI:

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

Аутентификация клиента

Чтобы взаимодействовать со службой Azure Key Vault, необходимо создать экземпляр класса KeyClient. Вам потребуется URL-адрес хранилища, который может отображаться как DNS-имя на портале, и учетные данные для создания экземпляра клиентского объекта.

В приведенных ниже примерах используется DefaultAzureCredential, который подходит для большинства сценариев, включая локальные среды разработки и рабочие среды, использующие проверку подлинности с управляемым удостоверением. Кроме того, мы рекомендуем использовать управляемое удостоверение для проверки подлинности в рабочих средах. Дополнительные сведения о различных способах проверки подлинности и соответствующих типах учетных данных см. в документации по удостоверениям Azure .

Чтобы использовать поставщика, показанного DefaultAzureCredential ниже, или других поставщиков учетных данных, предоставляемых пакетом SDK для Azure, необходимо сначала установить пакет Azure.Identity:

dotnet add package Azure.Identity

Активация управляемого устройства HSM

Этот раздел применяется только при создании управляемого модуля HSM. Все команды плоскости данных неактивны до тех пор, пока не будет активировано устройство HSM. Вы не сможете создавать ключи или назначать роли. Только администраторы, назначенные во время выполнения команды создания, могут активировать HSM. Чтобы активировать модуль HSM, необходимо скачать домен безопасности.

Чтобы активировать необходимый модуль HSM, выполните следующие действия:

• получите минимум 3 пары ключей RSA (максимум 10);
• укажите минимальное число ключей, необходимых для расшифровки домена безопасности (кворум).

Чтобы активировать устройство HSM, отправьте в него по крайней мере 3 (максимум 10) открытых ключей RSA. HSM шифрует домен безопасности с помощью этих ключей и отправляет их обратно. После успешного скачивания этого домена безопасности модуль HSM будет готов к использованию. Также необходимо указать кворум, который является минимальным числом закрытых ключей, необходимых для расшифровки домена безопасности.

В приведенном ниже примере показано, как использовать openssl для создания трех самозаверяющих сертификатов.

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, чтобы скачать домен безопасности и активировать управляемое устройство HSM. В приведенном ниже примере используется 3 пары ключей RSA (для этой команды требуются только открытые ключи) и кворум имеет значение 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

Создание KeyClient

Создайте экземпляр для DefaultAzureCredential передачи клиенту. Один и тот же экземпляр учетных данных маркера можно использовать с несколькими клиентами, если они будут выполнять проверку подлинности с помощью одного удостоверения.

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

После создания KeyVaultKey в Key Vault Azure можно также создать 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);

Основные понятия

KeyVaultKey

Azure Key Vault поддерживает несколько типов ключей и алгоритмов, а также позволяет использовать аппаратные модули безопасности (HSM) для ключей с высокими значениями.

KeyClient

В пакете KeyClient SDK существует как синхронные, так и асинхронные операции, позволяющие выбрать клиент на основе варианта использования приложения. После инициализации KeyClientможно взаимодействовать с основными типами ресурсов в Azure Key Vault.

CryptographyClient

В пакете CryptographyClient SDK существует как синхронные, так и асинхронные операции, позволяющие выбрать клиент на основе варианта использования приложения. После инициализации CryptographyClientможно использовать его для выполнения криптографических операций с ключами, хранящимися в Azure Key Vault.

Потокобезопасность

Мы гарантируем, что все методы экземпляра клиента являются потокобезопасны и независимы друг от друга (руководство). Это гарантирует, что рекомендации по повторному использованию экземпляров клиента всегда будут безопасными, даже в разных потоках.

Дополнительные понятия

Параметры | клиента Доступ к ответу | Длительные операции | Обработка сбоев | Диагностики | Насмешливый | Время существования клиента

Примеры

Пакет Azure.Security.KeyVault.Keys поддерживает синхронные и асинхронные API.

В следующем разделе представлено несколько фрагментов кода с помощью созданногоclient выше кода, охватывающих некоторые из наиболее распространенных задач Azure Key Vault, связанных с ключевыми службами.

Примеры синхронизации

• Создание ключа
• Получение ключа
• Обновление существующего ключа
• Удаление ключа
• Удаление и очистка ключа
• получение списка ключей;
• Шифрование и расшифровка

Асинхронные примеры

• Асинхронное создание ключа
• Асинхронный вывод списка ключей
• Асинхронное удаление ключа

Создание ключа

Создайте ключ, который будет храниться в Key Vault Azure. Если ключ с таким же именем уже существует, создается новая версия ключа.

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

Получение ключа

GetKeyизвлекает ключ, ранее сохраненный в Key Vault Azure.

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

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

Обновление существующего ключа

UpdateKeyPropertiesобновляет ключ, ранее сохраненный в 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);

Удаление ключа

StartDeleteKeyзапускает длительную операцию удаления ключа, ранее хранящегося в Key Vault Azure. Ключ можно получить немедленно, не дожидаясь завершения операции. Если обратимое удаление не включено для Key Vault Azure, эта операция окончательно удаляет ключ.

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

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

Удаление и очистка ключа

Прежде чем пытаться очистить или восстановить ключ, необходимо дождаться завершения длительной операции.

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

Отображает ключи.

В этом примере перечислены все ключи в указанном Key Vault Azure.

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

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

Шифрование и расшифровка

В этом примере создается CryptographyClient и используется для шифрования и расшифровки с помощью ключа в 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);

Асинхронное создание ключа

Асинхронные API идентичны своим синхронным аналогам, но возвращаются с типичным суффиксом "Async" для асинхронных методов и возвращают задачу.

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

Асинхронный вывод списка ключей

Ключи для перечисления GetPropertiesOfKeysAsync не зависят от ожидания метода, но возвращают AsyncPageable<KeyProperties> объект , который можно использовать с инструкцией await foreach :

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

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

Асинхронное удаление ключа

При асинхронном удалении ключа перед его очисткой можно ожидать WaitForCompletionAsync выполнения метода в операции. По умолчанию этот цикл выполняется бесконечно, но его можно отменить, передав .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);

Устранение неполадок

Дополнительные сведения о диагностике различных сценариев сбоев см. в нашем руководстве по устранению неполадок .

Общее

При взаимодействии с клиентской библиотекой ключей Azure Key Vault с помощью пакета SDK для .NET ошибки, возвращаемые службой, соответствуют тем же кодам состояния HTTP, возвращенным для запросов REST API.

Например, при попытке получить ключ, который не существует в Key Vault Azure, возвращается ошибка с сообщением 404 "Не найдено".

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

Вы заметите, что в журнал записываются дополнительные сведения, например идентификатор запроса клиента операции.

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

Дальнейшие действия

В этом репозитории GitHub доступно несколько примеров клиентской библиотеки ключей Azure Key Vault. В этих примерах приведен пример кода для дополнительных сценариев, часто встречающихся при работе с Azure Key Vault:

• Sample1_HelloWorld.md — для работы с Key Vault Azure, в том числе:

  • Создание ключа
  • Получение существующего ключа
  • Обновление существующего ключа
  • Удаление ключа

• Sample2_BackupAndRestore.md — содержит фрагменты кода, работающие с ключами azure Key Vault, в том числе:

  • Резервное копирование и восстановление ключа

• Sample3_GetKeys.md — пример кода для работы с ключами Key Vault Azure, в том числе:

  • Создание ключей
  • Вывод списка всех ключей в Key Vault
  • Обновление ключей в Key Vault
  • Вывод списка версий указанного ключа
  • Удаление ключей из Key Vault
  • Вывод списка удаленных ключей в Key Vault

• Sample4_EncryptDecrypt.md — пример кода для выполнения криптографических операций с помощью ключей Key Vault Azure, в том числе:

  • Шифрование и расшифровка данных с помощью CryptographyClient

• Sample5_SignVerify.md — пример кода для работы с ключами Key Vault Azure, в том числе:

  • Подписывание предварительно вычисляемого дайджеста и проверка подписи с помощью подписи и проверки
  • Подпись необработанных данных и проверка подписи с помощью SignData и VerifyData

• Sample6_WrapUnwrap.md — пример кода для работы с ключами Key Vault Azure, в том числе:

  • Перенос и распаковка симметричного ключа

Дополнительная документация

• Более подробную документацию по azure Key Vault см. в справочной документации по API.
• Сведения о клиентской библиотеке секретов см. в разделе Клиентская библиотека секретов.
• Сведения о клиентской библиотеке сертификатов см. в разделе Клиентская библиотека сертификатов.

Участие

Дополнительные сведения о создании, тестировании и участии в этих библиотеках см. в CONTRIBUTING.md .

На этом проекте приветствуются публикации и предложения. Для участия в большинстве процессов по разработке документации необходимо принять лицензионное соглашение участника (CLA), в котором указывается, что вы предоставляете нам права на использование ваших публикаций. Для получения подробных сведений посетите веб-страницу https://cla.microsoft.com.

При отправке запроса на включение внесенных изменений CLA-бот автоматически определит необходимость предоставления соглашения CLA и соответствующего оформления запроса на включение внесенных изменений (например, добавление метки, комментария). Просто следуйте инструкциям бота. Будет достаточно выполнить их один раз для всех репозиториев, поддерживающих соглашение CLA.

В рамках этого проекта действуют правила поведения в отношении продуктов с открытым исходным кодом Майкрософт. Дополнительные сведения см. в разделе часто задаваемых вопросов о правилах поведения или обратитесь к opencode@microsoft.com с любыми дополнительными вопросами или комментариями.