AWS Encryption SDK for .NET

AWS Encryption SDK for .NET은 C# 및 기타 .NET 프로그래밍 언어로 애플리케이션을 작성하는 개발자를 위한 클라이언트측 암호화 라이브러리입니다. 이는 Windows, macOS, Linux에서 지원됩니다.

AWS Encryption SDK의 모든 프로그래밍 언어 구현은 완전히 상호 연동이 가능합니다. 하지만 AWS Encryption SDK for .NET의 버전 4.x 또는 AWS Encryption SDK for Java의 버전 3.x에서 필수 암호화 컨텍스트 CMM을 사용하여 데이터를 암호화하는 경우에는 AWS Encryption SDK for .NET의 버전 4.x에서만 복호화할 수 있습니다.

참고

AWS Encryption SDK for .NET의 버전 4.0.0은 AWS Encryption SDK 메시지 사양에서 벗어납니다. 따라서 버전 4.0.0으로 암호화된 메시지는 AWS Encryption SDK for .NET의 버전 4.0.0 이상에서만 복호화할 수 있으며, 다른 프로그래밍 언어 구현으로는 복호화할 수 없습니다.

AWS Encryption SDK for .NET의 버전 4.0.1은 AWS Encryption SDK 메시지 사양에 따라 메시지를 작성하며 다른 프로그래밍 언어 구현과 상호 운용할 수 있습니다. 기본적으로 버전 4.0.1은 버전 4.0.0으로 암호화된 메시지를 읽을 수 있습니다. 그러나 버전 4.0.0으로 암호화된 메시지를 복호화하지 않으려면 클라이언트가 이러한 메시지를 읽지 못하도록 NetV4_0_0_RetryPolicy 속성을 지정합니다. 자세한 내용은 GitHub의 aws-encryption-sdk-dafny 리포지토리에 있는 v4.0.1 릴리스 정보를 참조하세요.

AWS Encryption SDK for .NET은 다음과 같은 점에서 AWS Encryption SDK의 다른 프로그래밍 언어 구현과 다릅니다.

• 데이터 키 캐싱이 지원되지 않음

  참고

  AWS Encryption SDK for .NET의 버전 4.x는 대체 암호화 자료 캐싱 솔루션인 AWS KMS 계층적 키링을 지원합니다.

• 스트리밍 데이터가 지원되지 않음

• AWS Encryption SDK for .NET에서 로깅 또는 스택 추적이 없음

• AWS SDK for .NET이 필요함

AWS Encryption SDK for .NET에는 AWS Encryption SDK의 다른 언어 구현의 버전 2.0.x 이상에 도입된 모든 보안 기능이 포함되어 있습니다. 하지만 AWS Encryption SDK의 다른 언어 구현의 버전 2.0.x 이전에 암호화된 데이터를 복호화하기 위해 AWS Encryption SDK for .NET을 사용하는 경우 커밋 정책을 조정해야 할 수 있습니다. 자세한 내용은 커밋 정책 설정 방법을 참조하세요.

AWS Encryption SDK for .NET은 사양, 해당 사양 구현을 위한 코드 및 테스트용 증명을 작성하는 공식 검증 언어인 Dafny용 AWS Encryption SDK의 산물입니다. 그 결과, 기능적 정확성을 보장하는 프레임워크에서 AWS Encryption SDK의 기능을 구현하는 라이브러리가 탄생했습니다.

자세히 알아보기

• AWS Encryption SDK에서 옵션을 구성하는 방법(예: 대체 알고리즘 제품군 지정, 암호화된 데이터 키 제한, AWS KMS 다중 리전 키 사용)을 보여주는 예제는 AWS Encryption SDK 구성 섹션을 참조하세요.

• AWS Encryption SDK for .NET을 사용한 프로그래밍에 대한 자세한 내용은 GitHub의 aws-encryption-sdk-dafny 리포지토리의 aws-encryption-sdk-net 디렉터리를 참조하세요.

주제

• 설치 및 빌드
• 디버깅
• AWS KMS 키링
• 필수 암호화 컨텍스트 CMM
• 예제

AWS Encryption SDK for .NET 설치

AWS Encryption SDK for .NET은 NuGet에서 AWS.Cryptography.EncryptionSDK 패키지로 사용할 수 있습니다. AWS Encryption SDK for .NET 설치 및 빌드에 대한 자세한 내용은 aws-encryption-sdk-net 리포지토리의 README.md 파일을 참조하세요.

