AWS Encryption SDK for C 예제

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

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

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

암호화를 위한 AWS KMS 키링을 생성합니다. 이 예제의 키링은 하나로 구성되지만 AWS KMS key, 서로 다른 계정 AWS 리전 과 다른 계정을 AWS KMS keys포함하여 여러 로 AWS KMS 키링 AWS KMS keys 을 구성할 수 있습니다.

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

AWS KMS 키링 AWS KMS keys 에서 식별

여러 로 키링을 생성할 때 일반 텍스트 데이터 키를 생성하고 암호화하는 데 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);

할당자, 모드 열거자, 키링을 사용하여 세션을 생성합니다.

모든 세션에는 모드가 필요합니다. 암호화하려면 AWS_CRYPTOSDK_ENCRYPT, 복호화하려면 AWS_CRYPTOSDK_DECRYPT 중 하나를 선택해야 합니다. 기존 세션의 모드를 변경하려면 aws_cryptosdk_session_reset 메서드를 사용합니다.

키링으로 세션을 생성한 후, SDK가 제공하는 메서드를 사용하여 키링에 대한 참조를 릴리스할 수 있습니다. 세션은 수명 기간 동안 키링 객체에 대한 참조를 유지합니다. 세션을 삭제하면 키링 및 세션 객체에 대한 참조가 릴리스됩니다. 이 참조 카운트 기술은 메모리 누수를 방지하고 객체가 사용 중일 때 객체가 릴리스되지 않도록 도와줍니다.

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);

암호화 컨텍스트는 비밀이 아닌 임의의 추가 인증 데이터입니다. 암호화에 암호화 컨텍스트를 제공하면 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)

일반 텍스트 문자열을 암호화하려면 세션이 암호화 모드인 상태에서 aws_cryptosdk_session_process_full 메서드를 사용합니다. AWS Encryption SDK 버전 1.9.x 및 2.2.x에 도입된이 방법은 비스트리밍 암호화 및 복호화를 위해 설계되었습니다. 스트리밍 데이터를 처리하려면 aws_cryptosdk_session_process를 루프에서 호출합니다.

암호화할 때 일반 텍스트 필드는 입력 필드이고 사이퍼텍스트 필드는 출력 필드입니다. 처리가 완료되면 실제 사이퍼텍스트, 암호화된 데이터 키, 암호화 컨텍스트를 비롯한 암호화된 메시지가 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;
}

마지막 단계에서는 CMM 및 키링에 대한 참조를 포함하여 세션을 삭제합니다.

원하는 경우 세션을 삭제하는 대신 동일한 키링과 CMM으로 세션을 재사용하여 문자열을 복호화하거나 다른 메시지를 암호화 또는 복호화할 수 있습니다. 세션을 복호화에 사용하려면 aws_cryptosdk_session_reset 메서드를 사용하여 모드를 AWS_CRYPTOSDK_DECRYPT로 변경합니다.

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

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

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

에서 데이터를 복호화하면 암호화 API가 반환한 암호화된 메시지를 AWS KMS전달합니다. Decrypt API는를 입력 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 의를 사용하여 복호화할 권한이 없기 때문에 SDK가 사용자가 제공한 키링 AWS KMS keys 의를 사용하여 암호화된 데이터 키를 복호화할 수 없는 경우 복호화 호출이 실패합니다.

복호화 키링에 AWS KMS key 대해를 지정할 때 해당 키 ARN을 사용해야 합니다. 별칭 ARN은 암호화 키링에서만 허용됩니다. AWS KMS 키링 AWS KMS keys 에서를 식별하는 데 도움이 필요하면 섹션을 참조하세요AWS KMS 키링 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);

할당자와 키링을 사용하여 세션을 생성합니다. 복호화를 위한 세션을 구성하려면 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);

문자열을 복호화하려면 복호화를 위해 구성된 세션에서 aws_cryptosdk_session_process_full 메서드를 사용합니다. 이 메서드는 AWS Encryption SDK 버전 1.9.x 및 2.2.x에 도입되었으며, 비스트리밍 암호화 및 복호화를 위해 설계되었습니다. 스트리밍 데이터를 처리하려면 aws_cryptosdk_session_process를 루프에서 호출합니다.

복호화 시 사이퍼텍스트 필드는 입력 필드이고 일반 텍스트 필드는 출력 필드입니다. ciphertext_input 필드에는 암호화 메서드가 반환한 암호화된 메시지가 있습니다. 처리가 완료되면 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;
}

메시지를 복호화하는 데 사용된 실제 암호화 컨텍스트에 메시지를 암호화할 때 제공한 암호화 컨텍스트가 포함되어 있는지 확인하세요. 암호화 구성 요소 관리자(CMM)가 메시지를 암호화하기 전에 제공된 암호화 컨텍스트에 페어를 추가할 수 있으므로 실제 암호화 컨텍스트에 추가 페어가 포함될 수 있습니다.

에서는 암호화 컨텍스트가 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();
    }
}

암호화 컨텍스트를 확인한 후 세션을 삭제하거나 재사용할 수 있습니다. 세션을 재구성해야 하는 경우 aws_cryptosdk_session_reset 메서드를 사용합니다.

aws_cryptosdk_session_destroy(session);