기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.
AWS Encryption SDK는 쉽게 사용할 수 있도록 설계되었습니다. AWS Encryption SDK에는 여러 구성 옵션이 있지만 기본값은 대부분의 애플리케이션에서 실용적이고 안전하도록 신중하게 선택되었습니다. 하지만 성능을 개선하거나 사용자 지정 기능을 포함하여 설계하려면 구성을 조정해야 할 수도 있습니다.
구현을 구성할 때는 AWS Encryption SDK 모범 사례를 검토하여 최대한 많이 구현하세요.
프로그래밍 언어 선택
AWS Encryption SDK는 여러 프로그래밍 언어에서 사용할 수 있습니다. 언어 구현은 서로 다른 방식으로 구현될 수 있지만 완전히 상호 연동되고 동일한 기능을 제공하도록 설계되었습니다. 일반적으로 애플리케이션과 호환되는 라이브러리를 사용합니다. 하지만 특정 구현을 위한 프로그래밍 언어를 선택할 수도 있습니다. 예를 들어 키링으로 작업하려는 경우 AWS Encryption SDK for C 또는 AWS Encryption SDK for JavaScript를 선택할 수 있습니다.
래핑 키 선택
AWS Encryption SDK는 고유한 대칭 데이터 키를 생성하여 각 메시지를 암호화합니다. 데이터 키 캐싱을 사용하지 않는 한 데이터 키를 구성하거나, 관리하거나 사용할 필요가 없습니다. AWS Encryption SDK가 이를 대신 처리합니다.
하지만 각 데이터 키를 암호화하려면 래핑 키를 하나 이상 선택해야 합니다. AWS Encryption SDK는 다양한 크기의 AES 대칭 키 및 RSA 비대칭 키를 지원합니다. 또한 AWS Key Management Service(AWS KMS) 대칭 암호화 AWS KMS keys도 지원합니다. 래핑 키의 안전성과 내구성에 대한 책임은 사용자에게 있으므로 하드웨어 보안 모듈이나 키 인프라 서비스(예: AWS KMS)에서 암호화 키를 사용하는 것이 좋습니다.
암호화 및 복호화를 위한 래핑 키를 지정하려면 키링(C, JavaScript) 또는 마스터 키 공급자(Java, Python, AWS Encryption CLI)를 사용합니다. 하나의 래핑 키를 지정하거나, 같거나 다른 유형의 여러 래핑 키를 지정할 수 있습니다. 여러 래핑 키를 사용하여 데이터 키를 래핑하는 경우 각 래핑 키는 동일한 데이터 키의 사본을 암호화합니다. 암호화된 데이터 키(래핑 키당 하나)는 AWS Encryption SDK가 반환하는 암호화된 메시지에 암호화된 데이터와 함께 저장됩니다. 해당 데이터를 복호화하려면 먼저 AWS Encryption SDK가 래핑 키 중 하나를 사용하여 암호화된 데이터 키를 복호화해야 합니다.
키링 또는 마스터 키 공급자에서 AWS KMS key를 지정하려면 지원되는 AWS KMS 키 식별자를 사용합니다. AWS KMS 키 식별자에 대한 자세한 내용은 AWS Key Management Service 개발자 가이드의 키 식별자를 참조하세요.
-
AWS Encryption SDK for Java, AWS Encryption SDK for JavaScript, AWS Encryption SDK for Python, 또는 AWS Encryption CLI로 암호화하는 경우 KMS 키에 유효한 키 식별자(키 ID, 키 ARN, 별칭 이름 또는 별칭 ARN)를 사용할 수 있습니다. AWS Encryption SDK for C로 암호화할 때는 키 ID 또는 키 ARN만 사용할 수 있습니다.
암호화할 때 KMS 키의 별칭 이름 또는 별칭 ARN을 지정하면 AWS Encryption SDK는 해당 별칭과 현재 연결된 키 ARN을 저장하지만 별칭은 저장하지 않습니다. 별칭을 변경해도 데이터 키를 복호화하는 데 사용되는 KMS 키에는 영향을 주지 않습니다.
-
엄격 모드(특정 래핑 키를 지정하는 경우)에서 복호화할 때는 키 ARN을 사용하여 AWS KMS keys를 식별해야 합니다. 이 요구 사항은 AWS Encryption SDK의 모든 언어 구현에 적용됩니다.
AWS KMS 키링으로 암호화하는 경우 AWS Encryption SDK는 암호화된 데이터 키의 메타데이터에 AWS KMS key의 키 ARN을 저장합니다. 엄격 모드에서 복호화하는 경우 AWS Encryption SDK는 래핑 키를 사용하여 암호화된 데이터 키 복호화를 시도하기 전에 동일한 키 ARN이 키링(또는 마스터 키 공급자)에 나타나는지 확인합니다. 다른 키 식별자를 사용하는 경우 AWS Encryption SDK는 식별자가 동일한 키를 참조하더라도 AWS KMS key를 인식하거나 사용하지 않습니다.
원시 AES 키 또는 원시 RSA 키 페어를 키링의 래핑 키로 지정하려면 네임스페이스와 이름을 지정해야 합니다. 마스터 키 공급자에서 Provider
ID는 네임스페이스에 해당하고 Key ID는 이름에 해당합니다. 복호화할 때는 암호화할 때 사용한 것과 정확히 동일한 네임스페이스와 이름을 각 원시 래핑 키에 사용해야 합니다. 다른 네임스페이스나 이름을 사용하면 키 구성 요소가 동일하더라도 AWS Encryption SDK가 래핑 키를 인식하지 못하거나 사용하지 않습니다.
다중 리전 AWS KMS keys 사용
AWS Encryption SDK에서 AWS Key Management Service(AWS KMS) 다중 리전 키를 래핑 키로 사용할 수 있습니다. 하나의 AWS 리전에서 다중 리전 키를 사용하여 암호화한 경우 다른 AWS 리전에서 관련 다중 리전 키를 사용하여 복호화할 수 있습니다. 다중 리전 키 지원은 AWS Encryption SDK 버전 2.3.x 및 AWS Encryption CLI 버전 3.0.x에 도입되었습니다.
AWS KMS 다중 리전 키는 서로 다른 AWS 리전에 있는 AWS KMS keys의 집합이며 동일한 키 구성 요소와 키 ID를 가지고 있습니다. 이러한 관련 키를 다른 리전에서 마치 동일한 키인 것처럼 사용할 수 있습니다. 다중 리전 키는 AWS KMS에 리전 간 호출을 하지 않고도 한 리전에서 암호화하고 다른 리전에서 복호화해야 하는 일반적인 재해 복구 및 백업 시나리오를 지원합니다. 다중 리전 키에 대한 자세한 내용은 AWS Key Management Service 개발자 가이드의 다중 리전 키 사용을 참조하세요.
다중 리전 키를 지원하기 위해 AWS Encryption SDK에는 AWS KMS 다중 리전 인식 키링과 마스터 키 공급자가 포함되어 있습니다. 각 프로그래밍 언어의 새로운 다중 리전 인식 기호는 단일 리전 키와 다중 리전 키를 모두 지원합니다.
-
단일 리전 키의 경우 다중 리전 인식 기호는 단일 리전 AWS KMS 키링 및 마스터 키 공급자처럼 작동합니다. 데이터를 암호화한 단일 리전 키로만 사이퍼텍스트 복호화를 시도합니다.
-
다중 리전 키의 경우 다중 리전 인식 기호는 데이터를 암호화한 것과 동일한 다중 리전 키 또는 사용자가 지정한 리전의 관련 다중 리전 키를 사용하여 사이퍼텍스트를 복호화하려고 시도합니다.
KMS 키를 두 개 이상 사용하는 다중 리전 인식 키링 및 마스터 키 공급자에서는 단일 리전 및 다중 리전 키를 여러 개 지정할 수 있습니다. 그러나 관련 다중 리전 키의 각 집합에서 하나의 키만 지정할 수 있습니다. 키 ID가 같은 키 식별자를 두 개 이상 지정하면 생성자 호출이 실패합니다.
표준 단일 리전 AWS KMS 키링 및 마스터 키 공급자와 함께 다중 리전 키를 사용할 수도 있습니다. 하지만 암호화하고 복호화하려면 동일한 리전에서 동일한 다중 리전 키를 사용해야 합니다. 단일 리전 키링 및 마스터 키 공급자는 데이터를 암호화한 키로만 사이퍼텍스트 복호화를 시도합니다.
다음 예제는 다중 리전 키와 새로운 다중 리전 인식 키링 및 마스터 키 공급자를 사용하여 데이터를 암호화하고 복호화하는 방법을 보여줍니다. 이 예제에서는 us-east-1 리전의 데이터를 암호화하고 각 리전의 관련 다중 리전 키를 사용하여 us-west-2 리전의 데이터를 복호화합니다. 이 예제를 실행하기 전에 예제 다중 리전 키 ARN을 AWS 계정의 유효한 값으로 바꿉니다.
- C
-
다중 리전 키로 암호화하려면 Aws::Cryptosdk::KmsMrkAwareSymmetricKeyring::Builder() 메서드를 사용하여 키링을 인스턴스화합니다. 다중 리전 키를 지정합니다.
이 간단한 예제에는 암호화 컨텍스트가 포함되어 있지 않습니다. C에서 암호화 컨텍스트를 사용하는 예제는 문자열 암호화 및 복호화 섹션을 참조하세요.
전체 예제를 보려면 GitHub의 AWS Encryption SDK for C 리포지토리에서 kms_multi_region_keys.cpp를 참조하세요.
/* Encrypt with a multi-Region KMS key in us-east-1 */
/* Load error strings for debugging */
aws_cryptosdk_load_error_strings();
/* Initialize a multi-Region keyring */
const char *mrk_us_east_1 = "arn:aws:kms:us-east-1:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab";
struct aws_cryptosdk_keyring *mrk_keyring =
Aws::Cryptosdk::KmsMrkAwareSymmetricKeyring::Builder().Build(mrk_us_east_1);
/* Create a session; release the keyring */
struct aws_cryptosdk_session *session =
aws_cryptosdk_session_new_from_keyring_2(aws_default_allocator(), AWS_CRYPTOSDK_ENCRYPT, mrk_keyring);
aws_cryptosdk_keyring_release(mrk_keyring);
/* Encrypt the data
* aws_cryptosdk_session_process_full is designed for non-streaming data
*/
aws_cryptosdk_session_process_full(
session, ciphertext, ciphertext_buf_sz, &ciphertext_len, plaintext, plaintext_len));
/* Clean up the session */
aws_cryptosdk_session_destroy(session);
- C# / .NET
-
미국 동부(버지니아 북부)(us-east-1) 리전에서 다중 리전 키를 사용하여 암호화하려면 다중 리전 키의 키 식별자와 지정된 리전의 AWS KMS 클라이언트를 사용하여 CreateAwsKmsMrkKeyringInput 객체를 인스턴스화합니다. 그런 다음 CreateAwsKmsMrkKeyring() 메서드를 사용하여 키링을 생성합니다.
CreateAwsKmsMrkKeyring() 메서드는 정확히 하나의 다중 리전 키로 키링을 생성합니다. 다중 리전 키를 비롯한 여러 래핑 키로 암호화하려면 CreateAwsKmsMrkMultiKeyring() 메서드를 사용합니다.
전체 예제를 보려면 GitHub의 AWS Encryption SDK for .NET 리포지토리에서 AwsKmsMrkKeyringExample.cs를 참조하세요.
//Encrypt with a multi-Region KMS key in us-east-1 Region
// Instantiate the AWS Encryption SDK and material providers
var encryptionSdk = AwsEncryptionSdkFactory.CreateDefaultAwsEncryptionSdk();
var materialProviders =
AwsCryptographicMaterialProvidersFactory.CreateDefaultAwsCryptographicMaterialProviders();
// Multi-Region keys have a distinctive key ID that begins with 'mrk'
// Specify a multi-Region key in us-east-1
string mrkUSEast1 = "arn:aws:kms:us-east-1:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab";
// Create the keyring
// You can specify the Region or get the Region from the key ARN
var createMrkEncryptKeyringInput = new CreateAwsKmsMrkKeyringInput
{
KmsClient = new AmazonKeyManagementServiceClient(RegionEndpoint.USEast1),
KmsKeyId = mrkUSEast1
};
var mrkEncryptKeyring = materialProviders.CreateAwsKmsMrkKeyring(createMrkEncryptKeyringInput);
// Define the encryption context
var encryptionContext = new Dictionary<string, string>()
{
{"purpose", "test"}
};
// Encrypt your plaintext data.
var encryptInput = new EncryptInput
{
Plaintext = plaintext,
Keyring = mrkEncryptKeyring,
EncryptionContext = encryptionContext
};
var encryptOutput = encryptionSdk.Encrypt(encryptInput);
- AWS Encryption CLI
-
이 예제에서는 us-east-1 리전의 다중 리전 키를 사용하여 hello.txt 파일을 암호화합니다. 이 예제에서는 리전 요소를 사용하여 키 ARN을 지정하므로 이 예제에서는 --wrapping-keys 파라미터의 region 속성을 사용하지 않습니다.
래핑 키의 키 ID가 리전을 지정하지 않는 경우 --wrapping-keys key=$keyID region=us-east-1과 같은 --wrapping-keys의 region 속성을 사용하여 리전을 지정할 수 있습니다.
# Encrypt with a multi-Region KMS key in us-east-1 Region
# To run this example, replace the fictitious key ARN with a valid value.
$ mrkUSEast1=arn:aws:kms:us-east-1:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab
$ aws-encryption-cli --encrypt \
--input hello.txt \
--wrapping-keys key=$mrkUSEast1 \
--metadata-output ~/metadata \
--encryption-context purpose=test \
--output .
- Java
-
다중 리전 키를 사용하여 암호화하려면 AwsKmsMrkAwareMasterKeyProvider를 인스턴스화하고 다중 리전 키를 지정합니다.
전체 예제는 GitHub의 AWS Encryption SDK for Java 리포지토리에서 BasicMultiRegionKeyEncryptionExample.java 섹션을 참조하세요.
//Encrypt with a multi-Region KMS key in us-east-1 Region
// Instantiate the client
final AwsCrypto crypto = AwsCrypto.builder()
.withCommitmentPolicy(CommitmentPolicy.RequireEncryptRequireDecrypt)
.build();
// Multi-Region keys have a distinctive key ID that begins with 'mrk'
// Specify a multi-Region key in us-east-1
final String mrkUSEast1 = "arn:aws:kms:us-east-1:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab";
// Instantiate an AWS KMS master key provider in strict mode for multi-Region keys
// Configure it to encrypt with the multi-Region key in us-east-1
final AwsKmsMrkAwareMasterKeyProvider kmsMrkProvider = AwsKmsMrkAwareMasterKeyProvider
.builder()
.buildStrict(mrkUSEast1);
// Create an encryption context
final Map<String, String> encryptionContext = Collections.singletonMap("Purpose", "Test");
// Encrypt your plaintext data
final CryptoResult<byte[], AwsKmsMrkAwareMasterKey> encryptResult = crypto.encryptData(
kmsMrkProvider,
encryptionContext,
sourcePlaintext);
byte[] ciphertext = encryptResult.getResult();
- JavaScript Browser
-
다중 리전 키로 암호화하려면 buildAwsKmsMrkAwareStrictMultiKeyringBrowser() 메서드를 사용하여 키링을 만들고 다중 리전 키를 지정합니다.
전체 예제를 보려면 GitHub의 AWS Encryption SDK for JavaScript 리포지토리에서 kms_multi_region_simple.ts를 참조하세요.
/* Encrypt with a multi-Region KMS key in us-east-1 Region */
import {
buildAwsKmsMrkAwareStrictMultiKeyringBrowser,
buildClient,
CommitmentPolicy,
KMS,
} from '@aws-crypto/client-browser'
/* Instantiate an AWS Encryption SDK client */
const { encrypt } = buildClient(
CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT
)
declare const credentials: {
accessKeyId: string
secretAccessKey: string
sessionToken: string
}
/* Instantiate an AWS KMS client
* The AWS Encryption SDK for JavaScript gets the Region from the key ARN
*/
const clientProvider = (region: string) => new KMS({ region, credentials })
/* Specify a multi-Region key in us-east-1 */
const multiRegionUsEastKey =
'arn:aws:kms:us-east-1:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab'
/* Instantiate the keyring */
const encryptKeyring = buildAwsKmsMrkAwareStrictMultiKeyringBrowser({
generatorKeyId: multiRegionUsEastKey,
clientProvider,
})
/* Set the encryption context */
const context = {
purpose: 'test',
}
/* Test data to encrypt */
const cleartext = new Uint8Array([1, 2, 3, 4, 5])
/* Encrypt the data */
const { result } = await encrypt(encryptKeyring, cleartext, {
encryptionContext: context,
})
- JavaScript Node.js
-
다중 리전 키로 암호화하려면 buildAwsKmsMrkAwareStrictMultiKeyringNode() 메서드를 사용하여 키링을 만들고 다중 리전 키를 지정합니다.
전체 예제를 보려면 GitHub의 AWS Encryption SDK for JavaScript 리포지토리에서 kms_multi_region_simple.ts를 참조하세요.
//Encrypt with a multi-Region KMS key in us-east-1 Region
import { buildClient } from '@aws-crypto/client-node'
/* Instantiate the AWS Encryption SDK client
const { encrypt } = buildClient(
CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT
)
/* Test string to encrypt */
const cleartext = 'asdf'
/* Multi-Region keys have a distinctive key ID that begins with 'mrk'
* Specify a multi-Region key in us-east-1
*/
const multiRegionUsEastKey =
'arn:aws:kms:us-east-1:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab'
/* Create an AWS KMS keyring */
const mrkEncryptKeyring = buildAwsKmsMrkAwareStrictMultiKeyringNode({
generatorKeyId: multiRegionUsEastKey,
})
/* Specify an encryption context */
const context = {
purpose: 'test',
}
/* Create an encryption keyring */
const { result } = await encrypt(mrkEncryptKeyring, cleartext, {
encryptionContext: context,
})
- Python
-
AWS KMS 다중 리전 키로 암호화하려면 MRKAwareStrictAwsKmsMasterKeyProvider() 메서드를 사용하여 다중 리전 키를 지정합니다.
전체 예제는 GitHub의 AWS Encryption SDK for Python 리포지토리에서 mrk_aware_kms_provider.py 섹션을 참조하세요.
* Encrypt with a multi-Region KMS key in us-east-1 Region
# Instantiate the client
client = aws_encryption_sdk.EncryptionSDKClient(commitment_policy=CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT)
# Specify a multi-Region key in us-east-1
mrk_us_east_1 = "arn:aws:kms:us-east-1:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab"
# Use the multi-Region method to create the master key provider
# in strict mode
strict_mrk_key_provider = MRKAwareStrictAwsKmsMasterKeyProvider(
key_ids=[mrk_us_east_1]
)
# Set the encryption context
encryption_context = {
"purpose": "test"
}
# Encrypt your plaintext data
ciphertext, encrypt_header = client.encrypt(
source=source_plaintext,
encryption_context=encryption_context,
key_provider=strict_mrk_key_provider
)
다음으로, 사이퍼텍스트를 us-west-2 리전으로 이동시킵니다. 사이퍼텍스트를 다시 암호화할 필요는 없습니다.
us-west-2 리전에서 엄격 모드로 사이퍼텍스트를 복호화하려면 us-west-2 리전에서 관련 다중 리전 키의 키 ARN을 사용하여 다중 리전 인식 기호를 인스턴스화합니다. 다른 리전(암호화된 us-east-1 포함)에 있는 관련 다중 리전 키의 키 ARN을 지정하면 다중 리전 인식 기호가 해당 AWS KMS key에 대하여 리전 간 호출을 수행합니다.
엄격 모드에서 복호화할 때 다중 리전 인식 기호에는 키 ARN이 필요합니다. 여기에서는 관련 다중 리전 키의 각 집합에서 하나의 키 ARN만 허용합니다.
이 예제를 실행하기 전에 예제 다중 리전 키 ARN을 AWS 계정의 유효한 값으로 바꿉니다.
- C
-
다중 리전 키를 사용하여 엄격 모드에서 복호화하려면 Aws::Cryptosdk::KmsMrkAwareSymmetricKeyring::Builder() 메서드를 사용하여 키링을 인스턴스화합니다. 로컬(us-west-2) 리전에서 관련 다중 리전 키를 지정합니다.
전체 예제를 보려면 GitHub의 AWS Encryption SDK for C 리포지토리에서 kms_multi_region_keys.cpp를 참조하세요.
/* Decrypt with a related multi-Region KMS key in us-west-2 Region */
/* Load error strings for debugging */
aws_cryptosdk_load_error_strings();
/* Initialize a multi-Region keyring */
const char *mrk_us_west_2 = "arn:aws:kms:us-west-2:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab";
struct aws_cryptosdk_keyring *mrk_keyring =
Aws::Cryptosdk::KmsMrkAwareSymmetricKeyring::Builder().Build(mrk_us_west_2);
/* Create a session; release the keyring */
struct aws_cryptosdk_session *session =
aws_cryptosdk_session_new_from_keyring_2(aws_default_allocator(), AWS_CRYPTOSDK_ENCRYPT, mrk_keyring);
aws_cryptosdk_session_set_commitment_policy(session,
COMMITMENT_POLICY_REQUIRE_ENCRYPT_REQUIRE_DECRYPT);
aws_cryptosdk_keyring_release(mrk_keyring);
/* Decrypt the ciphertext
* aws_cryptosdk_session_process_full is designed for non-streaming data
*/
aws_cryptosdk_session_process_full(
session, plaintext, plaintext_buf_sz, &plaintext_len, ciphertext, ciphertext_len));
/* Clean up the session */
aws_cryptosdk_session_destroy(session);
- C# / .NET
-
단일 다중 리전 키를 사용하여 엄격 모드에서 복호화하려면 입력을 결합하는 데 사용하고 암호화를 위한 키링을 만드는 데 사용한 것과 동일한 생성자와 메서드를 사용합니다. 관련 다중 리전 키의 키 ARN과 미국 서부(오레곤)(us-west-2) 리전의 AWS KMS 클라이언트를 사용하여 CreateAwsKmsMrkKeyringInput 객체를 인스턴스화합니다. 그런 다음 CreateAwsKmsMrkKeyring() 메서드를 사용하여 하나의 다중 리전 KMS 키로 다중 리전 키링을 생성합니다.
전체 예제를 보려면 GitHub의 AWS Encryption SDK for .NET 리포지토리에서 AwsKmsMrkKeyringExample.cs를 참조하세요.
// Decrypt with a related multi-Region KMS key in us-west-2 Region
// Instantiate the AWS Encryption SDK and material providers
var encryptionSdk = AwsEncryptionSdkFactory.CreateDefaultAwsEncryptionSdk();
var materialProviders =
AwsCryptographicMaterialProvidersFactory.CreateDefaultAwsCryptographicMaterialProviders();
// Specify the key ARN of the multi-Region key in us-west-2
string mrkUSWest2 = "arn:aws:kms:us-west-2:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab";
// Instantiate the keyring input
// You can specify the Region or get the Region from the key ARN
var createMrkDecryptKeyringInput = new CreateAwsKmsMrkKeyringInput
{
KmsClient = new AmazonKeyManagementServiceClient(RegionEndpoint.USWest2),
KmsKeyId = mrkUSWest2
};
// Create the multi-Region keyring
var mrkDecryptKeyring = materialProviders.CreateAwsKmsMrkKeyring(createMrkDecryptKeyringInput);
// Decrypt the ciphertext
var decryptInput = new DecryptInput
{
Ciphertext = ciphertext,
Keyring = mrkDecryptKeyring
};
var decryptOutput = encryptionSdk.Decrypt(decryptInput);
- AWS Encryption CLI
-
us-west-2 리전에서 관련 다중 리전 키를 사용하여 복호화하려면 --wrapping-keys 파라미터의 key 속성을 사용하여 키 ARN을 지정합니다.
# Decrypt with a related multi-Region KMS key in us-west-2 Region
# To run this example, replace the fictitious key ARN with a valid value.
$ mrkUSWest2=arn:aws:kms:us-west-2:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab
$ aws-encryption-cli --decrypt \
--input hello.txt.encrypted \
--wrapping-keys key=$mrkUSWest2 \
--commitment-policy require-encrypt-require-decrypt \
--encryption-context purpose=test \
--metadata-output ~/metadata \
--max-encrypted-data-keys 1 \
--buffer \
--output .
- Java
-
엄격 모드에서 복호화하려면 AwsKmsMrkAwareMasterKeyProvider를 인스턴스화하고 로컬(us-west-2) 리전에서 관련 다중 리전 키를 지정합니다.
전체 예제를 보려면 GitHub의 AWS Encryption SDK for Java 리포지토리에서 BasicMultiRegionKeyEncryptionExample.java를 참조하세요.
// Decrypt with a related multi-Region KMS key in us-west-2 Region
// Instantiate the client
final AwsCrypto crypto = AwsCrypto.builder()
.withCommitmentPolicy(CommitmentPolicy.RequireEncryptRequireDecrypt)
.build();
// Related multi-Region keys have the same key ID. Their key ARNs differs only in the Region field.
String mrkUSWest2 = "arn:aws:kms:us-west-2:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab";
// Use the multi-Region method to create the master key provider
// in strict mode
AwsKmsMrkAwareMasterKeyProvider kmsMrkProvider = AwsKmsMrkAwareMasterKeyProvider.builder()
.buildStrict(mrkUSWest2);
// Decrypt your ciphertext
CryptoResult<byte[], AwsKmsMrkAwareMasterKey> decryptResult = crypto.decryptData(
kmsMrkProvider,
ciphertext);
byte[] decrypted = decryptResult.getResult();
- JavaScript Browser
-
엄격 모드에서 복호화하려면 buildAwsKmsMrkAwareStrictMultiKeyringBrowser() 메서드를 사용하여 키링을 만들고 로컬(us-west-2) 리전에서 관련 다중 리전 키를 지정합니다.
전체 예제를 보려면 GitHub의 AWS Encryption SDK for JavaScript 리포지토리에서 kms_multi_region_simple.ts를 참조하세요.
/* Decrypt with a related multi-Region KMS key in us-west-2 Region */
import {
buildAwsKmsMrkAwareStrictMultiKeyringBrowser,
buildClient,
CommitmentPolicy,
KMS,
} from '@aws-crypto/client-browser'
/* Instantiate an AWS Encryption SDK client */
const { decrypt } = buildClient(
CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT
)
declare const credentials: {
accessKeyId: string
secretAccessKey: string
sessionToken: string
}
/* Instantiate an AWS KMS client
* The AWS Encryption SDK for JavaScript gets the Region from the key ARN
*/
const clientProvider = (region: string) => new KMS({ region, credentials })
/* Specify a multi-Region key in us-west-2 */
const multiRegionUsWestKey =
'arn:aws:kms:us-west-2:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab'
/* Instantiate the keyring */
const mrkDecryptKeyring = buildAwsKmsMrkAwareStrictMultiKeyringBrowser({
generatorKeyId: multiRegionUsWestKey,
clientProvider,
})
/* Decrypt the data */
const { plaintext, messageHeader } = await decrypt(mrkDecryptKeyring, result)
- JavaScript Node.js
-
엄격 모드에서 복호화하려면 buildAwsKmsMrkAwareStrictMultiKeyringNode() 메서드를 사용하여 키링을 만들고 로컬(us-west-2) 리전에서 관련 다중 리전 키를 지정합니다.
전체 예제를 보려면 GitHub의 AWS Encryption SDK for JavaScript 리포지토리에서 kms_multi_region_simple.ts를 참조하세요.
/* Decrypt with a related multi-Region KMS key in us-west-2 Region */
import { buildClient } from '@aws-crypto/client-node'
/* Instantiate the client
const { decrypt } = buildClient(
CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT
)
/* Multi-Region keys have a distinctive key ID that begins with 'mrk'
* Specify a multi-Region key in us-east-1
*/
const multiRegionUsWestKey =
'arn:aws:kms:us-west-2:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab'
/* Create an AWS KMS keyring */
const mrkDecryptKeyring = buildAwsKmsMrkAwareStrictMultiKeyringNode({
generatorKeyId: multiRegionUsWestKey,
})
/* Decrypt your ciphertext */
const { plaintext, messageHeader } = await decrypt(decryptKeyring, result)
- Python
-
엄격 모드에서 복호화하려면 MRKAwareStrictAwsKmsMasterKeyProvider() 메서드를 사용하여 마스터 키 공급자를 생성합니다. 로컬(us-west-2) 리전에서 관련 다중 리전 키를 지정합니다.
전체 예제는 GitHub의 AWS Encryption SDK for Python 리포지토리에서 mrk_aware_kms_provider.py 섹션을 참조하세요.
# Decrypt with a related multi-Region KMS key in us-west-2 Region
# Instantiate the client
client = aws_encryption_sdk.EncryptionSDKClient(commitment_policy=CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT)
# Related multi-Region keys have the same key ID. Their key ARNs differs only in the Region field
mrk_us_west_2 = "arn:aws:kms:us-west-2:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab"
# Use the multi-Region method to create the master key provider
# in strict mode
strict_mrk_key_provider = MRKAwareStrictAwsKmsMasterKeyProvider(
key_ids=[mrk_us_west_2]
)
# Decrypt your ciphertext
plaintext, _ = client.decrypt(
source=ciphertext,
key_provider=strict_mrk_key_provider
)
AWS KMS 다중 리전 키를 사용하여 검색 모드에서 복호화할 수도 있습니다. 검색 모드에서 복호화할 때는 어떤 AWS KMS keys도 지정하지 않습니다. (단일 리전 AWS KMS 검색 키링에 대한 자세한 내용은 AWS KMS 검색 키링 사용 섹션을 참조하세요.)
다중 리전 키로 암호화한 경우 검색 모드에서 다중 리전 인식 기호는 로컬 리전의 관련 다중 리전 키를 사용하여 복호화를 시도합니다. 존재하지 않는 경우 호출이 실패합니다. 검색 모드에서 AWS Encryption SDK는 암호화에 사용되는 다중 리전 키에 대하여 리전 간 호출을 시도하지 않습니다.
검색 모드에서 다중 리전 인식 기호를 사용하여 데이터를 암호화하는 경우 암호화 작업이 실패합니다.
다음 예제는 검색 모드에서 다중 리전 인식 기호를 사용하여 복호화하는 방법을 보여줍니다. AWS KMS key를 지정하지 않았기 때문에 AWS Encryption SDK는 다른 소스에서 리전을 가져와야 합니다. 가능하면 로컬 리전을 명시적으로 지정하세요. 그러지 않으면 AWS Encryption SDK는 사용자의 프로그래밍 언어의 AWS SDK에서 구성된 리전에서 로컬 리전을 가져옵니다.
이 예제를 실행하기 전에 예제 계정 ID와 다중 리전 키 ARN을 AWS 계정의 유효한 값으로 바꿉니다.
- C
-
다중 리전 키를 사용하여 검색 모드에서 복호화하려면 Aws::Cryptosdk::KmsMrkAwareSymmetricKeyring::Builder() 메서드를 사용하여 키링을 빌드하고 Aws::Cryptosdk::KmsKeyring::DiscoveryFilter::Builder() 메서드를 사용하여 검색 필터를 빌드합니다. 로컬 리전을 지정하려면 ClientConfiguration을 정의하고 AWS KMS 클라이언트에서 이를 지정합니다.
전체 예제를 보려면 GitHub의 AWS Encryption SDK for C 리포지토리에서 kms_multi_region_keys.cpp를 참조하세요.
/* Decrypt in discovery mode with a multi-Region KMS key */
/* Load error strings for debugging */
aws_cryptosdk_load_error_strings();
/* Construct a discovery filter for the account and partition. The
* filter is optional, but it's a best practice that we recommend.
*/
const char *account_id = "111122223333";
const char *partition = "aws";
const std::shared_ptr<Aws::Cryptosdk::KmsKeyring::DiscoveryFilter> discovery_filter =
Aws::Cryptosdk::KmsKeyring::DiscoveryFilter::Builder(partition).AddAccount(account_id).Build();
/* Create an AWS KMS client in the desired region. */
const char *region = "us-west-2";
Aws::Client::ClientConfiguration client_config;
client_config.region = region;
const std::shared_ptr<Aws::KMS::KMSClient> kms_client =
Aws::MakeShared<Aws::KMS::KMSClient>("AWS_SAMPLE_CODE", client_config);
struct aws_cryptosdk_keyring *mrk_keyring =
Aws::Cryptosdk::KmsMrkAwareSymmetricKeyring::Builder()
.WithKmsClient(kms_client)
.BuildDiscovery(region, discovery_filter);
/* Create a session; release the keyring */
struct aws_cryptosdk_session *session =
aws_cryptosdk_session_new_from_keyring_2(aws_default_allocator(), AWS_CRYPTOSDK_DECRYPT, mrk_keyring);
aws_cryptosdk_keyring_release(mrk_keyring);
commitment_policy=CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT
/* Decrypt the ciphertext
* aws_cryptosdk_session_process_full is designed for non-streaming data
*/
aws_cryptosdk_session_process_full(
session, plaintext, plaintext_buf_sz, &plaintext_len, ciphertext, ciphertext_len));
/* Clean up the session */
aws_cryptosdk_session_destroy(session);
- C# / .NET
AWS Encryption SDK for .NET에서 다중 리전 인식 검색 키링을 만들려면 특정 AWS 리전에 대한 AWS KMS 클라이언트를 사용하는 CreateAwsKmsMrkDiscoveryKeyringInput 객체를 인스턴스화하고, KMS 키를 특정 AWS 파티션 및 계정으로 제한하는 선택 사항인 검색 필터를 인스턴스화합니다. 그런 다음 입력 객체로 CreateAwsKmsMrkDiscoveryKeyring() 메서드를 호출합니다. 전체 예제를 보려면 GitHub의 AWS Encryption SDK for .NET 리포지토리에서 AwsKmsMrkDiscoveryKeyringExample.cs를 참조하세요.
둘 이상의 AWS 리전에 대해 다중 리전 인식 검색 키링을 만들려면 CreateAwsKmsMrkDiscoveryMultiKeyring() 메서드를 사용하여 다중 키링을 만들거나, CreateAwsKmsMrkDiscoveryKeyring()을 사용하여 다중 리전 인식 검색 키링을 여러 개 만든 다음 CreateMultiKeyring() 메서드를 사용하여 하나의 다중 키링으로 결합합니다.
예제는 AwsKmsMrkDiscoveryMultiKeyringExample.cs를 참조하세요.
// Decrypt in discovery mode with a multi-Region KMS key
// Instantiate the AWS Encryption SDK and material providers
var encryptionSdk = AwsEncryptionSdkFactory.CreateDefaultAwsEncryptionSdk();
var materialProviders =
AwsCryptographicMaterialProvidersFactory.CreateDefaultAwsCryptographicMaterialProviders();
List<string> account = new List<string> { "111122223333" };
// Instantiate the discovery filter
DiscoveryFilter mrkDiscoveryFilter = new DiscoveryFilter()
{
AccountIds = account,
Partition = "aws"
}
// Create the keyring
var createMrkDiscoveryKeyringInput = new CreateAwsKmsMrkDiscoveryKeyringInput
{
KmsClient = new AmazonKeyManagementServiceClient(RegionEndpoint.USWest2),
DiscoveryFilter = mrkDiscoveryFilter
};
var mrkDiscoveryKeyring = materialProviders.CreateAwsKmsMrkDiscoveryKeyring(createMrkDiscoveryKeyringInput);
// Decrypt the ciphertext
var decryptInput = new DecryptInput
{
Ciphertext = ciphertext,
Keyring = mrkDiscoveryKeyring
};
var decryptOutput = encryptionSdk.Decrypt(decryptInput);
- AWS Encryption CLI
-
검색 모드에서 복호화하려면 --wrapping-keys 파라미터의 discovery 속성을 사용합니다. discovery-account 및 discovery-partition 속성은 선택 사항이지만 권장되는 사항입니다.
리전을 지정하려면 이 명령에 --wrapping-keys 파라미터의 region 속성이 포함되어야 합니다.
# Decrypt in discovery mode with a multi-Region KMS key
$ aws-encryption-cli --decrypt \
--input hello.txt.encrypted \
--wrapping-keys discovery=true \
discovery-account=111122223333 \
discovery-partition=aws \
region=us-west-2 \
--encryption-context purpose=test \
--metadata-output ~/metadata \
--max-encrypted-data-keys 1 \
--buffer \
--output .
- Java
-
로컬 리전을 지정하려면 builder().withDiscoveryMrkRegion 파라미터를 사용합니다. 그러지 않으면 AWS Encryption SDK는 AWS SDK for Java에서 구성된 리전으로부터 로컬 리전을 가져옵니다.
전체 예제를 보려면 GitHub의 AWS Encryption SDK for Java 리포지토리에서 DiscoveryMultiRegionDecryptionExample.java를 참조하세요.
// Decrypt in discovery mode with a multi-Region KMS key
// Instantiate the client
final AwsCrypto crypto = AwsCrypto.builder()
.withCommitmentPolicy(CommitmentPolicy.RequireEncryptRequireDecrypt)
.build();
DiscoveryFilter discoveryFilter = new DiscoveryFilter("aws", 111122223333);
AwsKmsMrkAwareMasterKeyProvider mrkDiscoveryProvider = AwsKmsMrkAwareMasterKeyProvider
.builder()
.withDiscoveryMrkRegion(Region.US_WEST_2)
.buildDiscovery(discoveryFilter);
// Decrypt your ciphertext
final CryptoResult<byte[], AwsKmsMrkAwareMasterKey> decryptResult = crypto
.decryptData(mrkDiscoveryProvider, ciphertext);
- JavaScript Browser
-
대칭형 다중 리전 키를 사용하여 검색 모드에서 복호화하려면 AwsKmsMrkAwareSymmetricDiscoveryKeyringBrowser() 메서드를 사용합니다.
전체 예제를 보려면 GitHub의 AWS Encryption SDK for JavaScript 리포지토리에서 kms_multi_region_discovery.ts를 참조하세요.
/* Decrypt in discovery mode with a multi-Region KMS key */
import {
AwsKmsMrkAwareSymmetricDiscoveryKeyringBrowser,
buildClient,
CommitmentPolicy,
KMS,
} from '@aws-crypto/client-browser'
/* Instantiate an AWS Encryption SDK client */
const { decrypt } = buildClient()
declare const credentials: {
accessKeyId: string
secretAccessKey: string
sessionToken: string
}
/* Instantiate the KMS client with an explicit Region */
const client = new KMS({ region: 'us-west-2', credentials })
/* Create a discovery filter */
const discoveryFilter = { partition: 'aws', accountIDs: ['111122223333'] }
/* Create an AWS KMS discovery keyring */
const mrkDiscoveryKeyring = new AwsKmsMrkAwareSymmetricDiscoveryKeyringBrowser({
client,
discoveryFilter,
})
/* Decrypt the data */
const { plaintext, messageHeader } = await decrypt(mrkDiscoveryKeyring, ciphertext)
- JavaScript Node.js
-
대칭형 다중 리전 키를 사용하여 검색 모드에서 복호화하려면 AwsKmsMrkAwareSymmetricDiscoveryKeyringNode() 메서드를 사용합니다.
전체 예제를 보려면 GitHub의 AWS Encryption SDK for JavaScript 리포지토리에서 kms_multi_region_discovery.ts를 참조하세요.
/* Decrypt in discovery mode with a multi-Region KMS key */
import {
AwsKmsMrkAwareSymmetricDiscoveryKeyringNode,
buildClient,
CommitmentPolicy,
KMS,
} from '@aws-crypto/client-node'
/* Instantiate the Encryption SDK client
const { decrypt } = buildClient()
/* Instantiate the KMS client with an explicit Region */
const client = new KMS({ region: 'us-west-2' })
/* Create a discovery filter */
const discoveryFilter = { partition: 'aws', accountIDs: ['111122223333'] }
/* Create an AWS KMS discovery keyring */
const mrkDiscoveryKeyring = new AwsKmsMrkAwareSymmetricDiscoveryKeyringNode({
client,
discoveryFilter,
})
/* Decrypt your ciphertext */
const { plaintext, messageHeader } = await decrypt(mrkDiscoveryKeyring, result)
- Python
-
다중 리전 키를 사용하여 검색 모드에서 복호화하려면 MRKAwareDiscoveryAwsKmsMasterKeyProvider() 메서드를 사용합니다.
전체 예제는 GitHub의 AWS Encryption SDK for Python 리포지토리에서 mrk_aware_kms_provider.py 섹션을 참조하세요.
# Decrypt in discovery mode with a multi-Region KMS key
# Instantiate the client
client = aws_encryption_sdk.EncryptionSDKClient()
# Create the discovery filter and specify the region
decrypt_kwargs = dict(
discovery_filter=DiscoveryFilter(account_ids="111122223333", partition="aws"),
discovery_region="us-west-2",
)
# Use the multi-Region method to create the master key provider
# in discovery mode
mrk_discovery_key_provider = MRKAwareDiscoveryAwsKmsMasterKeyProvider(**decrypt_kwargs)
# Decrypt your ciphertext
plaintext, _ = client.decrypt(
source=ciphertext,
key_provider=mrk_discovery_key_provider
)
알고리즘 제품군 선택
AWS Encryption SDK는 사용자가 지정한 래핑 키로 데이터 키를 암호화하는 여러 대칭 및 비대칭 암호화 알고리즘을 지원합니다. 그러나 이러한 데이터 키를 사용하여 데이터를 암호화하는 경우, AWS Encryption SDK는 AES-GCM 알고리즘(키 유도, 디지털 서명, 키 커밋 포함)을 사용하는 권장 알고리즘 제품군을 기본값으로 사용합니다. 기본 알고리즘 제품군이 대부분의 애플리케이션에 적합할 가능성이 높지만 대체 알고리즘 제품군을 선택할 수도 있습니다. 예를 들어, 일부 신뢰 모델은 디지털 서명이 없는 알고리즘 제품군으로 충분할 수 있습니다. AWS Encryption SDK가 지원하는 알고리즘 제품군에 대한 자세한 내용은 AWS Encryption SDK에서 지원되는 알고리즘 제품군 섹션을 참조하세요.
다음 예제에서는 암호화 시 대체 알고리즘 제품군을 선택하는 방법을 보여줍니다. 이 예제에서는 키 유도 및 키 커밋은 있지만 디지털 서명은 없는 권장 AES-GCM 알고리즘 제품군을 선택합니다. 디지털 서명이 포함되지 않은 알고리즘 제품군으로 암호화하는 경우 복호화할 때 무서명 전용 복호화 모드를 사용합니다. 이 모드는 서명된 사이퍼텍스트가 발견되면 실패하는 모드로, 스트리밍 복호화 시 가장 유용합니다.
- C
-
AWS Encryption SDK for C에서 대체 알고리즘 제품군을 지정하려면 CMM을 명시적으로 만들어야 합니다. 그런 다음 aws_cryptosdk_default_cmm_set_alg_id를 CMM 및 선택한 알고리즘 제품군과 함께 사용합니다.
/* Specify an algorithm suite without signing */
/* Load error strings for debugging */
aws_cryptosdk_load_error_strings();
/* Construct an AWS KMS keyring */
struct aws_cryptosdk_keyring *kms_keyring = Aws::Cryptosdk::KmsKeyring::Builder().Build(key_arn);
/* To set an alternate algorithm suite, create an cryptographic
materials manager (CMM) explicitly
*/
struct aws_cryptosdk_cmm *cmm = aws_cryptosdk_default_cmm_new(aws_default_allocator(), kms_keyring);
aws_cryptosdk_keyring_release(kms_keyring);
/* Specify the algorithm suite for the CMM */
aws_cryptosdk_default_cmm_set_alg_id(cmm, ALG_AES256_GCM_HKDF_SHA512_COMMIT_KEY);
/* Construct the session with the CMM,
then release the CMM reference
*/
struct aws_cryptosdk_session *session = aws_cryptosdk_session_new_from_cmm_2(alloc, AWS_CRYPTOSDK_ENCRYPT, cmm);
aws_cryptosdk_cmm_release(cmm);
/* Encrypt the data
Use aws_cryptosdk_session_process_full with non-streaming data
*/
if (AWS_OP_SUCCESS != aws_cryptosdk_session_process_full(
session,
ciphertext,
ciphertext_buf_sz,
&ciphertext_len,
plaintext,
plaintext_len)) {
aws_cryptosdk_session_destroy(session);
return AWS_OP_ERR;
}
디지털 서명 없이 암호화된 데이터를 복호화할 때는 AWS_CRYPTOSDK_DECRYPT_UNSIGNED를 사용합니다. 그러면 서명된 사이퍼텍스트가 발견된 경우 복호화가 실패합니다.
/* Decrypt unsigned streaming data */
/* Load error strings for debugging */
aws_cryptosdk_load_error_strings();
/* Construct an AWS KMS keyring */
struct aws_cryptosdk_keyring *kms_keyring = Aws::Cryptosdk::KmsKeyring::Builder().Build(key_arn);
/* Create a session for decrypting with the AWS KMS keyring
Then release the keyring reference
*/
struct aws_cryptosdk_session *session =
aws_cryptosdk_session_new_from_keyring_2(alloc, AWS_CRYPTOSDK_DECRYPT_UNSIGNED, kms_keyring);
aws_cryptosdk_keyring_release(kms_keyring);
if (!session) {
return AWS_OP_ERR;
}
/* Limit encrypted data keys */
aws_cryptosdk_session_set_max_encrypted_data_keys(session, 1);
/* Decrypt
Use aws_cryptosdk_session_process_full with non-streaming data
*/
if (AWS_OP_SUCCESS != aws_cryptosdk_session_process_full(
session,
plaintext,
plaintext_buf_sz,
&plaintext_len,
ciphertext,
ciphertext_len)) {
aws_cryptosdk_session_destroy(session);
return AWS_OP_ERR;
}
- C# / .NET
-
AWS Encryption SDK for .NET에서 대체 알고리즘 제품군을 지정하려면 EncryptInput 객체의 AlgorithmSuiteId 속성을 지정합니다. AWS Encryption SDK for .NET에는 선호하는 알고리즘 제품군을 식별하는 데 사용할 수 있는 상수가 포함되어 있습니다.
이 라이브러리는 스트리밍 데이터를 지원하지 않기 때문에 AWS Encryption SDK for .NET에는 스트리밍 복호화 시 서명된 사이퍼텍스트를 탐지하는 메서드가 없습니다.
// Specify an algorithm suite without signing
// Instantiate the AWS Encryption SDK and material providers
var encryptionSdk = AwsEncryptionSdkFactory.CreateDefaultAwsEncryptionSdk();
var materialProviders =
AwsCryptographicMaterialProvidersFactory.CreateDefaultAwsCryptographicMaterialProviders();
// Create the keyring
var keyringInput = new CreateAwsKmsKeyringInput
{
KmsClient = new AmazonKeyManagementServiceClient(),
KmsKeyId = keyArn
};
var keyring = materialProviders.CreateAwsKmsKeyring(keyringInput);
// Encrypt your plaintext data
var encryptInput = new EncryptInput
{
Plaintext = plaintext,
Keyring = keyring,
AlgorithmSuiteId = AlgorithmSuiteId.ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY
};
var encryptOutput = encryptionSdk.Encrypt(encryptInput);
- AWS Encryption CLI
-
이 예제에서는 hello.txt 파일을 암호화할 때 --algorithm 파라미터를 사용하여 디지털 서명이 없는 알고리즘 제품군을 지정합니다.
# Specify an algorithm suite without signing
# To run this example, replace the fictitious key ARN with a valid value.
$ keyArn=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab
$ aws-encryption-cli --encrypt \
--input hello.txt \
--wrapping-keys key=$keyArn \
--algorithm AES_256_GCM_HKDF_SHA512_COMMIT_KEY \
--metadata-output ~/metadata \
--encryption-context purpose=test \
--commitment-policy require-encrypt-require-decrypt \
--output hello.txt.encrypted \
--decode
이 예제에서는 복호화할 때 --decrypt-unsigned 파라미터를 사용합니다. 이 파라미터는 특히 항상 입력과 출력을 스트리밍하는 CLI를 사용하여 서명되지 않은 사이퍼텍스트를 복호화할 때 사용하는 것이 좋습니다.
# Decrypt unsigned streaming data
# To run this example, replace the fictitious key ARN with a valid value.
$ keyArn=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab
$ aws-encryption-cli --decrypt-unsigned \
--input hello.txt.encrypted \
--wrapping-keys key=$keyArn \
--max-encrypted-data-keys 1 \
--commitment-policy require-encrypt-require-decrypt \
--encryption-context purpose=test \
--metadata-output ~/metadata \
--output .
- Java
-
대체 알고리즘 제품군을 지정하려면 AwsCrypto.builder().withEncryptionAlgorithm() 메서드를 사용합니다. 이 예제에서는 디지털 서명이 없는 대체 알고리즘 제품군을 지정합니다.
// Specify an algorithm suite without signing
// Instantiate the client
AwsCrypto crypto = AwsCrypto.builder()
.withCommitmentPolicy(CommitmentPolicy.RequireEncryptRequireDecrypt)
.withEncryptionAlgorithm(CryptoAlgorithm.ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY)
.build();
String awsKmsKey = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";
// Create a master key provider in strict mode
KmsMasterKeyProvider masterKeyProvider = KmsMasterKeyProvider.builder()
.buildStrict(awsKmsKey);
// Create an encryption context to identify this ciphertext
Map<String, String> encryptionContext = Collections.singletonMap("Example", "FileStreaming");
// Encrypt your plaintext data
CryptoResult<byte[], KmsMasterKey> encryptResult = crypto.encryptData(
masterKeyProvider,
sourcePlaintext,
encryptionContext);
byte[] ciphertext = encryptResult.getResult();
복호화를 위해 데이터를 스트리밍할 때는 createUnsignedMessageDecryptingStream() 메서드를 사용하여 복호화하는 모든 사이퍼텍스트가 서명되지 않았는지 확인합니다.
// Decrypt unsigned streaming data
// Instantiate the client
AwsCrypto crypto = AwsCrypto.builder()
.withCommitmentPolicy(CommitmentPolicy.RequireEncryptRequireDecrypt)
.withMaxEncryptedDataKeys(1)
.build();
// Create a master key provider in strict mode
String awsKmsKey = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";
KmsMasterKeyProvider masterKeyProvider = KmsMasterKeyProvider.builder()
.buildStrict(awsKmsKey);
// Decrypt the encrypted message
FileInputStream in = new FileInputStream(srcFile + ".encrypted");
CryptoInputStream<KmsMasterKey> decryptingStream = crypto.createUnsignedMessageDecryptingStream(masterKeyProvider, in);
// Return the plaintext data
// Write the plaintext data to disk
FileOutputStream out = new FileOutputStream(srcFile + ".decrypted");
IOUtils.copy(decryptingStream, out);
decryptingStream.close();
- JavaScript Browser
-
대체 알고리즘 제품군을 지정하려면 suiteId 파라미터를 AlgorithmSuiteIdentifier 열거형 값과 함께 사용합니다.
// Specify an algorithm suite without signing
// Instantiate the client
const { encrypt } = buildClient( CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT )
// Specify a KMS key
const generatorKeyId = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";
// Create a keyring with the KMS key
const keyring = new KmsKeyringBrowser({ generatorKeyId })
// Encrypt your plaintext data
const { result } = await encrypt(keyring, cleartext, { suiteId: AlgorithmSuiteIdentifier.ALG_AES256_GCM_IV12_TAG16_HKDF_SHA512_COMMIT_KEY, encryptionContext: context, })
복호화할 때는 표준 decrypt 메서드를 사용합니다. 브라우저가 스트리밍을 지원하지 않기 때문에 브라우저의 AWS Encryption SDK for JavaScript에는 decrypt-unsigned 모드가 없습니다.
// Decrypt unsigned streaming data
// Instantiate the client
const { decrypt } = buildClient( CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT )
// Create a keyring with the same KMS key used to encrypt
const generatorKeyId = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";
const keyring = new KmsKeyringBrowser({ generatorKeyId })
// Decrypt the encrypted message
const { plaintext, messageHeader } = await decrypt(keyring, ciphertextMessage)
- JavaScript Node.js
-
대체 알고리즘 제품군을 지정하려면 suiteId 파라미터를 AlgorithmSuiteIdentifier 열거형 값과 함께 사용합니다.
// Specify an algorithm suite without signing
// Instantiate the client
const { encrypt } = buildClient( CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT )
// Specify a KMS key
const generatorKeyId = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";
// Create a keyring with the KMS key
const keyring = new KmsKeyringNode({ generatorKeyId })
// Encrypt your plaintext data
const { result } = await encrypt(keyring, cleartext, { suiteId: AlgorithmSuiteIdentifier.ALG_AES256_GCM_IV12_TAG16_HKDF_SHA512_COMMIT_KEY, encryptionContext: context, })
디지털 서명 없이 암호화된 데이터를 복호화할 때는 decryptUnsignedMessageStream을 사용합니다. 서명된 사이퍼텍스트가 발견되면 이 메서드는 실패합니다.
// Decrypt unsigned streaming data
// Instantiate the client
const { decryptUnsignedMessageStream } = buildClient( CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT )
// Create a keyring with the same KMS key used to encrypt
const generatorKeyId = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";
const keyring = new KmsKeyringNode({ generatorKeyId })
// Decrypt the encrypted message
const outputStream = createReadStream(filename) .pipe(decryptUnsignedMessageStream(keyring))
- Python
-
대체 암호화 알고리즘을 지정하려면 algorithm 파라미터를 Algorithm 열거형 값과 함께 사용합니다.
# Specify an algorithm suite without signing
# Instantiate a client
client = aws_encryption_sdk.EncryptionSDKClient(commitment_policy=CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT,
max_encrypted_data_keys=1)
# Create a master key provider in strict mode
aws_kms_key = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"
aws_kms_strict_master_key_provider = StrictAwsKmsMasterKeyProvider(
key_ids=[aws_kms_key]
)
# Encrypt the plaintext using an alternate algorithm suite
ciphertext, encrypted_message_header = client.encrypt(
algorithm=Algorithm.AES_256_GCM_HKDF_SHA512_COMMIT_KEY, source=source_plaintext, key_provider=kms_key_provider
)
디지털 서명 없이 암호화된 메시지를 복호화할 때, 특히 스트리밍 중에 복호화할 때는 decrypt-unsigned 스트리밍 모드를 사용합니다.
# Decrypt unsigned streaming data
# Instantiate the client
client = aws_encryption_sdk.EncryptionSDKClient(commitment_policy=CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT,
max_encrypted_data_keys=1)
# Create a master key provider in strict mode
aws_kms_key = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"
aws_kms_strict_master_key_provider = StrictAwsKmsMasterKeyProvider(
key_ids=[aws_kms_key]
)
# Decrypt with decrypt-unsigned
with open(ciphertext_filename, "rb") as ciphertext, open(cycled_plaintext_filename, "wb") as plaintext:
with client.stream(mode="decrypt-unsigned",
source=ciphertext,
key_provider=master_key_provider) as decryptor:
for chunk in decryptor:
plaintext.write(chunk)
# Verify that the encryption context
assert all(
pair in decryptor.header.encryption_context.items() for pair in encryptor.header.encryption_context.items()
)
return ciphertext_filename, cycled_plaintext_filename
암호화된 데이터 키 제한
암호화된 메시지의 암호화된 데이터 키의 최대 수를 제한할 수 있습니다. 이 모범 사례 기능을 사용하면 암호화할 때 잘못 구성된 키링을 탐지하거나 복호화할 때 악성 사이퍼텍스트를 탐지할 수 있습니다. 이렇게 하면 키 인프라에 대하여 불필요하며 비용이 높고 잠재적으로 소모적인 호출 또한 방지합니다. 암호화된 데이터 키를 제한하는 것은 신뢰할 수 없는 소스의 메시지를 복호화할 때 가장 유용합니다.
대부분의 암호화된 메시지에는 암호화에 사용되는 래핑 키마다 암호화된 데이터 키가 하나씩 있지만 암호화된 메시지에는 최대 65,535개의 암호화된 데이터 키가 포함될 수 있습니다. 악의적인 공격자는 수천 개의 암호화된 데이터 키를 사용하여 암호화된 메시지를 구성할 수 있지만 이들 중 어느 것도 복호화될 수 없습니다. 그 결과 AWS Encryption SDK는 메시지의 암호화된 데이터 키가 모두 소진될 때까지 각각의 암호화된 데이터 키를 복호화하려고 시도합니다.
암호화된 데이터 키를 제한하려면 MaxEncryptedDataKeys 파라미터를 사용합니다. 이 파라미터는 AWS Encryption SDK 버전 1.9.x 및 2.2.x부터 지원되는 모든 프로그래밍 언어에서 사용할 수 있습니다. 이는 선택 사항이며 암호화 및 복호화 시 유효합니다. 다음 예제에서는 세 가지의 서로 다른 래핑 키로 암호화된 데이터를 복호화합니다. MaxEncryptedDataKeys 값은 3으로 설정되어 있습니다.
- C
-
/* Load error strings for debugging */
aws_cryptosdk_load_error_strings();
/* Construct an AWS KMS keyring */
struct aws_cryptosdk_keyring *kms_keyring =
Aws::Cryptosdk::KmsKeyring::Builder().Build(key_arn1, { key_arn2, key_arn3 });
/* Create a session */
struct aws_cryptosdk_session *session =
aws_cryptosdk_session_new_from_keyring_2(alloc, AWS_CRYPTOSDK_DECRYPT, kms_keyring);
aws_cryptosdk_keyring_release(kms_keyring);
/* Limit encrypted data keys */
aws_cryptosdk_session_set_max_encrypted_data_keys(session, 3);
/* Decrypt */
size_t ciphertext_consumed_output;
aws_cryptosdk_session_process(session,
plaintext_output,
plaintext_buf_sz_output,
&plaintext_len_output,
ciphertext_input,
ciphertext_len_input,
&ciphertext_consumed_output);
assert(aws_cryptosdk_session_is_done(session));
assert(ciphertext_consumed == ciphertext_len);
- C# / .NET
-
AWS Encryption SDK for .NET에서 암호화된 데이터 키를 제한하려면 AWS Encryption SDK for .NET의 클라이언트를 인스턴스화하고 선택 사항인 MaxEncryptedDataKeys 파라미터를 원하는 값으로 설정합니다. 그런 다음 구성된 AWS Encryption SDK 인스턴스에서 Decrypt() 메서드를 호출합니다.
// Decrypt with limited data keys
// Instantiate the material providers
var materialProviders =
AwsCryptographicMaterialProvidersFactory.CreateDefaultAwsCryptographicMaterialProviders();
// Configure the commitment policy on the AWS Encryption SDK instance
var config = new AwsEncryptionSdkConfig
{
MaxEncryptedDataKeys = 3
};
var encryptionSdk = AwsEncryptionSdkFactory.CreateAwsEncryptionSdk(config);
// Create the keyring
string keyArn = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";
var createKeyringInput = new CreateAwsKmsKeyringInput
{
KmsClient = new AmazonKeyManagementServiceClient(),
KmsKeyId = keyArn
};
var decryptKeyring = materialProviders.CreateAwsKmsKeyring(createKeyringInput);
// Decrypt the ciphertext
var decryptInput = new DecryptInput
{
Ciphertext = ciphertext,
Keyring = decryptKeyring
};
var decryptOutput = encryptionSdk.Decrypt(decryptInput);
- AWS Encryption CLI
-
# Decrypt with limited encrypted data keys
$ aws-encryption-cli --decrypt \
--input hello.txt.encrypted \
--wrapping-keys key=$key_arn1 key=$key_arn2 key=$key_arn3 \
--buffer \
--max-encrypted-data-keys 3 \
--encryption-context purpose=test \
--metadata-output ~/metadata \
--output .
- Java
-
// Construct a client with limited encrypted data keys
final AwsCrypto crypto = AwsCrypto.builder()
.withMaxEncryptedDataKeys(3)
.build();
// Create an AWS KMS master key provider
final KmsMasterKeyProvider keyProvider = KmsMasterKeyProvider.builder()
.buildStrict(keyArn1, keyArn2, keyArn3);
// Decrypt
final CryptoResult<byte[], KmsMasterKey> decryptResult = crypto.decryptData(keyProvider, ciphertext)
- JavaScript Browser
-
// Construct a client with limited encrypted data keys
const { encrypt, decrypt } = buildClient({ maxEncryptedDataKeys: 3 })
declare const credentials: {
accessKeyId: string
secretAccessKey: string
sessionToken: string
}
const clientProvider = getClient(KMS, {
credentials: { accessKeyId, secretAccessKey, sessionToken }
})
// Create an AWS KMS keyring
const keyring = new KmsKeyringBrowser({
clientProvider,
keyIds: [keyArn1, keyArn2, keyArn3],
})
// Decrypt
const { plaintext, messageHeader } = await decrypt(keyring, ciphertext)
- JavaScript Node.js
-
// Construct a client with limited encrypted data keys
const { encrypt, decrypt } = buildClient({ maxEncryptedDataKeys: 3 })
// Create an AWS KMS keyring
const keyring = new KmsKeyringBrowser({
keyIds: [keyArn1, keyArn2, keyArn3],
})
// Decrypt
const { plaintext, messageHeader } = await decrypt(keyring, ciphertext)
- Python
-
# Instantiate a client with limited encrypted data keys
client = aws_encryption_sdk.EncryptionSDKClient(max_encrypted_data_keys=3)
# Create an AWS KMS master key provider
master_key_provider = aws_encryption_sdk.StrictAwsKmsMasterKeyProvider(
key_ids=[key_arn1, key_arn2, key_arn3])
# Decrypt
plaintext, header = client.decrypt(source=ciphertext, key_provider=master_key_provider)
검색 필터 생성
KMS 키로 암호화된 데이터를 복호화할 때는 사용하는 래핑 키를 사용자가 지정한 키로만 제한하는 엄격 모드에서 복호화하는 것이 가장 좋습니다. 하지만 필요한 경우 래핑 키를 지정하지 않는 검색 모드에서 복호화할 수도 있습니다. 이 모드에서는 누가 해당 KMS 키를 소유하거나 액세스 권한이 있는지에 관계없이 AWS KMS가 암호화된 데이터 키를 암호화한 KMS 키를 사용하여 암호화된 데이터 키를 복호화할 수 있습니다.
검색 모드에서 복호화해야 하는 경우 항상 검색 필터를 사용하여 사용할 수 있는 KMS 키를 지정된 AWS 계정 및 파티션에 있는 키로 제한하는 것이 좋습니다. 검색 필터는 선택 사항이지만 모범 사례입니다.
다음 표를 사용하여 검색 필터의 파티션 값을 확인하세요.
| 리전 |
파티션 |
| AWS 리전 |
aws |
| 중국 리전 |
aws-cn |
| AWS GovCloud (US) Regions |
aws-us-gov |
이 섹션의 예제에서는 검색 필터를 만드는 방법을 보여줍니다. 코드를 사용하기 전에 예제 값을 AWS 계정 및 파티션에 유효한 값으로 바꿉니다.
- C
-
전체 예제는 AWS Encryption SDK for C의 kms_discovery.cpp를 참조하세요.
/* Create a discovery filter for an AWS account and partition */
const char *account_id = "111122223333";
const char *partition = "aws";
const std::shared_ptr<Aws::Cryptosdk::KmsKeyring::DiscoveryFilter> discovery_filter =
Aws::Cryptosdk::KmsKeyring::DiscoveryFilter::Builder(partition).AddAccount(account_id).Build();
- C# / .NET
-
전체 예제는 AWS Encryption SDK for .NET의 DiscoveryFilterExample.cs를 참조하세요.
// Create a discovery filter for an AWS account and partition
List<string> account = new List<string> { "111122223333" };
DiscoveryFilter exampleDiscoveryFilter = new DiscoveryFilter()
{
AccountIds = account,
Partition = "aws"
}
- AWS Encryption CLI
-
# Decrypt in discovery mode with a discovery filter
$ aws-encryption-cli --decrypt \
--input hello.txt.encrypted \
--wrapping-keys discovery=true \
discovery-account=111122223333 \
discovery-partition=aws \
--encryption-context purpose=test \
--metadata-output ~/metadata \
--max-encrypted-data-keys 1 \
--buffer \
--output .
- Java
-
전체 예제는 AWS Encryption SDK for Java의 DiscoveryDecryptionExample.java를 참조하세요.
// Create a discovery filter for an AWS account and partition
DiscoveryFilter discoveryFilter = new DiscoveryFilter("aws", 111122223333);
- JavaScript (Node and Browser)
-
전체 예제를 보려면 AWS Encryption SDK for JavaScript의 kms_filtered_discovery.ts(Node.js) 및 kms_multi_region_discovery.ts(브라우저)를 참조하세요.
/* Create a discovery filter for an AWS account and partition */
const discoveryFilter = {
accountIDs: ['111122223333'],
partition: 'aws',
}
- Python
-
전체 예제는 AWS Encryption SDK for Python의 discovery_kms_provider.py를 참조하세요.
# Create the discovery filter and specify the region
decrypt_kwargs = dict(
discovery_filter=DiscoveryFilter(account_ids="111122223333", partition="aws"),
discovery_region="us-west-2",
)
커밋 정책 설정
커밋 정책은 애플리케이션이 키 커밋을 사용하여 암호화 및 복호화할지 여부를 결정하는 구성 설정입니다. 키 커밋으로 데이터를 암호화하고 복호화하는 것이 AWS Encryption SDK 모범 사례입니다.
커밋 정책을 설정하고 조정하는 것은 AWS Encryption SDK 버전 1.7.x 이하에서 버전 2.0.x 이상으로 마이그레이션하기 위한 중요한 단계입니다. 이 진행 과정은 마이그레이션 주제에 자세히 설명되어 있습니다.
AWS Encryption SDK의 최신 버전(버전 2.0.x부터)의 기본 커밋 정책 값인 RequireEncryptRequireDecrypt는 대부분의 상황에 적합합니다. 하지만 키 커밋 없이 암호화된 사이퍼텍스트를 복호화해야 하는 경우에는 커밋 정책을 RequireEncryptAllowDecrypt로 변경해야 할 수도 있습니다. 각 프로그래밍 언어에서 커밋 정책을 설정하는 방법에 대한 예는 커밋 정책 설정 섹션을 참조하세요.
스트리밍 데이터로 작업
복호화를 위해 데이터를 스트리밍하는 경우 AWS Encryption SDK는 무결성 검사는 완료한 후지만 디지털 서명이 확인되기 전에 복호화된 일반 텍스트를 반환한다는 점에 유의하세요. 서명이 확인될 때까지 일반 텍스트를 반환하거나 사용하지 않도록 하려면 전체 복호화 프로세스가 완료될 때까지 스트리밍된 일반 텍스트를 버퍼링하는 것이 좋습니다.
이 문제는 복호화를 위해 사이퍼텍스트를 스트리밍하는 경우와, 디지털 서명이 포함된 알고리즘 제품군(예: 기본 알고리즘 제품군)을 사용하는 경우에만 발생합니다.
버퍼링을 더 쉽게 하기 위해 Node.js의 AWS Encryption SDK for JavaScript와 같은 일부 AWS Encryption SDK 언어 구현에는 복호화 메서드의 일부로 버퍼링 기능이 포함되어 있습니다. 항상 입력과 출력을 스트리밍하는 AWS Encryption CLI는 버전 1.9.x 및 2.2.x에 --buffer 파라미터를 도입했습니다. 다른 언어 구현에서는 기존의 버퍼링 기능을 사용할 수 있습니다. (AWS Encryption SDK for .NET은 스트리밍을 지원하지 않습니다.)
디지털 서명이 없는 알고리즘 제품군을 사용하는 경우 각 언어 구현에서 decrypt-unsigned 기능을 사용해야 합니다. 이 기능은 사이퍼텍스트를 복호화하지만 서명된 사이퍼텍스트를 발견하면 실패합니다. 자세한 내용은 알고리즘 제품군 선택 섹션을 참조하세요.
데이터 키 캐싱
일반적으로 데이터 키를 재사용하는 것은 권장되지 않지만 AWS Encryption SDK는 데이터 키를 제한적으로 재사용할 수 있는 데이터 키 캐싱 옵션을 제공합니다. 데이터 키 캐싱은 일부 애플리케이션의 성능을 향상시키고 키 인프라에 대한 호출을 줄일 수 있습니다. 프로덕션 환경에서 데이터 키 캐싱을 사용하기 전에 보안 임계값을 조정하고, 데이터 키 재사용의 이점이 단점보다 큰지 테스트하세요.