버전 3.x

AWS Encryption SDK for .NET 버전 3.x는 윈도우에서만 .NET Framework 4.5.2~4.8을 지원합니다. 지원되는 모든 운영 체제에서 .NET Core 3.0 이상 및 .NET 5.0 이상을 지원합니다.

버전 4.x

AWS Encryption SDK for .NET의 버전 4.x는 .NET 6.0 및 .NET Framework net48 이상을 지원합니다.

AWS Encryption SDK for .NET은 AWS Key Management Service(AWS KMS) 키를 사용하지 않는 경우에도 AWS SDK for .NET이 필요합니다. NuGet 패키지와 함께 설치됩니다. 그러나 AWS KMS 키를 사용하지 않는 한 AWS Encryption SDK for .NET에는 AWS 계정, AWS 보안 인증 또는 AWS 서비스와의 상호 작용이 필요하지 않습니다. AWS 계정을 설정하는 데 도움이 필요하면 AWS KMS에서 AWS Encryption SDK 사용 섹션을 참조하세요.

AWS Encryption SDK for .NET 디버깅

AWS Encryption SDK for .NET은 로그를 생성하지 않습니다. AWS Encryption SDK for .NET의 예외는 예외 메시지를 생성하지만 스택 추적은 생성하지 않습니다.

디버깅에 도움이 되도록 AWS SDK for .NET에서 로그인을 활성화해야 합니다. AWS SDK for .NET의 로그와 오류 메시지를 통해 AWS SDK for .NET for .NET에서 발생하는 오류와, AWS Encryption SDK for .NET에서 발생하는 오류를 구분할 수 있습니다. AWS SDK for .NET 로깅에 대한 도움이 필요하면 AWS SDK for .NET 개발자 가이드의 AWSLogging을 참조하세요. (이 주제를 보려면 .NET Framework 콘텐츠를 열어서 보기 섹션을 확장하세요.)

AWS Encryption SDK for .NET의 AWS KMS 키링

AWS Encryption SDK for .NET의 기본 AWS KMS 키링에는 KMS 키가 하나만 사용됩니다. 또한 KMS 키에 맞게 AWS 리전에 대한 클라이언트를 구성할 수 있는 AWS KMS 클라이언트가 필요합니다.

하나 이상의 래핑 키로 AWS KMS 키링을 생성하려면 다중 키링을 사용합니다. AWS Encryption SDK for .NET에는 하나 이상의 AWS KMS 키를 사용하는 특수 다중 키링과, 지원되는 유형의 키링을 하나 이상 사용하는 표준 다중 키링이 있습니다. 일부 프로그래머는 다중 키링 메서드를 사용하여 모든 키링을 만드는 것을 선호하며, AWS Encryption SDK for .NET은 이러한 전략을 지원합니다.

AWS Encryption SDK for .NET은 AWS KMS 다중 리전 키를 포함하여 모든 일반적인 사용 사례에 사용할 수 있는 기본 단일 키링 및 다중 키링을 제공합니다.

예를 들어, AWS KMS 키 하나로 AWS KMS 키링을 만들기 위해 CreateAwsKmsKeyring() 메서드를 사용할 수 있습니다.

Version 3.x

다음 예제에서는 AWS Encryption SDK for .NET의 버전 3.x를 사용하여 지정된 키가 포함된 리전의 기본 AWS KMS 클라이언트를 생성합니다.

// Instantiate the AWS Encryption SDK and material providers
var encryptionSdk = AwsEncryptionSdkFactory.CreateDefaultAwsEncryptionSdk();
var materialProviders =
    AwsCryptographicMaterialProvidersFactory.CreateDefaultAwsCryptographicMaterialProviders();

string keyArn = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";

// Instantiate the keyring input object
var kmsKeyringInput = new CreateAwsKmsKeyringInput
{
    KmsClient = new AmazonKeyManagementServiceClient(),
    KmsKeyId = keyArn
};

// Create the keyring
var keyring = materialProviders.CreateAwsKmsKeyring(kmsKeyringInput);

Version 4.x

다음 예제에서는 AWS Encryption SDK for .NET의 버전 4.x를 사용하여 지정된 키가 포함된 리전의 AWS KMS 클라이언트를 생성합니다.

// Instantiate the AWS Encryption SDK and material providers
var esdk =  new ESDK(new AwsEncryptionSdkConfig());
var mpl = new MaterialProviders(new MaterialProvidersConfig());

