Клиентская библиотека администрирования Azure KeyVault для .NET версии 4.3.0

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

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

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

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

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

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

dotnet add package Azure.Security.KeyVault.Administration

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

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

Чтобы создать управляемый ресурс 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, необходимо создать экземпляр клиентских классов, указанных ниже. Вам потребуется URL-адрес хранилища, который может отображаться как DNS-имя на портале, и учетные данные для создания экземпляра клиентского объекта.

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

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

dotnet add package Azure.Identity

Активация управляемого устройства 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-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

Управление доступом к управляемому устройству HSM

Назначенные администраторы, назначенные во время создания, автоматически добавляются во встроенную роль "Администраторы управляемых устройств HSM", которые могут скачивать домен безопасности и управлять ролями для доступа к плоскости данных, помимо других ограниченных разрешений.

Для выполнения других действий с ключами необходимо назначить субъектам другие роли, такие как "Управляемый пользователь шифрования HSM", которые могут выполнять неразрушающие операции с ключами:

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>

Ознакомьтесь с рекомендациями по обеспечению правильной защиты управляемого устройства HSM.

Создание KeyVaultAccessControlClient

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

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

Создание KeyVaultBackupClient

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

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

Создание KeyVaultSettingClient

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

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

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

KeyVaultRoleDefinition

— KeyVaultRoleDefinition это коллекция разрешений. Определение роли определяет операции, которые можно выполнять, такие как чтение, запись и удаление. Он также может определить операции, которые исключаются из разрешенных операций.

KeyVaultRoleDefinitions можно указать как часть KeyVaultRoleAssignment.

KeyVaultRoleAssignment

— KeyVaultRoleAssignment это связь KeyVaultRoleDefinition с субъектом-службой. Их можно создавать, перечислять, получать по отдельности и удалять.

KeyVaultAccessControlClient

Предоставляет KeyVaultAccessControlClient синхронные и асинхронные операции, позволяющие управлять объектами KeyVaultRoleDefinition и KeyVaultRoleAssignment .

KeyVaultBackupClient

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

BackupOperation

Представляет BackupOperation собой длительную операцию для полного резервного копирования ключа.

RestoreOperation

Представляет RestoreOperation собой долго выполняющуюся операцию как для полного ключа, так и для выборочного восстановления ключа.

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

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

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

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

Примеры

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

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

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

• Управление доступом
  • Перечисление всех определений ролей
  • Перечисление всех назначений ролей
  • Создание назначения ролей
  • Получение назначения роли
  • Удаление назначения ролей
• Резервное копирование и восстановление
  • Выполнение полного резервного копирования ключа
  • Выполнение полного восстановления ключа

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

• Управление доступом
  • Перечисление всех определений ролей
  • Перечисление всех назначений ролей
  • Создание назначения ролей
  • Получение назначения роли
  • Удаление назначения ролей
• Резервное копирование и восстановление
  • Выполнение полного резервного копирования ключа
  • Выполнение полного восстановления ключа

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

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

Общее

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

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

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

Настройка ведения журнала консоли

Самый простой способ просмотреть журналы — включить ведение журнала консоли. Чтобы создать прослушиватель журнала пакета AZURE SDK, который выводит сообщения в консоль, используйте AzureEventSourceListener.CreateConsoleLogger метод .

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

Дополнительные сведения о других механизмах ведения журнала см. здесь.

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

Начало работы с нашими примерами.

Участие

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

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