AWS Encryption SDK for C 사용

이 섹션에서는 다른 프로그래밍 언어 구현에서는 지원되지 않는 AWS Encryption SDK for C의 몇 가지 기능을 설명합니다.

이 섹션의 예제에서는 2.0.x 이상 버전의 AWS Encryption SDK for C를 사용하는 방법을 보여줍니다. 이하 버전을 사용하는 예제는 GitHub의 aws-encryption-sdk-c 리포지토리 리포지토리의 릴리스 목록에서 해당하는 릴리스를 찾을 수 있습니다.

AWS Encryption SDK for C를 사용한 프로그래밍에 대한 자세한 내용은 C 예제, GitHub의 aws-encryption-sdk-c 리포지토리에 있는 예제, AWS Encryption SDK for C API 설명서를 참조하세요.

또한 키링 사용 섹션도 참조하세요.

데이터 암호화 및 복호화 패턴

AWS Encryption SDK for C를 사용할 경우 일반적으로 키링을 생성하고, 키링을 사용하는 CMM을 생성하고, CMM(및 키링)을 사용하는 세션을 생성한 후 세션을 처리하는 패턴을 따릅니다.

1. 오류 문자열을 로드합니다.

C 또는 C++ 코드에서 aws_cryptosdk_load_error_strings() 메서드를 호출합니다. 이 메서드는 디버깅에 매우 유용한 오류 정보를 로드합니다.

main 메서드에서와 같이 한 번만 호출하면 됩니다.

/* Load error strings for debugging */
aws_cryptosdk_load_error_strings();

2. 키링을 생성합니다.

데이터 키를 암호화하는 데 사용할 래핑 키로 키링을 구성합니다. 이 예제는 AWS KMS 키링을 하나의 AWS KMS key와 함께 사용하지만, 다른 유형의 키링을 대신 사용해도 됩니다.

AWS Encryption SDK for C에서 암호화 키링의 AWS KMS key를 식별하려면 키 ARN 또는 별칭 ARN을 지정합니다. 복호화 키링에서는 키 ARN을 사용해야 합니다. 자세한 내용은 AWS KMS 키링의 AWS KMS keys 식별 섹션을 참조하세요.

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_streaming.cpp 예제를 참조하세요. aws_cryptosdk_session_process_full은 AWS Encryption SDK 버전 1.9.x 및 2.2.x에 도입되었습니다.

세션이 데이터를 암호화하도록 구성된 경우 일반 텍스트 필드는 입력을 설명하고 사이퍼텍스트 필드는 출력을 설명합니다. plaintext 필드에는 암호화하려는 메시지가 들어 있고 ciphertext 필드는 암호화 메서드가 반환하는 암호화된 메시지를 가져옵니다.

/* Encrypting data */
aws_cryptosdk_session_process_full(session,
                                   ciphertext,
                                   ciphertext_buffer_size,
                                   &ciphertext_length,
                                   plaintext,
                                   plaintext_length)
                              

세션이 데이터를 복호화하도록 구성된 경우 사이퍼텍스트 필드는 입력을 설명하고 일반 텍스트 필드는 출력을 설명합니다. ciphertext 필드에는 암호화 메서드가 반환한 암호화된 메시지가 들어 있고 plaintext 필드는 복호화 메서드가 반환하는 일반 텍스트 메시지를 가져옵니다.

데이터를 복호화하려면 aws_cryptosdk_session_process_full 메서드를 호출합니다.

/* Decrypting data */
aws_cryptosdk_session_process_full(session,
                                   plaintext,
                                   plaintext_buffer_size,
                                   &plaintext_length,
                                   ciphertext,
                                   ciphertext_length)
                                   

참조 카운트

메모리 누수를 방지하려면 생성하는 모든 객체의 사용을 마친 후 그에 대한 참조를 릴리스해야 합니다. 그러지 않으면 메모리 누수가 발생합니다. SDK는 이 작업을 더 쉽게 수행할 수 있는 방법을 제공합니다.

다음 하위 객체 중 하나를 사용하여 상위 객체를 만들 때마다 상위 객체는 다음과 같이 하위 객체에 대한 참조를 가져오고 유지합니다.

• 키링(예: 키링으로 세션 만들기)

• 기본 암호화 구성 요소 관리자(CMM)(예: 기본 CMM을 사용하여 세션 또는 사용자 지정 CMM 만들기)

• 데이터 키 캐시(예: 키링 및 캐시가 있는 캐싱 CMM 생성)

하위 객체에 대한 독립적인 참조가 필요하지 않은 한, 상위 객체를 만드는 즉시 하위 객체에 대한 참조를 릴리스할 수 있습니다. 상위 객체가 삭제되면 하위 객체에 대한 나머지 참조가 릴리스됩니다. 이 패턴을 사용하면 각 개체에 대한 참조를 필요한 기간 동안만 유지할 수 있으며 릴리스되지 않은 참조로 인해 메모리가 누수되는 것을 방지할 수 있습니다.

명시적으로 만드는 하위 객체에 대한 참조만 릴리스하면 됩니다. 사용자에게는 SDK가 생성하는 객체에 대한 참조를 관리할 책임이 없습니다. SDK가 aws_cryptosdk_caching_cmm_new_from_keyring 메서드가 세션에 추가하는 기본 CMM과 같은 객체를 만드는 경우 SDK는 객체와 해당 참조의 생성 및 삭제를 관리합니다.

다음 예제에서 키링이 있는 세션을 만들면 세션은 키링에 대한 참조를 가져오고 세션이 삭제될 때까지 해당 참조를 유지합니다. 키링에 대한 추가 참조를 유지할 필요가 없는 경우, 세션이 만들어지는 즉시 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에서 알고리즘 제품군을 지정하는 등 복잡한 작업의 경우, 객체에 대한 독립적인 참조를 유지해야 할 수 있습니다. 이 경우 릴리스 메서드를 즉시 호출하지 마세요. 대신, 세션을 삭제하는 것 외에도 객체를 더 이상 사용하지 않을 때 참조를 릴리스하세요.

이 참조 카운트 기술은 데이터 키 캐싱을 위한 캐싱 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);