.NET용 Azure KeyVault 관리 클라이언트 라이브러리 - 버전 4.3.0

Azure Key Vault 관리형 HSM은 FIPS 140-2 수준 3 유효성 검사 HSM을 사용하여 클라우드 애플리케이션에 대한 암호화 키를 보호할 수 있는 완전 관리형 고가용성 단일 테넌트 표준 규격 클라우드 서비스입니다.

Azure Key Vault 관리 라이브러리 클라이언트는 전체 백업/복원 및 RBAC(키 수준 역할 기반 액세스 제어)와 같은 관리 작업을 지원합니다.

소스 코드 | 패키지(NuGet) | 제품 설명서 | 샘플

시작

패키지 설치

NuGet을 사용하여 .NET용 Azure Key Vault 관리 클라이언트 라이브러리를 설치합니다.

dotnet add package Azure.Security.KeyVault.Administration

필수 구성 요소

• Azure 구독.
• 기존 Azure Key Vault. Azure Key Vault 만들어야 하는 경우 Azure CLI를 사용할 수 있습니다.
• RBAC(권장) 또는 액세스 제어를 사용하여 기존 Azure Key Vault 권한 부여

관리형 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 서비스와 상호 작용하려면 아래 클라이언트 클래스의 instance 만들어야 합니다. 포털에서 "DNS 이름"으로 표시할 수 있는 자격 증명 모음 URL과 클라이언트 개체를 인스턴스화하기 위한 자격 증명이 필요합니다.

아래에 표시된 예제에서는 로컬 개발 및 프로덕션 환경을 비롯한 대부분의 시나리오에 적합한 를 사용합니다 DefaultAzureCredential. 또한 프로덕션 환경에서 인증에 관리 ID를 사용하는 것이 좋습니다. Azure ID 설명서에서 다양한 인증 방법 및 해당 자격 증명 형식에 대한 자세한 정보를 찾을 수 있습니다.

아래에 표시된 공급자 또는 Azure SDK와 함께 제공되는 다른 자격 증명 공급자를 사용 DefaultAzureCredential 하려면 먼저 Azure.Identity 패키지를 설치해야 합니다.

dotnet add package Azure.Identity

관리형 HSM 활성화

HSM이 활성화되기 전까지는 모든 데이터 평면 명령이 비활성화됩니다. 키를 만들거나 역할을 할당할 수 없습니다. create 명령을 실행하는 동안 할당된 지정된 관리자만 HSM을 활성화할 수 있습니다. HSM을 활성화하려면 보안 도메인을 다운로드해야 합니다.

HSM을 활성화하려면 다음이 필요합니다.

• 최소 3개의 RSA 키 쌍(최대 10개)
• 보안 도메인 암호 해독에 필요한 최소 키 수 지정(쿼럼)

HSM을 활성화하려면 적어도 3개(최대 10개)의 RSA 공개 키를 HSM에 전송합니다. HSM은 이러한 키를 사용하여 보안 도메인을 암호화하고 다시 보냅니다. 이 보안 도메인이 성공적으로 다운로드되면 HSM을 사용할 준비가 된 것입니다. 또한 보안 도메인의 암호를 해독하는 데 필요한 최소 프라이빗 키 수인 쿼럼을 지정해야 합니다.

아래 예제에서는 openssl을 사용하여 3개의 자체 서명된 인증서를 생성하는 방법을 보여 줍니다.

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. 동일한 ID로 인증하는 경우 토큰 자격 증명의 동일한 instance 여러 클라이언트에서 사용할 수 있습니다.

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

KeyVaultBackupClient 만들기

에 전달하려면 를 DefaultAzureCredential 인스턴스화합니다 KeyVaultBackupClient. 동일한 ID로 인증하는 경우 토큰 자격 증명의 동일한 instance 여러 클라이언트에서 사용할 수 있습니다.

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

KeyVaultSettingClient 만들기

