기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.
# AWS Encryption SDK for C
는 C로 애플리케이션을 작성하는 개발자를 위한 클라이언트 측 암호화 라이브러리를 AWS Encryption SDK for C 제공합니다. 또한 AWS Encryption SDK 상위 수준 프로그래밍 언어로를 구현하기 위한 기반 역할을 합니다.
의 모든 구현과 마찬가지로 AWS Encryption SDK는 고급 데이터 보호 기능을 AWS Encryption SDK for C 제공합니다. 이러한 기능에는 [봉투 암호화](concepts.md#envelope-encryption), 추가 인증 데이터(AAD), 안전하고 인증된 대칭 키 [알고리즘 제품군](concepts.md#crypto-algorithm)(예: 키 유도 및 서명을 사용하는 256비트 AES-GCM)이 포함됩니다.
의 모든 언어별 구현 AWS Encryption SDK 은 완전히 상호 운용 가능합니다. 예를 들어,를 사용하여 데이터를 암호화 AWS Encryption SDK for C 하고 [AWS Encryption CLI](crypto-cli.md)를 포함하여 [지원되는 언어 구현](programming-languages.md)으로 데이터를 해독할 수 있습니다.
를 AWS Encryption SDK for C 사용하려면가 AWS Key Management Service ()와 상호 작용 AWS SDK for C\$1\$1 해야 합니다AWS KMS. 선택 사항인 [AWS KMS 키링](use-kms-keyring.md)을 사용하는 경우에만 이를 사용해야 합니다. 그러나 AWS Encryption SDK 에는 AWS KMS 또는 다른 AWS 서비스가 필요하지 않습니다.
**자세히 알아보기**
+ 를 사용한 프로그래밍에 대한 자세한 내용은 [C 예제](c-examples.md), GitHub[https://github.com/aws/aws-encryption-sdk-c/tree/master/examples](https://github.com/aws/aws-encryption-sdk-c/tree/master/examples)의 [aws-encryption-sdk-c 리포지토리](https://github.com/aws/aws-encryption-sdk-c/) 예제 및 [AWS Encryption SDK for C API 설명서를](https://aws.github.io/aws-encryption-sdk-c/html/) AWS Encryption SDK for C참조하세요.
+ 여러에서 데이터를 해독할 수 있도록 AWS Encryption SDK for C 를 사용하여 데이터를 암호화하는 방법에 대한 자세한 내용은 AWS 보안 블로그의 C에서를 사용하여 여러 리전의 사이퍼텍스트를 해독하는 방법을 AWS 리전참조하세요. [AWS Encryption SDK](https://aws.amazon.com/blogs/security/how-to-decrypt-ciphertexts-multiple-regions-aws-encryption-sdk-in-c/)
**Topics**
+ [설치](c-language-installation.md)
+ [C SDK 사용](c-language-using.md)
+ [예제](c-examples.md)
# 설치 AWS Encryption SDK for C
AWS Encryption SDK for C의 최신 버전을 설치합니다.
**참고**
2.0.0 AWS Encryption SDK for C 이전의 모든 버전은 [end-of-support 단계에](https://docs.aws.amazon.com/sdkref/latest/guide/maint-policy.html#version-life-cycle) 있습니다.
코드나 데이터를 변경하지 않고 버전 2.0.*x* 이상에서 AWS Encryption SDK for C 의 최신 버전으로 안전하게 업데이트할 수 있습니다. 그러나 버전 2.0.*x*에 도입된 [새로운 보안 기능](about-versions.md#version-2)은 이하 버전과 호환되지 않습니다. 1.7.*x* 이하 버전에서 2.0.*x* 이상 버전으로 업데이트하려면 먼저 AWS Encryption SDK for C의 최신 1.*x* 버전으로 업데이트해야 합니다. 자세한 내용은 [마이그레이션 AWS Encryption SDK](migration.md)을 참조하세요.
설치 및 빌드에 대한 자세한 지침은 [aws-encryption-sdk-c](https://github.com/aws/aws-encryption-sdk-c/) 리포지토리의 [README 파일](https://github.com/aws/aws-encryption-sdk-c/#readme) AWS Encryption SDK for C 에서 확인할 수 있습니다. 여기에는 Amazon Linux, Ubuntu, macOS, Windows 플랫폼에서 빌드하는 방법에 대한 지침이 포함되어 있습니다.
시작하기 전에 AWS Encryption SDK에서 [AWS KMS 키링](use-kms-keyring.md)을 사용할지 여부를 결정합니다. AWS KMS 키링을 사용하는 경우를 설치해야 합니다 AWS SDK for C\$1\$1. AWS SDK는 [AWS Key Management Service](https://docs.aws.amazon.com/kms/latest/developerguide/) ()와 상호 작용하는 데 필요합니다AWS KMS. AWS KMS 키링을 사용하는 경우는를 AWS Encryption SDK AWS KMS 사용하여 데이터를 보호하는 암호화 키를 생성하고 보호합니다.
원시 AES 키링, 원시 RSA 키링 또는 키링이 포함되지 않은 다중 키링과 같은 다른 AWS KMS 키링 유형을 사용하는 AWS SDK for C\$1\$1 경우를 설치할 필요가 없습니다. 하지만 원시 키링 유형을 사용하는 경우 원시 래핑 키를 직접 생성하고 보호해야 합니다.
설치에 문제가 있는 경우 `aws-encryption-sdk-c` 리포지토리에 [문제를 제출](https://github.com/aws/aws-encryption-sdk-c/issues)하거나 이 페이지에 있는 피드백 링크를 사용하세요.
# 사용 AWS Encryption SDK for C
이 주제에서는 다른 프로그래밍 언어 구현에서 지원되지 AWS Encryption SDK for C 않는의 일부 기능에 대해 설명합니다.
이 섹션의 예제에서는 [2.0.*x*](about-versions.md) 이상 버전의 AWS Encryption SDK for C를 사용하는 방법을 보여줍니다. 이하 버전을 사용하는 예제는 GitHub의 [aws-encryption-sdk-c 리포지토리](https://github.com/aws/aws-encryption-sdk-c/) 리포지토리의 [릴리스](https://github.com/aws/aws-encryption-sdk-c/releases) 목록에서 해당하는 릴리스를 찾을 수 있습니다.
를 사용한 프로그래밍에 대한 자세한 내용은 [C 예제](c-examples.md), GitHub[https://github.com/aws/aws-encryption-sdk-c/tree/master/examples](https://github.com/aws/aws-encryption-sdk-c/tree/master/examples)의 [aws-encryption-sdk-c 리포지토리](https://github.com/aws/aws-encryption-sdk-c/) 예제 및 [AWS Encryption SDK for C API 설명서를](https://aws.github.io/aws-encryption-sdk-c/html/) AWS Encryption SDK for C참조하세요.
또한 [키링](choose-keyring.md) 섹션도 참조하세요.
**Topics**
+ [데이터 암호화 및 복호화 패턴](#c-language-using-pattern)
+ [참조 카운트](#c-language-using-release)
## 데이터 암호화 및 복호화 패턴
를 사용하는 경우 다음과 유사한 패턴을 AWS Encryption SDK for C따릅니다. [키링](concepts.md#keyring) 생성, 키링을 사용하는 [CMM](concepts.md#crypt-materials-manager) 생성, CMM(및 키링)을 사용하는 세션 생성, 세션 처리.
1. 오류 문자열을 로드합니다.
C 또는 C\$1\$1 코드에서 `aws_cryptosdk_load_error_strings()` 메서드를 호출합니다. 이 메서드는 디버깅에 매우 유용한 오류 정보를 로드합니다.
`main` 메서드에서와 같이 한 번만 호출하면 됩니다.
```
/* Load error strings for debugging */
aws_cryptosdk_load_error_strings();
```
2. 키링을 생성합니다.
데이터 키를 암호화하는 데 사용할 래핑 키로 [키링](concepts.md#keyring)을 구성합니다. 이 예제에서는 [AWS KMS 키링](use-kms-keyring.md)을 1과 함께 사용하지만 AWS KMS key그 자리에 모든 유형의 키링을 사용할 수 있습니다.
AWS KMS key 의 암호화 키링에서를 식별하려면 [키 ARN](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-key-ARN) 또는 [별칭 ARN을](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-alias-arn) AWS Encryption SDK for C지정합니다. 복호화 키링에서는 키 ARN을 사용해야 합니다. 자세한 내용은 [AWS KMS 키링 AWS KMS keys 에서 식별](use-kms-keyring.md#kms-keyring-id)을 참조하세요.
```
const char * KEY_ARN = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"
struct aws_cryptosdk_keyring *kms_keyring =
Aws::Cryptosdk::KmsKeyring::Builder().Build(KEY_ARN);
```
3. 세션을 생성합니다.
에서 *세션을* AWS Encryption SDK for C사용하여 크기에 관계없이 단일 일반 텍스트 메시지를 암호화하거나 단일 사이퍼텍스트 메시지를 해독합니다. 세션은 처리 과정 내내 메시지 상태를 유지합니다.
할당자, 키링, 모드(`AWS_CRYPTOSDK_ENCRYPT` 또는 `AWS_CRYPTOSDK_DECRYPT`)를 사용하여 세션을 구성합니다. 세션 모드를 변경해야 하는 경우 `aws_cryptosdk_session_reset` 메서드를 사용합니다.
키링으로 세션을 생성하면가 AWS Encryption SDK for C 자동으로 기본 암호화 자료 관리자(CMM)를 생성합니다. 이 객체를 만들거나 유지 관리하거나 삭제할 필요가 없습니다.
예를 들어 다음 세션은 1단계에서 정의한 키링과 할당자를 사용합니다. 데이터를 암호화할 때 모드는 `AWS_CRYPTOSDK_ENCRYPT`입니다.
```
struct aws_cryptosdk_session * session = aws_cryptosdk_session_new_from_keyring_2(allocator, AWS_CRYPTOSDK_ENCRYPT, kms_keyring);
```
4. 데이터를 암호화 또는 복호화합니다.
세션에서 데이터를 처리하려면 `aws_cryptosdk_session_process` 메서드를 사용합니다. 입력 버퍼가 전체 일반 텍스트를 수용할 수 있을 만큼 크고 출력 버퍼가 전체 사이퍼텍스트를 수용할 수 있을 만큼 큰 경우, `aws_cryptosdk_session_process_full`을 호출할 수 있습니다. 그러나 스트리밍 데이터를 처리해야 하는 경우 루프에서 `aws_cryptosdk_session_process`를 호출할 수 있습니다. 예를 들어 [file\$1streaming.cpp](https://github.com/aws/aws-encryption-sdk-c/blob/master/examples/file_streaming.cpp) 예제를 참조하세요. `aws_cryptosdk_session_process_full`는 AWS Encryption SDK 버전 1.9.*x* 및 2.2.*x*에 도입되었습니다.
세션이 데이터를 암호화하도록 구성된 경우 일반 텍스트 필드는 입력을 설명하고 사이퍼텍스트 필드는 출력을 설명합니다. `plaintext` 필드에는 암호화하려는 메시지가 들어 있고 `ciphertext` 필드는 암호화 메서드가 반환하는 [암호화된 메시지](message-format.md)를 가져옵니다.
```
/* Encrypting data */
aws_cryptosdk_session_process_full(session,
ciphertext,
ciphertext_buffer_size,
&ciphertext_length,
plaintext,
plaintext_length)
```
세션이 데이터를 복호화하도록 구성된 경우 사이퍼텍스트 필드는 입력을 설명하고 일반 텍스트 필드는 출력을 설명합니다. `ciphertext` 필드에는 암호화 메서드가 반환한 [암호화된 메시지](message-format.md)가 들어 있고 `plaintext` 필드는 복호화 메서드가 반환하는 일반 텍스트 메시지를 가져옵니다.
데이터를 복호화하려면 `aws_cryptosdk_session_process_full` 메서드를 호출합니다.
```
/* Decrypting data */
aws_cryptosdk_session_process_full(session,
plaintext,
plaintext_buffer_size,
&plaintext_length,
ciphertext,
ciphertext_length)
```
## 참조 카운트
메모리 누수를 방지하려면 생성하는 모든 객체의 사용을 마친 후 그에 대한 참조를 릴리스해야 합니다. 그러지 않으면 메모리 누수가 발생합니다. SDK는 이 작업을 더 쉽게 수행할 수 있는 방법을 제공합니다.
다음 하위 객체 중 하나를 사용하여 상위 객체를 만들 때마다 상위 객체는 다음과 같이 하위 객체에 대한 참조를 가져오고 유지합니다.
+ [키링](concepts.md#keyring)(예: 키링으로 세션 만들기)
+ 기본 [암호화 구성 요소 관리자(CMM)](concepts.md#crypt-materials-manager)(예: 기본 CMM을 사용하여 세션 또는 사용자 지정 CMM 만들기)
+ [데이터 키 캐시](data-key-caching.md)(예: 키링 및 캐시가 있는 캐싱 CMM 생성)
하위 객체에 대한 독립적인 참조가 필요하지 않은 한, 상위 객체를 만드는 즉시 하위 객체에 대한 참조를 릴리스할 수 있습니다. 상위 객체가 삭제되면 하위 객체에 대한 나머지 참조가 릴리스됩니다. 이 패턴을 사용하면 각 개체에 대한 참조를 필요한 기간 동안만 유지할 수 있으며 릴리스되지 않은 참조로 인해 메모리가 누수되는 것을 방지할 수 있습니다.
명시적으로 만드는 하위 객체에 대한 참조만 릴리스하면 됩니다. 사용자에게는 SDK가 생성하는 객체에 대한 참조를 관리할 책임이 없습니다. SDK가 `aws_cryptosdk_caching_cmm_new_from_keyring` 메서드가 세션에 추가하는 기본 CMM과 같은 객체를 만드는 경우 SDK는 객체와 해당 참조의 생성 및 삭제를 관리합니다.
다음 예제에서 [키링](concepts.md#keyring)이 있는 세션을 만들면 세션은 키링에 대한 참조를 가져오고 세션이 삭제될 때까지 해당 참조를 유지합니다. 키링에 대한 추가 참조를 유지할 필요가 없는 경우, 세션이 만들어지는 즉시 `aws_cryptosdk_keyring_release` 메서드를 사용하여 키링 객체를 릴리스할 수 있습니다. 이 메서드를 사용하면 키링의 참조 횟수가 줄어듭니다. 키링에 대한 세션의 참조는 `aws_cryptosdk_session_destroy`를 호출하여 세션을 삭제할 때 릴리스됩니다.
```
// The session gets a reference to the keyring.
struct aws_cryptosdk_session *session =
aws_cryptosdk_session_new_from_keyring_2(alloc, AWS_CRYPTOSDK_ENCRYPT, keyring);
// After you create a session with a keyring, release the reference to the keyring object.
aws_cryptosdk_keyring_release(keyring);
```
여러 세션에 대해 키링을 재사용하거나 CMM에서 알고리즘 제품군을 지정하는 등 복잡한 작업의 경우, 객체에 대한 독립적인 참조를 유지해야 할 수 있습니다. 이 경우 릴리스 메서드를 즉시 호출하지 마세요. 대신, 세션을 삭제하는 것 외에도 객체를 더 이상 사용하지 않을 때 참조를 릴리스하세요.
이 참조 카운트 기술은 [데이터 키 캐싱](data-key-caching.md)을 위한 캐싱 CMM과 같은 대체 CMM을 사용할 때도 사용할 수 있습니다. 캐시와 키링에서 캐싱 CMM을 만들면 캐싱 CMM이 두 객체 모두에 대한 참조를 가져옵니다. 다른 작업에 필요하지 않은 한, 캐싱 CMM이 만들어지는 즉시 캐시 및 키링에 대한 독립적인 참조를 릴리스할 수 있습니다. 그런 다음 캐싱 CMM으로 세션을 만들 때, 캐싱 CMM에 대한 참조를 릴리스할 수 있습니다.
명시적으로 생성하는 객체에 대한 참조만 릴리스하면 됩니다. 캐싱 CMM의 기반이 되는 기본 CMM과 같이 메서드가 만드는 객체는 메서드에 의해 관리됩니다.
```
/ Create the caching CMM from a cache and a keyring.
struct aws_cryptosdk_cmm *caching_cmm = aws_cryptosdk_caching_cmm_new_from_keyring(allocator, cache, kms_keyring, NULL, 60, AWS_TIMESTAMP_SECS);
// Release your references to the cache and the keyring.
aws_cryptosdk_materials_cache_release(cache);
aws_cryptosdk_keyring_release(kms_keyring);
// Create a session with the caching CMM.
struct aws_cryptosdk_session *session = aws_cryptosdk_session_new_from_cmm_2(allocator, AWS_CRYPTOSDK_ENCRYPT, caching_cmm);
// Release your references to the caching CMM.
aws_cryptosdk_cmm_release(caching_cmm);
// ...
aws_cryptosdk_session_destroy(session);
```
# AWS Encryption SDK for C 예제
다음 예제에서는를 사용하여 데이터를 암호화하고 복호화 AWS Encryption SDK for C 하는 방법을 보여줍니다.
이 섹션의 예제에서는 2.0.*x* 이상 버전의 AWS Encryption SDK for C를 사용하는 방법을 보여줍니다. 이하 버전을 사용하는 예제는 GitHub의 [aws-encryption-sdk-c 리포지토리](https://github.com/aws/aws-encryption-sdk-c/) 리포지토리의 [릴리스](https://github.com/aws/aws-encryption-sdk-c/releases) 목록에서 해당하는 릴리스를 찾을 수 있습니다.
를 설치하고 빌드하면 이러한 예제 및 기타 예제 AWS Encryption SDK for C의 소스 코드가 `examples` 하위 디렉터리에 포함되고 디렉터리에 컴파일 및 빌드됩니다`build`. GitHub의 [aws-encryption-sdk-c](https://github.com/aws/aws-encryption-sdk-c/) 리포지토리의 [예제](https://github.com/aws/aws-encryption-sdk-c/tree/master/examples) 하위 디렉터리에서도 해당 예제를 찾을 수 있습니다.
**Topics**
+ [문자열 암호화 및 복호화](#c-example-strings)
## 문자열 암호화 및 복호화
다음 예제에서는를 사용하여 문자열 AWS Encryption SDK for C 을 암호화하고 복호화하는 방법을 보여줍니다.
이 예제는 [AWS Key Management Service (AWS KMS)](https://docs.aws.amazon.com/kms/latest/developerguide/) AWS KMS key 의를 사용하여 데이터 키를 생성하고 암호화하는 키링 [AWS KMS](use-kms-keyring.md)유형인 키링을 특징으로 합니다. 이 예제에는 C\$1\$1로 작성된 코드가 포함되어 있습니다. AWS Encryption SDK for C 에서는 AWS KMS 키링을 사용할 AWS KMS 때를 호출 AWS SDK for C\$1\$1 해야 합니다. 원시 AES 키링 AWS KMS, 원시 RSA 키링 또는 키링이 포함되지 않은 다중 키링과 같이와 상호 작용하지 않는 AWS KMS 키링을 사용하는 경우 AWS SDK for C\$1\$1 는 필요하지 않습니다.
생성에 대한 도움말은 *AWS Key Management Service 개발자 안내서*의 키 생성을 AWS KMS key참조하세요. [https://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html](https://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html) AWS KMS 키링 AWS KMS keys 에서를 식별하는 데 도움이 필요하면 섹션을 참조하세요[AWS KMS 키링 AWS KMS keys 에서 식별](use-kms-keyring.md#kms-keyring-id).
**전체 코드 샘플 보기**: [string.cpp](https://github.com/aws/aws-encryption-sdk-c/blob/master/examples/string.cpp)
**Topics**
+ [문자열 암호화](#c-example-string-encrypt)
+ [문자열 복호화](#c-example-string-decrypt)
### 문자열 암호화
이 예제의 첫 번째 부분에서는 AWS KMS 키링을 1과 함께 사용하여 일반 텍스트 문자열을 암호화 AWS KMS key 합니다.
1단계: 오류 문자열을 로드합니다.
C 또는 C\$1\$1 코드에서 `aws_cryptosdk_load_error_strings()` 메서드를 호출합니다. 이 메서드는 디버깅에 매우 유용한 오류 정보를 로드합니다.
`main` 메서드에서와 같이 한 번만 호출하면 됩니다.
```
/* Load error strings for debugging */
aws_cryptosdk_load_error_strings();
```
2단계: 키링을 구성합니다.
암호화를 위한 AWS KMS 키링을 생성합니다. 이 예제의 키링은 1로 구성 AWS KMS key되지만 서로 다른 계정 AWS 리전 과 다른 계정을 AWS KMS keys포함하여 여러 로 AWS KMS 키링 AWS KMS keys 을 구성할 수 있습니다.
AWS KMS key 의 암호화 키링에서를 식별하려면 [키 ARN](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-key-ARN) 또는 [별칭 ARN을](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-alias-arn) AWS Encryption SDK for C지정합니다. 복호화 키링에서는 키 ARN을 사용해야 합니다. 자세한 내용은 [AWS KMS 키링 AWS KMS keys 에서 식별](use-kms-keyring.md#kms-keyring-id)을 참조하세요.
[AWS KMS 키링 AWS KMS keys 에서 식별](use-kms-keyring.md#kms-keyring-id)
여러 로 키링을 생성할 때 일반 텍스트 데이터 키를 생성하고 암호화하는 데 AWS KMS key 사용되는와 동일한 일반 텍스트 데이터 키를 AWS KMS keys 암호화하는 추가의 선택적 배열을 AWS KMS keys지정합니다. 이 경우 생성기만 지정합니다 AWS KMS key.
이 코드를 실행하기 전에 예제 키 ARN을 유효한 키로 바꿉니다.
```
const char * key_arn = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";
struct aws_cryptosdk_keyring *kms_keyring =
Aws::Cryptosdk::KmsKeyring::Builder().Build(key_arn);
```
3단계: 세션을 생성합니다.
할당자, 모드 열거자, 키링을 사용하여 세션을 생성합니다.
모든 세션에는 모드가 필요합니다. 암호화하려면 `AWS_CRYPTOSDK_ENCRYPT`, 복호화하려면 `AWS_CRYPTOSDK_DECRYPT` 중 하나를 선택해야 합니다. 기존 세션의 모드를 변경하려면 `aws_cryptosdk_session_reset` 메서드를 사용합니다.
키링으로 세션을 생성한 후, SDK가 제공하는 메서드를 사용하여 키링에 대한 참조를 릴리스할 수 있습니다. 세션은 수명 기간 동안 키링 객체에 대한 참조를 유지합니다. 세션을 삭제하면 키링 및 세션 객체에 대한 참조가 릴리스됩니다. 이 [참조 카운트](c-language-using.md#c-language-using-release) 기술은 메모리 누수를 방지하고 객체가 사용 중일 때 객체가 릴리스되지 않도록 도와줍니다.
```
struct aws_cryptosdk_session *session =
aws_cryptosdk_session_new_from_keyring_2(alloc, AWS_CRYPTOSDK_ENCRYPT, kms_keyring);
/* When you add the keyring to the session, release the keyring object */
aws_cryptosdk_keyring_release(kms_keyring);
```
4단계: 암호화 컨텍스트를 설정합니다.
[암호화 컨텍스트](concepts.md#encryption-context)는 비밀이 아닌 임의의 추가 인증 데이터입니다. 암호화 시 암호화 컨텍스트를 제공하면 AWS Encryption SDK 는 암호화 컨텍스트를 사이퍼텍스트에 암호화 방식으로 바인딩하여 데이터를 복호화하는 데 동일한 암호화 컨텍스트가 필요합니다. 암호화 컨텍스트를 사용하는 것은 선택 사항이지만 권장되는 모범 사례입니다.
먼저 암호화 컨텍스트 문자열을 포함하는 해시 테이블을 생성합니다.
```
/* Allocate a hash table for the encryption context */
int set_up_enc_ctx(struct aws_allocator *alloc, struct aws_hash_table *my_enc_ctx)
// Create encryption context strings
AWS_STATIC_STRING_FROM_LITERAL(enc_ctx_key1, "Example");
AWS_STATIC_STRING_FROM_LITERAL(enc_ctx_value1, "String");
AWS_STATIC_STRING_FROM_LITERAL(enc_ctx_key2, "Company");
AWS_STATIC_STRING_FROM_LITERAL(enc_ctx_value2, "MyCryptoCorp");
// Put the key-value pairs in the hash table
aws_hash_table_put(my_enc_ctx, enc_ctx_key1, (void *)enc_ctx_value1, &was_created)
aws_hash_table_put(my_enc_ctx, enc_ctx_key2, (void *)enc_ctx_value2, &was_created)
```
세션에서 암호화 컨텍스트에 대한 변경 가능한 포인터를 가져옵니다. 그런 다음 `aws_cryptosdk_enc_ctx_clone` 함수를 사용하여 암호화 컨텍스트를 세션에 복사합니다. 이 복사본은 데이터를 복호화한 후 값을 검증할 수 있도록 `my_enc_ctx`에 보관됩니다.
암호화 컨텍스트는 세션 프로세스 함수에 전달되는 파라미터가 아니라 세션의 일부입니다. 이렇게 하면 전체 메시지를 암호화하기 위해 세션 프로세스 함수를 여러 번 호출하더라도 메시지의 모든 세그먼트에 동일한 암호화 컨텍스트가 사용되도록 합니다.
```
struct aws_hash_table *session_enc_ctx = aws_cryptosdk_session_get_enc_ctx_ptr_mut(session);
aws_cryptosdk_enc_ctx_clone(alloc, session_enc_ctx, my_enc_ctx)
```
5단계: 문자열을 암호화합니다.
일반 텍스트 문자열을 암호화하려면 세션이 암호화 모드인 상태에서 `aws_cryptosdk_session_process_full` 메서드를 사용합니다. AWS Encryption SDK 버전 1.9.*x* 및 2.2.*x*에 도입된이 방법은 비스트리밍 암호화 및 복호화를 위해 설계되었습니다. 스트리밍 데이터를 처리하려면 `aws_cryptosdk_session_process`를 루프에서 호출합니다.
암호화할 때 일반 텍스트 필드는 입력 필드이고 사이퍼텍스트 필드는 출력 필드입니다. 처리가 완료되면 실제 사이퍼텍스트, 암호화된 데이터 키, 암호화 컨텍스트를 비롯한 [암호화된 메시지](concepts.md#message)가 `ciphertext_output` 필드에 포함됩니다. 지원되는 프로그래밍 언어에 AWS Encryption SDK 대해를 사용하여이 암호화된 메시지를 해독할 수 있습니다.
```
/* Gets the length of the plaintext that the session processed */
size_t ciphertext_len_output;
if (AWS_OP_SUCCESS != aws_cryptosdk_session_process_full(session,
ciphertext_output,
ciphertext_buf_sz_output,
&ciphertext_len_output,
plaintext_input,
plaintext_len_input)) {
aws_cryptosdk_session_destroy(session);
return 8;
}
```
6단계: 세션을 정리합니다.
마지막 단계에서는 CMM 및 키링에 대한 참조를 포함하여 세션을 삭제합니다.
원하는 경우 세션을 삭제하는 대신 동일한 키링과 CMM으로 세션을 재사용하여 문자열을 복호화하거나 다른 메시지를 암호화 또는 복호화할 수 있습니다. 세션을 복호화에 사용하려면 `aws_cryptosdk_session_reset` 메서드를 사용하여 모드를 `AWS_CRYPTOSDK_DECRYPT`로 변경합니다.
### 문자열 복호화
이 예제의 두 번째 부분에서는 원본 문자열의 사이퍼텍스트가 포함된 암호화된 메시지를 복호화합니다.
1단계: 오류 문자열을 로드합니다.
C 또는 C\$1\$1 코드에서 `aws_cryptosdk_load_error_strings()` 메서드를 호출합니다. 이 메서드는 디버깅에 매우 유용한 오류 정보를 로드합니다.
`main` 메서드에서와 같이 한 번만 호출하면 됩니다.
```
/* Load error strings for debugging */
aws_cryptosdk_load_error_strings();
```
2단계: 키링을 구성합니다.
에서 데이터를 복호화하면 암호화 API가 반환한 [암호화된 메시지를](concepts.md#message) AWS KMS전달합니다. [Decrypt API](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html)는를 입력 AWS KMS key 으로 사용하지 않습니다. 대신 동일한를 AWS KMS 사용하여 암호화 AWS KMS key 에 사용한 사이퍼텍스트를 복호화합니다. 그러나를 AWS Encryption SDK 사용하면 암호화 및 복호화 AWS KMS keys 시를 사용하여 AWS KMS 키링을 지정할 수 있습니다.
복호화 시 암호화된 메시지를 복호화 AWS KMS keys 하는 데 사용할 로만 키링을 구성할 수 있습니다. 예를 들어 조직의 특정 역할에서 AWS KMS key 사용하는 만 사용하여 키링을 생성할 수 있습니다. 는 AWS Encryption SDK 복호화 키링에 나타나지 않는 AWS KMS key 한를 사용하지 않습니다. 제공된 키링 AWS KMS keys 에서를 사용하여 암호화된 데이터 키를 복호화할 수 없는 경우 키링 AWS KMS keys 의가 데이터 키를 암호화하는 데 사용되지 않았거나 호출자가 키링 AWS KMS keys 의를 사용하여 복호화할 권한이 없기 때문에 복호화 호출이 실패합니다.
복호화 키링에 AWS KMS key 대해를 지정할 때는 해당 [키 ARN](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-key-ARN)을 사용해야 합니다. [별칭 ARN](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-alias-arn)은 암호화 키링에서만 허용됩니다. AWS KMS 키링 AWS KMS keys 에서를 식별하는 데 도움이 필요하면 섹션을 참조하세요[AWS KMS 키링 AWS KMS keys 에서 식별](use-kms-keyring.md#kms-keyring-id).
이 예제에서는 문자열을 암호화하는 데 AWS KMS key 사용된 것과 동일한 로 구성된 키링을 지정합니다. 이 코드를 실행하기 전에 예제 키 ARN을 유효한 키로 바꿉니다.
```
const char * key_arn = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"
struct aws_cryptosdk_keyring *kms_keyring =
Aws::Cryptosdk::KmsKeyring::Builder().Build(key_arn);
```
3단계: 세션을 생성합니다.
할당자와 키링을 사용하여 세션을 생성합니다. 복호화를 위한 세션을 구성하려면 `AWS_CRYPTOSDK_DECRYPT` 모드를 사용하여 세션을 구성합니다.
키링으로 세션을 생성한 후, SDK가 제공하는 메서드를 사용하여 키링에 대한 참조를 릴리스할 수 있습니다. 세션은 수명 동안 키링 객체에 대한 참조를 유지하며, 세션과 키링은 세션을 삭제할 때 릴리스됩니다. 이 참조 카운트 기술은 메모리 누수를 방지하고 객체가 사용 중일 때 객체가 릴리스되지 않도록 도와줍니다.
```
struct aws_cryptosdk_session *session =
aws_cryptosdk_session_new_from_keyring_2(alloc, AWS_CRYPTOSDK_DECRYPT, kms_keyring);
/* When you add the keyring to the session, release the keyring object */
aws_cryptosdk_keyring_release(kms_keyring);
```
4단계: 문자열을 복호화합니다.
문자열을 복호화하려면 복호화를 위해 구성된 세션에서 `aws_cryptosdk_session_process_full` 메서드를 사용합니다. 이 메서드는 AWS Encryption SDK 버전 1.9.*x* 및 2.2.*x*에 도입되었으며, 비스트리밍 암호화 및 복호화를 위해 설계되었습니다. 스트리밍 데이터를 처리하려면 `aws_cryptosdk_session_process`를 루프에서 호출합니다.
복호화 시 사이퍼텍스트 필드는 입력 필드이고 일반 텍스트 필드는 출력 필드입니다. `ciphertext_input` 필드에는 암호화 메서드가 반환한 [암호화된 메시지](message-format.md)가 있습니다. 처리가 완료되면 `plaintext_output` 필드에 일반 텍스트(복호화된) 문자열이 포함됩니다.
```
size_t plaintext_len_output;
if (AWS_OP_SUCCESS != aws_cryptosdk_session_process_full(session,
plaintext_output,
plaintext_buf_sz_output,
&plaintext_len_output,
ciphertext_input,
ciphertext_len_input)) {
aws_cryptosdk_session_destroy(session);
return 13;
}
```
5단계: 암호화 컨텍스트를 확인합니다.
메시지를 복호화하는 데 사용된 실제 암호화 컨텍스트에 메시지를 암호화할 때 제공한 암호화 컨텍스트가 포함되어 있는지 확인하세요. [암호화 구성 요소 관리자(CMM)](concepts.md#crypt-materials-manager)가 메시지를 암호화하기 전에 제공된 암호화 컨텍스트에 페어를 추가할 수 있으므로 실제 암호화 컨텍스트에 추가 페어가 포함될 수 있습니다.
에서는 암호화 컨텍스트가 SDK가 반환하는 암호화된 메시지에 포함되므로 복호화할 때 암호화 컨텍스트를 제공할 필요가 AWS Encryption SDK for C없습니다. 하지만 복호화 함수는 일반 텍스트 메시지를 반환하기 전에 제공된 암호화 컨텍스트의 모든 페어가 메시지를 복호화하는 데 사용된 암호화 컨텍스트에 나타나는지 확인해야 합니다.
먼저 세션의 해시 테이블에 대한 읽기 전용 포인터를 가져옵니다. 이 해시 테이블에는 메시지를 복호화하는 데 사용된 암호화 컨텍스트가 포함되어 있습니다.
```
const struct aws_hash_table *session_enc_ctx = aws_cryptosdk_session_get_enc_ctx_ptr(session);
```
그런 다음 암호화할 때 복사한 `my_enc_ctx` 해시 테이블에서 암호화 컨텍스트를 반복합니다. 암호화에 사용된 `my_enc_ctx` 해시 테이블의 각 페어가 복호화에 사용된 `session_enc_ctx` 해시 테이블에 나타나는지 확인합니다. 누락된 키가 있거나 해당 키의 값이 다른 경우 처리를 중지하고 오류 메시지를 작성합니다.
```
for (struct aws_hash_iter iter = aws_hash_iter_begin(my_enc_ctx); !aws_hash_iter_done(&iter);
aws_hash_iter_next(&iter)) {
struct aws_hash_element *session_enc_ctx_kv_pair;
aws_hash_table_find(session_enc_ctx, iter.element.key, &session_enc_ctx_kv_pair)
if (!session_enc_ctx_kv_pair ||
!aws_string_eq(
(struct aws_string *)iter.element.value, (struct aws_string *)session_enc_ctx_kv_pair->value)) {
fprintf(stderr, "Wrong encryption context!\n");
abort();
}
}
```
6단계: 세션을 정리합니다.
암호화 컨텍스트를 확인한 후 세션을 삭제하거나 재사용할 수 있습니다. 세션을 재구성해야 하는 경우 `aws_cryptosdk_session_reset` 메서드를 사용합니다.
```
aws_cryptosdk_session_destroy(session);
```