string keyArn = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";

// Instantiate the keyring input object
var createKeyringInput = new CreateAwsKmsKeyringInput
{
    KmsClient = new AmazonKeyManagementServiceClient(),
    KmsKeyId = kmsArn
};

// Create the keyring
var kmsKeyring = mpl.CreateAwsKmsKeyring(createKeyringInput);

하나 이상의 AWS KMS 키가 포함된 키링을 만들려면 CreateAwsKmsMultiKeyring() 메서드를 사용합니다. 이 예제에서는 두 개의 AWS KMS 키를 사용합니다. 한 개의 KMS 키를 지정하려면 Generator 파라미터만 사용합니다. 추가 KMS 키를 지정하는 KmsKeyIds 파라미터는 선택 사항입니다.

이 키링의 입력에는 AWS KMS 클라이언트를 사용하지 않습니다. 대신 AWS Encryption SDK는 키링의 KMS 키로 표시되는 각 리전의 기본 AWS KMS 클라이언트를 사용합니다. 예를 들어 Generator 파라미터의 값으로 식별되는 KMS 키가 미국 서부(오레곤) 리전(us-west-2) 에 있는 경우 AWS Encryption SDK는 us-west-2 리전의 기본 AWS KMS 클라이언트를 생성합니다. AWS KMS 클라이언트를 사용자 지정해야 하는 경우 CreateAwsKmsKeyring() 메서드를 사용합니다.

다음 예제에서는 AWS Encryption SDK for .NET의 버전 4.x와, AWS KMS 클라이언트를 사용자 지정하는 CreateAwsKmsKeyring() 메서드를 사용합니다.

// Instantiate the AWS Encryption SDK and material providers
var esdk =  new ESDK(new AwsEncryptionSdkConfig());
var mpl = new MaterialProviders(new MaterialProvidersConfig());

string generatorKey = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";
List<string> additionalKeys = new List<string> { "arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321" };

// Instantiate the keyring input object
var createEncryptKeyringInput = new CreateAwsKmsMultiKeyringInput
{
    Generator = generatorKey,
    KmsKeyIds = additionalKeys
};

var kmsEncryptKeyring = materialProviders.CreateAwsKmsMultiKeyring(createEncryptKeyringInput);

AWS Encryption SDK for .NET의 버전 4.x는 대칭 암호화(SYMMETRIC_DEFAULT) 또는 비대칭 RSA KMS 키를 사용하는 AWS KMS 키링을 지원합니다. 비대칭 RSA KMS 키로 만든 AWS KMS 키링은 하나의 키 페어만 포함할 수 있습니다.

비대칭 RSA AWS KMS 키링으로 암호화하려면 키링을 생성할 때 암호화에 사용할 퍼블릭 키 구성 요소를 지정해야 하기 때문에 KMS:GenerateDataKey 또는 kms:Encrypt가 필요하지 않습니다. 이 키링으로 암호화할 때는 AWS KMS 호출이 이루어지지 않습니다. 비대칭 RSA AWS KMS 키링으로 복호화하려면 kms:Decrypt 권한이 필요합니다.

비대칭 RSA AWS KMS 키링을 생성하려면 비대칭 RSA KMS 키에서 퍼블릭 키와 프라이빗 키 ARN을 제공해야 합니다. 퍼블릭 키는 PEM으로 인코딩되어야 합니다. 다음 예제에서는 비대칭 RSA 키 페어를 사용하여 AWS KMS 키링을 생성합니다.

// Instantiate the AWS Encryption SDK and material providers
var esdk =  new ESDK(new AwsEncryptionSdkConfig());
var mpl = new MaterialProviders(new MaterialProvidersConfig());
        
var publicKey = new MemoryStream(Encoding.UTF8.GetBytes(AWS KMS RSA public key));

// Instantiate the keyring input object
var createKeyringInput = new CreateAwsKmsRsaKeyringInput
{
    KmsClient = new AmazonKeyManagementServiceClient(),
    KmsKeyId = AWS KMS RSA private key ARN,
    PublicKey = publicKey,
    EncryptionAlgorithm = EncryptionAlgorithmSpec.RSAES_OAEP_SHA_256
};

// Create the keyring
var kmsRsaKeyring = mpl.CreateAwsKmsRsaKeyring(createKeyringInput);

버전 4.x의 필수 암호화 컨텍스트