에 전달하려면 를 DefaultAzureCredential 인스턴스화합니다 KeyVaultSettingsClient. 동일한 ID로 인증하는 경우 토큰 자격 증명의 동일한 instance 여러 클라이언트에서 사용할 수 있습니다.

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

주요 개념

KeyVaultRoleDefinition

는 KeyVaultRoleDefinition 사용 권한의 컬렉션입니다. 역할 정의는 읽기, 쓰기 및 삭제와 같이 수행할 수 있는 작업을 정의합니다. 허용되는 작업에서 제외되는 작업을 정의할 수도 있습니다.

KeyVaultRoleDefinitions를 의 일부로 KeyVaultRoleAssignment나열하고 지정할 수 있습니다.

KeyVaultRoleAssignment

KeyVaultRoleAssignment 은 KeyVaultRoleDefinition과 서비스 주체의 연결입니다. 생성, 나열, 개별적으로 페치 및 삭제할 수 있습니다.

KeyVaultAccessControlClient

는 KeyVaultAccessControlClient 및 개체를 관리할 KeyVaultRoleDefinitionKeyVaultRoleAssignment 수 있도록 동기 및 비동기 작업을 모두 제공합니다.

KeyVaultBackupClient

는 KeyVaultBackupClient 전체 키 백업, 전체 키 복원 및 선택적 키 복원을 수행하기 위한 동기 및 비동기 작업을 모두 제공합니다.

BackupOperation

은 BackupOperation 전체 키 백업에 대한 장기 실행 작업을 나타냅니다.

RestoreOperation

은 RestoreOperation 전체 키 및 선택적 키 복원 모두에 대한 장기 실행 작업을 나타냅니다.

스레드로부터의 안전성

모든 클라이언트 instance 메서드는 스레드로부터 안전하고 서로 독립적임을 보장합니다(지침). 이렇게 하면 스레드 간에 클라이언트 인스턴스를 다시 사용하는 것이 항상 안전합니다.

추가 개념

클라이언트 옵션 | 응답 | 에 액세스 장기 실행 작업 | 오류 | 처리 진단 | 조롱 | 클라이언트 수명

예제

Azure.Security.KeyVault.Administration 패키지는 동기 및 비동기 API를 지원합니다.

다음 섹션에서는 액세스 제어 또는 백업 클라이언트에 대해 위에서 만든 을 사용하여 client 가장 일반적인 Azure Key Vault 액세스 제어 관련 작업을 다루는 몇 가지 코드 조각을 제공합니다.

동기화 예제

• Access Control
  • 모든 역할 정의 나열
  • 모든 역할 할당 나열
  • 역할 할당 만들기
  • 역할 할당 가져오기
  • 역할 할당 삭제
• 백업 및 복원
  • 전체 키 백업 수행
  • 전체 키 복원 수행

비동기 예제

• Access Control
  • 모든 역할 정의 나열
  • 모든 역할 할당 나열
  • 역할 할당 만들기
  • 역할 할당 가져오기
  • 역할 할당 삭제
• 백업 및 복원
  • 전체 키 백업 수행
  • 전체 키 복원 수행

문제 해결

다양한 오류 시나리오를 진단하는 방법에 대한 자세한 내용은 문제 해결 가이드 를 참조하세요.

일반

.NET SDK를 사용하여 Azure Key Vault 관리 라이브러리와 상호 작용하는 경우 서비스에서 반환되는 오류는 REST API 요청에 대해 반환된 동일한 HTTP 상태 코드에 해당합니다.

예를 들어 Azure Key Vault 존재하지 않는 역할 할당을 검색하려고 하면 "찾을 수 없음"을 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 을 참조하세요.

이 프로젝트는 Microsoft 오픈 소스 준수 사항을 채택했습니다. 자세한 내용은 Code of Conduct FAQ(규정 FAQ)를 참조하세요. 또는 추가 질문이나 의견은 opencode@microsoft.com으로 문의하세요.