AWS Encryption SDK for .NET의 버전 4.x에서는 필수 암호화 컨텍스트 CMM을 사용하여 암호화 작업에 암호화 컨텍스트를 요구할 수 있습니다. 암호화 컨텍스트는 비밀이 아닌 키-값 페어 세트입니다. 암호화 컨텍스트는 암호화된 데이터에 암호적으로 바인딩되므로 필드를 복호화하는 데 동일한 암호화 컨텍스트가 필요합니다. 필수 암호화 컨텍스트 CMM을 사용하는 경우 모든 암호화 및 복호화 호출에 포함되어야 하는 필수 암호화 컨텍스트 키(필수 키)를 하나 이상 지정할 수 있습니다.

참고

필수 암호화 컨텍스트 CMM은 AWS Encryption SDK for Java의 버전 3.x와만 상호 운용할 수 있으며, 다른 프로그래밍 언어 구현과는 상호 운용할 수 없습니다. 필수 암호화 컨텍스트 CMM을 사용하여 데이터를 암호화하는 경우 AWS Encryption SDK for Java의 버전 3.x 또는 AWS Encryption SDK for .NET의 버전 4.x에서만 복호화할 수 있습니다.

암호화 시, AWS Encryption SDK는 필요한 모든 암호화 컨텍스트 키가 지정된 암호화 컨텍스트에 포함되어 있는지 확인합니다. AWS Encryption SDK는 지정한 암호화 컨텍스트에 서명합니다. 필수 키가 아닌 키-값 페어만 직렬화되어, 암호화 작업에서 반환되는 암호화된 메시지의 헤더에 일반 텍스트로 저장됩니다.

복호화 시, 필수 키를 나타내는 모든 키-값 페어가 포함된 암호화 컨텍스트를 제공해야 합니다. AWS Encryption SDK에서는 이 암호화 컨텍스트와, 암호화된 메시지의 헤더에 저장된 키-값 페어를 사용하여 암호화 작업에서 지정한 원래 암호화 컨텍스트를 재구성합니다. AWS Encryption SDK에서 원래 암호화 컨텍스트를 재구성할 수 없는 경우 복호화 작업이 실패합니다. 필수 키가 포함된 키-값 페어에 잘못된 값을 입력하면 암호화된 메시지를 복호화할 수 없습니다. 암호화 시 지정한 것과 동일한 키-값 페어를 제공해야 합니다.

중요

암호화 컨텍스트에서 필수 키에 어떤 값을 선택할지 신중하게 고려하세요. 복호화 시 동일한 키와 해당 값을 다시 제공할 수 있어야 합니다. 필수 키를 재생성할 수 없는 경우 암호화된 메시지를 복호화할 수 없습니다.

다음 예제에서는 필수 암호화 컨텍스트 CMM을 사용하여 AWS KMS 키링을 초기화합니다.

var encryptionContext = new Dictionary<string, string>()
{
    {"encryption", "context"},
    {"is not", "secret"},
    {"but adds", "useful metadata"},
    {"that can help you", "be confident that"},
    {"the data you are handling", "is what you think it is"}
};

// Instantiate the AWS Encryption SDK and material providers
var esdk =  new ESDK(new AwsEncryptionSdkConfig());
var mpl = new MaterialProviders(new MaterialProvidersConfig());
        
// Instantiate the keyring input object
var createKeyringInput = new CreateAwsKmsKeyringInput
{
    KmsClient = new AmazonKeyManagementServiceClient(),
    KmsKeyId = kmsKey
};
 
// Create the keyring 
var kmsKeyring = mpl.CreateAwsKmsKeyring(createKeyringInput);
        
var createCMMInput = new CreateRequiredEncryptionContextCMMInput
{
    UnderlyingCMM = mpl.CreateDefaultCryptographicMaterialsManager(new CreateDefaultCryptographicMaterialsManagerInput{Keyring = kmsKeyring}),
    // If you pass in a keyring but no underlying cmm, it will result in a failure because only cmm is supported.
    RequiredEncryptionContextKeys = new List<string>(encryptionContext.Keys)
};
 
// Create the required encryption context CMM
var requiredEcCMM = mpl.CreateRequiredEncryptionContextCMM(createCMMInput);

AWS KMS 키링을 사용하는 경우 AWS Encryption SDK for .NET은 암호화 컨텍스트도 사용하여 AWS KMS에 대한 키링의 호출에서 추가 인증 데이터(AAD)를 제공합니다.