기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다. # AWS Encryption SDK 프로그래밍 언어 AWS Encryption SDK 는 다음 프로그래밍 언어에 사용할 수 있습니다. 모든 언어 구현은 상호 연동이 가능합니다. 하나의 언어 구현으로 암호화하고 다른 언어 구현으로 복호화할 수 있습니다. 상호 연동성에는 언어 제약 조건이 적용될 수 있습니다. 이 경우 이러한 제약 조건은 언어 구현에 대한 주제에 설명되어 있습니다. 또한 암호화 및 복호화를 수행할 때는 호환되는 키링이나 마스터 키 및 마스터 키 공급자를 사용해야 합니다. 자세한 내용은 [키링 호환성](choose-keyring.md#keyring-compatibility) 섹션을 참조하세요. **Topics** + [C](c-language.md) + [.NET](dot-net.md) + [Go](go.md) + [Java](java.md) + [JavaScript](javascript.md) + [Python](python.md) + [Rust](rust.md) + [명령줄 인터페이스](crypto-cli.md) # 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); ``` # AWS Encryption SDK .NET용 AWS Encryption SDK for .NET은 C\$1 및 기타 .NET 프로그래밍 언어로 애플리케이션을 작성하는 개발자를 위한 클라이언트 측 암호화 라이브러리입니다. 이는 Windows, macOS, Linux에서 지원됩니다. **참고** AWS Encryption SDK for .NET 버전 4.0.0은 AWS Encryption SDK 메시지 사양을 벗어납니다. 따라서 버전 4.0.0으로 암호화된 메시지는 for .NET 버전 4.0.0 이상으로만 복호화할 수 AWS Encryption SDK 있습니다. 다른 프로그래밍 언어 구현으로는 복호화할 수 없습니다. AWS Encryption SDK for .NET 버전 4.0.1은 AWS Encryption SDK 메시지 사양에 따라 메시지를 작성하고 다른 프로그래밍 언어 구현과 상호 운용할 수 있습니다. 기본적으로 버전 4.0.1은 버전 4.0.0으로 암호화된 메시지를 읽을 수 있습니다. 그러나 버전 4.0.0으로 암호화된 메시지를 복호화하지 않으려면 클라이언트가 이러한 메시지를 읽지 못하도록 [https://github.com/aws/aws-encryption-sdk/tree/mainline/AwsEncryptionSDK/runtimes/net/Examples/NetV4_0_0Example.cs](https://github.com/aws/aws-encryption-sdk/tree/mainline/AwsEncryptionSDK/runtimes/net/Examples/NetV4_0_0Example.cs) 속성을 지정합니다. 자세한 내용은 GitHub의 aws-encryption-sdk 리포지토리에서 [v4.0.1 릴리스 정보를](https://github.com/aws/aws-encryption-sdk/releases/tag/v4.0.1) 참조하세요. AWS Encryption SDK for .NET은 다음과 같은 점 AWS Encryption SDK 에서의 다른 프로그래밍 언어 구현과 다릅니다. + [데이터 키 캐싱](data-key-caching.md)이 지원되지 않음 **참고** for .NET 버전 AWS Encryption SDK 4.*x*는 대체 암호화 자료 캐싱 솔루션인 [AWS KMS 계층적 키링](use-hierarchical-keyring.md)을 지원합니다. + 스트리밍 데이터가 지원되지 않음 + AWS Encryption SDK for .NET에서 [로깅 또는 스택 추적이 없음](#dot-net-debugging) + [가 필요합니다. AWS SDK for .NET](#dot-net-install) AWS Encryption SDK for .NET에는의 다른 언어 구현 버전 2.0.*x* 이상에 도입된 모든 보안 기능이 포함되어 있습니다 AWS Encryption SDK. 그러나 AWS Encryption SDK for .NET을 사용하여의 다른 언어 구현인 2.0.*x* 이전 버전으로 암호화된 데이터를 해독 AWS Encryption SDK하는 경우 [커밋 정책을](concepts.md#commitment-policy) 조정해야 할 수 있습니다. 자세한 내용은 [커밋 정책 설정 방법](migrate-commitment-policy.md#migrate-commitment-step1)을 참조하세요. AWS Encryption SDK for .NET은 사양을 작성하는 공식 확인 언어인 [Dafny](https://github.com/dafny-lang/dafny/blob/master/README.md) AWS Encryption SDK 의 제품이며, 이를 구현할 코드와 이를 테스트하기 위한 증명입니다. 그 결과, 기능적 정확성을 보장하는 프레임워크에서 AWS Encryption SDK 의 기능을 구현하는 라이브러리가 탄생했습니다. **자세히 알아보기** + 대체 알고리즘 제품군 지정 AWS Encryption SDK, 암호화된 데이터 키 제한, AWS KMS 다중 리전 키 사용 등에서 옵션을 구성하는 방법을 보여주는 예제는 섹션을 참조하세요[구성 AWS Encryption SDK](configure.md). + AWS Encryption SDK for .NET을 사용한 프로그래밍에 대한 자세한 내용은 GitHub의 aws-encryption-sdk 리포지토리 [https://github.com/aws/aws-encryption-sdk/tree/mainline/AwsEncryptionSDK/runtimes/net/](https://github.com/aws/aws-encryption-sdk/tree/mainline/AwsEncryptionSDK/runtimes/net/) 디렉터리를 참조하세요. **Topics** + [설치 및 빌드](#dot-net-install) + [디버깅](#dot-net-debugging) + [예제](dot-net-examples.md) ## AWS Encryption SDK for .NET 설치 AWS Encryption SDK for .NET은 NuGet에서 [https://www.nuget.org/packages/AWS.Cryptography.EncryptionSDK](https://www.nuget.org/packages/AWS.Cryptography.EncryptionSDK) 패키지로 사용할 수 있습니다. for .NET 설치 및 빌드 AWS Encryption SDK 에 대한 자세한 내용은 `aws-encryption-sdk-net`리포지토리의 [README.md](https://github.com/aws/aws-encryption-sdk/tree/mainline/AwsEncryptionSDK/runtimes/net/#readme) 파일을 참조하세요. **버전 3.x** AWS Encryption SDK for .NET 버전 3.*x*는 Windows에서만 .NET Framework 4.5.2\$14.8을 지원합니다. 지원되는 모든 운영 체제에서 .NET Core 3.0 이상 및 .NET 5.0 이상을 지원합니다. **버전 4.x** AWS Encryption SDK for .NET 버전 4.*x*는 .NET 6.0 및 .NET Framework net48 이상을 지원합니다. 버전 4.*x*에는 .NET v3용 AWS SDK가 필요합니다. **버전 5.x** AWS Encryption SDK for .NET 버전 5.*x*는 .NET 6.0 및 .NET Framework net48 이상을 지원합니다. 버전 5.*x*에는 .NET v4용 재료 공급자 라이브러리(MPL) 및 AWS SDK 버전 2.*x*가 필요합니다. AWS Encryption SDK for .NET에는 AWS Key Management Service (AWS KMS) 키를 사용하지 않더라도 SDK for .NET 가 필요합니다. NuGet 패키지와 함께 설치됩니다. 그러나 AWS KMS 키를 사용하지 않는 한 AWS Encryption SDK for .NET에는 AWS 계정자격 AWS 증명 또는 AWS 서비스와의 상호 작용이 필요하지 않습니다. 필요한 경우 AWS 계정 설정에 대한 도움말은 섹션을 참조하세요[와 AWS Encryption SDK 함께 사용 AWS KMS](getting-started.md). ## AWS Encryption SDK for .NET 디버깅 AWS Encryption SDK for .NET은 로그를 생성하지 않습니다. AWS Encryption SDK for .NET의 예외는 예외 메시지를 생성하지만 스택 추적은 생성하지 않습니다. 디버깅에 도움이 되도록 SDK for .NET에서 로그인을 활성화해야 합니다. 의 로그 및 오류 메시지는에서 발생하는 오류를 AWS Encryption SDK for .NET의 오류 SDK for .NET 와 구별하는 데 도움이 될 SDK for .NET 수 있습니다. SDK for .NET 로깅에 대한 도움말은 *AWS SDK for .NET 개발자 안내서*의 [AWSLogging](https://docs.aws.amazon.com/sdk-for-net/v4/developer-guide/net-dg-config-other.html#config-setting-awslogging)을 참조하세요. (이 주제를 보려면 **.NET Framework 콘텐츠를 열어서 보기** 섹션을 확장하세요.) # AWS Encryption SDK for .NET 예제 다음 예제에서는 for AWS Encryption SDK .NET을 사용하여 프로그래밍할 때 사용하는 기본 코딩 패턴을 보여줍니다. 특히 AWS Encryption SDK 및 재료 공급자 라이브러리를 인스턴스화합니다. 그런 다음 각 메서드를 호출하기 전에 메서드의 입력을 정의하는 객체를 인스턴스화합니다. 이는 SDK for .NET에서 사용하는 코딩 패턴과 매우 비슷합니다. 대체 알고리즘 제품군 지정 AWS Encryption SDK, 암호화된 데이터 키 제한, AWS KMS 다중 리전 키 사용 등에서 옵션을 구성하는 방법을 보여주는 예제는 섹션을 참조하세요[구성 AWS Encryption SDK](configure.md). for .NET을 사용한 프로그래밍에 AWS Encryption SDK 대한 자세한 예는 GitHub의 `aws-encryption-sdk`리포지토리 `aws-encryption-sdk-net` 디렉터리에 있는 [예제](https://github.com/aws/aws-encryption-sdk/tree/mainline/AwsEncryptionSDK/runtimes/net/Examples)를 참조하세요. ## AWS Encryption SDK for .NET에서 데이터 암호화 이 예제에서는 데이터를 암호화하는 기본 패턴을 보여줍니다. 하나의 AWS KMS 래핑 키로 보호되는 데이터 키로 작은 파일을 암호화합니다. 1단계: AWS Encryption SDK 및 재료 공급자 라이브러리를 인스턴스화합니다. 먼저 AWS Encryption SDK 및 재료 공급자 라이브러리를 인스턴스화합니다. 의 메서드를 사용하여 데이터를 암호화하고 해독 AWS Encryption SDK 합니다. 구성 요소 공급자 라이브러리의 메서드를 사용하여, 데이터를 보호하는 키를 지정하는 키링을 만들 수 있습니다. AWS Encryption SDK 및 재료 공급자 라이브러리를 인스턴스화하는 방법은 for . AWS Encryption SDK NET의 버전 3.*x*와 4.*x* 간에 다릅니다. 다음 단계는 for . AWS Encryption SDK NET의 버전 3.*x*와 4.*x*에서 모두 동일합니다. ``` // Instantiate the AWS Encryption SDK and material providers var encryptionSdk = AwsEncryptionSdkFactory.CreateDefaultAwsEncryptionSdk(); var materialProviders = AwsCryptographicMaterialProvidersFactory.CreateDefaultAwsCryptographicMaterialProviders(); ``` ``` // Instantiate the AWS Encryption SDK and material providers var esdk = new ESDK(new AwsEncryptionSdkConfig()); var mpl = new MaterialProviders(new MaterialProvidersConfig()); ``` 2단계: 키링에 대한 입력 객체를 생성합니다. 키링을 만드는 각 메서드에는 해당하는 입력 객체 클래스가 있습니다. 예를 들어, `CreateAwsKmsKeyring()` 메서드의 입력 객체를 만들려면 `CreateAwsKmsKeyringInput` 클래스의 인스턴스를 생성합니다. 이 키링의 입력에 [생성기 키](use-kms-keyring.md#kms-keyring-encrypt)를 지정하지 않더라도 `KmsKeyId` 파라미터로 지정된 단일 KMS 키는 생성기 키입니다. 데이터를 암호화하는 데이터 키를 생성하고 암호화합니다. 이 입력 객체에는 KMS 키 AWS 리전 의에 대한 AWS KMS 클라이언트가 필요합니다. AWS KMS 클라이언트를 생성하려면에서 `AmazonKeyManagementServiceClient` 클래스를 인스턴스화합니다 SDK for .NET. 파라미터 없이 `AmazonKeyManagementServiceClient()` 생성자를 호출하면 기본값으로 클라이언트가 만들어집니다. AWS Encryption SDK for .NET을 사용한 암호화에 사용되는 AWS KMS 키링에서 키 ID, 키 ARN, 별칭 이름 또는 별칭 ARN을 사용하여 [KMS 키를 식별할](use-kms-keyring.md#kms-keyring-id) 수 있습니다. 복호화에 사용되는 AWS KMS 키링에서는 키 ARN을 사용하여 각 KMS 키를 식별해야 합니다. 복호화에 암호화 키링을 재사용하려는 경우 모든 KMS 키에 키 ARN 식별자를 사용합니다. ``` 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 }; ``` 3단계: 키링을 생성합니다. 키링을 생성하려면 키링 입력 객체를 사용하여 키링 메서드를 호출합니다. 이 예제에서는 KMS 키를 하나만 사용하는 `CreateAwsKmsKeyring()` 메서드를 사용합니다. ``` var keyring = materialProviders.CreateAwsKmsKeyring(kmsKeyringInput); ``` 4단계: 암호화 컨텍스트를 정의합니다. [암호화 컨텍스트](concepts.md#encryption-context)는 선택 사항이지만에서 암호화 작업의 권장 요소입니다 AWS Encryption SDK. 비밀이 아닌 키-값 페어를 하나 이상 정의할 수 있습니다. AWS Encryption SDK for .NET 버전 4.*x*에서는 필요한 암호화 컨텍스트 [CMM을 사용하여 모든 암호화 요청에 암호화 컨텍스트](configure.md#config-required-encryption-context-cmm)를 요구할 수 있습니다. ``` // Define the encryption context var encryptionContext = new Dictionary() { {"purpose", "test"} }; ``` 5단계: 암호화에 대한 입력 객체를 생성합니다. `Encrypt()` 메서드를 호출하기 전에 `EncryptInput` 클래스의 인스턴스를 생성합니다. ``` string plaintext = File.ReadAllText("C:\\Documents\\CryptoTest\\TestFile.txt"); // Define the encrypt input var encryptInput = new EncryptInput { Plaintext = plaintext, Keyring = keyring, EncryptionContext = encryptionContext }; ``` 6단계: 일반 텍스트를 암호화합니다. 의 `Encrypt()` 메 AWS Encryption SDK 서드를 사용하여 정의한 키링을 사용하여 일반 텍스트를 암호화합니다. `Encrypt() ` 메서드가 반환하는 `EncryptOutput`에는 암호화된 메시지(`Ciphertext`), 암호화 컨텍스트 및 알고리즘 제품군을 가져오는 메서드가 있습니다. ``` var encryptOutput = encryptionSdk.Encrypt(encryptInput); ``` 7단계: 암호화된 메시지를 가져옵니다. AWS Encryption SDK for .NET의 `Decrypt()` 메서드는 `EncryptOutput` 인스턴스의 `Ciphertext` 멤버를 가져옵니다. `EncryptOutput` 객체의 `Ciphertext` 멤버는 암호화 컨텍스트를 비롯해 암호화된 데이터, 암호화된 데이터 키 및 메타데이터를 포함하는 이동 가능 객체인 [암호화된 메시지](concepts.md#message)입니다. 암호화된 메시지를 장기간 안전하게 저장하거나 `Decrypt()` 메서드에 제출하여 일반 텍스트를 복구할 수 있습니다. ``` var encryptedMessage = encryptOutput.Ciphertext; ``` ## AWS Encryption SDK for .NET의 엄격 모드에서 복호화 모범 사례에서는 데이터를 복호화하는 데 사용할 키를 지정하는 것이 좋으며, 이러한 옵션을 *엄격한 모드*라고 합니다. 는 키링에 지정한 KMS 키만 AWS Encryption SDK 사용하여 사이퍼텍스트를 복호화합니다. 복호화 키링의 키에는 데이터를 암호화한 키가 하나 이상 포함되어야 합니다. 이 예제에서는 AWS Encryption SDK for .NET을 사용하여 엄격한 모드에서 복호화하는 기본 패턴을 보여줍니다. 1단계: AWS Encryption SDK 및 재료 공급자 라이브러리를 인스턴스화합니다. ``` // Instantiate the AWS Encryption SDK and material providers var esdk = new ESDK(new AwsEncryptionSdkConfig()); var mpl = new MaterialProviders(new MaterialProvidersConfig()); ``` 2단계: 키링에 대한 입력 객체를 생성합니다. 키링 메서드의 파라미터를 지정하려면 입력 객체를 생성합니다. AWS Encryption SDK for .NET의 각 키링 메서드에는 해당 입력 객체가 있습니다. 이 예제에서는 `CreateAwsKmsKeyring()` 메서드를 사용하여 키링을 만들기 때문에 입력에 대한 `CreateAwsKmsKeyringInput` 클래스를 인스턴스화합니다. 복호화 키링에서는 키 ARN을 사용하여 KMS 키를 식별해야 합니다. ``` 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 }; ``` 3단계: 키링을 생성합니다. 이 예제에서는 복호화 키링을 생성하기 위해 `CreateAwsKmsKeyring()` 메서드와 키링 입력 객체를 사용합니다. ``` var keyring = materialProviders.CreateAwsKmsKeyring(kmsKeyringInput); ``` 4단계: 복호화에 대한 입력 객체를 생성합니다. `Decrypt()` 메서드의 입력 객체를 만들려면 `DecryptInput` 클래스를 인스턴스화합니다. `DecryptInput()` 생성자의 `Ciphertext` 파라미터는 `Encrypt()` 메서드가 반환한 `EncryptOutput` 객체의 `Ciphertext` 멤버를 가져옵니다. `Ciphertext` 속성은 [암호화된 메시지](concepts.md#message)를 나타내며, 여기에는 AWS Encryption SDK 가 메시지를 복호화하는 데 필요한 암호화된 데이터, 암호화된 데이터 키 및 메타데이터가 포함됩니다. AWS Encryption SDK for .NET 버전 4.*x*에서는 선택적 `EncryptionContext` 파라미터를 사용하여 `Decrypt()` 메서드에서 암호화 컨텍스트를 지정할 수 있습니다. `EncryptionContext` 파라미터를 사용하여 암호화에 사용된 암호화 컨텍스트가 사이퍼텍스트를 복호화하는 데 사용되는 암호화 컨텍스트에 *포함되어 있는지* 확인합니다. 는 기본 알고리즘 제품군과 같이 서명과 함께 알고리즘 제품군을 사용하는 경우 디지털 서명을 포함하여 암호화 컨텍스트에 페어를 AWS Encryption SDK 추가합니다. ``` var encryptedMessage = encryptOutput.Ciphertext; var decryptInput = new DecryptInput { Ciphertext = encryptedMessage, Keyring = keyring, EncryptionContext = encryptionContext // OPTIONAL }; ``` 5단계: 사이퍼텍스트를 복호화합니다. ``` var decryptOutput = encryptionSdk.Decrypt(decryptInput); ``` 6단계: 암호화 컨텍스트 - 버전 3.*x*를 확인합니다. AWS Encryption SDK for .NET 버전 3.*x*의 `Decrypt()` 메서드는 암호화 컨텍스트를 사용하지 않습니다. 암호화된 메시지의 메타데이터에서 암호화 컨텍스트 값을 가져옵니다. 하지만 일반 텍스트를 반환하거나 사용하기 전에, 사이퍼텍스트를 복호화하는 데 사용된 암호화 컨텍스트에 암호화 시 제공한 암호화 컨텍스트가 포함되어 있는지 확인하는 것이 모범 사례입니다. 암호화에 사용된 암호화 컨텍스트가 사이퍼텍스트를 복호화하는 데 사용된 암호화 컨텍스트에 *포함되어 있는지* 확인합니다. 는 기본 알고리즘 제품군과 같이 서명과 함께 알고리즘 제품군을 사용하는 경우 디지털 서명을 포함하여 암호화 컨텍스트에 페어를 AWS Encryption SDK 추가합니다. ``` // Verify the encryption context string contextKey = "purpose"; string contextValue = "test"; if (!decryptOutput.EncryptionContext.TryGetValue(contextKey, out var decryptContextValue) || !decryptContextValue.Equals(contextValue)) { throw new Exception("Encryption context does not match expected values"); } ``` ## AWS Encryption SDK for .NET에서 검색 키링을 사용하여 복호화 복호화를 위한 KMS 키를 지정하는 대신, KMS 키를 지정하지 않는 키링인 AWS KMS *검색 키링*을 제공할 수 있습니다. 호출자에게 키에 대한 AWS Encryption SDK 복호화 권한이 있는 경우 검색 키링을 사용하면가 데이터를 암호화한 KMS 키를 사용하여 데이터를 복호화할 수 있습니다. 모범 사례를 위해 지정된 파티션 AWS 계정 의 KMS 키로 사용할 수 있는 KMS 키를 제한하는 검색 필터를 추가합니다. AWS Encryption SDK for .NET은 클라이언트가 필요한 AWS KMS 기본 검색 키링과 하나 이상의를 지정해야 하는 검색 다중 키링을 제공합니다 AWS 리전. 클라이언트와 리전은 암호화된 메시지를 복호화하는 데 사용할 수 있는 KMS 키를 제한합니다. 두 키링의 입력 객체는 권장 검색 필터를 사용합니다. 다음 예제에서는 AWS KMS 검색 키링 및 검색 필터를 사용하여 데이터를 복호화하는 패턴을 보여줍니다. 1단계: AWS Encryption SDK 및 재료 공급자 라이브러리를 인스턴스화합니다. ``` // Instantiate the AWS Encryption SDK and material providers var esdk = new ESDK(new AwsEncryptionSdkConfig()); var mpl = new MaterialProviders(new MaterialProvidersConfig()); ``` 2단계: 키링에 대한 입력 객체를 생성합니다. 키링 메서드의 파라미터를 지정하려면 입력 객체를 생성합니다. AWS Encryption SDK for .NET의 각 키링 메서드에는 해당 입력 객체가 있습니다. 이 예제에서는 `CreateAwsKmsDiscoveryKeyring()` 메서드를 사용하여 키링을 만들기 때문에 입력에 대한 `CreateAwsKmsDiscoveryKeyringInput` 클래스를 인스턴스화합니다. ``` List accounts = new List { "111122223333" }; var discoveryKeyringInput = new CreateAwsKmsDiscoveryKeyringInput { KmsClient = new AmazonKeyManagementServiceClient(), DiscoveryFilter = new DiscoveryFilter() { AccountIds = accounts, Partition = "aws" } }; ``` 3단계: 키링을 생성합니다. 이 예제에서는 복호화 키링을 생성하기 위해 `CreateAwsKmsDiscoveryKeyring()` 메서드와 키링 입력 객체를 사용합니다. ``` var discoveryKeyring = materialProviders.CreateAwsKmsDiscoveryKeyring(discoveryKeyringInput); ``` 4단계: 복호화에 대한 입력 객체를 생성합니다. `Decrypt()` 메서드의 입력 객체를 만들려면 `DecryptInput` 클래스를 인스턴스화합니다. `Ciphertext` 파라미터의 값은 `Encrypt()` 메서드가 반환하는 `EncryptOutput` 객체의 `Ciphertext` 멤버입니다. AWS Encryption SDK for .NET 버전 4.*x*에서는 선택적 `EncryptionContext` 파라미터를 사용하여 `Decrypt()` 메서드에서 암호화 컨텍스트를 지정할 수 있습니다. `EncryptionContext` 파라미터를 사용하여 암호화에 사용된 암호화 컨텍스트가 사이퍼텍스트를 복호화하는 데 사용되는 암호화 컨텍스트에 *포함되어 있는지* 확인합니다. 는 기본 알고리즘 제품군과 같이 서명과 함께 알고리즘 제품군을 사용하는 경우 디지털 서명을 포함하여 암호화 컨텍스트에 페어를 AWS Encryption SDK 추가합니다. ``` var ciphertext = encryptOutput.Ciphertext; var decryptInput = new DecryptInput { Ciphertext = ciphertext, Keyring = discoveryKeyring, EncryptionContext = encryptionContext // OPTIONAL }; var decryptOutput = encryptionSdk.Decrypt(decryptInput); ``` 5단계: 암호화 컨텍스트 - 버전 3.*x*를 확인합니다. AWS Encryption SDK for .NET 버전 3.*x*의 `Decrypt()` 메서드는에서 암호화 컨텍스트를 취하지 않습니다`Decrypt()`. 암호화된 메시지의 메타데이터에서 암호화 컨텍스트 값을 가져옵니다. 하지만 일반 텍스트를 반환하거나 사용하기 전에, 사이퍼텍스트를 복호화하는 데 사용된 암호화 컨텍스트에 암호화 시 제공한 암호화 컨텍스트가 포함되어 있는지 확인하는 것이 모범 사례입니다. 암호화에 사용된 암호화 컨텍스트가 사이퍼텍스트를 복호화하는 데 사용된 암호화 컨텍스트에 *포함되어 있는지* 확인합니다. 는 기본 알고리즘 제품군과 같이 서명과 함께 알고리즘 제품군을 사용하는 경우 디지털 서명을 포함하여 암호화 컨텍스트에 페어를 AWS Encryption SDK 추가합니다. ``` // Verify the encryption context string contextKey = "purpose"; string contextValue = "test"; if (!decryptOutput.EncryptionContext.TryGetValue(contextKey, out var decryptContextValue) || !decryptContextValue.Equals(contextValue)) { throw new Exception("Encryption context does not match expected values"); } ``` # AWS Encryption SDK Go용 이 주제에서는 AWS Encryption SDK for Go를 설치하고 사용하는 방법을 설명합니다. AWS Encryption SDK for Go를 사용한 프로그래밍에 대한 자세한 내용은 GitHub에서 aws-encryption-sdk 리포지토리의 [go](https://github.com/aws/aws-encryption-sdk/tree/mainline/releases/go/encryption-sdk/) 디렉터리를 참조하세요. AWS Encryption SDK for Go는 다음과 같은 점 AWS Encryption SDK 에서의 다른 프로그래밍 언어 구현과 다릅니다. + [데이터 키 캐싱](data-key-caching.md)은 지원되지 않습니다. 그러나 AWS Encryption SDK for Go는 대체 암호화 자료 캐싱 솔루션인 [AWS KMS 계층적 키링](use-hierarchical-keyring.md)을 지원합니다. + 스트리밍 데이터가 지원되지 않음 AWS Encryption SDK for Go에는의 다른 언어 구현 버전 2.0.*x* 이상에 도입된 모든 보안 기능이 포함되어 있습니다 AWS Encryption SDK. 그러나 AWS Encryption SDK for Go를 사용하여의 다른 언어 구현인 2.0.*x* 이전 버전으로 암호화된 데이터를 복호화 AWS Encryption SDK하는 경우 [커밋 정책을](concepts.md#commitment-policy) 조정해야 할 수 있습니다. 자세한 내용은 [커밋 정책 설정 방법](migrate-commitment-policy.md#migrate-commitment-step1)을 참조하세요. AWS Encryption SDK for Go는 사양을 작성하는 공식 확인 언어인 [Dafny](https://github.com/dafny-lang/dafny/blob/master/README.md) AWS Encryption SDK 의 제품이며, 이를 구현할 코드와 이를 테스트하기 위한 증거입니다. 그 결과, 기능적 정확성을 보장하는 프레임워크에서 AWS Encryption SDK 의 기능을 구현하는 라이브러리가 탄생했습니다. **자세히 알아보기** + 대체 알고리즘 제품군 지정 AWS Encryption SDK, 암호화된 데이터 키 제한, AWS KMS 다중 리전 키 사용 등에서 옵션을 구성하는 방법을 보여주는 예제는 섹션을 참조하세요[구성 AWS Encryption SDK](configure.md). + AWS Encryption SDK for Go를 구성하고 사용하는 방법을 보여주는 예제는 GitHub의 aws-encryption-sdk 리포지토리에 있는 [Go 예제](https://github.com/aws/aws-encryption-sdk/tree/mainline/releases/go/encryption-sdk/examples)를 참조하세요. **Topics** + [사전 조건](#prerequisites-go) + [설치](#go-installation) ## 사전 조건 AWS Encryption SDK for Go를 설치하기 전에 다음 사전 조건이 있는지 확인합니다. **Go의 지원되는 버전** Go용 에는 AWS Encryption SDK Go 1.23 이상이 필요합니다. Go 다운로드 및 설치에 대한 자세한 내용은 [Go installation](https://go.dev/doc/install)을 참조하세요. ## 설치 최신 버전의 AWS Encryption SDK for Go를 설치합니다. for Go 설치 및 빌드 AWS Encryption SDK 에 대한 자세한 내용은 GitHub에서 aws-encryption-sdk 리포지토리의 go 디렉터리에 있는 [README.md](https://github.com/aws/aws-encryption-sdk/tree/mainline/releases/go/encryption-sdk/README.md) 참조하십시오. **최신 버전 설치** + AWS Encryption SDK for Go 설치 ``` go get github.com/aws/aws-encryption-sdk/releases/go/encryption-sdk@latest ``` + [암호화 자료 공급자 라이브러리](https://github.com/aws/aws-cryptographic-material-providers-library)(MPL) 설치 ``` go get github.com/aws/aws-cryptographic-material-providers-library/releases/go/mpl ``` # AWS Encryption SDK for Java 이 주제에서는 AWS Encryption SDK for Java를 설치 및 사용하는 방법을 설명합니다. 를 사용한 프로그래밍에 대한 자세한 내용은 GitHub의 [aws-encryption-sdk-java](https://github.com/aws/aws-encryption-sdk-java/) 리포지토리를 AWS Encryption SDK for Java참조하세요. API 설명서를 보려면 AWS Encryption SDK for Java용 [Javadoc](https://aws.github.io/aws-encryption-sdk-java/)을 참조하세요. **Topics** + [사전 조건](#java-prerequisites) + [설치](#java-installation) + [예제](java-example-code.md) ## 사전 조건 를 설치하기 전에 다음 사전 조건이 있는지 AWS Encryption SDK for Java확인합니다. **Java 개발 환경** Java 8 이상이 필요합니다. Oracle 웹 사이트에서 [Java SE 다운로드](https://www.oracle.com/java/technologies/downloads/)로 이동한 다음 Java SE Development Kit(JDK)를 다운로드하여 설치합니다. Oracle JDK를 사용하는 경우 [Java Cryptography Extension(JCE) Unlimited Strength Jurisdiction Policy File](http://www.oracle.com/java/technologies/javase-jce8-downloads.html)도 다운로드하여 설치해야 합니다. **Bouncy Castle** 에는 [Bouncy Castle](https://www.bouncycastle.org/download/bouncy-castle-java/)이 AWS Encryption SDK for Java 필요합니다. + AWS Encryption SDK for Java 버전 1.6.1 이상에서는 Bouncy Castle을 사용하여 암호화 객체를 직렬화하고 역직렬화합니다. 이 요구 사항을 충족하기 위해 Bouncy Castle 또는 [Bouncy Castle FIPS](https://www.bouncycastle.org/about/bouncy-castle-fips-faq/)를 사용할 수 있습니다. Bouncy Castle FIPS 설치 및 구성에 대한 도움말은 [BC FIPS 설명서](https://www.bouncycastle.org/documentation/), 특히 **사용 설명서** 및 **보안 정책** PDF를 참조하세요. + 이전 버전의 에서는 Java용 Bouncy Castle의 암호화 API를 AWS Encryption SDK for Java 사용합니다. 이 요구 사항은 비 FIPS Bouncy Castle만 만족합니다. Bouncy Castle이 없는 경우 [Java용 Bouncy Castle 다운로드](https://bouncycastle.org/download/bouncy-castle-java/)로 이동하여 JDK에 해당하는 공급자 파일을 다운로드합니다. [Apache Maven](https://maven.apache.org/)을 사용하여 표준 Bouncy Castle 공급자([bcprov-ext-jdk15on](https://mvnrepository.com/artifact/org.bouncycastle/bcprov-ext-jdk15on))용 아티팩트 또는 Bouncy Castle FIPS([bc-fips](https://mvnrepository.com/artifact/org.bouncycastle/bc-fips))용 아티팩트를 가져올 수 있습니다. **AWS SDK for Java** 의 버전 3.*x*에는 AWS KMS 키링을 사용하지 AWS SDK for Java 2.x않더라도가 AWS Encryption SDK for Java 필요합니다. 버전 2.*x* 이하 AWS Encryption SDK for Java 에서는가 필요하지 않습니다 AWS SDK for Java. 그러나 [AWS Key Management Service](https://aws.amazon.com/kms/) (AWS KMS)를 마스터 키 공급자로 사용하려면 AWS SDK for Java 가 필요합니다. AWS Encryption SDK for Java 버전 2.4.0부터는 1.x 및 2.x용 AWS SDK for Java. AWS Encryption SDK code 버전 AWS SDK for Java 1.x 및 2.x를 모두 AWS Encryption SDK for Java 지원하며 상호 운용할 수 있습니다. 예를 들어, AWS SDK for Java 가1.x를 지원하는 AWS Encryption SDK 코드로 데이터를 암호화하고가 지원하는 코드 AWS SDK for Java 2.x (또는 그 반대)를 사용하여 복호화할 수 있습니다. 2.4.0 AWS Encryption SDK for Java 이전 버전의는 AWS SDK for Java 1.x만 지원합니다. 버전 업데이트에 대한 자세한 내용은 섹션을 AWS Encryption SDK참조하세요[마이그레이션 AWS Encryption SDK](migration.md). AWS Encryption SDK for Java 코드를 AWS SDK for Java 1.x에서 로 업데이트할 때 [`AWSKMS` 인터페이스](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/kms/package-summary.html) in AWS SDK for Java 1.x에 대한 참조를 [`KmsClient` 인터페이스](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/kms/package-summary.html) in에 대한 참조로 AWS SDK for Java 2.x바꿉니다 AWS SDK for Java 2.x. AWS Encryption SDK for Java 는 [`KmsAsyncClient` 인터페이스를](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/kms/KmsAsyncClient.html) 지원하지 않습니다. 또한 `kms` 네임스페이스 대신 `kmssdkv2` 네임스페이스의 AWS KMS관련 객체를 사용하도록 코드를 업데이트하세요. 를 설치하려면 Apache Maven을 AWS SDK for Java사용합니다. + [전체 AWS SDK for Java를 종속성으로 가져오려면](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/setup-project-maven.html#build-the-entire-sdk-into-your-project) `pom.xml` 파일에 선언하세요. + AWS SDK for Java 1.x의 AWS KMS 모듈에 대해서만 종속성을 생성하려면 [특정 모듈 지정](https://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/setup-project-maven.html#modules-dependencies) 지침을 따르고를 `artifactId`로 설정합니다`aws-java-sdk-kms`. + AWS SDK for Java 2.x의 AWS KMS 모듈에 대해서만 종속성을 생성하려면 [특정 모듈 지정](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/setup-project-maven.html#modules-dependencies) 지침을 따르세요. `groupId`를 `software.amazon.awssdk`로, `artifactId`를 `kms`로 설정합니다. 자세한 내용은 AWS SDK for Java 2.x 개발자 안내서[의 AWS SDK for Java 1.x와 2.x의 차이점](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/migration-whats-different.html)을 참조하세요. AWS Encryption SDK 개발자 안내서의 Java 예제에서는를 사용합니다 AWS SDK for Java 2.x. ## 설치 AWS Encryption SDK for Java의 최신 버전을 설치합니다. **참고** 2.0.0 AWS Encryption SDK for Java 이전의 모든 버전은 [end-of-support 단계에](https://docs.aws.amazon.com/sdkref/latest/guide/maint-policy.html#version-life-cycle) 있습니다. 코드나 데이터를 변경하지 않고 버전 2.0.*x* 이상에서 AWS Encryption SDK for Java 의 최신 버전으로 안전하게 업데이트할 수 있습니다. 그러나 버전 2.0.*x*에 도입된 [새로운 보안 기능](about-versions.md#version-2)은 이하 버전과 호환되지 않습니다. 1.7.*x* 이하 버전에서 2.0.*x* 이상 버전으로 업데이트하려면 먼저 AWS Encryption SDK의 최신 1.*x* 버전으로 업데이트해야 합니다. 자세한 내용은 [마이그레이션 AWS Encryption SDK](migration.md)을 참조하세요. 다음과 같은 AWS Encryption SDK for Java 방법으로를 설치할 수 있습니다. **직접** 를 설치하려면 [aws-encryption-sdk-java](https://github.com/aws/aws-encryption-sdk-java/) GitHub 리포지토리를 AWS Encryption SDK for Java복제하거나 다운로드합니다. **Apache Maven 사용** AWS Encryption SDK for Java 는 다음 종속성 정의와 함께 [Apache Maven](https://maven.apache.org/)을 통해 사용할 수 있습니다. ``` com.amazonaws aws-encryption-sdk-java 3.0.0 ``` SDK를 설치한 후에는 이 가이드의 [예제 Java 코드](java-example-code.md)와 [GitHub의 Javadoc](https://aws.github.io/aws-encryption-sdk-java/)을 살펴보는 것부터 시작하세요. # AWS Encryption SDK for Java 예제 다음 예제에서는를 사용하여 데이터를 암호화하고 복호화 AWS Encryption SDK for Java 하는 방법을 보여줍니다. 이 예제에서는 버전 3.*x* 이상을 사용하는 방법을 보여줍니다 AWS Encryption SDK for Java. 의 버전 3.*x*에는가 AWS Encryption SDK for Java 필요합니다 AWS SDK for Java 2.x. 의 버전 3.*x*는 [마스터 키 공급자](concepts.md#master-key-provider)를 키링으로 AWS Encryption SDK for Java 대체합니다. [키링 및 마스터 키 공급자](concepts.md#keyring) 이하 버전을 사용하는 예제의 경우 GitHub의 [aws-encryption-sdk-java](https://github.com/aws/aws-encryption-sdk-java/) 리포지토리의 [릴리스](https://github.com/aws/aws-encryption-sdk-java/releases) 목록에서 해당하는 릴리스를 찾을 수 있습니다. **Topics** + [문자열](#java-example-strings) + [바이트 스트림](#java-example-streams) + [여러 마스터 키 공급자를 사용하는 바이트 스트림](#java-example-multiple-providers) ## 문자열 암호화 및 복호화 다음 예제에서는의 버전 3.*x* AWS Encryption SDK for Java 를 사용하여 문자열을 암호화하고 복호화하는 방법을 보여줍니다. 문자열을 사용하기 전에 바이트 배열로 변환하세요. 이 예제에서는 [AWS KMS 키링](use-kms-keyring.md)을 사용합니다. AWS KMS 키링으로 암호화할 때 키 ID, 키 ARN, 별칭 이름 또는 별칭 ARN을 사용하여 KMS 키를 식별할 수 있습니다. 복호화할 때 키 ARN을 사용하여 KMS 키를 식별해야 합니다. `encryptData()` 메서드를 호출하면 사이퍼텍스트, 암호화된 데이터 키 및 암호화 컨텍스트를 포함하는 [암호화된 메시지](concepts.md#message)(`CryptoResult`)가 반환됩니다. `CryptoResult` 객체에서 `getResult`를 호출하면 `decryptData()` 메서드에 전달할 수 있는 [암호화된 메시지](message-format.md)의 base-64 인코딩 문자열 버전이 반환됩니다. 마찬가지로 `decryptData()`를 호출할 때 반환되는 `CryptoResult` 객체에는 일반 텍스트 메시지와 AWS KMS key ID가 포함됩니다. 애플리케이션이 일반 텍스트를 반환하기 전에 암호화된 메시지의 AWS KMS key ID와 암호화 컨텍스트가 예상한 것인지 확인합니다. ``` // Copyright Amazon.com Inc. or its affiliates. All Rights Reserved. // SPDX-License-Identifier: Apache-2.0 package com.amazonaws.crypto.keyrings; import com.amazonaws.encryptionsdk.AwsCrypto; import com.amazonaws.encryptionsdk.CommitmentPolicy; import com.amazonaws.encryptionsdk.CryptoResult; import software.amazon.cryptography.materialproviders.IKeyring; import software.amazon.cryptography.materialproviders.MaterialProviders; import software.amazon.cryptography.materialproviders.model.CreateAwsKmsMultiKeyringInput; import software.amazon.cryptography.materialproviders.model.MaterialProvidersConfig; import java.nio.charset.StandardCharsets; import java.util.Arrays; import java.util.Collections; import java.util.Map; /** * Encrypts and then decrypts data using an AWS KMS Keyring. * *

Arguments: * *

    *
  1. Key ARN: For help finding the Amazon Resource Name (ARN) of your AWS KMS customer master * key (CMK), see 'Viewing Keys' at * http://docs.aws.amazon.com/kms/latest/developerguide/viewing-keys.html *
*/ public class BasicEncryptionKeyringExample { private static final byte[] EXAMPLE_DATA = "Hello World".getBytes(StandardCharsets.UTF_8); public static void main(final String[] args) { final String keyArn = args[0]; encryptAndDecryptWithKeyring(keyArn); } public static void encryptAndDecryptWithKeyring(final String keyArn) { // 1. Instantiate the SDK // This builds the AwsCrypto client with the RequireEncryptRequireDecrypt commitment policy, // which means this client only encrypts using committing algorithm suites and enforces // that the client will only decrypt encrypted messages that were created with a committing // algorithm suite. // This is the default commitment policy if you build the client with // `AwsCrypto.builder().build()` // or `AwsCrypto.standard()`. final AwsCrypto crypto = AwsCrypto.builder() .withCommitmentPolicy(CommitmentPolicy.RequireEncryptRequireDecrypt) .build(); // 2. Create the AWS KMS keyring. // This example creates a multi keyring, which automatically creates the KMS client. final MaterialProviders materialProviders = MaterialProviders.builder() .MaterialProvidersConfig(MaterialProvidersConfig.builder().build()) .build(); final CreateAwsKmsMultiKeyringInput keyringInput = CreateAwsKmsMultiKeyringInput.builder().generator(keyArn).build(); final IKeyring kmsKeyring = materialProviders.CreateAwsKmsMultiKeyring(keyringInput); // 3. Create an encryption context // We recommend using an encryption context whenever possible // to protect integrity. This sample uses placeholder values. // For more information see: // blogs.aws.amazon.com/security/post/Tx2LZ6WBJJANTNW/How-to-Protect-the-Integrity-of-Your-Encrypted-Data-by-Using-AWS-Key-Management final Map encryptionContext = Collections.singletonMap("ExampleContextKey", "ExampleContextValue"); // 4. Encrypt the data final CryptoResult encryptResult = crypto.encryptData(kmsKeyring, EXAMPLE_DATA, encryptionContext); final byte[] ciphertext = encryptResult.getResult(); // 5. Decrypt the data final CryptoResult decryptResult = crypto.decryptData( kmsKeyring, ciphertext, // Verify that the encryption context in the result contains the // encryption context supplied to the encryptData method encryptionContext); // 6. Verify that the decrypted plaintext matches the original plaintext assert Arrays.equals(decryptResult.getResult(), EXAMPLE_DATA); } } ``` ## 바이트 스트림 암호화 및 복호화 다음 예제에서는를 사용하여 바이트 스트림을 암호화하고 복호화 AWS Encryption SDK 하는 방법을 보여줍니다. 이 예제에서는 [원시 AES 키링](use-raw-aes-keyring.md)을 사용합니다. 암호화할 때 이 예제에서는 `AwsCrypto.builder() .withEncryptionAlgorithm()` 메서드를 사용하여 [디지털 서명](concepts.md#digital-sigs)이 없는 알고리즘 제품군을 지정합니다. 이 예제에서는 복호화할 때 사이퍼텍스트에 서명이 없는지 확인하기 위해 `createUnsignedMessageDecryptingStream()` 메서드를 사용합니다. 디지털 서명이 있는 사이퍼텍스트가 발생하면 `createUnsignedMessageDecryptingStream()` 메서드가 실패합니다. 디지털 서명이 포함된 기본 알고리즘 제품군으로 암호화하는 경우 다음 예제와 같이 `createDecryptingStream()` 메서드를 대신 사용하세요. ``` // Copyright Amazon.com Inc. or its affiliates. All Rights Reserved. // SPDX-License-Identifier: Apache-2.0 package com.amazonaws.crypto.keyrings; import com.amazonaws.encryptionsdk.AwsCrypto; import com.amazonaws.encryptionsdk.CommitmentPolicy; import com.amazonaws.encryptionsdk.CryptoAlgorithm; import com.amazonaws.encryptionsdk.CryptoInputStream; import com.amazonaws.encryptionsdk.jce.JceMasterKey; import com.amazonaws.util.IOUtils; import software.amazon.cryptography.materialproviders.IKeyring; import software.amazon.cryptography.materialproviders.MaterialProviders; import software.amazon.cryptography.materialproviders.model.AesWrappingAlg; import software.amazon.cryptography.materialproviders.model.CreateRawAesKeyringInput; import software.amazon.cryptography.materialproviders.model.MaterialProvidersConfig; import java.io.FileInputStream; import java.io.FileOutputStream; import java.io.IOException; import java.nio.ByteBuffer; import java.security.SecureRandom; import java.util.Collections; import java.util.Map; import javax.crypto.SecretKey; import javax.crypto.spec.SecretKeySpec; /** *

* Encrypts and then decrypts a file under a random key. * *

* Arguments: *

    *
  1. Name of file containing plaintext data to encrypt *
* *

* This program demonstrates using a standard Java {@link SecretKey} object as a {@link IKeyring} to * encrypt and decrypt streaming data. */ public class FileStreamingKeyringExample { private static String srcFile; public static void main(String[] args) throws IOException { srcFile = args[0]; // In this example, we generate a random key. In practice, // you would get a key from an existing store SecretKey cryptoKey = retrieveEncryptionKey(); // Create a Raw Aes Keyring using the random key and an AES-GCM encryption algorithm final MaterialProviders materialProviders = MaterialProviders.builder() .MaterialProvidersConfig(MaterialProvidersConfig.builder().build()) .build(); final CreateRawAesKeyringInput keyringInput = CreateRawAesKeyringInput.builder() .wrappingKey(ByteBuffer.wrap(cryptoKey.getEncoded())) .keyNamespace("Example") .keyName("RandomKey") .wrappingAlg(AesWrappingAlg.ALG_AES128_GCM_IV12_TAG16) .build(); IKeyring keyring = materialProviders.CreateRawAesKeyring(keyringInput); // Instantiate the SDK. // This builds the AwsCrypto client with the RequireEncryptRequireDecrypt commitment policy, // which means this client only encrypts using committing algorithm suites and enforces // that the client will only decrypt encrypted messages that were created with a committing // algorithm suite. // This is the default commitment policy if you build the client with // `AwsCrypto.builder().build()` // or `AwsCrypto.standard()`. // This example encrypts with an algorithm suite that doesn't include signing for faster decryption, // since this use case assumes that the contexts that encrypt and decrypt are equally trusted. final AwsCrypto crypto = AwsCrypto.builder() .withCommitmentPolicy(CommitmentPolicy.RequireEncryptRequireDecrypt) .withEncryptionAlgorithm(CryptoAlgorithm.ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY) .build(); // Create an encryption context to identify the ciphertext Map context = Collections.singletonMap("Example", "FileStreaming"); // Because the file might be too large to load into memory, we stream the data, instead of //loading it all at once. FileInputStream in = new FileInputStream(srcFile); CryptoInputStream encryptingStream = crypto.createEncryptingStream(keyring, in, context); FileOutputStream out = new FileOutputStream(srcFile + ".encrypted"); IOUtils.copy(encryptingStream, out); encryptingStream.close(); out.close(); // Decrypt the file. Verify the encryption context before returning the plaintext. // Since the data was encrypted using an unsigned algorithm suite, use the recommended // createUnsignedMessageDecryptingStream method, which only accepts unsigned messages. in = new FileInputStream(srcFile + ".encrypted"); CryptoInputStream decryptingStream = crypto.createUnsignedMessageDecryptingStream(keyring, in); // Does it contain the expected encryption context? if (!"FileStreaming".equals(decryptingStream.getCryptoResult().getEncryptionContext().get("Example"))) { throw new IllegalStateException("Bad encryption context"); } // Write the plaintext data to disk. out = new FileOutputStream(srcFile + ".decrypted"); IOUtils.copy(decryptingStream, out); decryptingStream.close(); out.close(); } /** * In practice, this key would be saved in a secure location. * For this demo, we generate a new random key for each operation. */ private static SecretKey retrieveEncryptionKey() { SecureRandom rnd = new SecureRandom(); byte[] rawKey = new byte[16]; // 128 bits rnd.nextBytes(rawKey); return new SecretKeySpec(rawKey, "AES"); } } ``` ## 다중 키 링을 사용하여 바이트 스트림 암호화 및 복호화 다음 예제에서는 [다중 키 링](use-multi-keyring.md)과 AWS Encryption SDK 함께를 사용하는 방법을 보여줍니다. 다중 키링을 사용하여 데이터를 암호화하는 경우 해당 키링의 모든 래핑 키로 해당 데이터를 복호화할 수 있습니다. 이 예제에서는 [AWS KMS 키링](use-kms-keyring.md)과 [Raw RSA 키링](use-raw-rsa-keyring.md)을 하위 키링으로 사용합니다. 이 예제는 [디지털 서명](concepts.md#digital-sigs)이 포함된 [기본 알고리즘 제품군](supported-algorithms.md)을 사용하여 암호화합니다. 스트리밍할 때는 무결성 검사 후 디지털 서명을 확인하기 전에 일반 텍스트를 AWS Encryption SDK 릴리스합니다. 서명이 확인될 때까지 일반 텍스트를 사용하지 않도록 이 예제에서는 일반 텍스트를 버퍼링하고 복호화 및 확인이 완료될 때만 디스크에 씁니다. ``` // Copyright Amazon.com Inc. or its affiliates. All Rights Reserved. // SPDX-License-Identifier: Apache-2.0 package com.amazonaws.crypto.keyrings; import com.amazonaws.encryptionsdk.AwsCrypto; import com.amazonaws.encryptionsdk.CommitmentPolicy; import com.amazonaws.encryptionsdk.CryptoOutputStream; import com.amazonaws.util.IOUtils; import software.amazon.cryptography.materialproviders.IKeyring; import software.amazon.cryptography.materialproviders.MaterialProviders; import software.amazon.cryptography.materialproviders.model.CreateAwsKmsMultiKeyringInput; import software.amazon.cryptography.materialproviders.model.CreateMultiKeyringInput; import software.amazon.cryptography.materialproviders.model.CreateRawRsaKeyringInput; import software.amazon.cryptography.materialproviders.model.MaterialProvidersConfig; import software.amazon.cryptography.materialproviders.model.PaddingScheme; import java.io.ByteArrayInputStream; import java.io.ByteArrayOutputStream; import java.io.FileInputStream; import java.io.FileOutputStream; import java.nio.ByteBuffer; import java.security.GeneralSecurityException; import java.security.KeyPair; import java.security.KeyPairGenerator; import java.util.Collections; /** *

* Encrypts a file using both AWS KMS Key and an asymmetric key pair. * *

* Arguments: *

    *
  1. Key ARN: For help finding the Amazon Resource Name (ARN) of your AWS KMS key, * see 'Viewing Keys' at http://docs.aws.amazon.com/kms/latest/developerguide/viewing-keys.html * *
  2. Name of file containing plaintext data to encrypt *
*

* You might use AWS Key Management Service (AWS KMS) for most encryption and decryption operations, but * still want the option of decrypting your data offline independently of AWS KMS. This sample * demonstrates one way to do this. *

* The sample encrypts data under both an AWS KMS key and an "escrowed" RSA key pair * so that either key alone can decrypt it. You might commonly use the AWS KMS key for decryption. However, * at any time, you can use the private RSA key to decrypt the ciphertext independent of AWS KMS. *

* This sample uses the RawRsaKeyring to generate a RSA public-private key pair * and saves the key pair in memory. In practice, you would store the private key in a secure offline * location, such as an offline HSM, and distribute the public key to your development team. */ public class EscrowedEncryptKeyringExample { private static ByteBuffer publicEscrowKey; private static ByteBuffer privateEscrowKey; public static void main(final String[] args) throws Exception { // This sample generates a new random key for each operation. // In practice, you would distribute the public key and save the private key in secure // storage. generateEscrowKeyPair(); final String kmsArn = args[0]; final String fileName = args[1]; standardEncrypt(kmsArn, fileName); standardDecrypt(kmsArn, fileName); escrowDecrypt(fileName); } private static void standardEncrypt(final String kmsArn, final String fileName) throws Exception { // Encrypt with the KMS key and the escrowed public key // 1. Instantiate the SDK // This builds the AwsCrypto client with the RequireEncryptRequireDecrypt commitment policy, // which means this client only encrypts using committing algorithm suites and enforces // that the client will only decrypt encrypted messages that were created with a committing // algorithm suite. // This is the default commitment policy if you build the client with // `AwsCrypto.builder().build()` // or `AwsCrypto.standard()`. final AwsCrypto crypto = AwsCrypto.builder() .withCommitmentPolicy(CommitmentPolicy.RequireEncryptRequireDecrypt) .build(); // 2. Create the AWS KMS keyring. // This example creates a multi keyring, which automatically creates the KMS client. final MaterialProviders matProv = MaterialProviders.builder() .MaterialProvidersConfig(MaterialProvidersConfig.builder().build()) .build(); final CreateAwsKmsMultiKeyringInput keyringInput = CreateAwsKmsMultiKeyringInput.builder() .generator(kmsArn) .build(); IKeyring kmsKeyring = matProv.CreateAwsKmsMultiKeyring(keyringInput); // 3. Create the Raw Rsa Keyring with Public Key. final CreateRawRsaKeyringInput encryptingKeyringInput = CreateRawRsaKeyringInput.builder() .keyName("Escrow") .keyNamespace("Escrow") .paddingScheme(PaddingScheme.OAEP_SHA512_MGF1) .publicKey(publicEscrowKey) .build(); IKeyring rsaPublicKeyring = matProv.CreateRawRsaKeyring(encryptingKeyringInput); // 4. Create the multi-keyring. final CreateMultiKeyringInput createMultiKeyringInput = CreateMultiKeyringInput.builder() .generator(kmsKeyring) .childKeyrings(Collections.singletonList(rsaPublicKeyring)) .build(); IKeyring multiKeyring = matProv.CreateMultiKeyring(createMultiKeyringInput); // 5. Encrypt the file // To simplify this code example, we omit the encryption context. Production code should always // use an encryption context. final FileInputStream in = new FileInputStream(fileName); final FileOutputStream out = new FileOutputStream(fileName + ".encrypted"); final CryptoOutputStream encryptingStream = crypto.createEncryptingStream(multiKeyring, out); IOUtils.copy(in, encryptingStream); in.close(); encryptingStream.close(); } private static void standardDecrypt(final String kmsArn, final String fileName) throws Exception { // Decrypt with the AWS KMS key and the escrow public key. // 1. Instantiate the SDK. // This builds the AwsCrypto client with the RequireEncryptRequireDecrypt commitment policy, // which means this client only encrypts using committing algorithm suites and enforces // that the client will only decrypt encrypted messages that were created with a committing // algorithm suite. // This is the default commitment policy if you build the client with // `AwsCrypto.builder().build()` // or `AwsCrypto.standard()`. final AwsCrypto crypto = AwsCrypto.builder() .withCommitmentPolicy(CommitmentPolicy.RequireEncryptRequireDecrypt) .build(); // 2. Create the AWS KMS keyring. // This example creates a multi keyring, which automatically creates the KMS client. final MaterialProviders matProv = MaterialProviders.builder() .MaterialProvidersConfig(MaterialProvidersConfig.builder().build()) .build(); final CreateAwsKmsMultiKeyringInput keyringInput = CreateAwsKmsMultiKeyringInput.builder() .generator(kmsArn) .build(); IKeyring kmsKeyring = matProv.CreateAwsKmsMultiKeyring(keyringInput); // 3. Create the Raw Rsa Keyring with Public Key. final CreateRawRsaKeyringInput encryptingKeyringInput = CreateRawRsaKeyringInput.builder() .keyName("Escrow") .keyNamespace("Escrow") .paddingScheme(PaddingScheme.OAEP_SHA512_MGF1) .publicKey(publicEscrowKey) .build(); IKeyring rsaPublicKeyring = matProv.CreateRawRsaKeyring(encryptingKeyringInput); // 4. Create the multi-keyring. final CreateMultiKeyringInput createMultiKeyringInput = CreateMultiKeyringInput.builder() .generator(kmsKeyring) .childKeyrings(Collections.singletonList(rsaPublicKeyring)) .build(); IKeyring multiKeyring = matProv.CreateMultiKeyring(createMultiKeyringInput); // 5. Decrypt the file // To simplify this code example, we omit the encryption context. Production code should always // use an encryption context. final FileInputStream in = new FileInputStream(fileName + ".encrypted"); final FileOutputStream out = new FileOutputStream(fileName + ".decrypted"); // Since we are using a signing algorithm suite, we avoid streaming decryption directly to the output file, // to ensure that the trailing signature is verified before writing any untrusted plaintext to disk. final ByteArrayOutputStream plaintextBuffer = new ByteArrayOutputStream(); final CryptoOutputStream decryptingStream = crypto.createDecryptingStream(multiKeyring, plaintextBuffer); IOUtils.copy(in, decryptingStream); in.close(); decryptingStream.close(); final ByteArrayInputStream plaintextReader = new ByteArrayInputStream(plaintextBuffer.toByteArray()); IOUtils.copy(plaintextReader, out); out.close(); } private static void escrowDecrypt(final String fileName) throws Exception { // You can decrypt the stream using only the private key. // This method does not call AWS KMS. // 1. Instantiate the SDK final AwsCrypto crypto = AwsCrypto.standard(); // 2. Create the Raw Rsa Keyring with Private Key. final MaterialProviders matProv = MaterialProviders.builder() .MaterialProvidersConfig(MaterialProvidersConfig.builder().build()) .build(); final CreateRawRsaKeyringInput encryptingKeyringInput = CreateRawRsaKeyringInput.builder() .keyName("Escrow") .keyNamespace("Escrow") .paddingScheme(PaddingScheme.OAEP_SHA512_MGF1) .publicKey(publicEscrowKey) .privateKey(privateEscrowKey) .build(); IKeyring escrowPrivateKeyring = matProv.CreateRawRsaKeyring(encryptingKeyringInput); // 3. Decrypt the file // To simplify this code example, we omit the encryption context. Production code should always // use an encryption context. final FileInputStream in = new FileInputStream(fileName + ".encrypted"); final FileOutputStream out = new FileOutputStream(fileName + ".deescrowed"); final CryptoOutputStream decryptingStream = crypto.createDecryptingStream(escrowPrivateKeyring, out); IOUtils.copy(in, decryptingStream); in.close(); decryptingStream.close(); } private static void generateEscrowKeyPair() throws GeneralSecurityException { final KeyPairGenerator kg = KeyPairGenerator.getInstance("RSA"); kg.initialize(4096); // Escrow keys should be very strong final KeyPair keyPair = kg.generateKeyPair(); publicEscrowKey = RawRsaKeyringExample.getPEMPublicKey(keyPair.getPublic()); privateEscrowKey = RawRsaKeyringExample.getPEMPrivateKey(keyPair.getPrivate()); } } ``` # AWS Encryption SDK for JavaScript AWS Encryption SDK for JavaScript 는 JavaScript로 웹 브라우저 애플리케이션을 작성하거나 Node.js로 웹 서버 애플리케이션을 작성하는 개발자를 위한 클라이언트 측 암호화 라이브러리를 제공하도록 설계되었습니다. 의 모든 구현과 마찬가지로 AWS Encryption SDK는 고급 데이터 보호 기능을 AWS Encryption SDK for JavaScript 제공합니다. 이러한 기능에는 [봉투 암호화](concepts.md#envelope-encryption), 추가 인증 데이터(AAD), 안전하고 인증된 대칭 키 [알고리즘 제품군](concepts.md#crypto-algorithm)(예: 키 유도 및 서명을 사용하는 256비트 AES-GCM)이 포함됩니다. 의 모든 언어별 구현 AWS Encryption SDK 은 언어의 제약 조건에 따라 상호 운용 가능하도록 설계되었습니다. JavaScript의 언어 제약에 대한 자세한 내용은 [의 호환성 AWS Encryption SDK for JavaScript](javascript-compatibility.md) 섹션을 참조하세요. **자세히 알아보기** + 를 사용한 프로그래밍에 대한 자세한 내용은 GitHub의 [aws-encryption-sdk-javascript](https://github.com/aws/aws-encryption-sdk-javascript/) 리포지토리를 AWS Encryption SDK for JavaScript참조하세요. + 프로그래밍 예제는 [AWS Encryption SDK for JavaScript 예제](js-examples.md) 문서와, [aws-encryption-sdk-javascript](https://github.com/aws/aws-encryption-sdk-javascript/) 리포지토리의 [example-browser](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/example-browser) 및 [example-node](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/example-node) 모듈을 참조하세요. + 를 사용하여 웹 애플리케이션에서 데이터를 AWS Encryption SDK for JavaScript 암호화하는 실제 예제는 AWS 보안 블로그의 [AWS Encryption SDK for JavaScript 및 Node.js를 사용하여 브라우저에서 암호화를 활성화하는 방법을](https://aws.amazon.com/blogs/security/how-to-enable-encryption-browser-aws-encryption-sdk-javascript-node-js/) 참조하세요. **Topics** + [호환성](javascript-compatibility.md) + [설치](javascript-installation.md) + [모듈](javascript-modules.md) + [예제](js-examples.md) # 의 호환성 AWS Encryption SDK for JavaScript AWS Encryption SDK for JavaScript 는의 다른 언어 구현과 상호 운용 가능하도록 설계되었습니다 AWS Encryption SDK. 대부분의 경우를 사용하여 데이터를 암호화 AWS Encryption SDK for JavaScript 하고 [AWS Encryption SDK 명령줄 인터페이스를](crypto-cli.md) 포함한 다른 언어 구현으로 데이터를 해독할 수 있습니다. 또한를 사용하여의 다른 언어 구현에서 생성된 [암호화된 메시지를](concepts.md#message) 복호화 AWS Encryption SDK for JavaScript 할 수 있습니다 AWS Encryption SDK. 그러나를 사용할 때는 JavaScript 언어 구현 및 웹 브라우저에서 몇 가지 호환성 문제를 알고 AWS Encryption SDK for JavaScript있어야 합니다. 또한 다른 언어 구현을 사용할 때는 호환 가능한 마스터 키 공급자, 마스터 키 및 키링을 구성해야 합니다. 자세한 내용은 [키링 호환성](choose-keyring.md#keyring-compatibility)을 참조하세요. ## AWS Encryption SDK for JavaScript 호환성 의 JavaScript 구현은 다음과 같은 점에서 다른 언어 구현과 AWS Encryption SDK 다릅니다. + 의 암호화 작업은 프레임 처리되지 않은 사이퍼텍스트를 반환하지 AWS Encryption SDK for JavaScript 않습니다. 그러나 AWS Encryption SDK for JavaScript 는의 다른 언어 구현에서 반환된 프레임 처리된 사이퍼텍스트와 프레임 처리되지 않은 사이퍼텍스트를 해독합니다 AWS Encryption SDK. + Node.js 버전 12.9.0 이상 Node.js는 다음 RSA 키 래핑 옵션을 지원합니다. + OAEP와 SHA1, SHA256, SHA384 또는 SHA512 + OAEP와 SHA1 및 MGF1과 SHA1 + PKCS1v15 + 버전 12.9.0 이전의 Node.js는 다음 RSA 키 래핑 옵션만 지원합니다. + OAEP와 SHA1 및 MGF1과 SHA1 + PKCS1v15 ## 브라우저 호환성 일부 웹 브라우저는 AWS Encryption SDK for JavaScript 에 필요한 기본 암호화 작업을 지원하지 않습니다. 브라우저에서 구현하는 WebCrypto API에 대한 폴백을 구성하여 일부 누락된 작업을 보완할 수 있습니다. **웹 브라우저 제한 사항** 다음 제한 사항은 모든 웹 브라우저에 공통적으로 적용됩니다. + WebCrypto API는 PKCS1v15 키 래핑을 지원하지 않습니다. + 브라우저는 192비트 키를 지원하지 않습니다. **필요한 암호화 작업** 를 사용하려면 웹 브라우저에서 다음 작업이 AWS Encryption SDK for JavaScript 필요합니다. 브라우저가 이러한 작업을 지원하지 않는 경우, AWS Encryption SDK for JavaScript와 호환되지 않습니다. + 브라우저는 암호화 방식으로 임의의 값을 생성하는 메서드인 `crypto.getRandomValues()`를 포함해야 합니다. `crypto.getRandomValues()`를 지원하는 웹 브라우저 버전에 대한 자세한 내용은 [crypto.getRandomValues()를 사용할 수 있나요?](https://caniuse.com/#feat=getrandomvalues)를 참조하세요. **필요한 폴백** 에는 웹 브라우저에서 다음과 같은 라이브러리 및 작업이 AWS Encryption SDK for JavaScript 필요합니다. 이러한 요구 사항을 충족하지 않는 웹 브라우저를 지원하는 경우 폴백을 구성해야 합니다. 그렇지 않으면 브라우저 AWS Encryption SDK for JavaScript 에서를 사용하려는 시도가 실패합니다. + 웹 애플리케이션에서 기본 암호화 작업을 수행하는 WebCrypto API는 일부 브라우저에서 사용할 수 없습니다. 웹 암호화를 지원하는 웹 브라우저 버전에 대한 자세한 내용은 [웹 암호화를 사용할 수 있나요?](https://caniuse.com/#feat=cryptography)를 참조하세요. + 최신 버전의 Safari 웹 브라우저는에 AWS Encryption SDK 필요한 0바이트의 AES-GCM 암호화를 지원하지 않습니다. 브라우저가 WebCrypto API를 구현하지만 AES-GCM을 사용하여 0바이트를 암호화할 수 없는 경우는 0바이트 암호화에만 폴백 라이브러리를 AWS Encryption SDK for JavaScript 사용합니다. 다른 모든 작업에는 WebCrypto API를 사용합니다. 두 가지 중 한 제한 사항에 폴백을 구성하려면 코드에 다음 문을 추가합니다. [configureFallback](https://github.com/aws/aws-encryption-sdk-javascript/blob/master/modules/web-crypto-backend/src/backend-factory.ts#L78) 함수에서 누락된 기능을 지원하는 라이브러리를 지정합니다. 다음 예제는 Microsoft Research JavaScript 암호화 라이브러리(`msrcrypto`)를 사용하지만 호환 가능한 라이브러리로 바꿀 수 있습니다. 전체 예제는 [fallback.ts](https://github.com/aws/aws-encryption-sdk-javascript/blob/master/modules/example-browser/src/fallback.ts)를 참조하세요. ``` import { configureFallback } from '@aws-crypto/client-browser' configureFallback(msrCrypto) ``` # 설치 AWS Encryption SDK for JavaScript 는 상호 종속 모듈 모음으로 AWS Encryption SDK for JavaScript 구성됩니다. 여러 모듈은 함께 작동하도록 설계된 모듈 모음일 뿐입니다. 일부 모듈은 독립적으로 작동하도록 설계됩니다. 모든 구현에는 몇 개의 모듈이 필요합니다. 다른 몇 개 모듈은 특수한 경우에만 필요합니다. JavaScript AWS Encryption SDK 용의 모듈에 대한 자세한 내용은 GitHub의 [aws-encryption-sdk-javascript](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules) 리포지토리에 있는 각 모듈의 [의 모듈 AWS Encryption SDK for JavaScript](javascript-modules.md) 및 `README.md` 파일을 참조하세요. **참고** 2.0.0 AWS Encryption SDK for JavaScript 이전의 모든 버전은 [end-of-support 단계에](https://docs.aws.amazon.com/sdkref/latest/guide/maint-policy.html#version-life-cycle) 있습니다. 코드나 데이터를 변경하지 않고 버전 2.0.*x* 이상에서 AWS Encryption SDK for JavaScript 의 최신 버전으로 안전하게 업데이트할 수 있습니다. 그러나 버전 2.0.*x*에 도입된 [새로운 보안 기능](about-versions.md#version-2)은 이하 버전과 호환되지 않습니다. 1.7.*x* 이하 버전에서 2.0.*x* 이상 버전으로 업데이트하려면 먼저 AWS Encryption SDK for JavaScript의 최신 1.*x* 버전으로 업데이트해야 합니다. 자세한 내용은 [마이그레이션 AWS Encryption SDK](migration.md)을 참조하세요. 모듈을 설치하려면 [npm 패키지 관리자](https://www.npmjs.com/get-npm)를 사용하세요. 예를 들어 Node.js AWS Encryption SDK for JavaScript 에서 로 프로그래밍해야 하는 모든 모듈이 포함된 `client-node` 모듈을 설치하려면 다음 명령을 사용합니다. ``` npm install @aws-crypto/client-node ``` AWS Encryption SDK for JavaScript 브라우저에서 로 프로그래밍해야 하는 모든 모듈이 포함된 `client-browser` 모듈을 설치하려면 다음 명령을 사용합니다. ``` npm install @aws-crypto/client-browser ``` 사용 방법에 대한 실제 예제는 GitHub의 [aws-encryption-sdk-javascript](https://github.com/aws/aws-encryption-sdk-javascript/) 리포지토리에 있는 `example-node` 및 `example-browser` 모듈의 예제를 AWS Encryption SDK for JavaScript참조하세요. # 의 모듈 AWS Encryption SDK for JavaScript 의 모듈을 AWS Encryption SDK for JavaScript 사용하면 프로젝트에 필요한 코드를 쉽게 설치할 수 있습니다. ## JavaScript Node.js 모듈 [client-node](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/client-node) Node.js AWS Encryption SDK for JavaScript 에서를 사용하여 프로그래밍해야 하는 모든 모듈을 포함합니다. [caching-materials-manager-node](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/caching-materials-manager-node) Node.js의에서 [데이터 키 캐싱](data-key-caching.md) 기능을 지원하는 함수 AWS Encryption SDK for JavaScript 를 내보냅니다. [decrypt-node](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/decrypt-node) 데이터 및 데이터 스트림을 나타내는 암호화된 메시지를 복호화하고 확인하는 함수를 내보냅니다. `client-node` 모듈에 포함됩니다. [encrypt-node](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/encrypt-node) 다양한 유형의 데이터를 암호화하고 서명하는 함수를 내보냅니다. `client-node` 모듈에 포함됩니다. [example-node](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/example-node) Node.js AWS Encryption SDK for JavaScript 에서를 사용한 프로그래밍의 실제 예제를 내보냅니다. 다양한 유형의 키링 및 다양한 유형의 데이터 예제를 포함합니다. [hkdf-node](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/hkdf-node) Node.js의가 특정 알고리즘 제품군 AWS Encryption SDK for JavaScript 에서 사용하는 [HMAC 기반 키 파생 함수](https://en.wikipedia.org/wiki/HKDF)(HKDF)를 내보냅니다. 브라우저 AWS Encryption SDK for JavaScript 의는 WebCrypto API의 기본 HKDF 함수를 사용합니다. [integration-node](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/integration-node) Node.js AWS Encryption SDK for JavaScript 의가의 다른 언어 구현과 호환되는지 확인하는 테스트를 정의합니다 AWS Encryption SDK. [kms-keyring-node](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/kms-keyring-node) Node.js에서 AWS KMS 키링을 지원하는 함수를 내보냅니다. [raw-aes-keyring-node](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/raw-aes-keyring-node) Node.js에서 [Raw AES 키링](use-raw-aes-keyring.md)을 지원하는 함수를 내보냅니다. [raw-rsa-keyring-node](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/raw-rsa-keyring-node) Node.js에서 [Raw RSA 키링](use-raw-rsa-keyring.md)을 지원하는 함수를 내보냅니다. ## JavaScript 브라우저용 모듈 [client-browser](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/client-browser) AWS Encryption SDK for JavaScript 브라우저에서를 사용하여 프로그래밍해야 하는 모든 모듈을 포함합니다. [caching-materials-manager-browser](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/caching-materials-manager-browser) 브라우저에서 JavaScript용으로 [데이터 키 캐싱](data-key-caching.md) 기능을 지원하는 함수를 내보냅니다. [decrypt-browser](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/decrypt-browser) 데이터 및 데이터 스트림을 나타내는 암호화된 메시지를 복호화하고 확인하는 함수를 내보냅니다. [encrypt-browser](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/encrypt-browser) 다양한 유형의 데이터를 암호화하고 서명하는 함수를 내보냅니다. [example-browser](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/example-browser) 브라우저 AWS Encryption SDK for JavaScript 에서를 사용한 프로그래밍의 실제 예제입니다. 다양한 유형의 키링 및 다양한 유형의 데이터 예제를 포함합니다. [integration-browser](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/integration-browser) 브라우저의 스크립트가 AWS Encryption SDK for Java의 다른 언어 구현과 호환되는지 확인하는 테스트를 정의합니다 AWS Encryption SDK. [kms-keyring-browser](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/kms-keyring-browser) 브라우저에서 [AWS KMS 키링](use-kms-keyring.md)을 지원하는 함수를 내보냅니다. [raw-aes-keyring-browser](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/raw-aes-keyring-browser) 브라우저에서 [Raw AES 키링](use-raw-aes-keyring.md)을 지원하는 함수를 내보냅니다. [raw-rsa-keyring-browser](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/raw-rsa-keyring-browser) 브라우저에서 [Raw RSA 키링](use-raw-rsa-keyring.md)을 지원하는 함수를 내보냅니다. ## 모든 구현을 위한 모듈 [cache-material](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/cache-material) [데이터 키 캐싱](data-key-caching.md) 기능을 지원합니다. 각 데이터 키로 캐시된 암호화 자료를 어셈블하기 위한 코드를 제공합니다. [kms-keyring](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/kms-keyring) [KMS 키링](use-kms-keyring.md)을 지원하는 함수를 내보냅니다. [material-management](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/material-management) [암호화 자료 관리자](concepts.md#crypt-materials-manager)(CMM)를 구현합니다. [raw-keyring](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/raw-keyring) Raw AES 및 RSA 키링에 필요한 함수를 내보냅니다. [serialize](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/serialize) SDK가 출력을 직렬화하는 데 사용하는 함수를 내보냅니다. [web-crypto-backend](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/web-crypto-backend) 브라우저의에서 WebCrypto API를 사용하는 함수 AWS Encryption SDK for JavaScript 를 내보냅니다. # AWS Encryption SDK for JavaScript 예제 다음 예제에서는 AWS Encryption SDK for JavaScript 를 사용하여 데이터를 암호화 및 복호화하는 방법을 보여줍니다. GitHub의 aws-encryption-sdk-javascript AWS Encryption SDK for JavaScript 리포지토리의 example-node 및 [example-browser](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/example-browser) 모듈에서를 사용하는 더 많은 예제를 찾을 수 있습니다. [https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/example-node](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/example-node) [aws-encryption-sdk-javascript](https://github.com/aws/aws-encryption-sdk-javascript/) 이러한 예제 모듈은 `client-browser` 또는 `client-node` 모듈을 설치할 때 설치되지 않습니다. **전체 코드 샘플을 참조**: 노드: [kms\$1simple.ts](https://github.com/aws/aws-encryption-sdk-javascript/blob/master/modules/example-node/src/kms_simple.ts), 브라우저: [kms\$1simple.ts](https://github.com/aws/aws-encryption-sdk-javascript/blob/master/modules/example-browser/src/kms_simple.ts) **Topics** + [AWS KMS 키링을 사용하여 데이터 암호화](#javascript-example-encrypt) + [AWS KMS 키링을 사용하여 데이터 복호화](#javascript-example-decrypt) ## AWS KMS 키링을 사용하여 데이터 암호화 다음 예제에서는를 사용하여 짧은 문자열 또는 바이트 배열 AWS Encryption SDK for JavaScript 을 암호화하고 해독하는 방법을 보여줍니다. 이 예제에서는 [AWS KMS](use-kms-keyring.md)를 사용하여 데이터 키를 생성하고 암호화하는 키링 유형인 키링 AWS KMS key 이 특징입니다. 생성에 대한 도움말은 *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) 1단계: 커밋 정책을 설정합니다. 버전 1.7.*x*부터 AWS Encryption SDK 클라이언트를 인스턴스화하는 새 `buildClient` 함수를 호출할 때 커밋 정책을 설정할 AWS Encryption SDK for JavaScript수 있습니다. `buildClient` 함수는 커밋 정책을 나타내는 열거형 값을 사용합니다. 암호화 및 복호화 시 커밋 정책을 적용하는 업데이트된 `encrypt` 및 `decrypt` 함수를 반환합니다. 다음 예제에서는 `buildClient` 함수를 사용하여 [기본 커밋 정책](migrate-commitment-policy.md)인를 지정합니다`REQUIRE_ENCRYPT_REQUIRE_DECRYPT`. 를 사용하여 암호화된 메시지의 암호화된 데이터 키 수를 제한`buildClient`할 수도 있습니다. 자세한 내용은 [암호화된 데이터 키 제한](configure.md#config-limit-keys) 단원을 참조하십시오. ``` import { KmsKeyringBrowser, KMS, getClient, buildClient, CommitmentPolicy, } from '@aws-crypto/client-browser' const { encrypt, decrypt } = buildClient( CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT ) ``` ``` import { KmsKeyringNode, buildClient, CommitmentPolicy, } from '@aws-crypto/client-node' const { encrypt, decrypt } = buildClient( CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT ) ``` 2단계: 키링을 구성합니다. 암호화를 위한 AWS KMS 키링을 생성합니다. AWS KMS 키링으로 암호화할 때는 *생성기 키*, 즉 일반 텍스트 데이터 키를 생성하고 암호화하는 데 AWS KMS key 사용되는를 지정해야 합니다. 동일한 일반 텍스트 데이터 키를 암호화하는 0개 이상의 *추가 키*를 지정할 수도 있습니다. 키링은 일반 텍스트 데이터 키와 생성기 키를 포함하여 키링의 각 AWS KMS key 에 대한 해당 데이터 키의 암호화된 사본 하나를 반환합니다. 데이터를 복호화하려면 암호화된 데이터 키 중 하나를 복호화해야 합니다. 에서 암호화 키링에 AWS KMS keys 대해를 지정하려면 [지원되는 모든 AWS KMS 키 식별자](use-kms-keyring.md#kms-keyring-id)를 사용할 AWS Encryption SDK for JavaScript수 있습니다. 이 예에서는 [별칭 ARN](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-alias-ARN)으로 식별되는 생성기 키와 [키 ARN](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-key-ARN)으로 식별되는 추가 키 하나를 사용합니다. 복호화를 위해 AWS KMS 키링을 재사용하려는 경우 키 ARNs 사용하여 키링 AWS KMS keys 에서를 식별해야 합니다. 이 코드를 실행하기 전에 예제 AWS KMS key 식별자를 유효한 식별자로 바꿉니다. 키링에서 [AWS KMS keys를 사용하는 데 필요한 권한](use-kms-keyring.md#kms-keyring-permissions)이 있어야 합니다. 브라우저에 자격 증명을 제공하여 시작하세요. 이 AWS Encryption SDK for JavaScript 예에서는 자격 증명 상수를 실제 자격 증명으로 대체하는 [webpack.DefinePlugin](https://webpack.js.org/plugins/define-plugin/)을 사용합니다. 그러나 모든 방법을 사용하여 자격 증명을 제공할 수 있습니다. 그런 다음 자격 증명을 사용하여 AWS KMS 클라이언트를 생성합니다. ``` declare const credentials: {accessKeyId: string, secretAccessKey:string, sessionToken:string } const clientProvider = getClient(KMS, { credentials: { accessKeyId, secretAccessKey, sessionToken } }) ``` 그런 다음 생성기 키 및 추가 키에 AWS KMS keys 를 지정합니다. 그런 다음 클라이언트와를 사용하여 AWS KMS AWS KMS 키링을 생성합니다 AWS KMS keys. ``` const generatorKeyId = 'arn:aws:kms:us-west-2:111122223333:alias/EncryptDecrypt' const keyIds = ['arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'] const keyring = new KmsKeyringBrowser({ clientProvider, generatorKeyId, keyIds }) ``` ``` const generatorKeyId = 'arn:aws:kms:us-west-2:111122223333:alias/EncryptDecrypt' const keyIds = ['arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'] const keyring = new KmsKeyringNode({ generatorKeyId, keyIds }) ``` 3단계: 암호화 컨텍스트를 설정합니다. [암호화 컨텍스트](concepts.md#encryption-context)는 비밀이 아닌 임의의 추가 인증 데이터입니다. 암호화에 암호화 컨텍스트를 제공하면 AWS Encryption SDK 는 암호화 컨텍스트를 사이퍼텍스트에 암호화 방식으로 바인딩하여 데이터를 복호화하는 데 동일한 암호화 컨텍스트가 필요합니다. 암호화 컨텍스트를 사용하는 것은 선택 사항이지만 권장되는 모범 사례입니다. 암호화 컨텍스트 페어를 포함하는 단순 객체를 만듭니다. 각 페어의 키와 값은 문자열이어야 합니다. ``` const context = { stage: 'demo', purpose: 'simple demonstration app', origin: 'us-west-2' } ``` ``` const context = { stage: 'demo', purpose: 'simple demonstration app', origin: 'us-west-2' } ``` 4단계: 데이터를 암호화합니다. 일반 텍스트 데이터를 암호화하려면 `encrypt` 함수를 호출합니다. AWS KMS 키링, 일반 텍스트 데이터 및 암호화 컨텍스트를 전달합니다. 이 `encrypt` 함수는 암호화된 데이터, 암호화된 데이터 키 및 암호화 컨텍스트 및 서명을 포함한 중요한 메타데이터를 포함하는 [암호화된 메시지](concepts.md#message)(`result`)를 반환합니다. 지원되는 프로그래밍 언어 AWS Encryption SDK 에 대해를 사용하여 [이 암호화된 메시지를 복호](#javascript-example-decrypt)화할 수 있습니다. ``` const plaintext = new Uint8Array([1, 2, 3, 4, 5]) const { result } = await encrypt(keyring, plaintext, { encryptionContext: context }) ``` ``` const plaintext = 'asdf' const { result } = await encrypt(keyring, plaintext, { encryptionContext: context }) ``` ## AWS KMS 키링을 사용하여 데이터 복호화 를 사용하여 암호화된 메시지를 해독하고 원본 데이터를 복구 AWS Encryption SDK for JavaScript 할 수 있습니다. 이 예에서는 [AWS KMS 키링을 사용하여 데이터 암호화](#javascript-example-encrypt) 예제에서 암호화된 데이터를 복호화합니다. 1단계: 커밋 정책을 설정합니다. 버전 1.7.*x*부터 AWS Encryption SDK 클라이언트를 인스턴스화하는 새 `buildClient` 함수를 호출할 때 커밋 정책을 설정할 AWS Encryption SDK for JavaScript수 있습니다. `buildClient` 함수는 커밋 정책을 나타내는 열거형 값을 사용합니다. 암호화 및 복호화 시 커밋 정책을 적용하는 업데이트된 `encrypt` 및 `decrypt` 함수를 반환합니다. 다음 예제에서는 `buildClient` 함수를 사용하여 [기본 커밋 정책](migrate-commitment-policy.md)인를 지정합니다`REQUIRE_ENCRYPT_REQUIRE_DECRYPT`. 를 사용하여 암호화된 메시지의 암호화된 데이터 키 수를 제한`buildClient`할 수도 있습니다. 자세한 내용은 [암호화된 데이터 키 제한](configure.md#config-limit-keys) 단원을 참조하십시오. ``` import { KmsKeyringBrowser, KMS, getClient, buildClient, CommitmentPolicy, } from '@aws-crypto/client-browser' const { encrypt, decrypt } = buildClient( CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT ) ``` ``` import { KmsKeyringNode, buildClient, CommitmentPolicy, } from '@aws-crypto/client-node' const { encrypt, decrypt } = buildClient( CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT ) ``` 2단계: 키링을 구성합니다. 데이터를 복호화하려면 `encrypt` 함수가 반환한 [암호화된 메시지](concepts.md#message)(`result`)를 전달하세요. 암호화된 메시지는 암호화된 데이터, 암호화된 데이터 키 및 암호화 컨텍스트 및 서명을 포함한 중요한 메타데이터를 포함합니다. 또한 복호화할 때 [AWS KMS 키링](use-kms-keyring.md)을 지정해야 합니다. 데이터를 암호화하는 데 사용된 것과 동일한 키링이나 다른 키링을 사용할 수 있습니다. 성공하려면 복호화 키링 AWS KMS key 에 있는 하나 이상의가 암호화된 메시지의 암호화된 데이터 키 중 하나를 복호화할 수 있어야 합니다. 데이터 키가 생성되지 않으므로 복호화 키링에 생성기 키를 지정할 필요가 없습니다. 이렇게 하면 생성기 키와 추가 키가 같은 방식으로 처리됩니다. 에서 복호화 키링에 AWS KMS key 대해를 지정하려면 [키 ARN](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-key-ARN)을 사용해야 AWS Encryption SDK for JavaScript합니다. 그렇지 않으면 AWS KMS key 가 인식되지 않습니다. AWS KMS 키링 AWS KMS keys 에서를 식별하는 데 도움이 필요하면 섹션을 참조하세요. [AWS KMS 키링 AWS KMS keys 에서 식별](use-kms-keyring.md#kms-keyring-id) 암호화 및 복호화에 동일한 키링을 사용하는 경우 키 ARNs 사용하여 키링 AWS KMS keys 에서를 식별합니다. 이 예제에서는 암호화 키링 AWS KMS keys 에 중 하나만 포함하는 키링을 생성합니다. 이 코드를 실행하기 전에 예제 키 ARN을 유효한 키로 바꿉니다. AWS KMS key에 대한 `kms:Decrypt` 권한이 있어야 합니다. 브라우저에 자격 증명을 제공하여 시작하세요. 이 AWS Encryption SDK for JavaScript 예에서는 자격 증명 상수를 실제 자격 증명으로 대체하는 [webpack.DefinePlugin](https://webpack.js.org/plugins/define-plugin/)을 사용합니다. 그러나 모든 방법을 사용하여 자격 증명을 제공할 수 있습니다. 그런 다음 자격 증명을 사용하여 AWS KMS 클라이언트를 생성합니다. ``` declare const credentials: {accessKeyId: string, secretAccessKey:string, sessionToken:string } const clientProvider = getClient(KMS, { credentials: { accessKeyId, secretAccessKey, sessionToken } }) ``` 그런 다음 AWS KMS 클라이언트를 사용하여 AWS KMS 키링을 생성합니다. 이 예제에서는 AWS KMS keys 암호화 키링의 중 하나만 사용합니다. ``` const keyIds = ['arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'] const keyring = new KmsKeyringBrowser({ clientProvider, keyIds }) ``` ``` const keyIds = ['arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'] const keyring = new KmsKeyringNode({ keyIds }) ``` 3단계: 데이터 암호화를 해제합니다. 그런 다음 `decrypt` 함수를 호출합니다. 방금 생성한 복호화 키링(`keyring`)과, `encrypt` 함수가 반환한 [암호화된 메시지](concepts.md#message)(`result`)를 전달하세요. 는 키링을 AWS Encryption SDK 사용하여 암호화된 데이터 키 중 하나를 복호화합니다. 그런 다음 일반 텍스트 데이터 키를 사용하여 데이터를 복호화합니다. 호출이 성공하면 `plaintext` 필드에 일반 텍스트(복호화된) 데이터가 포함됩니다. 이 `messageHeader` 필드에는 데이터 복호화에 사용된 암호화 컨텍스트를 포함하여 복호화 프로세스에 대한 메타데이터가 포함됩니다. ``` const { plaintext, messageHeader } = await decrypt(keyring, result) ``` ``` const { plaintext, messageHeader } = await decrypt(keyring, result) ``` 4단계: 암호화 컨텍스트를 확인합니다. 데이터를 복호화하는 데 사용된 [암호화 컨텍스트](concepts.md#encryption-context)는 `decrypt` 함수가 반환하는 메시지 헤더(`messageHeader`)에 포함됩니다. 애플리케이션에서 일반 텍스트 데이터를 반환하기 전에 암호화할 때 제공한 암호화 컨텍스트가 복호화할 때 사용된 암호화 컨텍스트에 포함되어 있는지 확인합니다. 불일치는 데이터가 변조되었거나 올바른 암호화 텍스트를 복호화하지 않았음을 나타낼 수 있습니다. 암호화 컨텍스트를 확인할 때 정확히 일치할 필요는 없습니다. 서명과 함께 암호화 알고리즘을 사용하는 경우 [암호화 자료 관리자](concepts.md#crypt-materials-manager)(CMM)은 메시지를 암호화하기 전에 암호화 컨텍스트에 퍼블릭 서명 키를 추가합니다. 그러나 제출한 모든 암호화 컨텍스트 페어는 반환된 암호화 컨텍스트에 포함되어야 합니다. 먼저 메시지 헤더에서 암호화 컨텍스트를 가져옵니다. 그런 다음 원래 암호화 컨텍스트(`context`)의 각 키-값 페어가 반환된 암호화 컨텍스트(`encryptionContext`)의 키-값 페어와 일치하는지 확인합니다. ``` const { encryptionContext } = messageHeader Object .entries(context) .forEach(([key, value]) => { if (encryptionContext[key] !== value) throw new Error('Encryption Context does not match expected values') }) ``` ``` const { encryptionContext } = messageHeader Object .entries(context) .forEach(([key, value]) => { if (encryptionContext[key] !== value) throw new Error('Encryption Context does not match expected values') }) ``` 암호화 컨텍스트 검사가 성공하면 일반 텍스트 데이터를 반환할 수 있습니다. # AWS Encryption SDK for Python 이 주제에서는 AWS Encryption SDK for Python를 설치 및 사용하는 방법을 설명합니다. 를 사용한 프로그래밍에 대한 자세한 내용은 GitHub의 [aws-encryption-sdk-python](https://github.com/aws/aws-encryption-sdk-python/) 리포지토리를 AWS Encryption SDK for Python참조하세요. API 설명서는 [문서 읽기](https://aws-encryption-sdk-python.readthedocs.io/en/latest/)를 참조하세요. **Topics** + [사전 조건](#python-prerequisites) + [설치](#python-installation) + [예제](python-example-code.md) ## 사전 조건 를 설치하기 전에 다음 사전 조건이 있는지 AWS Encryption SDK for Python확인합니다. **지원되는 Python 버전** AWS Encryption SDK for Python 버전 3.2.0 이상에서는 Python 3.8 이상이 필요합니다. [AWS 암호화 자료 공급자 라이브러리](https://github.com/aws/aws-cryptographic-material-providers-library)(MPL)는 버전 4.*x*에 AWS Encryption SDK for Python 도입된에 대한 선택적 종속성입니다. MPL을 설치하려는 경우 Python 3.11 이상을 사용해야 합니다. 이전 버전의는 Python 2.7 및 Python 3.4 이상을 AWS Encryption SDK 지원하지만 최신 버전의를 사용하는 것이 좋습니다 AWS Encryption SDK. Python을 다운로드하려면 [Python 다운로드](https://www.python.org/downloads/)를 참조하세요. **Python용 pip 설치 도구** `pip`는 Python 3.6 이상 버전에 포함되어 있지만 업그레이드가 필요할 수도 있습니다. `pip` 업그레이드 또는 설치에 관한 자세한 정보는 `pip` 설명서의 [설치](https://pip.pypa.io/en/latest/installation/)를 참조하세요. ## 설치 AWS Encryption SDK for Python의 최신 버전을 설치합니다. **참고** 3.0.0 AWS Encryption SDK for Python 이전의 모든 버전은 [end-of-support 단계에](https://docs.aws.amazon.com/sdkref/latest/guide/maint-policy.html#version-life-cycle) 있습니다. 코드나 데이터를 변경하지 않고 버전 2.0.*x* 이상에서 AWS Encryption SDK 의 최신 버전으로 안전하게 업데이트할 수 있습니다. 그러나 버전 2.0.*x*에 도입된 [새로운 보안 기능](about-versions.md#version-2)은 이하 버전과 호환되지 않습니다. 1.7.*x* 이하 버전에서 2.0.*x* 이상 버전으로 업데이트하려면 먼저 AWS Encryption SDK의 최신 1.*x* 버전으로 업데이트해야 합니다. 자세한 내용은 [마이그레이션 AWS Encryption SDK](migration.md)을 참조하세요. 다음 예제와 AWS Encryption SDK for Python같이 `pip`를 사용하여를 설치합니다. **최신 버전 설치** ``` pip install "aws-encryption-sdk[MPL]" ``` 접`[MPL]`미사는 [AWS 암호화 자료 공급자 라이브러리](https://github.com/aws/aws-cryptographic-material-providers-library)(MPL)를 설치합니다. MPL에는 데이터를 암호화하고 해독하기 위한 구문이 포함되어 있습니다. MPL은 버전 4.*x*에 AWS Encryption SDK for Python 도입된에 대한 선택적 종속성입니다. MPL을 설치하는 것이 좋습니다. 그러나 MPL을 사용하지 않으려는 경우 접`[MPL]`미사를 생략할 수 있습니다. pip를 사용하여 패키지를 설치 및 업그레이드하는 방법에 대한 자세한 내용은 [패키지 설치](https://packaging.python.org/tutorials/installing-packages/)를 참조하세요. 에는 모든 플랫폼에서 [암호화 라이브러리](https://cryptography.io/en/latest/)(pyca/cryptography)가 AWS Encryption SDK for Python 필요합니다. `pip`의 모든 버전은 `cryptography` 라이브러리를 Windows에 자동으로 설치하고 빌드합니다. `pip` 8.1 이상 버전은 Linux에 `cryptography`를 자동으로 설치하고 빌드합니다. 이하 버전의 `pip`를 사용 중이며 `cryptography` 라이브러리 빌드에 필요한 도구가 Linux 환경에 없는 경우에는 이러한 도구를 설치해야 합니다. 자세한 내용은 [Linux에서 암호화 빌드](https://cryptography.io/en/latest/installation.html#building-cryptography-on-linux)를 참조하세요. 버전 1.10.0 및 2.5.0은 2.5.0과 3.3.2 사이의 [암호화](https://cryptography.io/en/latest/) 종속성을 AWS Encryption SDK for Python 고정합니다. 다른 버전의는 최신 버전의 암호화를 AWS Encryption SDK for Python 설치합니다. 3.3.2 이상 버전의 암호화가 필요한 경우 AWS Encryption SDK for Python의 최신 메이저 버전을 사용하는 것이 좋습니다. 의 최신 개발 버전은 GitHub의 [aws-encryption-sdk-python](https://github.com/aws/aws-encryption-sdk-python/) 리포지토리를 AWS Encryption SDK for Python참조하십시오. 를 설치한 후이 가이드의 [Python 예제 코드를](python-example-code.md) 살펴보 AWS Encryption SDK for Python면서 시작합니다. # AWS Encryption SDK for Python 예제 코드 다음 예제에서는를 사용하여 데이터를 암호화하고 복호화 AWS Encryption SDK for Python 하는 방법을 보여줍니다. 이 섹션의 예제에서는 선택적 [암호화 자료 공급자 라이브러리](https://github.com/aws/aws-cryptographic-material-providers-library) 종속성()과 AWS Encryption SDK for Python 함께 버전 4.*x*를 사용하는 방법을 보여줍니다`aws-cryptographic-material-providers`. 이전 버전을 사용하거나 재료 공급자 라이브러리(MPL)가 없는 설치를 사용하는 예제를 보려면 GitHub의 [aws-encryption-sdk-python](https://github.com/aws/aws-encryption-sdk-python/) 리포지토리 릴리스 목록에서 [릴리스](https://github.com/aws/aws-encryption-sdk-python/releases)를 찾습니다. MPL과 AWS Encryption SDK for Python 함께 버전 4.*x*를 사용하는 경우 [키링을](choose-keyring.md) 사용하여 [봉투 암호화](concepts.md#envelope-encryption)를 수행합니다. 는 이전 버전에서 사용한 마스터 키 공급자와 호환되는 키링을 AWS Encryption SDK 제공합니다. 자세한 내용은 [키링 호환성](choose-keyring.md#keyring-compatibility) 단원을 참조하십시오. 마스터 키 공급자에서 키링으로 마이그레이션하는 방법에 대한 예제는 GitHub의 `aws-encryption-sdk-python`리포지토리에서 [마이그레이션 예제](https://github.com/aws/aws-encryption-sdk-python/tree/master/examples/src/migration)를 참조하세요. **Topics** + [문자열](#python-example-strings) + [바이트 스트림](#python-example-streams) ## 문자열 암호화 및 복호화 다음 예제에서는를 사용하여 문자열을 암호화하고 복호화 AWS Encryption SDK 하는 방법을 보여줍니다. 이 예제에서는 대칭 암호화 KMS 키와 함께 키[AWS KMS 링](use-kms-keyring.md)을 사용합니다. 이 예제에서는 [기본 커밋 정책](migrate-commitment-policy.md)인를 사용하여 AWS Encryption SDK 클라이언트를 인스턴스화합니다`REQUIRE_ENCRYPT_REQUIRE_DECRYPT`. 자세한 내용은 [커밋 정책 설정](migrate-commitment-policy.md) 단원을 참조하십시오. ``` # Copyright Amazon.com Inc. or its affiliates. All Rights Reserved. # SPDX-License-Identifier: Apache-2.0 """ This example sets up the KMS Keyring The AWS KMS keyring uses symmetric encryption KMS keys to generate, encrypt and decrypt data keys. This example creates a KMS Keyring and then encrypts a custom input EXAMPLE_DATA with an encryption context. This example also includes some sanity checks for demonstration: 1. Ciphertext and plaintext data are not the same 2. Encryption context is correct in the decrypted message header 3. Decrypted plaintext value matches EXAMPLE_DATA These sanity checks are for demonstration in the example only. You do not need these in your code. AWS KMS keyrings can be used independently or in a multi-keyring with other keyrings of the same or a different type. """ import boto3 from aws_cryptographic_material_providers.mpl import AwsCryptographicMaterialProviders from aws_cryptographic_material_providers.mpl.config import MaterialProvidersConfig from aws_cryptographic_material_providers.mpl.models import CreateAwsKmsKeyringInput from aws_cryptographic_material_providers.mpl.references import IKeyring from typing import Dict # noqa pylint: disable=wrong-import-order import aws_encryption_sdk from aws_encryption_sdk import CommitmentPolicy EXAMPLE_DATA: bytes = b"Hello World" def encrypt_and_decrypt_with_keyring( kms_key_id: str ): """Demonstrate an encrypt/decrypt cycle using an AWS KMS keyring. Usage: encrypt_and_decrypt_with_keyring(kms_key_id) :param kms_key_id: KMS Key identifier for the KMS key you want to use for encryption and decryption of your data keys. :type kms_key_id: string """ # 1. Instantiate the encryption SDK client. # This builds the client with the REQUIRE_ENCRYPT_REQUIRE_DECRYPT commitment policy, # which enforces that this client only encrypts using committing algorithm suites and enforces # that this client will only decrypt encrypted messages that were created with a committing # algorithm suite. # This is the default commitment policy if you were to build the client as # `client = aws_encryption_sdk.EncryptionSDKClient()`. client = aws_encryption_sdk.EncryptionSDKClient( commitment_policy=CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT ) # 2. Create a boto3 client for KMS. kms_client = boto3.client('kms', region_name="us-west-2") # 3. Optional: create encryption context. # Remember that your encryption context is NOT SECRET. encryption_context: Dict[str, str] = { "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", } # 4. Create your keyring mat_prov: AwsCryptographicMaterialProviders = AwsCryptographicMaterialProviders( config=MaterialProvidersConfig() ) keyring_input: CreateAwsKmsKeyringInput = CreateAwsKmsKeyringInput( kms_key_id=kms_key_id, kms_client=kms_client ) kms_keyring: IKeyring = mat_prov.create_aws_kms_keyring( input=keyring_input ) # 5. Encrypt the data with the encryptionContext. ciphertext, _ = client.encrypt( source=EXAMPLE_DATA, keyring=kms_keyring, encryption_context=encryption_context ) # 6. Demonstrate that the ciphertext and plaintext are different. # (This is an example for demonstration; you do not need to do this in your own code.) assert ciphertext != EXAMPLE_DATA, \ "Ciphertext and plaintext data are the same. Invalid encryption" # 7. Decrypt your encrypted data using the same keyring you used on encrypt. plaintext_bytes, _ = client.decrypt( source=ciphertext, keyring=kms_keyring, # Provide the encryption context that was supplied to the encrypt method encryption_context=encryption_context, ) # 8. Demonstrate that the decrypted plaintext is identical to the original plaintext. # (This is an example for demonstration; you do not need to do this in your own code.) assert plaintext_bytes == EXAMPLE_DATA, \ "Decrypted plaintext should be identical to the original plaintext. Invalid decryption" ``` ## 바이트 스트림 암호화 및 복호화 다음 예제에서는를 사용하여 바이트 스트림을 암호화하고 복호화 AWS Encryption SDK 하는 방법을 보여줍니다. 이 예제에서는 [원시 AES 키링](use-raw-aes-keyring.md)을 사용합니다. 이 예제에서는 [기본 커밋 정책](migrate-commitment-policy.md)인를 사용하여 AWS Encryption SDK 클라이언트를 인스턴스화합니다`REQUIRE_ENCRYPT_REQUIRE_DECRYPT`. 자세한 내용은 [커밋 정책 설정](migrate-commitment-policy.md) 단원을 참조하십시오. ``` # Copyright Amazon.com Inc. or its affiliates. All Rights Reserved. # SPDX-License-Identifier: Apache-2.0 """ This example demonstrates file streaming for encryption and decryption. File streaming is useful when the plaintext or ciphertext file/data is too large to load into memory. Therefore, the AWS Encryption SDK allows users to stream the data, instead of loading it all at once in memory. In this example, we demonstrate file streaming for encryption and decryption using a Raw AES keyring. However, you can use any keyring with streaming. This example creates a Raw AES Keyring and then encrypts an input stream from the file `plaintext_filename` with an encryption context to an output (encrypted) file `ciphertext_filename`. It then decrypts the ciphertext from `ciphertext_filename` to a new file `decrypted_filename`. This example also includes some sanity checks for demonstration: 1. Ciphertext and plaintext data are not the same 2. Encryption context is correct in the decrypted message header 3. Decrypted plaintext value matches EXAMPLE_DATA These sanity checks are for demonstration in the example only. You do not need these in your code. See raw_aes_keyring_example.py in the same directory for another raw AES keyring example in the AWS Encryption SDK for Python. """ import filecmp import secrets from aws_cryptographic_material_providers.mpl import AwsCryptographicMaterialProviders from aws_cryptographic_material_providers.mpl.config import MaterialProvidersConfig from aws_cryptographic_material_providers.mpl.models import AesWrappingAlg, CreateRawAesKeyringInput from aws_cryptographic_material_providers.mpl.references import IKeyring from typing import Dict # noqa pylint: disable=wrong-import-order import aws_encryption_sdk from aws_encryption_sdk import CommitmentPolicy def encrypt_and_decrypt_with_keyring( plaintext_filename: str, ciphertext_filename: str, decrypted_filename: str ): """Demonstrate a streaming encrypt/decrypt cycle. Usage: encrypt_and_decrypt_with_keyring(plaintext_filename ciphertext_filename decrypted_filename) :param plaintext_filename: filename of the plaintext data :type plaintext_filename: string :param ciphertext_filename: filename of the ciphertext data :type ciphertext_filename: string :param decrypted_filename: filename of the decrypted data :type decrypted_filename: string """ # 1. Instantiate the encryption SDK client. # This builds the client with the REQUIRE_ENCRYPT_REQUIRE_DECRYPT commitment policy, # which enforces that this client only encrypts using committing algorithm suites and enforces # that this client will only decrypt encrypted messages that were created with a committing # algorithm suite. # This is the default commitment policy if you were to build the client as # `client = aws_encryption_sdk.EncryptionSDKClient()`. client = aws_encryption_sdk.EncryptionSDKClient( commitment_policy=CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT ) # 2. The key namespace and key name are defined by you. # and are used by the Raw AES keyring to determine # whether it should attempt to decrypt an encrypted data key. key_name_space = "Some managed raw keys" key_name = "My 256-bit AES wrapping key" # 3. Optional: create encryption context. # Remember that your encryption context is NOT SECRET. encryption_context: Dict[str, str] = { "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", } # 4. Generate a 256-bit AES key to use with your keyring. # In practice, you should get this key from a secure key management system such as an HSM. # Here, the input to secrets.token_bytes() = 32 bytes = 256 bits static_key = secrets.token_bytes(32) # 5. Create a Raw AES keyring # We choose to use a raw AES keyring, but any keyring can be used with streaming. mat_prov: AwsCryptographicMaterialProviders = AwsCryptographicMaterialProviders( config=MaterialProvidersConfig() ) keyring_input: CreateRawAesKeyringInput = CreateRawAesKeyringInput( key_namespace=key_name_space, key_name=key_name, wrapping_key=static_key, wrapping_alg=AesWrappingAlg.ALG_AES256_GCM_IV12_TAG16 ) raw_aes_keyring: IKeyring = mat_prov.create_raw_aes_keyring( input=keyring_input ) # 6. Encrypt the data stream with the encryptionContext with open(plaintext_filename, 'rb') as pt_file, open(ciphertext_filename, 'wb') as ct_file: with client.stream( mode='e', source=pt_file, keyring=raw_aes_keyring, encryption_context=encryption_context ) as encryptor: for chunk in encryptor: ct_file.write(chunk) # 7. Demonstrate that the ciphertext and plaintext are different. # (This is an example for demonstration; you do not need to do this in your own code.) assert not filecmp.cmp(plaintext_filename, ciphertext_filename), \ "Ciphertext and plaintext data are the same. Invalid encryption" # 8. Decrypt your encrypted data stream using the same keyring you used on encrypt. with open(ciphertext_filename, 'rb') as ct_file, open(decrypted_filename, 'wb') as pt_file: with client.stream( mode='d', source=ct_file, keyring=raw_aes_keyring, encryption_context=encryption_context ) as decryptor: for chunk in decryptor: pt_file.write(chunk) # 10. Demonstrate that the decrypted plaintext is identical to the original plaintext. # (This is an example for demonstration; you do not need to do this in your own code.) assert filecmp.cmp(plaintext_filename, decrypted_filename), \ "Decrypted plaintext should be identical to the original plaintext. Invalid decryption" ``` # AWS Encryption SDK Rust용 이 주제에서는 AWS Encryption SDK for Rust를 설치하고 사용하는 방법을 설명합니다. AWS Encryption SDK for Rust를 사용한 프로그래밍에 대한 자세한 내용은 GitHub의 aws-encryption-sdk 리포지토리의 [Rust](https://github.com/aws/aws-encryption-sdk-dafny/tree/mainline/AwsEncryptionSDK/runtimes/rust/) 디렉터리를 참조하세요. AWS Encryption SDK for Rust는 다음과 AWS Encryption SDK 같은 방식으로의 다른 프로그래밍 언어 구현과 다릅니다. + [데이터 키 캐싱](data-key-caching.md)은 지원되지 않습니다. 그러나 AWS Encryption SDK for Rust는 대체 암호화 자료 캐싱 솔루션인 [AWS KMS 계층적 키링](use-hierarchical-keyring.md)을 지원합니다. + 스트리밍 데이터가 지원되지 않음 AWS Encryption SDK for Rust에는의 다른 언어 구현 버전 2.0.*x* 이상에 도입된 모든 보안 기능이 포함되어 있습니다 AWS Encryption SDK. 그러나 AWS Encryption SDK for Rust를 사용하여의 다른 언어 구현인 2.0.*x* 이전 버전으로 암호화된 데이터를 복호화 AWS Encryption SDK하는 경우 [커밋 정책을](concepts.md#commitment-policy) 조정해야 할 수 있습니다. 자세한 내용은 [커밋 정책 설정 방법](migrate-commitment-policy.md#migrate-commitment-step1)을 참조하세요. AWS Encryption SDK for Rust는 사양을 작성하는 공식 확인 언어인 [Dafny](https://github.com/dafny-lang/dafny/blob/master/README.md) AWS Encryption SDK 의 제품이며, 이를 구현할 코드와 이를 테스트하기 위한 증거입니다. 그 결과, 기능적 정확성을 보장하는 프레임워크에서 AWS Encryption SDK 의 기능을 구현하는 라이브러리가 탄생했습니다. **자세히 알아보기** + 대체 알고리즘 제품군 지정 AWS Encryption SDK, 암호화된 데이터 키 제한, AWS KMS 다중 리전 키 사용 등에서 옵션을 구성하는 방법을 보여주는 예제는 섹션을 참조하세요[구성 AWS Encryption SDK](configure.md). + AWS Encryption SDK for Rust를 구성하고 사용하는 방법을 보여주는 예제는 GitHub의 aws-encryption-sdk 리포지토리에 있는 [Rust 예제](https://github.com/aws/aws-encryption-sdk-dafny/tree/mainline/AwsEncryptionSDK/runtimes/rust/examples)를 참조하세요. **Topics** + [사전 조건](#prerequisites-rust) + [설치](#rust-installation) + [예제](rust-examples.md) ## 사전 조건 AWS Encryption SDK for Rust를 설치하기 전에 다음 사전 조건이 있는지 확인합니다. **Rust 및 Cargo 설치** [Rustup](https://rustup.rs/)을 사용하여 현재 안정적인 [Rust](https://www.rust-lang.org/) 릴리스를 설치합니다. rustup 다운로드 및 설치에 대한 자세한 내용은 카고 북의 [설치 절차를](https://doc.rust-lang.org/cargo/getting-started/installation.html) 참조하세요. ## 설치 AWS Encryption SDK for Rust는 Crates.io [https://crates.io/crates/aws-esdk](https://crates.io/crates/aws-esdk) 크레이트로 사용할 수 있습니다. AWS Encryption SDK for Rust 설치 및 빌드에 대한 자세한 내용은 GitHub의 aws-encryption-sdk 리포지토리에서 [README.md](https://github.com/aws/aws-encryption-sdk/tree/mainline) 참조하십시오. 다음과 같은 방법으로 AWS Encryption SDK for Rust를 설치할 수 있습니다. **직접** AWS Encryption SDK for Rust를 설치하려면 [aws-encryption-sdk](https://github.com/aws/aws-encryption-sdk/tree/mainline) GitHub 리포지토리를 복제하거나 다운로드합니다. **Crates.io 사용** 프로젝트 디렉터리에서 다음 Cargo 명령을 실행합니다. ``` cargo add aws-esdk ``` 또는 Cargo.toml에 다음 줄을 추가합니다. ``` aws-esdk = "" ``` # AWS Encryption SDK for Rust 예제 코드 다음 예제에서는 AWS Encryption SDK for Rust를 사용하여 프로그래밍할 때 사용하는 기본 코딩 패턴을 보여줍니다. 특히 AWS Encryption SDK 및 재료 공급자 라이브러리를 인스턴스화합니다. 그런 다음 각 메서드를 호출하기 전에 메서드에 대한 입력을 정의하는 객체를 인스턴스화합니다. 대체 알고리즘 제품군 지정 및 암호화된 데이터 키 제한 AWS Encryption SDK과 같이에서 옵션을 구성하는 방법을 보여주는 예제는 GitHub의 aws-encryption-sdk 리포지토리에 있는 [Rust 예제](https://github.com/aws/aws-encryption-sdk-dafny/tree/mainline/AwsEncryptionSDK/runtimes/rust/examples/)를 참조하세요. ## AWS Encryption SDK for Rust에서 데이터 암호화 및 복호화 이 예제에서는 데이터 암호화 및 복호화의 기본 패턴을 보여줍니다. 하나의 AWS KMS 래핑 키로 보호되는 데이터 키로 작은 파일을 암호화합니다. **1단계: 인스턴스화 AWS Encryption SDK.** 의 메서드를 사용하여 데이터를 암호화하고 복호화 AWS Encryption SDK 합니다. ``` let esdk_config = AwsEncryptionSdkConfig::builder().build()?; let esdk_client = esdk_client::Client::from_conf(esdk_config)?; ``` **2단계: AWS KMS 클라이언트를 생성합니다.** ``` let sdk_config = aws_config::load_defaults(aws_config::BehaviorVersion::latest()).await; let kms_client = aws_sdk_kms::Client::new(&sdk_config); ``` **선택 사항: 암호화 컨텍스트를 생성합니다.** ``` let encryption_context = HashMap::from([ ("encryption".to_string(), "context".to_string()), ("is not".to_string(), "secret".to_string()), ("but adds".to_string(), "useful metadata".to_string()), ("that can help you".to_string(), "be confident that".to_string()), ("the data you are handling".to_string(), "is what you think it is".to_string()), ]); ``` **3단계: 재료 공급자 라이브러리를 인스턴스화합니다.** 구성 요소 공급자 라이브러리의 메서드를 사용하여, 데이터를 보호하는 키를 지정하는 키링을 만들 수 있습니다. ``` let mpl_config = MaterialProvidersConfig::builder().build()?; let mpl = mpl_client::Client::from_conf(mpl_config)?; ``` **4단계: AWS KMS 키링을 생성합니다.** 키링을 생성하려면 키링 입력 객체를 사용하여 키링 메서드를 호출합니다. 이 예제에서는 `create_aws_kms_keyring()` 메서드를 사용하고 KMS 키 하나를 지정합니다. ``` let kms_keyring = mpl .create_aws_kms_keyring() .kms_key_id(kms_key_id) .kms_client(kms_client) .send() .await?; ``` **5단계: 일반 텍스트를 암호화합니다.** ``` let plaintext = example_data.as_bytes(); let encryption_response = esdk_client.encrypt() .plaintext(plaintext) .keyring(kms_keyring.clone()) .encryption_context(encryption_context.clone()) .send() .await?; let ciphertext = encryption_response .ciphertext .expect("Unable to unwrap ciphertext from encryption response"); ``` **6단계: 암호화에 사용한 것과 동일한 키링을 사용하여 암호화된 데이터를 복호화합니다.** ``` let decryption_response = esdk_client.decrypt() .ciphertext(ciphertext) .keyring(kms_keyring) // Provide the encryption context that was supplied to the encrypt method .encryption_context(encryption_context) .send() .await?; let decrypted_plaintext = decryption_response .plaintext .expect("Unable to unwrap plaintext from decryption response"); ``` # AWS Encryption SDK 명령줄 인터페이스 AWS Encryption SDK 명령줄 인터페이스(AWS 암호화 CLI)를 사용하면를 사용하여 명령줄과 스크립트에서 대화형으로 데이터를 암호화하고 해독 AWS Encryption SDK 할 수 있습니다. 암호학이나 프로그래밍 전문 지식이 없어도 됩니다. **참고** 4.0.0 이전의 AWS Encryption CLI 버전은 [end-of-support 단계에](https://docs.aws.amazon.com/sdkref/latest/guide/maint-policy.html#version-life-cycle) 있습니다. 코드나 데이터를 변경하지 않고 버전 2.1.*x* 이상에서 AWS Encryption CLI의 최신 버전으로 안전하게 업데이트할 수 있습니다. 그러나 버전 2.1.*x*에 도입된 [새로운 보안 기능](about-versions.md#version-2)은 이하 버전과 호환되지 않습니다. 버전 1.7.*x* 이하에서 업데이트하려면 먼저 AWS Encryption CLI의 최신 1.*x* 버전으로 업데이트해야 합니다. 자세한 내용은 [마이그레이션 AWS Encryption SDK](migration.md)을 참조하세요. 새로운 보안 기능은 원래 AWS Encryption CLI 버전 1.7.*x* 및 2.0.*x*에서 릴리스되었습니다. 그러나 AWS Encryption CLI 버전 1.8.*x*는 버전 1.7.*x*를 대체하고 AWS Encryption CLI 2.1.*x*는 2.0.*x*를 대체합니다. 자세한 내용은 GitHub의 [aws-encryption-sdk-cli](https://github.com/aws/aws-encryption-sdk-cli/) 리포지토리에서 관련 [보안 권고](https://github.com/aws/aws-encryption-sdk-cli/security/advisories/GHSA-2xwp-m7mq-7q3r)를 참조하세요. 의 모든 구현과 마찬가지로 AWS Encryption SDK AWS 암호화 CLI는 고급 데이터 보호 기능을 제공합니다. 이러한 기능에는 [봉투 암호화](https://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/how-it-works.html#envelope-encryption), 추가 인증 데이터(AAD) 및 보안, 인증, 대칭 키 [알고리즘 제품군](https://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/supported-algorithms.html)(예: 키 추출, [키 커밋](concepts.md#key-commitment) 및 서명을 사용하는 256비트 AES-GCM)이 포함됩니다. AWS Encryption CLI는를 기반으로 하며 Linux, macOS 및 Windows에서 지원[AWS Encryption SDK for Python](python.md)됩니다. Linux 또는 macOS의 기본 쉘, Windows의 명령 프롬프트 창(cmd.exe), 모든 시스템의 PowerShell 콘솔에서 명령과 스크립트를 실행하여 데이터를 암호화하고 복호화할 수 있습니다. AWS Encryption CLI를 AWS Encryption SDK포함하여의 모든 언어별 구현은 상호 운용 가능합니다. 예를 들어를 사용하여 데이터를 암호화[AWS Encryption SDK for Java](java.md)하고 AWS Encryption CLI를 사용하여 복호화할 수 있습니다. 이 주제에서는 AWS Encryption CLI를 소개하고, 이를 설치 및 사용하는 방법을 설명하고, 시작하는 데 도움이 되는 몇 가지 예제를 제공합니다. 빠른 시작은 AWS 보안 블로그[의 암호화 CLI를 사용하여 데이터를 AWS 암호화 및 해독하는 방법을 참조하세요](https://aws.amazon.com/blogs/security/how-to-encrypt-and-decrypt-your-data-with-the-aws-encryption-cli/). 자세한 내용은 [문서 읽기](https://aws-encryption-sdk-cli.readthedocs.io/en/latest/)를 참조하고 GitHub의 aws-encryption-sdk-cli 리포지토리에서 AWS Encryption CLI 개발에 참여하세요. [aws-encryption-sdk-cli](https://github.com/aws/aws-encryption-sdk-cli/) **성능** AWS Encryption CLI는를 기반으로 합니다 AWS Encryption SDK for Python. CLI를 실행할 때마다 Python 런타임의 새 인스턴스가 시작됩니다. 가능한 경우 성능을 개선하려면 일련의 독립 명령 대신 단일 명령을 사용합니다. 예를 들어, 각 파일에 대해 별도의 명령을 실행하는 대신 디렉터리에서 파일을 재귀적으로 처리하는 명령 하나를 실행합니다. **Topics** + [CLI 설치](crypto-cli-install.md) + [CLI 사용 방법](crypto-cli-how-to.md) + [예제](crypto-cli-examples.md) + [구문 및 파라미터 참조](crypto-cli-reference.md) + [버전](crypto-cli-versions.md) # AWS Encryption SDK 명령줄 인터페이스 설치 이 주제에서는 AWS 암호화 CLI를 설치하는 방법을 설명합니다. 자세한 내용은 GitHub의 [aws-encryption-sdk-cli](https://github.com/aws/aws-encryption-sdk-cli/) 리포지토리와 [문서 읽기](https://aws-encryption-sdk-cli.readthedocs.io/en/latest/)를 참조하세요. **Topics** + [사전 필수 소프트웨어 설치](#crypto-cli-prerequisites) + [CLI 설치](#install-sdk-cli) ## 사전 필수 소프트웨어 설치 AWS 암호화 CLI는를 기반으로 합니다 AWS Encryption SDK for Python. AWS Encryption CLI를 설치하려면 Python 패키지 관리 도구`pip`인 Python 및가 필요합니다. Python 및 `pip`는 지원되는 모든 플랫폼에서 사용할 수 있습니다. AWS Encryption CLI를 설치하기 전에 다음 사전 조건을 설치합니다. **Python** Python 3.8 이상은 AWS Encryption CLI 버전 4.2.0 이상에서 필요합니다. 이전 버전의 AWS Encryption CLI는 Python 2.7 및 3.4 이상을 지원하지만 최신 버전의 AWS Encryption CLI를 사용하는 것이 좋습니다. Python은 대부분의 Linux 및 macOS 설치에 포함되어 있지만 Python 3.6 이상으로 업그레이드해야 합니다. 최신 버전의 Python전을 사용하는 것이 좋습니다. Windows에서는 Python을 설치해야 하며, 이는 기본적으로 설치되어 있지 않습니다. Python을 다운로드하고 설치하려면 [Python 다운로드](https://www.python.org/downloads/)를 참조하세요. Python 설치 여부를 알아보려면 명령줄에서 다음을 입력합니다. ``` python ``` Python 버전을 확인하려면 `-V`(대문자 V) 파라미터를 사용합니다. ``` python -V ``` Windows에서는 Python을 설치한 후 **Path** 환경 변수의 값에 `Python.exe` 파일의 경로를 추가합니다. 기본적으로 Python은 모든 사용자 디렉터리 또는 `AppData\Local\Programs\Python` 하위 디렉터리의 사용자 프로필 디렉터리(`$home` 또는 `%userprofile%`)에 설치됩니다. 시스템에서 `Python.exe` 파일의 위치를 찾으려면 다음 레지스트리 키 중 하나를 확인합니다. PowerShell을 사용하여 레지스트리를 검색할 수 있습니다. ``` PS C:\> dir HKLM:\Software\Python\PythonCore\version\InstallPath # -or- PS C:\> dir HKCU:\Software\Python\PythonCore\version\InstallPath ``` **pip** `pip`는 Python 패키지 관리자입니다. AWS Encryption CLI 및 해당 종속성을 설치하려면 `pip` 8.1 이상이 필요합니다. `pip` 설치 또는 업그레이드에 도움이 필요하면 `pip` 설명서의 [설치](https://pip.pypa.io/en/latest/installing/)를 참조하세요. Linux 설치에서 8.1 `pip` 이전의 버전은 AWS Encryption CLI에 필요한 **암호화** 라이브러리를 빌드할 수 없습니다. `pip` 버전을 업데이트하지 않기로 선택한 경우 빌드 도구를 별도로 설치할 수 있습니다. 자세한 내용은 [Linux에서 암호화 빌드](https://cryptography.io/en/latest/installation.html#building-cryptography-on-linux)를 참조하세요. **AWS Command Line Interface** AWS Command Line Interface (AWS CLI)는 AWS 암호화 CLI와 함께 (AWS KMS) AWS KMS keys 에서 AWS Key Management Service 를 사용하는 경우에만 필요합니다. 다른 [마스터 키 공급자](concepts.md#master-key-provider)를 사용하는 경우 AWS CLI 가 필요하지 않습니다. AWS Encryption CLI와 AWS KMS keys 함께를 사용하려면를 [설치하고](https://docs.aws.amazon.com/cli/latest/userguide/installing.html) [구성](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html#cli-quick-configuration)해야 합니다 AWS CLI. 구성은 인증에 사용하는 자격 증명을 AWS Encryption CLI에서 AWS KMS 사용할 수 있도록 합니다. ## AWS Encryption CLI 설치 및 업데이트 최신 버전의 AWS Encryption CLI를 설치합니다. `pip`를 사용하여 AWS 암호화 CLI를 설치하면 , Python 암호화 라이브러리 및를 포함하여 CLI[AWS Encryption SDK for Python](python.md)에 필요한 [라이브러리](https://cryptography.io/en/latest/)가 자동으로 설치됩니다[AWS SDK for Python (Boto3)](https://boto3.amazonaws.com/v1/documentation/api/latest/index.html). **참고** 4.0.0 이전의 AWS Encryption CLI 버전은 [end-of-support 단계에](https://docs.aws.amazon.com/sdkref/latest/guide/maint-policy.html#version-life-cycle) 있습니다. 코드나 데이터를 변경하지 않고 버전 2.1.*x* 이상에서 AWS Encryption CLI의 최신 버전으로 안전하게 업데이트할 수 있습니다. 그러나 버전 2.1.*x*에 도입된 [새로운 보안 기능](about-versions.md#version-2)은 이하 버전과 호환되지 않습니다. 버전 1.7.*x* 이하에서 업데이트하려면 먼저 AWS Encryption CLI의 최신 1.*x* 버전으로 업데이트해야 합니다. 자세한 내용은 [마이그레이션 AWS Encryption SDK](migration.md)을 참조하세요. 새로운 보안 기능은 원래 AWS Encryption CLI 버전 1.7.*x* 및 2.0.*x*에서 릴리스되었습니다. 그러나 AWS Encryption CLI 버전 1.8.*x*는 버전 1.7.*x*를 대체하고 AWS Encryption CLI 2.1.*x*는 2.0.*x*를 대체합니다. 자세한 내용은 GitHub의 [aws-encryption-sdk-cli](https://github.com/aws/aws-encryption-sdk-cli/) 리포지토리에서 관련 [보안 권고](https://github.com/aws/aws-encryption-sdk-cli/security/advisories/GHSA-2xwp-m7mq-7q3r)를 참조하세요. **최신 버전의 AWS Encryption CLI를 설치하려면** ``` pip install aws-encryption-sdk-cli ``` ** AWS Encryption CLI의 최신 버전으로 업그레이드하려면** ``` pip install --upgrade aws-encryption-sdk-cli ``` ** AWS Encryption CLI 및의 버전 번호를 찾으려면 AWS Encryption SDK** ``` aws-encryption-cli --version ``` 출력에는 두 라이브러리의 버전 번호가 나열됩니다. ``` aws-encryption-sdk-cli/2.1.0 aws-encryption-sdk/2.0.0 ``` ** AWS Encryption CLI의 최신 버전으로 업그레이드하려면** ``` pip install --upgrade aws-encryption-sdk-cli ``` AWS Encryption CLI를 설치하면 아직 설치되지 않은 AWS SDK for Python (Boto3)경우 최신 버전의 도 설치됩니다. Boto3가 설치된 경우 설치 프로그램은 Boto3 버전을 확인하고 필요한 경우 업데이트합니다. **설치된 Boto3 버전 찾기** ``` pip show boto3 ``` **Boto3의 최신 버전으로 업데이트** ``` pip install --upgrade boto3 ``` 현재 개발 중인 AWS Encryption CLI 버전을 설치하려면 GitHub의 [aws-encryption-sdk-cli](https://github.com/aws/aws-encryption-sdk-cli/) 리포지토리를 참조하세요. `pip`를 사용하여 Python 패키지를 설치 및 업그레이드하는 방법에 대한 자세한 내용은 [pip 설명서](https://pip.pypa.io/en/stable/quickstart/)를 참조하세요. # AWS Encryption CLI 사용 방법 이 주제에서는 AWS 암호화 CLI에서 파라미터를 사용하는 방법을 설명합니다. 예제는 [AWS 암호화 CLI의 예](crypto-cli-examples.md) 섹션을 참조하세요. 전체 설명서는 [문서 읽기](https://aws-encryption-sdk-cli.readthedocs.io/en/latest/)를 참조하세요. 이 예제에 표시된 구문은 AWS Encryption CLI 버전 2.1.*x* 이상용입니다. **참고** 4.0.0 이전의 AWS Encryption CLI 버전은 [end-of-support 단계에](https://docs.aws.amazon.com/sdkref/latest/guide/maint-policy.html#version-life-cycle) 있습니다. 코드나 데이터를 변경하지 않고 버전 2.1.*x* 이상에서 AWS Encryption CLI의 최신 버전으로 안전하게 업데이트할 수 있습니다. 그러나 버전 2.1.*x*에 도입된 [새로운 보안 기능](about-versions.md#version-2)은 이하 버전과 호환되지 않습니다. 버전 1.7.*x* 이하에서 업데이트하려면 먼저 AWS Encryption CLI의 최신 1.*x* 버전으로 업데이트해야 합니다. 자세한 내용은 [마이그레이션 AWS Encryption SDK](migration.md)을 참조하세요. 새로운 보안 기능은 원래 AWS Encryption CLI 버전 1.7.*x* 및 2.0.*x*에서 릴리스되었습니다. 그러나 AWS Encryption CLI 버전 1.8.*x*는 버전 1.7.*x*를 대체하고 AWS Encryption CLI 2.1.*x*는 2.0.*x*를 대체합니다. 자세한 내용은 GitHub의 [aws-encryption-sdk-cli](https://github.com/aws/aws-encryption-sdk-cli/) 리포지토리에서 관련 [보안 권고](https://github.com/aws/aws-encryption-sdk-cli/security/advisories/GHSA-2xwp-m7mq-7q3r)를 참조하세요. 암호화된 데이터 키를 제한하는 보안 기능을 사용하는 방법을 보여주는 예제는 [암호화된 데이터 키 제한](configure.md#config-limit-keys) 섹션을 참조하세요. AWS KMS 다중 리전 키를 사용하는 방법을 보여주는 예는 섹션을 참조하세요[다중 리전 사용 AWS KMS keys](configure.md#config-mrks). **Topics** + [데이터 암호화 및 복호화 방법](#crypto-cli-e-d-intro) + [래핑 키를 지정하는 방법](#crypto-cli-master-key) + [입력을 제공하는 방법](#crypto-cli-input) + [출력 위치를 지정하는 방법](#crypto-cli-output) + [암호화 컨텍스트를 사용하는 방법](#crypto-cli-encryption-context) + [커밋 정책을 지정하는 방법](#crypto-cli-commitment-policy) + [구성 파일에 파라미터를 저장하는 방법](#crypto-cli-config-file) ## 데이터 암호화 및 복호화 방법 AWS Encryption CLI는의 기능을 사용하여 데이터를 쉽게 암호화하고 해독할 수 AWS Encryption SDK 있습니다. **참고** 이 `--master-keys` 파라미터는 AWS Encryption CLI의 버전 1.8.*x*에서 더 이상 사용되지 않으며 버전 2.1*x*에서 제거되었습니다. 대신 `--wrapping-keys` 파라미터를 사용합니다. 버전 2.1.*x*부터 암호화 및 복호화 시 `--wrapping-keys` 파라미터가 필요합니다. 자세한 내용은 [AWS Encryption SDK CLI 구문 및 파라미터 참조](crypto-cli-reference.md)을 참조하세요. + AWS 암호화 CLI에서 데이터를 암호화할 때 일반 텍스트 데이터와 AWS KMS key in AWS Key Management Service ()과 같은 [래핑 키](concepts.md#master-key)(또는 *마스터 키*)를 지정합니다AWS KMS. 사용자 지정 마스터 키 공급자를 사용하는 경우 공급자를 지정해야 합니다. 또한 암호화 작업에 대한 [암호화된 메시지](concepts.md#message) 및 메타데이터의 출력 위치를 지정할 수 있습니다. [암호화 컨텍스트](concepts.md#encryption-context)는 선택 사항이지만 권장됩니다. 버전 1.8.*x*에서, `--wrapping-keys` 파라미터를 사용하는 경우 `--commitment-policy` 파라미터가 필요하며, 그러지 않으면 유효하지 않습니다. 버전 2.1.*x*부터 `--commitment-policy` 파라미터는 선택 사항이지만 권장됩니다. ``` aws-encryption-cli --encrypt --input myPlaintextData \ --wrapping-keys key=1234abcd-12ab-34cd-56ef-1234567890ab \ --output myEncryptedMessage \ --metadata-output ~/metadata \ --encryption-context purpose=test \ --commitment-policy require-encrypt-require-decrypt ``` AWS Encryption CLI는 고유한 데이터 키로 데이터를 암호화합니다. 그러면 지정한 래핑 키에서 데이터 키가 암호화됩니다. 작업에 대한 [암호화된 메시지](concepts.md#message) 및 메타데이터를 반환합니다. 암호화된 메시지에는 암호화된 데이터(*사이퍼텍스트*) 및 암호화된 데이터 키 사본이 포함되어 있습니다. 데이터 키의 저장, 관리 또는 분실에 대해 걱정할 필요가 없습니다.   + 데이터를 복호화할 때는 암호화된 메시지, 선택적 암호화 컨텍스트, 일반 텍스트 출력 및 메타데이터의 위치를 전달합니다. 또한 AWS 암호화 CLI가 메시지를 해독하는 데 사용할 수 있는 래핑 키를 지정하거나 AWS 암호화 CLI에 메시지를 암호화한 래핑 키를 사용할 수 있다고 알립니다. 버전 1.8.*x*부터 복호화 시 `--wrapping-keys` 파라미터는 선택 사항이지만 권장됩니다. 버전 2.1.*x*부터 암호화 및 복호화 시 `--wrapping-keys` 파라미터가 필요합니다. 복호화할 때 `--wrapping-keys` 파라미터의 **key** 속성을 사용하여 데이터를 복호화하는 래핑 키를 지정할 수 있습니다. 복호화 시 AWS KMS 래핑 키를 지정하는 것은 선택 사항이지만 사용하지 않을 키를 사용하지 못하게 하는 [모범 사례](best-practices.md)입니다. 사용자 지정 마스터 키 공급자를 사용하는 경우 공급자 및 래핑 키를 지정해야 합니다. **키** 속성을 사용하지 않는 경우 `--wrapping-keys` 파라미터의 [**검색** 속성을](#discovery-cli-attribute) 로 설정해야 합니다. `true`그러면 AWS 암호화 CLI가 메시지를 암호화한 래핑 키를 사용하여 복호화할 수 있습니다. 암호화된 데이터 키가 너무 많은 잘못된 형식의 메시지를 복호화하지 않도록 `--max-encrypted-data-keys` 파라미터를 사용하는 것이 모범 사례입니다. 암호화된 데이터 키의 예상 수(암호화에 사용되는 각 래핑 키당 하나) 또는 합리적인 최대값(예: 5개)을 지정합니다. 자세한 내용은 [암호화된 데이터 키 제한](configure.md#config-limit-keys)을 참조하세요. `--buffer` 파라미터는 디지털 서명이 있는지 확인하는 등 모든 입력이 처리된 후에만 일반 텍스트를 반환합니다. `--decrypt-unsigned` 파라미터는 사이퍼텍스트를 복호화하고, 복호화 전에 메시지가 서명되지 않도록 합니다. `--algorithm` 파라미터를 사용하고 디지털 서명이 없는 알고리즘 제품군을 선택하여 데이터를 암호화한 경우 이 파라미터를 사용합니다. 사이퍼텍스트가 서명된 경우 복호화가 실패합니다. `--decrypt` 또는 `--decrypt-unsigned`를 복호화에 사용할 수 있지만 둘 다 사용할 수는 없습니다. ``` aws-encryption-cli --decrypt --input myEncryptedMessage \ --wrapping-keys key=1234abcd-12ab-34cd-56ef-1234567890ab \ --output myPlaintextData \ --metadata-output ~/metadata \ --max-encrypted-data-keys 1 \ --buffer \ --encryption-context purpose=test \ --commitment-policy require-encrypt-require-decrypt ``` AWS Encryption CLI는 래핑 키를 사용하여 암호화된 메시지의 데이터 키를 복호화합니다. 그런 다음 데이터 키를 사용하여 해당 데이터를 복호화합니다. 작업에 대한 일반 텍스트 데이터 및 메타데이터를 반환합니다. ## 래핑 키를 지정하는 방법 AWS 암호화 CLI에서 데이터를 암호화할 때는 하나 이상의 [래핑 키](concepts.md#master-key)(또는 *마스터 키*)를 지정해야 합니다. AWS KMS keys in AWS Key Management Service (AWS KMS), 사용자 지정 [마스터 키 공급자의 래핑 키](concepts.md#master-key-provider) 또는 둘 다를 사용할 수 있습니다. 사용자 지정 마스터 키 공급자는 호환되는 모든 Python 마스터 키 공급자일 수 있습니다. 버전 1.8.*x* 이상에서 래핑 키를 지정하려면 `--wrapping-keys` 파라미터(`-w`)를 사용합니다. 이 파라미터의 값은 `attribute=value` 형식의 [속성](#cli-master-key-attributes) 모음입니다. 사용하는 속성은 마스터 키 공급자 및 명령에 따라 달라집니다. + **AWS KMS**. 암호화 명령에서 **key** 속성이 있는 `--wrapping-keys` 파라미터를 지정해야 합니다. 버전 2.1.*x*부터 복호화 명령에 `--wrapping-keys` 파라미터도 필요합니다. 복호화할 때는 `--wrapping-keys` 파라미터에 값이 `true`인 **key** 속성 또는 **discovery** 속성이 있어야 합니다(둘 다는 아님). 다른 속성은 선택 사항입니다. + **사용자 지정 마스터 키 공급자**. 모든 명령에 `--wrapping-keys` 파라미터를 지정해야 합니다. 파라미터 값에는 **key** 및 **provider** 속성이 있어야 합니다. 동일한 명령에 [여러 `--wrapping-keys` 파라미터](#cli-many-cmks) 및 여러 **key** 속성을 포함할 수 있습니다. ### 주요 파라미터 속성 래핑 `--wrapping-keys` 파라미터 값은 다음 속성 및 해당 값으로 구성됩니다. 모든 암호화 명령에는 `--wrapping-keys`(또는 `--master-keys`) 파라미터가 필요합니다. 버전 2.1.*x*부터 복호화 시 `--wrapping-keys` 파라미터도 필요합니다. 속성 이름 또는 값에 공백이나 특수 문자가 포함된 경우 이름과 값을 모두 인용 부호로 묶습니다. 예를 들어 `--wrapping-keys key=12345 "provider=my cool provider"`입니다. **Key: 래핑 키 지정** **key** 속성을 사용하여 래핑 키를 식별합니다. 암호화할 때 값은 마스터 키 공급자가 인식하는 모든 키 식별자일 수 있습니다. ``` --wrapping-keys key=1234abcd-12ab-34cd-56ef-1234567890ab ``` 암호화 명령에는 하나 이상의 **key** 속성 및 값을 포함해야 합니다. 여러 래핑 키로 데이터 키를 암호화하려면 [여러 **key** 속성](#cli-many-cmks)을 사용합니다. ``` aws-encryption-cli --encrypt --wrapping-keys key=1234abcd-12ab-34cd-56ef-1234567890ab key=1a2b3c4d-5e6f-1a2b-3c4d-5e6f1a2b3c4d ``` 를 사용하는 암호화 명령에서 **키** 값은 키 ID AWS KMS keys, 키 ARN, 별칭 이름 또는 별칭 ARN일 수 있습니다. 예를 들어, 이 암호화 명령은 **key** 속성 값에 별칭 ARN을 사용합니다. 의 키 식별자에 대한 자세한 내용은 *AWS Key Management Service 개발자 안내서*의 [키 식별자](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id)를 AWS KMS key참조하세요. ``` aws-encryption-cli --encrypt --wrapping-keys key=arn:aws:kms:us-west-2:111122223333:alias/ExampleAlias ``` 사용자 지정 마스터 키 공급자를 사용하는 복호화 명령에서 **key** 및 **provider** 속성이 필요합니다. ``` \\ Custom master key provider aws-encryption-cli --decrypt --wrapping-keys provider='myProvider' key='100101' ``` 가 사용하는 복호화 명령에서 **키** 속성을 사용하여 복호화에 AWS KMS keys 사용할를 지정하거나 값이 인 [**검색** 속성을](#discovery-cli-attribute) AWS KMS지정하여 AWS Encryption CLI`true`가 메시지를 암호화하는 데 사용된 AWS KMS key 를 사용할 수 있습니다. 를 지정하는 경우 메시지를 암호화하는 데 사용되는 래핑 키 중 하나여야 AWS KMS key합니다. 래핑 키를 지정하는 것이 [AWS Encryption SDK 모범 사례](best-practices.md)입니다. 이를 통해 사용하려는를 사용할 수 AWS KMS key 있습니다. 복호화 명령에서 **key** 속성 값은 [키 ARN](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-key-ARN)이어야 합니다. ``` \\ AWS KMS key aws-encryption-cli --decrypt --wrapping-keys key=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab ``` **검색: 복호화 AWS KMS key 시 사용** 복호화 시 사용할 AWS KMS keys 를 제한할 필요가 없는 경우 값이 인 **검색** 속성을 사용할 수 있습니다`true`. 값이 이면 AWS Encryption CLI`true`가 메시지를 암호화 AWS KMS key 한를 사용하여 복호화할 수 있습니다. **discovery** 속성을 지정하지 않는 경우 discovery는 `false`(기본값)입니다. **검색** 속성은 복호화 명령에서만 유효하며 메시지가 암호화된 경우에만 유효합니다 AWS KMS keys. 값이 `true`인 **discovery** 속성은 **key** 속성을 사용하여 AWS KMS keys를 지정하는 대신 사용할 수 있습니다. 로 암호화된 메시지를 복호화할 때 AWS KMS keys각 `--wrapping-keys` 파라미터에는 **키** 속성 또는 값이 `true`이지만 둘 다는 아닌 **검색** 속성이 있어야 합니다. 검색이 true인 경우 **discovery-partition** 및 **discovery-account** 속성을 사용하여 AWS 계정 지정한의 속성으로 AWS KMS keys 사용되는를 제한하는 것이 가장 좋습니다. 다음 예제에서 **검색** 속성을 사용하면 AWS Encryption CLI가 지정된 AWS KMS key 의를 사용할 수 있습니다 AWS 계정. ``` aws-encryption-cli --decrypt --wrapping-keys \ discovery=true \ discovery-partition=aws \ discovery-account=111122223333 \ discovery-account=444455556666 ``` **Provider: 마스터 키 공급자 지정** **provider** 속성은 [마스터 키 공급자](concepts.md#master-key-provider)를 식별합니다. 기본값은 `aws-kms`이며, 이는 AWS KMS를 나타냅니다. 다른 마스터 키 공급자를 사용하는 경우 **provider** 속성이 필요합니다. ``` --wrapping-keys key=12345 provider=my_custom_provider ``` 사용자 지정(비AWS KMS) 마스터 키 공급자 사용에 대한 자세한 내용은 [AWS Encryption CLI](https://github.com/aws/aws-encryption-sdk-cli/) 리포지토리의 [README](https://github.com/aws/aws-encryption-sdk-cli/blob/master/README.rst) 파일에서 **고급 구성** 항목을 참조하세요. **리전: 지정 AWS 리전** **리전** 속성을 사용하여 AWS 리전 의를 지정합니다 AWS KMS key. 이 속성은 암호화 명령에서, 그리고 마스터 키 공급자가 AWS KMS인 경우에만 유효합니다. ``` --encrypt --wrapping-keys key=alias/primary-key region=us-east-2 ``` AWS 암호화 CLI 명령은 ARN과 같은 리전 AWS 리전 이 포함된 경우 **키** 속성 값에 지정된를 사용합니다. **키** 값이를 지정하면 AWS 리전**리전** 속성이 무시됩니다. **region** 속성은 다른 리전 사양보다 우선합니다. 리전 속성을 사용하지 않는 경우 AWS 암호화 CLI 명령은 AWS CLI [명명된 프로필](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html#cli-configure-files-using-profiles)에 AWS 리전 지정된 또는 기본 프로필을 사용합니다. **Profile: 명명된 프로필 지정** **profile** 속성을 사용하여 AWS CLI [명명된 프로필](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html#cli-configure-files-using-profiles)을 지정합니다. 명명된 프로필에는 보안 인증 및 AWS 리전이 포함될 수 있습니다. 이 속성은 마스터 키 공급자가 AWS KMS인 경우에만 유효합니다. ``` --wrapping-keys key=alias/primary-key profile=admin-1 ``` **profile** 속성을 사용하여 암호화 및 복호화 명령에서 대체 보안 인증을 지정할 수 있습니다. 암호화 명령에서 AWS Encryption CLI는 **키** 값에 리전이 포함되지 않고 **리전** 속성이 없는 경우에만 명명된 프로파일 AWS 리전 에서를 사용합니다. 복호화 명령에서는 이름 프로필 AWS 리전 의이 무시됩니다. ### 여러 래핑 키를 지정하는 방법 각 명령에 여러 래핑 키(또는 *마스터 키*)를 지정할 수 있습니다. 래핑 키를 두 개 이상 지정하면 첫 번째 래핑 키가 데이터 암호화에 사용되는 데이터 키를 생성 및 암호화합니다. 다른 래핑 키는 동일한 데이터 키를 암호화합니다. 결과적으로 생성되는 [암호화된 메시지](concepts.md#message)에는 암호화된 데이터("사이퍼텍스트")와 암호화된 데이터 키 모음(각 래핑 키로 하나씩 암호화됨)이 포함됩니다. 모든 래핑은 암호화된 데이터 키 하나를 복호화한 다음 데이터를 복호화할 수 있습니다. 여러 래핑 키는 다음과 같이 두 가지 방법으로 지정할 수 있습니다. + `--wrapping-keys` 파라미터 값에 여러 **key** 속성을 포함합니다. ``` $key_oregon=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab $key_ohio=arn:aws:kms:us-east-2:111122223333:key/0987ab65-43cd-21ef-09ab-87654321cdef --wrapping-keys key=$key_oregon key=$key_ohio ``` + 동일한 명령에 여러 `--wrapping-keys` 파라미터를 포함합니다. 지정한 속성 값이 명령의 일부 래핑 키에 적용되지 않는 경우 다음 구문을 사용합니다. ``` --wrapping-keys region=us-east-2 key=alias/test_key \ --wrapping-keys region=us-west-1 key=alias/test_key ``` 값이 인 **검색** 속성을 `true` 사용하면 AWS 암호화 CLI가 메시지를 암호화 AWS KMS key 한 모든를 사용할 수 있습니다. 동일한 명령에서 여러 `--wrapping-keys` 파라미터를 사용하는 경우 `--wrapping-keys` 파라미터의 `discovery=true`를 사용하면 다른 `--wrapping-keys` 파라미터에 있는 **key** 속성의 제한을 효과적으로 재정의할 수 있습니다. 예를 들어 다음 명령에서 첫 번째 `--wrapping-keys` 파라미터의 **키** 속성은 AWS Encryption CLI를 지정된 로 제한합니다 AWS KMS key. 그러나 두 번째 `--wrapping-keys` 파라미터의 **검색** 속성을 사용하면 AWS Encryption CLI가 지정된 계정 AWS KMS key 의를 사용하여 메시지를 해독할 수 있습니다. ``` aws-encryption-cli --decrypt \ --wrapping-keys key=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab \ --wrapping-keys discovery=true \ discovery-partition=aws \ discovery-account=111122223333 \ discovery-account=444455556666 ``` ## 입력을 제공하는 방법 Encryption CLI의 AWS 암호화 작업은 일반 텍스트 데이터를 입력으로 받아 [암호화된 메시지를](concepts.md#message) 반환합니다. 복호화 작업은 암호화된 메시지를 입력으로 받아 일반 텍스트 데이터를 반환합니다. 입력 위치를 AWS Encryption CLI에 알려주는 `--input` 파라미터(`-i`)는 모든 AWS Encryption CLI 명령에 필요합니다. 다음 방법 중 하나를 사용하여 입력을 제공할 수 있습니다. + 파일을 사용합니다. ``` --input myData.txt ``` + 파일 이름 패턴을 사용합니다. ``` --input testdir/*.xml ``` + 디렉터리 또는 디렉터리 이름 패턴을 사용합니다. 입력이 디렉터리인 경우 `--recursive` 파라미터(`-r`, `-R`)가 필요합니다. ``` --input testdir --recursive ``` + 입력을 명령(stdin)에 전달합니다. `-` 파라미터에 `--input` 값을 사용합니다. (`--input` 파라미터는 항상 필요합니다.) ``` echo 'Hello World' | aws-encryption-cli --encrypt --input - ``` ## 출력 위치를 지정하는 방법 `--output` 파라미터는 AWS 암호화 또는 복호화 작업의 결과를 작성할 위치를 암호화 CLI에 알려줍니다. 이는 모든 AWS Encryption CLI 명령에 필요합니다. AWS Encryption CLI는 작업의 모든 입력 파일에 대해 새 출력 파일을 생성합니다. 출력 파일이 이미 있는 경우 기본적으로 AWS Encryption CLI는 경고를 인쇄한 다음 파일을 덮어씁니다. 덮어쓰기를 방지하려면, 덮어쓰기 전에 확인 메시지를 표시하는 `--interactive` 파라미터를 사용하거나, 출력으로 인해 덮어쓰기가 발생할 경우 입력을 건너뛰는 `--no-overwrite`를 사용합니다. 덮어쓰기 경고를 표시하지 않으려면 `--quiet`를 사용합니다. AWS Encryption CLI에서 오류 및 경고를 캡처하려면 `2>&1`리디렉션 연산자를 사용하여 출력 스트림에 기록합니다. **참고** 출력 파일을 덮어쓰는 명령은 출력 파일을 삭제하여 시작합니다. 명령이 실패하는 경우 출력 파일이 이미 삭제되었을 수 있습니다. 여러 가지 방법으로 출력 위치를 지정할 수 있습니다. + 파일 이름을 지정합니다. 파일 경로를 지정하는 경우 명령이 실행되기 전에 경로에 있는 모든 디렉터리가 존재해야 합니다. ``` --output myEncryptedData.txt ``` + 디렉터리를 지정합니다. 명령이 실행되기 전에 출력 디렉터리가 있어야 합니다. 입력에 하위 디렉터리가 포함된 경우 명령은 지정된 디렉터리 아래의 하위 디렉터리를 다시 생성합니다. ``` --output Test ``` 출력 위치가 디렉터리(파일 이름 없음)인 경우 AWS Encryption CLI는 입력 파일 이름과 접미사를 기반으로 출력 파일 이름을 생성합니다. 암호화 작업은 `.encrypted`를 입력 파일 이름에 추가하고 복호화 작업은 `.decrypted`를 추가합니다. 접미사를 변경하려면 `--suffix` 파라미터를 사용합니다. 예를 들어, `file.txt`를 암호화하면 암호화 명령이 `file.txt.encrypted`를 생성합니다. `file.txt.encrypted`를 복호화하면 복호화 명령이 `file.txt.encrypted.decrypted`를 생성합니다.   + 명령줄(stdout)에 씁니다. `--output` 파라미터의 `-` 값을 입력합니다. `--output -`을 사용하여 출력을 다른 명령이나 프로그램으로 전달할 수 있습니다. ``` --output - ``` ## 암호화 컨텍스트를 사용하는 방법 AWS 암호화 CLI를 사용하면 암호화 및 복호화 명령에서 암호화 컨텍스트를 제공할 수 있습니다. 필수는 아니지만 권장되는 암호화 모범 사례입니다. *암호화 컨텍스트*는 비밀이 아닌 임의의 *추가 인증 데이터* 유형입니다. AWS Encryption CLI에서 암호화 컨텍스트는 `name=value` 페어 모음으로 구성됩니다. 파일에 대한 정보, 로그에서 암호화 작업을 찾는 데 도움이 되는 데이터 또는 허가나 정책에 필요한 데이터를 포함하여 페어로 구성된 모든 콘텐츠를 사용할 수 있습니다. **암호화 명령** 암호화 명령에서 지정하는 암호화 컨텍스트와, [CMM](concepts.md#crypt-materials-manager)이 추가하는 추가 페어는 암호화된 데이터에 암호화 방식으로 바인딩됩니다. 또한 명령이 반환하는 [암호화된 메시지](concepts.md#encryption-context)에도 (일반 텍스트로) 포함됩니다. 를 사용하는 경우 AWS KMS key암호화 컨텍스트는와 같은 감사 레코드 및 로그에 일반 텍스트로 표시될 수도 있습니다 AWS CloudTrail. 다음 예제는 `name=value` 페어 3개로 구성된 암호화 컨텍스트를 보여줍니다. ``` --encryption-context purpose=test dept=IT class=confidential ``` **복호화 명령** 복호화 명령에서 암호화 컨텍스트는 암호화된 메시지를 올바르게 복호화하고 있는지 확인하는 데 도움이 됩니다. 암호화 시 암호화 컨텍스트를 사용한 경우에도 복호화 명령에 암호화 컨텍스트를 제공할 필요는 없습니다. 그러나 이렇게 하면 AWS 암호화 CLI는 복호화 명령의 암호화 컨텍스트에 있는 모든 요소가 암호화된 메시지의 암호화 컨텍스트에 있는 요소와 일치하는지 확인합니다. 요소가 일치하지 않으면 복호화 명령이 실패합니다. 예를 들어, 다음 명령은 암호화 컨텍스트에 `dept=IT`가 포함된 경우에만 암호화된 메시지를 복호화합니다. ``` aws-encryption-cli --decrypt --encryption-context dept=IT ... ``` 암호화 컨텍스트는 보안 전략의 중요한 부분입니다. 그러나 암호화 컨텍스트를 선택할 때는 해당 값이 비밀이 아님을 기억해야 합니다. 암호화 컨텍스트에 기밀 데이터를 포함하지 마세요. **암호화 컨텍스트 지정** + **암호화** 명령에서 `--encryption-context` 파라미터를 하나 이상의 `name=value` 페어와 함께 사용합니다. 공백을 사용하여 각 페어를 구분합니다. ``` --encryption-context name=value [name=value] ... ``` + **복호화** 명령의 `--encryption-context` 파라미터 값에는 `name=value` 페어, `name` 요소(값 없음) 또는 이 둘의 조합이 포함될 수 있습니다. ``` --encryption-context name[=value] [name] [name=value] ... ``` `name=value` 페어의 `name` 또는 `value`에 공백이나 특수 문자가 포함된 경우 전체 페어를 인용 부호로 묶습니다. ``` --encryption-context "department=software engineering" "AWS 리전=us-west-2" ``` 예를 들어, 이 암호화 명령에는 두 페어의 `purpose=test` 및 `dept=23`이 포함된 암호화 컨텍스트가 포함됩니다. ``` aws-encryption-cli --encrypt --encryption-context purpose=test dept=23 ... ``` 이러한 복호화 명령은 성공합니다. 각 명령의 암호화 컨텍스트는 원래 암호화 컨텍스트의 하위 집합입니다. ``` \\ Any one or both of the encryption context pairs aws-encryption-cli --decrypt --encryption-context dept=23 ... \\ Any one or both of the encryption context names aws-encryption-cli --decrypt --encryption-context purpose ... \\ Any combination of names and pairs aws-encryption-cli --decrypt --encryption-context dept purpose=test ... ``` 하지만 이러한 복호화 명령은 실패합니다. 암호화된 메시지의 암호화 컨텍스트에는 지정된 요소가 포함되어 있지 않습니다. ``` aws-encryption-cli --decrypt --encryption-context dept=Finance ... aws-encryption-cli --decrypt --encryption-context scope ... ``` ## 커밋 정책을 지정하는 방법 명령에 대한 [커밋 정책](concepts.md#commitment-policy)을 설정하려면 [`--commitment-policy` 파라미터](crypto-cli-reference.md#syntax-commitment-policy)를 사용합니다. 이 파라미터는 버전 1.8.*x*에 도입되었습니다. 이는 암호화 및 복호화 명령에 유효합니다. 설정한 커밋 정책은 해당 정책이 나타나는 명령에만 유효합니다. 명령에 대한 커밋 정책을 설정하지 않으면 AWS Encryption CLI가 기본값을 사용합니다. 예를 들어 다음 파라미터 값은 커밋 정책을 `require-encrypt-allow-decrypt`로 설정합니다. 이 경우 커밋 정책은 항상 키 커밋으로 암호화하지만 키 커밋 사용 여부와 관계없이 암호화된 사이퍼텍스트는 복호화됩니다. ``` --commitment-policy require-encrypt-allow-decrypt ``` ## 구성 파일에 파라미터를 저장하는 방법 자주 사용되는 AWS Encryption CLI 파라미터와 값을 구성 파일에 저장하여 시간을 절약하고 입력 오류를 방지할 수 있습니다. *구성 파일은* AWS Encryption CLI 명령의 파라미터와 값을 포함하는 텍스트 파일입니다. AWS Encryption CLI 명령에서 구성 파일을 참조하면 참조가 구성 파일의 파라미터 및 값으로 대체됩니다. 명령줄에 파일 내용을 입력한 경우에도 동일한 효과가 나타납니다. 구성 파일은 어떤 이름이든 가질 수 있으며 현재 사용자가 액세스할 수 있는 모든 디렉터리에 위치할 수 있습니다. 다음 예제 구성 파일인 `key.conf`는 서로 다른 리전에 AWS KMS keys 두 개를 지정합니다. ``` --wrapping-keys key=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab --wrapping-keys key=arn:aws:kms:us-east-2:111122223333:key/0987ab65-43cd-21ef-09ab-87654321cdef ``` 명령에서 구성 파일을 사용하려면 파일 이름 앞에 at 기호(`@`)를 붙입니다. PowerShell 콘솔에서는 백틱 문자를 사용하여 at 기호(``@`)를 이스케이프 처리합니다. 이 예제 명령은 암호화 명령에서 `key.conf` 파일을 사용합니다. ------ #### [ Bash ] ``` $ aws-encryption-cli -e @key.conf -i hello.txt -o testdir ``` ------ #### [ PowerShell ] ``` PS C:\> aws-encryption-cli -e `@key.conf -i .\Hello.txt -o .\TestDir ``` ------ **구성 파일 규칙** 구성 파일 사용 규칙은 다음과 같습니다. + 각 구성 파일에 여러 파라미터를 포함하고 원하는 순서대로 나열할 수 있습니다. 각 파라미터를 해당 값(있는 경우)과 함께 별도의 줄에 나열합니다. + `#`을 사용하여 줄 전체 또는 일부에 주석을 추가합니다. + 다른 구성 파일에 대한 참조를 포함할 수 있습니다. PowerShell에서도 백틱을 사용하여 `@` 기호를 이스케이프 처리하지 마세요. + 구성 파일에서 따옴표를 사용하는 경우 인용된 텍스트는 여러 줄에 걸쳐 있을 수 없습니다. 예를 들어, 예제 `encrypt.conf` 파일의 내용은 다음과 같습니다. ``` # Archive Files --encrypt --output /archive/logs --recursive --interactive --encryption-context class=unclassified dept=IT --suffix # No suffix --metadata-output ~/metadata @caching.conf # Use limited caching ``` 명령에 여러 구성 파일을 포함할 수도 있습니다. 이 예제 명령은 `encrypt.conf` 및 `master-keys.conf` 구성 파일을 모두 사용합니다. ------ #### [ Bash ] ``` $ aws-encryption-cli -i /usr/logs @encrypt.conf @master-keys.conf ``` ------ #### [ PowerShell ] ``` PS C:\> aws-encryption-cli -i $home\Test\*.log `@encrypt.conf `@master-keys.conf ``` ------ **다음: ** [AWS Encryption CLI 예제 사용해 보기](crypto-cli-examples.md) # AWS 암호화 CLI의 예 다음 예제를 사용하여 원하는 플랫폼에서 AWS 암호화 CLI를 사용해 보세요. 마스터 키 및 기타 파라미터에 대한 도움말은 [AWS Encryption CLI 사용 방법](crypto-cli-how-to.md) 섹션을 참조하세요. 빠른 참조는 [AWS Encryption SDK CLI 구문 및 파라미터 참조](crypto-cli-reference.md) 섹션을 참조하세요. **참고** 다음 예제에서는 AWS Encryption CLI 버전 2.1.*x*의 구문을 사용합니다. 새로운 보안 기능은 원래 AWS Encryption CLI 버전 1.7.*x* 및 2.0.*x*에서 릴리스되었습니다. 그러나 AWS Encryption CLI 버전 1.8.*x*는 버전 1.7.*x*를 대체하고 AWS Encryption CLI 2.1.*x*는 2.0.*x*를 대체합니다. 자세한 내용은 GitHub의 [aws-encryption-sdk-cli](https://github.com/aws/aws-encryption-sdk-cli/) 리포지토리에서 관련 [보안 권고](https://github.com/aws/aws-encryption-sdk-cli/security/advisories/GHSA-2xwp-m7mq-7q3r)를 참조하세요. 암호화된 데이터 키를 제한하는 보안 기능을 사용하는 방법을 보여주는 예제는 [암호화된 데이터 키 제한](configure.md#config-limit-keys) 섹션을 참조하세요. AWS KMS 다중 리전 키를 사용하는 방법을 보여주는 예는 섹션을 참조하세요[다중 리전 사용 AWS KMS keys](configure.md#config-mrks). **Topics** + [파일 암호화](#cli-example-encrypt-file) + [파일 복호화](#cli-example-decrypt-file) + [디렉터리의 모든 파일 암호화](#cli-example-encrypt-directory) + [디렉터리의 모든 파일 복호화](#cli-example-decrypt-directory) + [명령줄에서 암호화 및 복호화](#cli-example-stdin) + [여러 마스터 키 사용](#cli-example-multimaster) + [스크립트의 암호화 및 복호화](#cli-example-script) + [데이터 키 캐싱 사용](#cli-example-caching) ## 파일 암호화 이 예제에서는 AWS Encryption CLI를 사용하여 "Hello World" 문자열이 포함된 `hello.txt` 파일의 내용을 암호화합니다. 파일에서 암호화 명령을 실행하면 AWS Encryption CLI는 파일의 콘텐츠를 가져오고, 고유한 [데이터 키를](concepts.md#DEK) 생성하고, 데이터 키 아래의 파일 콘텐츠를 암호화한 다음 암호화된 [메시지를](concepts.md#message) 새 파일에 씁니다. 첫 번째 명령은의 키 ARN을 `$keyArn` 변수 AWS KMS key 에 저장합니다. 를 사용하여 암호화할 때 키 ID AWS KMS key, 키 ARN, 별칭 이름 또는 별칭 ARN을 사용하여 식별할 수 있습니다. 의 키 식별자에 대한 자세한 내용은 *AWS Key Management Service 개발자 안내서*의 [키 식별자](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id)를 AWS KMS key참조하세요. 두 번째 명령은 파일 내용을 암호화합니다. 이 명령은 `--encrypt` 파라미터를 사용하여 작업을 지정하고 `--input` 파라미터를 사용하여 암호화할 파일을 표시합니다. [`--wrapping-keys` 파라미터](crypto-cli-how-to.md#crypto-cli-master-key)와 필요한 **키** 속성은 키 ARN으로 AWS KMS key 표시되는를 사용하도록 명령에 지시합니다. 이 명령은 `--metadata-output` 파라미터를 사용하여 암호화 작업에 대한 메타데이터를 위한 텍스트 파일을 지정합니다. 명령이 `--encryption-context` 파라미터를 사용하여 [암호화 컨텍스트](crypto-cli-how-to.md#crypto-cli-encryption-context)를 지정하는 것이 모범 사례입니다. 또한 이 명령은 [`--commitment-policy` 파라미터를](crypto-cli-reference.md#syntax-commitment-policy) 사용하여 커밋 정책을 명시적으로 설정합니다. 버전 1.8.*x*에서는 `--wrapping-keys` 파라미터를 사용할 때 이 파라미터가 필요합니다. 버전 2.1.*x*부터 `--commitment-policy` 파라미터는 선택 사항이지만 권장됩니다. `--output` 파라미터의 값인 점(.)은 출력 파일을 현재 디렉터리에 쓰도록 명령에 지시합니다. ------ #### [ Bash ] ``` \\ 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 \ --metadata-output ~/metadata \ --encryption-context purpose=test \ --commitment-policy require-encrypt-require-decrypt \ --output . ``` ------ #### [ PowerShell ] ``` # To run this example, replace the fictitious key ARN with a valid value. PS C:\> $keyArn = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab' PS C:\> aws-encryption-cli --encrypt ` --input Hello.txt ` --wrapping-keys key=$keyArn ` --metadata-output $home\Metadata.txt ` --commitment-policy require-encrypt-require-decrypt ` --encryption-context purpose=test ` --output . ``` ------ 암호화 명령이 성공하면 어떤 출력도 반환하지 않습니다. 명령의 성공 여부를 확인하려면 `$?` 변수의 부울 값을 확인합니다. 명령이 성공하면 `$?`의 값은 `0`(Bash) 또는 `True`(PowerShell)입니다. 명령이 실패하면 `$?`의 값은 0이 아니거나(Bash) `False`(PowerShell)입니다. ------ #### [ Bash ] ``` $ echo $? 0 ``` ------ #### [ PowerShell ] ``` PS C:\> $? True ``` ------ 디렉터리 목록 명령을 사용하여 암호화 명령이 `hello.txt.encrypted`라는 새 파일을 생성했는지 확인할 수도 있습니다. 암호화 명령이 출력의 파일 이름을 지정하지 않았기 때문에 AWS Encryption CLI는 입력 파일과 이름이 같고 접`.encrypted`미사가 있는 파일에 출력을 작성했습니다. 다른 접미사를 사용하거나 접미사를 숨기려면 `--suffix` 파라미터를 사용합니다. `hello.txt.encrypted` 파일에는 `hello.txt` 파일의 사이퍼텍스트, 데이터 키의 암호화된 사본, 추가 메타데이터(암호화 컨텍스트 포함)가 포함된 [암호화된 메시지](concepts.md#message)가 들어 있습니다. ------ #### [ Bash ] ``` $ ls hello.txt hello.txt.encrypted ``` ------ #### [ PowerShell ] ``` PS C:\> dir Directory: C:\TestCLI Mode LastWriteTime Length Name ---- ------------- ------ ---- -a---- 9/15/2017 5:57 PM 11 Hello.txt -a---- 9/17/2017 1:06 PM 585 Hello.txt.encrypted ``` ------ ## 파일 복호화 이 예제에서는 AWS Encryption CLI를 사용하여 이전 예제에서 암호화된 `Hello.txt.encrypted` 파일의 내용을 해독합니다. 복호화 명령은 `--decrypt` 파라미터를 사용하여 작업을 표시하고 `--input` 파라미터를 사용하여 복호화할 파일을 식별합니다. `--output` 파라미터의 값은 현재 디렉터리를 나타내는 점입니다. **key** 속성이 있는 `--wrapping-keys` 파라미터는 암호화된 메시지를 복호화하는 데 사용되는 래핑 키를 지정합니다. 를 사용한 복호화 명령에서 키 속성 AWS KMS keys의 값은 [키 ARN](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-key-ARN)이어야 합니다. `--wrapping-keys` 파라미터는 복호화 명령에 반드시 필요합니다. AWS KMS keys를 사용하는 경우 **key** 속성을 사용하여 복호화를 위해 AWS KMS keys 를 지정하거나 **discovery** 속성을 `true` 값으로 지정할 수 있습니다(둘 다 지정할 수는 없음). 사용자 지정 마스터 키 공급자를 사용하는 경우 **key** 속성과 **provider** 속성이 필요합니다. 버전 2.1.*x*부터 [`--commitment-policy` 파라미터](crypto-cli-reference.md#syntax-commitment-policy)는 선택 사항이지만 권장됩니다. 이를 명시적으로 사용하면 기본값인 `require-encrypt-require-decrypt`를 지정하더라도 의도를 명확히 알 수 있습니다. 암호화 명령에 [암호화 컨텍스트](crypto-cli-how-to.md#crypto-cli-encryption-context)가 제공된 경우에도 `--encryption-context` 파라미터는 복호화 명령에서 선택 사항입니다. 이 경우 복호화 명령은 암호화 명령에 제공된 것과 동일한 암호화 컨텍스트를 사용합니다. 암호화 해제 전에 AWS 암호화 CLI는 암호화된 메시지의 암호화 컨텍스트에 `purpose=test` 페어가 포함되어 있는지 확인합니다. 그러지 않으면 복호화 명령이 실패합니다. `--metadata-output` 파라미터는 복호화 작업에 대한 메타데이터를 위한 파일을 지정합니다. `--output` 파라미터의 값인 점(.)은 출력 파일을 현재 디렉터리에 씁니다. 암호화된 데이터 키가 너무 많은 잘못된 형식의 메시지를 복호화하지 않도록 `--max-encrypted-data-keys` 파라미터를 사용하는 것이 모범 사례입니다. 암호화된 데이터 키의 예상 수(암호화에 사용되는 각 래핑 키당 하나) 또는 합리적인 최대값(예: 5개)을 지정합니다. 자세한 내용은 [암호화된 데이터 키 제한](configure.md#config-limit-keys)을 참조하세요. `--buffer`는 디지털 서명이 있는지 확인하는 등 모든 입력이 처리된 후에만 일반 텍스트를 반환합니다. ------ #### [ Bash ] ``` \\ 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 \ --input hello.txt.encrypted \ --wrapping-keys key=$keyArn \ --commitment-policy require-encrypt-require-decrypt \ --encryption-context purpose=test \ --metadata-output ~/metadata \ --max-encrypted-data-keys 1 \ --buffer \ --output . ``` ------ #### [ PowerShell ] ``` \\ To run this example, replace the fictitious key ARN with a valid value. PS C:\> $keyArn = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab' PS C:\> aws-encryption-cli --decrypt ` --input Hello.txt.encrypted ` --wrapping-keys key=$keyArn ` --commitment-policy require-encrypt-require-decrypt ` --encryption-context purpose=test ` --metadata-output $home\Metadata.txt ` --max-encrypted-data-keys 1 ` --buffer ` --output . ``` ------ 복호화 명령이 성공하면 어떤 출력도 반환하지 않습니다. 명령의 성공 여부를 확인하려면 `$?` 변수의 값을 가져옵니다. 디렉터리 목록 명령을 사용하여 명령이 `.decrypted`라는 접미사가 붙은 새 파일을 생성했는지 확인할 수도 있습니다. 일반 텍스트 콘텐츠를 보려면 파일 콘텐츠를 가져오는 명령(예: `cat` 또는 [Get-Content](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.management/get-content))을 사용합니다. ------ #### [ Bash ] ``` $ ls hello.txt hello.txt.encrypted hello.txt.encrypted.decrypted $ cat hello.txt.encrypted.decrypted Hello World ``` ------ #### [ PowerShell ] ``` PS C:\> dir Directory: C:\TestCLI Mode LastWriteTime Length Name ---- ------------- ------ ---- -a---- 9/17/2017 1:01 PM 11 Hello.txt -a---- 9/17/2017 1:06 PM 585 Hello.txt.encrypted -a---- 9/17/2017 1:08 PM 11 Hello.txt.encrypted.decrypted PS C:\> Get-Content Hello.txt.encrypted.decrypted Hello World ``` ------ ## 디렉터리의 모든 파일 암호화 이 예제에서는 AWS Encryption CLI를 사용하여 디렉터리에 있는 모든 파일의 내용을 암호화합니다. 명령이 여러 파일에 영향을 미치는 경우 AWS Encryption CLI는 각 파일을 개별적으로 처리합니다. 파일 내용을 가져오고, 마스터 키에서 파일의 고유한 [데이터 키](concepts.md#DEK)를 가져오고, 데이터 키로 파일 내용을 암호화하고, 결과를 출력 디렉터리의 새 파일에 씁니다. 따라서 출력 파일을 독립적으로 복호화할 수 있습니다. 이 `TestDir` 디렉터리 목록에는 암호화하려는 일반 텍스트 파일이 표시됩니다. ------ #### [ Bash ] ``` $ ls testdir cool-new-thing.py hello.txt employees.csv ``` ------ #### [ PowerShell ] ``` PS C:\> dir C:\TestDir Directory: C:\TestDir Mode LastWriteTime Length Name ---- ------------- ------ ---- -a---- 9/12/2017 3:11 PM 2139 cool-new-thing.py -a---- 9/15/2017 5:57 PM 11 Hello.txt -a---- 9/17/2017 1:44 PM 46 Employees.csv ``` ------ 첫 번째 명령은의 [Amazon 리소스 이름(ARN)](https://docs.aws.amazon.com/kms/latest/developerguide/viewing-keys.html#find-cmk-id-arn)을 `$keyArn` 변수 AWS KMS key 에 저장합니다. 두 번째 명령은 `TestDir` 디렉터리에 있는 파일의 콘텐츠를 암호화하고 암호화된 콘텐츠의 파일을 `TestEnc` 디렉터리에 씁니다. `TestEnc` 디렉터리가 존재하지 않으면 명령이 실패합니다. 입력 위치가 디렉터리이므로 `--recursive` 파라미터가 필요합니다. [`--wrapping-keys` 파라미터](crypto-cli-how-to.md#crypto-cli-master-key)와 필수 **key** 속성은 사용할 래핑 키를 지정합니다. 암호화 명령에는 [암호화 컨텍스트](crypto-cli-how-to.md#crypto-cli-encryption-context)인 `dept=IT`가 포함됩니다. 여러 파일을 암호화하는 명령에 암호화 컨텍스트를 지정하면 모든 파일에 동일한 암호화 컨텍스트가 사용됩니다. 명령에는 암호화 작업에 대한 메타데이터를 작성할 위치를 AWS Encryption CLI에 알려주는 `--metadata-output` 파라미터도 있습니다. AWS Encryption CLI는 암호화된 각 파일에 대해 하나의 메타데이터 레코드를 씁니다. [`--commitment-policy parameter`](crypto-cli-how-to.md#crypto-cli-commitment-policy)는 버전 2.1.*x*부터 선택 사항이지만 권장됩니다. 명령이나 스크립트가 사이퍼텍스트를 복호화할 수 없어 실패하는 경우 명시적 커밋 정책 설정을 사용하면 문제를 빠르게 감지하는 데 도움이 될 수 있습니다. 명령이 완료되면 AWS Encryption CLI는 암호화된 파일을 `TestEnc` 디렉터리에 기록하지만 출력을 반환하지 않습니다. 마지막 명령은 `TestEnc` 디렉터리의 파일을 나열합니다. 일반 텍스트 콘텐츠의 각 입력 파일마다 암호화된 콘텐츠의 출력 파일이 하나씩 있습니다. 명령이 대체 접미사를 지정하지 않았으므로 암호화 명령이 각 입력 파일의 이름에 `.encrypted`를 추가했습니다. ------ #### [ Bash ] ``` # To run this example, replace the fictitious key ARN with a valid master key identifier. $ keyArn=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab $ aws-encryption-cli --encrypt \ --input testdir --recursive\ --wrapping-keys key=$keyArn \ --encryption-context dept=IT \ --commitment-policy require-encrypt-require-decrypt \ --metadata-output ~/metadata \ --output testenc $ ls testenc cool-new-thing.py.encrypted employees.csv.encrypted hello.txt.encrypted ``` ------ #### [ PowerShell ] ``` # To run this example, replace the fictitious key ARN with a valid master key identifier. PS C:\> $keyArn = arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab PS C:\> aws-encryption-cli --encrypt ` --input .\TestDir --recursive ` --wrapping-keys key=$keyArn ` --encryption-context dept=IT ` --commitment-policy require-encrypt-require-decrypt ` --metadata-output .\Metadata\Metadata.txt ` --output .\TestEnc PS C:\> dir .\TestEnc Directory: C:\TestEnc Mode LastWriteTime Length Name ---- ------------- ------ ---- -a---- 9/17/2017 2:32 PM 2713 cool-new-thing.py.encrypted -a---- 9/17/2017 2:32 PM 620 Hello.txt.encrypted -a---- 9/17/2017 2:32 PM 585 Employees.csv.encrypted ``` ------ ## 디렉터리의 모든 파일 복호화 이 예제는 디렉터리에 있는 모든 파일을 복호화합니다. 이전 예제에서 암호화된 `TestEnc` 디렉터리의 파일부터 시작합니다. ------ #### [ Bash ] ``` $ ls testenc cool-new-thing.py.encrypted hello.txt.encrypted employees.csv.encrypted ``` ------ #### [ PowerShell ] ``` PS C:\> dir C:\TestEnc Directory: C:\TestEnc Mode LastWriteTime Length Name ---- ------------- ------ ---- -a---- 9/17/2017 2:32 PM 2713 cool-new-thing.py.encrypted -a---- 9/17/2017 2:32 PM 620 Hello.txt.encrypted -a---- 9/17/2017 2:32 PM 585 Employees.csv.encrypted ``` ------ 이 복호화 명령은 TestEnc 디렉터리의 모든 파일을 복호화하고 일반 텍스트 파일을 TestDec 디렉터리에 씁니다. **키** 속성과 [키 ARN](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-key-ARN) 값이 있는 `--wrapping-keys` 파라미터는 AWS 파일을 복호화 AWS KMS keys 하는 데 사용할 암호화 CLI에 지시합니다. 명령은 `--interactive` 파라미터를 사용하여 동일한 이름의 파일을 덮어쓰기 전에 AWS Encryption CLI에 프롬프트를 표시하도록 지시합니다. 또한 이 명령은 파일이 암호화될 때 제공된 암호화 컨텍스트를 사용합니다. 여러 파일을 복호화할 때 AWS 암호화 CLI는 모든 파일의 암호화 컨텍스트를 확인합니다. 파일에 대한 암호화 컨텍스트 확인이 실패하면 AWS Encryption CLI는 파일을 거부하고 경고를 작성하고 메타데이터에 실패를 기록한 다음 나머지 파일을 계속 확인합니다. AWS Encryption CLI가 다른 이유로 파일을 복호화하지 못하면 전체 복호화 명령이 즉시 실패합니다. 이 예제에서는 모든 입력 파일의 암호화된 메시지에 `dept=IT` 암호화 컨텍스트 요소가 포함되어 있습니다. 하지만 암호화 컨텍스트가 다른 메시지를 복호화하는 경우에도 암호화 컨텍스트의 일부는 확인 가능할 수도 있습니다. 예를 들어 일부 메시지의 암호화 컨텍스트가 `dept=finance`이고 다른 메시지의 암호화된 컨텍스트가 `dept=IT`인 경우 값을 지정하지 않고도 암호화 컨텍스트에 항상 `dept` 이름이 포함되어 있는지 확인할 수 있습니다. 좀 더 구체적으로 확인하려면 별도의 명령으로 파일을 복호화할 수 있습니다. 복호화 명령은 어떤 출력도 반환하지 않지만 디렉터리 목록 명령을 사용하여 복호화 명령이 `.decrypted` 접미사가 붙은 새 파일을 만들었는지 확인할 수 있습니다. 일반 텍스트 콘텐츠를 보려면 파일 콘텐츠를 가져오는 명령을 사용합니다. ------ #### [ Bash ] ``` # To run this example, replace the fictitious key ARN with a valid master key identifier. $ keyArn=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab $ aws-encryption-cli --decrypt \ --input testenc --recursive \ --wrapping-keys key=$keyArn \ --encryption-context dept=IT \ --commitment-policy require-encrypt-require-decrypt \ --metadata-output ~/metadata \ --max-encrypted-data-keys 1 \ --buffer \ --output testdec --interactive $ ls testdec cool-new-thing.py.encrypted.decrypted hello.txt.encrypted.decrypted employees.csv.encrypted.decrypted ``` ------ #### [ PowerShell ] ``` # To run this example, replace the fictitious key ARN with a valid master key identifier. PS C:\> $keyArn = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab' PS C:\> aws-encryption-cli --decrypt ` --input C:\TestEnc --recursive ` --wrapping-keys key=$keyArn ` --encryption-context dept=IT ` --commitment-policy require-encrypt-require-decrypt ` --metadata-output $home\Metadata.txt ` --max-encrypted-data-keys 1 ` --buffer ` --output C:\TestDec --interactive PS C:\> dir .\TestDec Mode LastWriteTime Length Name ---- ------------- ------ ---- -a---- 10/8/2017 4:57 PM 2139 cool-new-thing.py.encrypted.decrypted -a---- 10/8/2017 4:57 PM 46 Employees.csv.encrypted.decrypted -a---- 10/8/2017 4:57 PM 11 Hello.txt.encrypted.decrypted ``` ------ ## 명령줄에서 암호화 및 복호화 이 예제는 입력을 명령(stdin)으로 파이프하고 출력을 명령줄(stdout)에 쓰는 방법을 보여줍니다. 명령에서 stdin 및 stdout을 표현하는 방법과, 기본 제공 Base64 인코딩 도구를 사용하여 쉘이 ASCII가 아닌 문자를 잘못 해석하지 않도록 하는 방법을 설명합니다. 이 예제에서는 일반 텍스트 문자열을 암호화 명령으로 파이프하고 암호화된 메시지를 변수에 저장합니다. 그런 다음 변수에 있는 암호화된 메시지를 복호화 명령으로 파이프하고, 해당 명령은 출력을 파이프라인(stdout)에 씁니다. 이 예제는 다음과 같은 세 가지 명령으로 구성되어 있습니다. + 첫 번째 명령은의 [키 ARN](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-key-ARN)을 `$keyArn` 변수 AWS KMS key 에 저장합니다. ------ #### [ Bash ] ``` $ keyArn=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab ``` ------ #### [ PowerShell ] ``` PS C:\> $keyArn = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab' ``` ------   + 두 번째 명령은 `Hello World` 문자열을 암호화 명령으로 파이프하고 그 결과를 `$encrypted` 변수에 저장합니다. `--input` 및 `--output` 파라미터는 모든 AWS Encryption CLI 명령에 반드시 필요합니다. 입력이 명령(stdin)으로 파이프되고 있음을 나타내려면 `--input` 파라미터의 값에 하이픈(`-`)을 사용합니다. 출력을 명령줄(stdout)로 보내려면 `--output` 파라미터의 값에 하이픈을 사용합니다. `--encode` 파라미터는 출력을 반환하기 전에 출력을 Base64 인코딩합니다. 이렇게 하면 쉘이 암호화된 메시지의 ASCII가 아닌 문자를 잘못 해석하는 것을 방지할 수 있습니다. 이 명령은 개념 증명일 뿐이므로 암호화 컨텍스트는 생략하고 메타데이터(`-S`)는 표시하지 않습니다. ------ #### [ Bash ] ``` $ encrypted=$(echo 'Hello World' | aws-encryption-cli --encrypt -S \ --input - --output - --encode \ --wrapping-keys key=$keyArn ) ``` ------ #### [ PowerShell ] ``` PS C:\> $encrypted = 'Hello World' | aws-encryption-cli --encrypt -S ` --input - --output - --encode ` --wrapping-keys key=$keyArn ``` ------   + 세 번째 명령은 `$encrypted` 변수의 암호화된 메시지를 복호화 명령으로 파이프합니다. 이 복호화 명령은 `--input -`을 사용하여 입력이 파이프라인(stdin)에서 들어오고 있음을 나타내고 `--output -`을 사용하여 출력을 파이프라인(stdout)으로 보냅니다. (입력 파라미터는 실제 입력 바이트가 아니라 입력 위치를 사용하므로 `$encrypted` 변수를 `--input` 파라미터의 값으로 사용할 수 없습니다.) 이 예제에서는 `--wrapping-keys` 파라미터의 **검색** 속성을 사용하여 AWS Encryption CLI가를 사용하여 데이터를 복호화 AWS KMS key 하도록 허용합니다. 여기서는 [커밋 정책](concepts.md#commitment-policy)을 지정하지 않으므로 버전 2.1.*x* 이상에 대한 기본값인 `require-encrypt-require-decrypt`를 사용합니다. 출력이 암호화된 후 인코딩되었으므로 복호화 명령은 `--decode` 파라미터를 사용하여 Base64로 인코딩된 입력을 복호화하기 전에 디코딩합니다. 또한 `--decode` 파라미터를 사용하여 Base64로 인코딩된 입력을 암호화하기 전에 디코딩할 수 있습니다. 앞서 말했듯이, 이 명령은 암호화 컨텍스트를 생략하고 메타데이터(-`S`)를 표시하지 않습니다. ------ #### [ Bash ] ``` $ echo $encrypted | aws-encryption-cli --decrypt --wrapping-keys discovery=true --input - --output - --decode --buffer -S Hello World ``` ------ #### [ PowerShell ] ``` PS C:\> $encrypted | aws-encryption-cli --decrypt --wrapping-keys discovery=$true --input - --output - --decode --buffer -S Hello World ``` ------ 중간 변수 없이 단일 명령으로 암호화 및 복호화 작업을 수행할 수도 있습니다. 이전 예제에서처럼 `--input` 및 `--output` 파라미터에는 `-` 값이 있으며 명령은 `--encode` 파라미터를 사용하여 출력을 인코딩하고 `--decode` 파라미터를 사용하여 입력을 디코딩합니다. ------ #### [ Bash ] ``` $ keyArn=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab $ echo 'Hello World' | aws-encryption-cli --encrypt --wrapping-keys key=$keyArn --input - --output - --encode -S | aws-encryption-cli --decrypt --wrapping-keys discovery=true --input - --output - --decode -S Hello World ``` ------ #### [ PowerShell ] ``` PS C:\> $keyArn = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab' PS C:\> 'Hello World' | aws-encryption-cli --encrypt --wrapping-keys key=$keyArn --input - --output - --encode -S | aws-encryption-cli --decrypt --wrapping-keys discovery=$true --input - --output - --decode -S Hello World ``` ------ ## 여러 마스터 키 사용 이 예제에서는 AWS Encryption CLI에서 데이터를 암호화하고 해독할 때 여러 마스터 키를 사용하는 방법을 보여줍니다. 여러 마스터 키를 사용하여 데이터를 암호화하면 해당 마스터 키 중 하나를 사용하여 데이터를 복호화할 수 있습니다. 이 전략을 사용하면 마스터 키 중 하나를 사용할 수 없는 상황에서도 데이터를 복호화할 수 있습니다. 암호화된 데이터를 여러에 저장하는 경우 AWS 리전이 전략을 사용하면 동일한 리전의 마스터 키를 사용하여 데이터를 해독할 수 있습니다. 여러 마스터 키로 암호화하는 경우 첫 번째 마스터 키가 특별한 역할을 합니다. 이 키는 데이터를 암호화하는 데 사용되는 데이터 키를 생성합니다. 나머지 마스터 키는 일반 텍스트 데이터 키를 암호화합니다. 그 결과, [암호화된 메시지](concepts.md#message)에는 암호화된 데이터와 암호화된 데이터 키 모음이 각 마스터 키마다 하나씩 포함됩니다. 데이터 키를 만든 것은 첫 번째 마스터 키이지만, 다른 모든 마스터 키로도 데이터 키를 복호화하여 데이터를 복호화할 수 있습니다. **세 개의 마스터 키를 사용한 암호화** 이 예제 명령은 세 개의 래핑 키를 사용하여 세 개의 AWS 리전각각에 하나씩 `Finance.log` 파일을 암호화합니다. 이 명령은 암호화된 메시지를 `Archive` 디렉터리에 씁니다. 이 명령은 값이 없는 `--suffix` 파라미터를 사용하여 접미사를 표시하지 않으므로 입력 및 출력 파일 이름이 동일합니다. 이 명령은 세 가지 **key** 속성을 가진 `--wrapping-keys` 파라미터를 사용합니다. 같은 명령에 여러 개의 `--wrapping-keys` 파라미터를 사용할 수도 있습니다. 로그 파일을 암호화하기 위해 AWS Encryption CLI는 목록의 첫 번째 래핑 키인 `$key1`에 데이터를 암호화하는 데 사용하는 데이터 키를 생성하도록 요청합니다. 그런 다음 나머지 래핑 키를 각각 사용하여 동일한 데이터 키의 일반 텍스트 사본을 암호화합니다. 출력 파일의 암호화된 메시지에는 암호화된 데이터 키 세 개가 모두 포함됩니다. ------ #### [ Bash ] ``` $ key1=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab $ key2=arn:aws:kms:us-east-2:111122223333:key/0987ab65-43cd-21ef-09ab-87654321cdef $ key3=arn:aws:kms:ap-southeast-1:111122223333:key/1a2b3c4d-5e6f-1a2b-3c4d-5e6f1a2b3c4d $ aws-encryption-cli --encrypt --input /logs/finance.log \ --output /archive --suffix \ --encryption-context class=log \ --metadata-output ~/metadata \ --wrapping-keys key=$key1 key=$key2 key=$key3 ``` ------ #### [ PowerShell ] ``` PS C:\> $key1 = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab' PS C:\> $key2 = 'arn:aws:kms:us-east-2:111122223333:key/0987ab65-43cd-21ef-09ab-87654321cdef' PS C:\> $key3 = 'arn:aws:kms:ap-southeast-1:111122223333:key/1a2b3c4d-5e6f-1a2b-3c4d-5e6f1a2b3c4d' PS C:\> aws-encryption-cli --encrypt --input D:\Logs\Finance.log ` --output D:\Archive --suffix ` --encryption-context class=log ` --metadata-output $home\Metadata.txt ` --wrapping-keys key=$key1 key=$key2 key=$key3 ``` ------ 이 명령은 `Finance.log` 파일의 암호화된 사본을 복호화하여 `Finance` 디렉터리의 `Finance.log.clear` 파일에 씁니다. 세 개로 암호화된 데이터를 해독하려면 동일한 세 AWS KMS keys 개 또는 하위 집합을 지정할 AWS KMS keys수 있습니다. 이 예제에서는 AWS KMS keys중 하나만 지정합니다. 데이터 복호화에 AWS KMS keys 사용할 AWS 암호화 CLI에 알리려면 `--wrapping-keys` 파라미터의 **키** 속성을 사용합니다. 를 사용하여 복호화할 때 **키** 속성 AWS KMS keys의 값은 [키 ARN](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-key-ARN)이어야 합니다. AWS KMS keys 지정한에서 [Decrypt API](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html)를 호출할 수 있는 권한이 있어야 합니다. 자세한 정보는 [AWS KMS에 대한 인증 및 액세스 제어](https://docs.aws.amazon.com/kms/latest/developerguide/control-access.html)를 참조하세요. 모범 사례로서, 이 예제는 암호화된 데이터 키가 너무 많은 잘못된 형식의 메시지를 복호화하지 않도록 `--max-encrypted-data-keys` 파라미터를 사용합니다. 이 예제에서는 복호화에 래핑 키 하나만 사용하지만, 암호화된 메시지에는 암호화할 때 사용되는 세 개의 래핑 키에 대해 각각 하나씩 총 세 개의 암호화된 데이터 키가 있습니다. 암호화된 데이터 키의 예상 개수 또는 적절한 최대값(예: 5)을 지정합니다. 최대값을 3보다 작게 지정하면 명령이 실패합니다. 자세한 내용은 [암호화된 데이터 키 제한](configure.md#config-limit-keys)을 참조하세요. ------ #### [ Bash ] ``` $ aws-encryption-cli --decrypt --input /archive/finance.log \ --wrapping-keys key=$key1 \ --output /finance --suffix '.clear' \ --metadata-output ~/metadata \ --max-encrypted-data-keys 3 \ --buffer \ --encryption-context class=log ``` ------ #### [ PowerShell ] ``` PS C:\> aws-encryption-cli --decrypt ` --input D:\Archive\Finance.log ` --wrapping-keys key=$key1 ` --output D:\Finance --suffix '.clear' ` --metadata-output .\Metadata\Metadata.txt ` --max-encrypted-data-keys 3 ` --buffer ` --encryption-context class=log ``` ------ ## 스크립트의 암호화 및 복호화 이 예제는 스크립트에서 AWS 암호화 CLI를 사용하는 방법을 보여줍니다. 데이터 암호화 및 복호화만 하는 스크립트를 작성하거나 데이터 관리 프로세스의 일부로 암호화 또는 복호화하는 스크립트를 작성할 수 있습니다. 이 예제에서 스크립트는 로그 파일 모음을 가져와 압축하고 암호화한 다음 암호화된 파일을 Amazon S3 버킷에 복사합니다. 이 스크립트는 각 파일을 개별적으로 처리하므로 사용자는 파일을 독립적으로 복호화하고 확장할 수 있습니다. 파일을 압축하고 암호화할 때는 반드시 암호화하기 전에 압축해야 합니다. 올바르게 암호화된 데이터는 압축할 수 없습니다. **주의** 악의적인 공격자가 제어할 수도 있는 비밀 키 및 데이터가 모두 포함된 데이터를 압축할 때는 주의해야 합니다. 압축된 데이터의 최종 크기로 인해 의도치 않게 데이터 내용에 대한 민감한 정보가 드러날 수 있습니다. ------ #### [ Bash ] ``` # Continue running even if an operation fails. set +e dir=$1 encryptionContext=$2 s3bucket=$3 s3folder=$4 masterKeyProvider="aws-kms" metadataOutput="/tmp/metadata-$(date +%s)" compress(){ gzip -qf $1 } encrypt(){ # -e encrypt # -i input # -o output # --metadata-output unique file for metadata # -m masterKey read from environment variable # -c encryption context read from the second argument. # -v be verbose aws-encryption-cli -e -i ${1} -o $(dirname ${1}) --metadata-output ${metadataOutput} -m key="${masterKey}" provider="${masterKeyProvider}" -c "${encryptionContext}" -v } s3put (){ # copy file argument 1 to s3 location passed into the script. aws s3 cp ${1} ${s3bucket}/${s3folder} } # Validate all required arguments are present. if [ "${dir}" ] && [ "${encryptionContext}" ] && [ "${s3bucket}" ] && [ "${s3folder}" ] && [ "${masterKey}" ]; then # Is $dir a valid directory? test -d "${dir}" if [ $? -ne 0 ]; then echo "Input is not a directory; exiting" exit 1 fi # Iterate over all the files in the directory, except *gz and *encrypted (in case of a re-run). for f in $(find ${dir} -type f \( -name "*" ! -name \*.gz ! -name \*encrypted \) ); do echo "Working on $f" compress ${f} encrypt ${f}.gz rm -f ${f}.gz s3put ${f}.gz.encrypted done; else echo "Arguments: " echo " and ENV var \$masterKey must be set" exit 255 fi ``` ------ #### [ PowerShell ] ``` #Requires -Modules AWSPowerShell, Microsoft.PowerShell.Archive Param ( [Parameter(Mandatory)] [ValidateScript({Test-Path $_})] [String[]] $FilePath, [Parameter()] [Switch] $Recurse, [Parameter(Mandatory=$true)] [String] $wrappingKeyID, [Parameter()] [String] $masterKeyProvider = 'aws-kms', [Parameter(Mandatory)] [ValidateScript({Test-Path $_})] [String] $ZipDirectory, [Parameter(Mandatory)] [ValidateScript({Test-Path $_})] [String] $EncryptDirectory, [Parameter()] [String] $EncryptionContext, [Parameter(Mandatory)] [ValidateScript({Test-Path $_})] [String] $MetadataDirectory, [Parameter(Mandatory)] [ValidateScript({Test-S3Bucket -BucketName $_})] [String] $S3Bucket, [Parameter()] [String] $S3BucketFolder ) BEGIN {} PROCESS { if ($files = dir $FilePath -Recurse:$Recurse) { # Step 1: Compress foreach ($file in $files) { $fileName = $file.Name try { Microsoft.PowerShell.Archive\Compress-Archive -Path $file.FullName -DestinationPath $ZipDirectory\$filename.zip } catch { Write-Error "Zip failed on $file.FullName" } # Step 2: Encrypt if (-not (Test-Path "$ZipDirectory\$filename.zip")) { Write-Error "Cannot find zipped file: $ZipDirectory\$filename.zip" } else { # 2>&1 captures command output $err = (aws-encryption-cli -e -i "$ZipDirectory\$filename.zip" ` -o $EncryptDirectory ` -m key=$wrappingKeyID provider=$masterKeyProvider ` -c $EncryptionContext ` --metadata-output $MetadataDirectory ` -v) 2>&1 # Check error status if ($? -eq $false) { # Write the error $err } elseif (Test-Path "$EncryptDirectory\$fileName.zip.encrypted") { # Step 3: Write to S3 bucket if ($S3BucketFolder) { Write-S3Object -BucketName $S3Bucket -File "$EncryptDirectory\$fileName.zip.encrypted" -Key "$S3BucketFolder/$fileName.zip.encrypted" } else { Write-S3Object -BucketName $S3Bucket -File "$EncryptDirectory\$fileName.zip.encrypted" } } } } } } ``` ------ ## 데이터 키 캐싱 사용 이 예제에서는 많은 수의 파일을 암호화하는 명령에 [데이터 키 캐싱](data-key-caching.md)을 사용합니다. 기본적으로 AWS Encryption CLI(및 기타 버전의 AWS Encryption SDK)는 암호화하는 각 파일에 대해 고유한 데이터 키를 생성합니다. 각 작업에 고유한 데이터 키를 사용하는 것이 암호화 모범 사례이긴 하지만, 일부 상황에서는 데이터 키를 제한적으로 재사용할 수 있습니다. 데이터 키 캐싱을 고려 중인 경우 보안 엔지니어에게 문의하여 애플리케이션의 보안 요구 사항을 파악하고 적합한 보안 임계값을 결정하세요. 이 예제에서는 데이터 키 캐싱으로 마스터 키 공급자에 대한 요청 빈도를 줄여서 암호화 작업의 속도를 높입니다. 이 예제의 명령은 총 약 800개의 작은 로그 파일이 포함된 여러 개의 하위 디렉터리가 있는 큰 디렉터리를 암호화합니다. 첫 번째 명령은 AWS KMS key 의 ARN을 `keyARN` 변수에 저장합니다. 두 번째 명령은 입력 디렉터리의 모든 파일을 (재귀적으로) 암호화하여 아카이브 디렉터리에 씁니다. 이 명령은 `--suffix` 파라미터를 사용하여 `.archive` 접미사를 지정합니다. `--caching` 파라미터는 데이터 키 캐싱 사용을 설정합니다. 직렬 파일 처리는 한 번에 두 개 이상의 데이터 키를 사용하지 않기 때문에 캐시의 데이터 키 수를 제한하는 **capacity** 속성은 1로 설정됩니다. 캐시된 데이터 키를 사용할 수 있는 기간을 결정하는 **max\$1age** 속성은 10초로 설정됩니다. 선택 사항인 **max\$1messages\$1crypted** 속성은 메시지 10개로 설정되므로 하나의 데이터 키는 10개 이상의 파일을 암호화하는 데 사용되지 않습니다. 각 데이터 키로 암호화되는 파일 수를 제한하면 혹시라도 데이터 키가 손상되는 예기치 못한 상황이 발생하더라도 영향을 받는 파일 수를 줄일 수 있습니다. 운영 체제에서 생성하는 로그 파일에서 이 명령을 실행하려면 관리자 권한(Linux의 경우 `sudo`, Windows의 경우 **관리자 권한으로 실행**)이 필요할 수 있습니다. ------ #### [ Bash ] ``` $ keyArn=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab $ aws-encryption-cli --encrypt \ --input /var/log/httpd --recursive \ --output ~/archive --suffix .archive \ --wrapping-keys key=$keyArn \ --encryption-context class=log \ --suppress-metadata \ --caching capacity=1 max_age=10 max_messages_encrypted=10 ``` ------ #### [ PowerShell ] ``` PS C:\> $keyARN = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab' PS C:\> aws-encryption-cli --encrypt ` --input C:\Windows\Logs --recursive ` --output $home\Archive --suffix '.archive' ` --wrapping-keys key=$keyARN ` --encryption-context class=log ` --suppress-metadata ` --caching capacity=1 max_age=10 max_messages_encrypted=10 ``` ------ 이 예제에서는 데이터 키 캐싱의 효과를 테스트하기 위해 PowerShell의 [Measure-Command](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.utility/measure-command) cmdlet을 사용합니다. 이 예제를 데이터 키 캐싱 없이 실행하면 완료하는 데 약 25초가 걸립니다. 이 프로세스는 디렉터리의 각 파일에 대해 새 데이터 키를 생성합니다. ``` PS C:\> Measure-Command {aws-encryption-cli --encrypt ` --input C:\Windows\Logs --recursive ` --output $home\Archive --suffix '.archive' ` --wrapping-keys key=$keyARN ` --encryption-context class=log ` --suppress-metadata } Days : 0 Hours : 0 Minutes : 0 Seconds : 25 Milliseconds : 453 Ticks : 254531202 TotalDays : 0.000294596298611111 TotalHours : 0.00707031116666667 TotalMinutes : 0.42421867 TotalSeconds : 25.4531202 TotalMilliseconds : 25453.1202 ``` 데이터 키 캐싱을 사용하면 각 데이터 키를 최대 10개 파일로 제한하는 경우에도 프로세스가 더 빨라집니다. 이제 이 명령은 완료하는 데 12초 미만이 소요되며 마스터 키 공급자에 대한 호출 수를 원래 값의 1/10로 줄입니다. ``` PS C:\> Measure-Command {aws-encryption-cli --encrypt ` --input C:\Windows\Logs --recursive ` --output $home\Archive --suffix '.archive' ` --wrapping-keys key=$keyARN ` --encryption-context class=log ` --suppress-metadata ` --caching capacity=1 max_age=10 max_messages_encrypted=10} Days : 0 Hours : 0 Minutes : 0 Seconds : 11 Milliseconds : 813 Ticks : 118132640 TotalDays : 0.000136727592592593 TotalHours : 0.00328146222222222 TotalMinutes : 0.196887733333333 TotalSeconds : 11.813264 TotalMilliseconds : 11813.264 ``` `max_messages_encrypted` 제한을 제거하면 모든 파일이 동일한 데이터 키로 암호화됩니다. 이렇게 변경하면 프로세스가 훨씬 빨라지지는 않고 데이터 키를 재사용할 위험이 증가합니다. 그러나 마스터 키 공급자에 대한 호출 횟수는 1로 줄어듭니다. ``` PS C:\> Measure-Command {aws-encryption-cli --encrypt ` --input C:\Windows\Logs --recursive ` --output $home\Archive --suffix '.archive' ` --wrapping-keys key=$keyARN ` --encryption-context class=log ` --suppress-metadata ` --caching capacity=1 max_age=10} Days : 0 Hours : 0 Minutes : 0 Seconds : 10 Milliseconds : 252 Ticks : 102523367 TotalDays : 0.000118661304398148 TotalHours : 0.00284787130555556 TotalMinutes : 0.170872278333333 TotalSeconds : 10.2523367 TotalMilliseconds : 10252.3367 ``` # AWS Encryption SDK CLI 구문 및 파라미터 참조 이 주제는 AWS Encryption SDK Command Line Interface(CLI)를 사용하는 데 도움이 될 구문 다이어그램 및 간단한 파라미터 설명을 제공합니다. 래핑 키 및 기타 파라미터 관련 도움말은 [AWS Encryption CLI 사용 방법](crypto-cli-how-to.md) 섹션을 참조하세요. 예제는 [AWS 암호화 CLI의 예](crypto-cli-examples.md) 섹션을 참조하세요. 전체 설명서는 [문서 읽기](https://aws-encryption-sdk-cli.readthedocs.io/en/latest/)를 참조하세요. **Topics** + [AWS 암호화 CLI 구문](#crypto-cli-syntax) + [AWS 암호화 CLI 명령줄 파라미터](#crypto-cli-parameters) + [고급 파라미터](#cli-advanced-parameters) ## AWS 암호화 CLI 구문 이러한 AWS Encryption CLI 구문 다이어그램은 AWS Encryption CLI로 수행하는 각 작업의 구문을 보여줍니다. 이는 AWS Encryption CLI 버전 2.1.*x* 이상에서 권장되는 구문을 나타냅니다. 새로운 보안 기능은 원래 AWS Encryption CLI 버전 1.7.*x* 및 2.0.*x*에서 릴리스되었습니다. 그러나 AWS Encryption CLI 버전 1.8.*x*는 버전 1.7.*x*를 대체하고 AWS Encryption CLI 2.1.*x*는 2.0.*x*를 대체합니다. 자세한 내용은 GitHub의 [aws-encryption-sdk-cli](https://github.com/aws/aws-encryption-sdk-cli/) 리포지토리에서 관련 [보안 권고](https://github.com/aws/aws-encryption-sdk-cli/security/advisories/GHSA-2xwp-m7mq-7q3r)를 참조하세요. **참고** 파라미터 설명에 명시되어 있지 않는 한, 각 파라미터 또는 속성은 각 명령에서 한 번만 사용할 수 있습니다. 파라미터가 지원하지 않는 속성을 사용하는 경우 AWS Encryption CLI는 경고나 오류 없이 지원되지 않는 속성을 무시합니다. **지원 받기** 파라미터 설명과 함께 전체 AWS Encryption CLI 구문을 가져오려면 `--help` 또는를 사용합니다`-h`. ``` aws-encryption-cli (--help | -h) ``` **버전 가져오기** AWS Encryption CLI 설치의 버전 번호를 가져오려면를 사용합니다`--version`. 질문을 하거나, 문제를 보고하거나, AWS 암호화 CLI 사용에 대한 팁을 공유할 때는 버전을 포함해야 합니다. ``` aws-encryption-cli --version ``` **Encrypt data** 다음 구문 다이어그램은 **encrypt** 명령에 사용되는 파라미터를 보여줍니다. ``` aws-encryption-cli --encrypt --input [--recursive] [--decode] --output [--interactive] [--no-overwrite] [--suffix []] [--encode] --wrapping-keys [--wrapping-keys] ... key= [key=] ... [provider=] [region=] [profile=] --metadata-output [--overwrite-metadata] | --suppress-metadata] [--commitment-policy ] [--encryption-context [ ...]] [--max-encrypted-data-keys ] [--algorithm ] [--caching ] [--frame-length ] [-v | -vv | -vvv | -vvvv] [--quiet] ``` **데이터 복호화** 다음 구문 다이어그램은 **decrypt** 명령에 사용되는 파라미터를 보여줍니다. 버전 1.8.*x*부터 복호화 시 `--wrapping-keys` 파라미터는 선택 사항이지만 권장됩니다. 버전 2.1.*x*부터 암호화 및 복호화 시 `--wrapping-keys` 파라미터가 필요합니다. AWS KMS keys의 경우 **key** 속성을 사용하여 래핑 키를 지정(모범 사례)하거나 **discovery** 속성을 `true`로 설정할 수 있습니다. 그러면 AWS Encryption CLI에서 사용할 수 있는 래핑 키가 제한되지 않습니다. ``` aws-encryption-cli --decrypt (or [--decrypt-unsigned]) --input [--recursive] [--decode] --output [--interactive] [--no-overwrite] [--suffix []] [--encode] --wrapping-keys [--wrapping-keys] ... [key=] [key=] ... [discovery={true|false}] [discovery-partition= discovery-account= [discovery-account=] ...] [provider=] [region=] [profile=] --metadata-output [--overwrite-metadata] | --suppress-metadata] [--commitment-policy ] [--encryption-context [ ...]] [--buffer] [--max-encrypted-data-keys ] [--caching ] [--max-length ] [-v | -vv | -vvv | -vvvv] [--quiet] ``` **구성 파일 사용** 파라미터와 해당 값이 포함된 구성 파일을 참조할 수 있습니다. 이는 명령에 파라미터와 값을 입력하는 것과 같습니다. 예제는 [구성 파일에 파라미터를 저장하는 방법](crypto-cli-how-to.md#crypto-cli-config-file) 섹션을 참조하세요. ``` aws-encryption-cli @ # In a PowerShell console, use a backtick to escape the @. aws-encryption-cli `@ ``` ## AWS 암호화 CLI 명령줄 파라미터 이 목록은 AWS Encryption CLI 명령 파라미터에 대한 기본 설명을 제공합니다. 전체 설명은 [aws-encryption-sdk-cli 설명서](http://aws-encryption-sdk-cli.readthedocs.io/en/latest/)를 참조하세요. **--encrypt (-e)** 입력 데이터를 암호화합니다. 모든 명령에는 `--encrypt`, `--decrypt` 또는 `--decrypt-unsigned` 파라미터가 있어야 합니다. **--decrypt (-d)** 입력 데이터를 복호화합니다. 모든 명령에는 `--encrypt`, `--decrypt` 또는 `--decrypt-unsigned` 파라미터가 있어야 합니다. **--decrypt-unsigned[버전 1.9.*x 및* 2.2.*x*에 도입됨]** `--decrypt-unsigned` 파라미터는 사이퍼텍스트를 복호화하고, 복호화 전에 메시지가 서명되지 않도록 합니다. `--algorithm` 파라미터를 사용하고 디지털 서명이 없는 알고리즘 제품군을 선택하여 데이터를 암호화한 경우 이 파라미터를 사용합니다. 사이퍼텍스트가 서명된 경우 복호화가 실패합니다. `--decrypt` 또는 `--decrypt-unsigned`를 복호화에 사용할 수 있지만 둘 다 사용할 수는 없습니다. **--wrapping-keys (-w)[버전 1.8.*x*에 도입됨]** 암호화 및 복호화 작업에 사용되는 [래핑 키](concepts.md#master-key)*(또는 마스터 키*)를 지정합니다. 각 명령에서 [여러 `--wrapping-keys` 파라미터](crypto-cli-how-to.md#cli-many-cmks)를 사용할 수 있습니다. 버전 2.1.*x*부터는 `--wrapping-keys` 파라미터가 암호화 및 복호화 명령에 필요합니다. 버전 1.8.*x*에서 암호화 명령에는 `--wrapping-keys` 또는 `--master-keys` 파라미터가 필요합니다. 버전 1.8.*x*에서 복호화 명령의 경우 `--wrapping-keys` 파라미터는 선택 사항이지만 권장됩니다. 사용자 지정 마스터 키 공급자를 사용하는 경우 암호화 및 복호화 명령에는 **key** 및 **provider** 속성이 필요합니다. 를 사용할 때 AWS KMS keys암호화 명령에는 **키** 속성이 필요합니다. 복호화 명령에는 값이 `true`인 **key** 속성 또는 **discovery** 속성이 필요합니다(둘 다는 아님). 복호화 시 **key** 속성을 사용하는 것이 [AWS Encryption SDK 모범 사례](best-practices.md)입니다. 이는 Amazon S3 버킷 또는 Amazon SQS 대기열에 있는 메시지와 같이 익숙하지 않은 메시지를 일괄 복호화하는 경우 특히 중요합니다. AWS KMS 다중 리전 키를 래핑 키로 사용하는 방법을 보여주는 예는 섹션을 참조하세요[다중 리전 사용 AWS KMS keys](configure.md#config-mrks). **속성**: `--wrapping-keys` 파라미터의 값은 다음 속성으로 구성됩니다. 형식은 `attribute_name=value`입니다. **key** 작업에 사용된 래핑 키를 식별합니다. 형식은 **key**=ID 페어입니다. 각 `--wrapping-keys` 파라미터 값에 여러 **key** 속성을 지정할 수 있습니다. + **암호화 명령**: 모든 암호화 명령에는 **key** 속성이 반드시 필요합니다. 암호화 명령 AWS KMS key 에서를 사용하는 경우 **키** 속성의 값은 키 ID, 키 ARN, 별칭 이름 또는 별칭 ARN일 수 있습니다. AWS KMS 키 식별자에 대한 설명은 *AWS Key Management Service 개발자 안내서*의 [키 식별자](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id)를 참조하세요. + **복호화 명령**: AWS KMS keys를 사용하여 복호화하는 경우 `--wrapping-keys` 파라미터에는 키 [ARN](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-key-ARN) 값이 있는 **key** 속성 또는 값이 `true`인 **discovery** 속성이 필요합니다(둘 다는 아님). **key** 속성을 사용하는 것이 [AWS Encryption SDK 모범 사례](best-practices.md)입니다. 사용자 지정 마스터 키 공급자를 사용하여 복호화할 때는 **key** 속성이 반드시 필요합니다. **참고** 복호화 명령에서 AWS KMS 래핑 키를 지정하려면 **키** 속성의 값이 키 ARN이어야 합니다. 키 ID, 별칭 이름 또는 별칭 ARN을 사용하는 경우 AWS Encryption CLI는 래핑 키를 인식하지 못합니다. 각 `--wrapping-keys` 파라미터 값에 여러 **key** 속성을 지정할 수 있습니다. 그러나 `--wrapping-keys` 파라미터의 모든 **provider**, **region** 및 **profile** 속성은 해당 파라미터 값의 모든 래핑 키에 적용됩니다. 서로 다른 속성 값으로 래핑 키를 지정하려면 명령에서 여러 `--wrapping-keys` 파라미터를 사용합니다. **discovery** AWS Encryption CLI가 임의의를 사용하여 메시지를 복호화 AWS KMS key 하도록 허용합니다. **discovery** 값은 `true` 또는 `false`일 수 있습니다. 기본값은 `false`입니다. **discovery** 속성은 복호화 명령에서, 그리고 마스터 키 공급자가 AWS KMS인 경우에만 유효합니다. 를 사용하여 복호화 AWS KMS keys할 때 `--wrapping-keys` 파라미터에는 **키** 속성 또는 값이 인 **검색** 속성이 필요합니다`true`(둘 다 아님). **key** 속성을 사용하는 경우 값이 `false`인 **discovery** 속성을 사용하여 검색을 명시적으로 거부할 수 있습니다. + `False` (기본값) - **검색** 속성이 지정되지 않았거나 값이 인 경우 `false` AWS Encryption CLI는 `--wrapping-keys` 파라미터의 **키** 속성으로 AWS KMS keys 지정된 만 사용하여 메시지를 복호화합니다. discovery가 `false`일 때 **key** 속성을 지정하지 않으면 복호화 명령이 실패합니다. 이 값은 AWS 암호화 CLI [모범 사례를](best-practices.md) 지원합니다. + `True` - **검색** 속성의 값이 인 경우 `true` AWS Encryption CLI는 암호화된 메시지의 메타데이터 AWS KMS keys 에서를 가져오고 이를 사용하여 메시지를 AWS KMS keys 복호화합니다. 값이 인 **검색** 속성은 복호화 시 래핑 키를 지정할 수 없는 버전 1.8.*x* 이전의 AWS Encryption CLI 버전처럼 `true` 동작합니다. 그러나를 사용하려는 의도 AWS KMS key 는 명시적입니다. discovery가 `true`일 때 **key** 속성을 지정하면 복호화 명령이 실패합니다. 이 `true` 값을 사용하면 AWS Encryption CLI가 서로 다른 AWS 계정 및 리전 AWS KMS keys 에서를 사용하거나 사용자에게 사용 권한이 없는 AWS KMS keys 를 사용하려고 할 수 있습니다. **검색**이 인 경우 **discovery-partition** 및 **discovery-account** 속성을 사용하여 AWS 계정 지정한의 속성으로 AWS KMS keys 사용되는를 제한하는 `true`것이 가장 좋습니다. **discovery-account** 복호화에 AWS KMS keys 사용되는를 지정된의 로 제한합니다 AWS 계정. 이 속성에 사용할 수 있는 유일한 값은 [AWS 계정 ID](https://docs.aws.amazon.com/general/latest/gr/acct-identifiers.html)입니다. 이 속성은 선택 사항이며 **검색** 속성 AWS KMS keys 이 로 설정`true`되고 **검색 파티션** 속성이 지정된 복호화 명령에서만 유효합니다. 각 **discovery-account** 속성은 하나의 AWS 계정 ID만 사용하지만 동일한 `--wrapping-keys` 파라미터에서 여러 **discovery-account** 속성을 지정할 수 있습니다. 지정된 `--wrapping-keys` 파라미터에 지정된 모든 계정은 지정된 AWS 파티션에 있어야 합니다. **discovery-partition** **discovery-account** 속성의 계정에 대한 AWS 파티션을 지정합니다. 값은 , `aws` `aws-cn`또는와 같은 AWS 파티션이어야 합니다`aws-gov-cloud`. 자세한 내용은 *AWS 일반 참조*의 [Amazon 리소스 이름](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html#arns-syntax)을 참조하세요. 이 속성은 **discovery-account** 속성을 사용할 때 필요합니다. 각 `--wrapping keys` 파라미터에는 **discovery-partition** 속성을 하나만 지정할 수 있습니다. 여러 파티션 AWS 계정 에서를 지정하려면 추가 `--wrapping-keys` 파라미터를 사용합니다. **provider** [마스터 키 공급자](concepts.md#master-key-provider)를 식별합니다. 형식은 **provider**=ID 페어입니다. 기본값인 **aws-kms**는를 나타냅니다 AWS KMS. 이 속성은 마스터 키 공급자가가 아닌 경우에만 필요합니다 AWS KMS. **리전** AWS 리전 의를 식별합니다 AWS KMS key. 이 속성은 에만 유효합니다 AWS KMS keys. 이 속성은 **key** 식별자에 리전이 지정되지 않을 때만 사용되며, 그렇지 않은 경우에는 무시됩니다. 사용 시 AWS CLI 명명된 프로파일의 기본 리전을 재정의합니다. **profile** AWS CLI [이름이 지정된 프로파일을 식별합니다](https://docs.aws.amazon.com/cli/latest/userguide/cli-multiple-profiles.html). 이 속성은 에만 유효합니다 AWS KMS keys. 이 프로필의 리전은 키 식별자에 리전이 지정되지 않고 이 명령에 **region** 속성이 없을 때만 사용됩니다. **--input (-i)** 암호화 또는 복호화할 데이터의 위치를 지정합니다. 이 파라미터는 필수 사항입니다. 값은 파일 또는 디렉터리 경로 또는 파일 이름 패턴일 수 있습니다. 명령(stdin)에 대한 입력을 전달하는 경우 `-`를 사용합니다. 입력이 없는 경우 명령이 오류나 경고 없이 성공적으로 완료됩니다. **--recursive (-r, -R)** 입력 디렉터리 및 해당 하위 디렉터리의 파일에 대해 작업을 수행합니다. 이 파라미터는 값이 `--input`인 디렉터리의 경우 필수입니다. **--decode** Base64로 인코딩된 입력을 디코딩합니다. 암호화된 후 인코딩된 메시지를 복호화하려면 메시지를 복호화하기 전에 먼저 메시지를 디코딩해야 합니다. 이 파라미터가 이 작업을 수행합니다. 예를 들어, 암호화 명령에 `--encode` 파라미터를 사용한 경우 해당 복호화 명령의 `--decode` 파라미터를 사용합니다. 또한 암호화하기 전에 이 파라미터를 사용하여 Base64로 인코딩된 입력을 디코딩할 수 있습니다. **--output (-o)** 출력 대상을 지정합니다. 이 파라미터는 필수 사항입니다. 값은 파일 이름, 기존 디렉터리, 또는 출력을 명령줄(stdout)에 쓰는 `-`일 수 있습니다. 지정된 출력 디렉터리가 존재하지 않으면 명령은 실패합니다. 입력에 하위 디렉터리가 포함된 경우 AWS Encryption CLI는 지정한 출력 디렉터리 아래에 하위 디렉터리를 재현합니다. 기본적으로 AWS Encryption CLI는 동일한 이름의 파일을 덮어씁니다. 이 동작을 변경하려면 `--interactive` 또는 `--no-overwrite` 파라미터를 사용합니다. 덮어쓰기 경고를 표시하지 않으려면 `--quiet` 파라미터를 사용합니다. 출력 파일을 덮어쓰는 명령이 실패하면 출력 파일이 삭제됩니다. **--interactive** 파일을 덮어쓰기 전에 메시지를 표시합니다. **--no-overwrite** 파일을 덮어쓰지 않습니다. 대신 출력 파일이 있는 경우 AWS 암호화 CLI는 해당 입력을 건너뜁니다. **--suffix** AWS Encryption CLI가 생성하는 파일의 사용자 지정 파일 이름 접미사를 지정합니다. 접미사가 없음을 나타내려면 값이 없는 파라미터(`--suffix`)를 사용합니다. 기본적으로 `--output` 파라미터가 파일 이름을 지정하지 않는 경우 출력 파일 이름은 입력 파일 이름에 접미사를 더한 것과 같은 이름을 가집니다. 암호화 명령의 접미사는 `.encrypted`입니다. 복호화 명령의 접미사는 `.decrypted`입니다. **--encode** Base64(바이너리를 텍스트로) 인코딩을 출력에 적용합니다. 인코딩은 쉘 호스트 프로그램이 출력 텍스트의 비ASCII 문자를 잘못 해석하는 것을 방지합니다. 특히 PowerShell 콘솔에서 출력을 다른 명령으로 전달하거나 변수에 저장하는 경우에도 stdout(`--output -`)에 암호화된 출력을 쓸 때 이 파라미터를 사용합니다. **--metadata-output** 암호화 작업에 대한 메타데이터의 위치를 지정합니다. 경로와 파일 이름을 입력합니다. 디렉터리가 존재하지 않으면 명령은 실패합니다. 명령줄(stdout)에 메타데이터를 쓰려면 `-`를 사용합니다. 명령 출력(`--output`) 및 메타데이터 출력(`--metadata-output`)을 동일한 명령으로 stdout에 쓸 수 없습니다. 또한 `--input` 또는 `--output` 값이 디렉터리(파일 이름 제외)인 경우 메타데이터 출력을 동일한 디렉터리나 해당 디렉터리의 하위 디렉터리에 쓸 수 없습니다. 기존 파일을 지정하는 경우 기본적으로 AWS Encryption CLI는 파일의 모든 콘텐츠에 새 메타데이터 레코드를 추가합니다. 이 기능을 사용하면 모든 암호화 작업에 대한 메타데이터가 포함된 단일 파일을 생성할 수 있습니다. 기존 파일의 내용을 덮어쓰려면 `--overwrite-metadata` 파라미터를 사용합니다. AWS Encryption CLI는 명령이 수행하는 각 암호화 또는 복호화 작업에 대해 JSON 형식의 메타데이터 레코드를 반환합니다. 각 메타데이터 레코드에는 입력 및 출력 파일의 전체 경로, 암호화 컨텍스트, 알고리즘 제품군, 그리고 작업을 검토하고 보안 표준을 충족하는지 확인하는 데 사용할 수 있는 기타 중요한 정보가 포함됩니다. **--overwrite-metadata** 메타데이터 출력 파일의 내용을 덮어씁니다. 기본적으로 `--metadata-output` 파라미터는 파일의 기존 내용에 메타데이터를 추가합니다. **--suppress-metadata (-S)** 암호화 또는 복호화 작업에 대한 메타데이터를 숨깁니다. **--commitment-policy** 암호화 및 복호화 명령에 대한 [커밋 정책](concepts.md#commitment-policy)을 지정합니다. 커밋 정책은 메시지가 [키 커밋](concepts.md#key-commitment) 보안 기능을 사용하여 암호화되고 복호화되는지 여부를 결정합니다. `--commitment-policy` 파라미터는 버전 1.8.*x*에 도입되었습니다. 이는 암호화 및 복호화 명령에 유효합니다. **버전 1.8.*x*에서** AWS Encryption CLI는 모든 암호화 및 복호화 작업에 `forbid-encrypt-allow-decrypt` 커밋 정책을 사용합니다. 암호화 또는 복호화 명령에서 `--wrapping-keys` 파라미터를 사용하는 경우 `forbid-encrypt-allow-decrypt` 값이 있는 `--commitment-policy` 파라미터가 반드시 필요합니다. `--wrapping-keys` 파라미터를 사용하지 않으면 `--commitment-policy` 파라미터는 유효하지 않습니다. 커밋 정책을 설정하면 커밋 정책이 버전 2.1.*x*로 업그레이드할 때 `require-encrypt-require-decrypt`로 자동 변경되는 것을 명시적으로 방지할 수 있습니다. 버전 **2.1.*x***부터 모든 커밋 정책 값이 지원됩니다. `--commitment-policy` 파라미터는 선택 사항이며 기본값은 `require-encrypt-require-decrypt`입니다. 이 파라미터의 값은 다음과 같습니다. + `forbid-encrypt-allow-decrypt` - 키 커밋으로 암호화할 수 없습니다. 암호화된 사이퍼텍스트를 키 커밋 사용 여부와 관계없이 복호화할 수 있습니다. 버전 1.8.*x*에서 이는 유일하게 유효한 값입니다. AWS Encryption CLI는 모든 암호화 및 복호화 작업에 `forbid-encrypt-allow-decrypt` 커밋 정책을 사용합니다. + `require-encrypt-allow-decrypt` - 키 커밋을 통해서만 암호화합니다. 키 커밋 사용 여부와 관계없이 복호화합니다. 이 값은 버전 2.1.*x*에 도입되었습니다. + `require-encrypt-require-decrypt`(기본값) - 키 커밋을 통해서만 암호화 및 복호화합니다. 이 값은 버전 2.1.*x*에 도입되었습니다. 이는 버전 2.1.*x* 이상에서 기본값입니다. 이 값을 사용하면 AWS Encryption CLI는 이전 버전의 로 암호화된 사이퍼텍스트를 복호화하지 않습니다 AWS Encryption SDK. 커밋 정책 설정에 대한 자세한 내용은 [마이그레이션 AWS Encryption SDK](migration.md) 섹션을 참조하세요. **--encryption-context (-c)** 작업의 [암호화 컨텍스트](crypto-cli-how-to.md#crypto-cli-encryption-context)를 지정합니다. 이 파라미터는 필수는 아니지만 권장됩니다. + `--encrypt` 명령에 하나 이상의 `name=value` 페어를 입력합니다. 공백을 사용하여 페어를 구분합니다. + `--decrypt` 명령에서 `name=value` 페어, 값이 없는 `name` 요소 또는 둘 다를 입력합니다. `name=value` 페어의 `name` 또는 `value`에 공백이나 특수 문자가 포함된 경우 전체 페어를 인용 부호로 묶습니다. 예를 들어 `--encryption-context "department=software development"`입니다. **--buffer (-b)[버전 1.9.*x* 및 2.2.*x*에 도입됨]** 디지털 서명이 있는지 확인하는 등 모든 입력이 처리된 후에만 일반 텍스트를 반환합니다. **--max-encrypted-data-keys[버전 1.9.*x* 및 2.2.*x*에 도입됨]** 암호화된 메시지의 암호화된 데이터 키의 최대 수를 지정합니다. 이 파라미터는 선택 사항입니다. 유효한 값은 1\$165,535입니다. 이 파라미터를 생략하면 AWS Encryption CLI는 최대값을 적용하지 않습니다. 암호화된 메시지는 최대 65,535(2^16 - 1)개의 암호화된 데이터 키를 보유할 수 있습니다. 암호화 명령에 이 파라미터를 사용하여 잘못된 형식의 메시지를 방지할 수 있습니다. 복호화 명령에 이를 사용하여 악성 메시지를 탐지하고 복호화할 수 없는 암호화된 데이터 키가 많이 포함된 메시지의 복호화를 방지할 수 있습니다. 자세한 정보 및 예제는 [암호화된 데이터 키 제한](configure.md#config-limit-keys) 섹션을 참조하세요. **--help (-h)** 명령줄에서 사용법과 구문을 인쇄합니다. **--version** AWS Encryption CLI의 버전을 가져옵니다. **-v \$1 -vv \$1 -vvv \$1 -vvvv** 자세한 정보, 경고 및 디버깅 메시지를 표시합니다. 출력의 세부 정보는 파라미터의 `v` 개수에 따라 증가합니다. 가장 세부적인 설정(`-vvvv`)은 AWS Encryption CLI 및 사용하는 모든 구성 요소에서 디버깅 수준 데이터를 반환합니다. **--quiet (-q)** 출력 파일을 덮어쓸 때 나타나는 메시지와 같은 경고 메시지를 표시하지 않습니다. **--master-keys (-m)[더 이상 사용되지 않음]** --master-keys 파라미터는 버전 1.8.*x*에서 더 이상 사용되지 않으며 버전 2.1.*x*에서 제거되었습니다. 대신 [--wrapping-keys](#wrapping-keys) 파라미터를 사용합니다. 암호화 및 복호화 작업에 사용되는 [마스터 키](concepts.md#master-key)를 지정합니다. 각 명령에서 여러 마스터 키 파라미터를 사용할 수 있습니다. `--master-keys` 파라미터는 암호화 명령에 반드시 필요합니다. 이 파라미터는 사용자 지정(비AWS KMS) 마스터 키 공급자를 사용 중일 때만 복호화 명령에 반드시 필요합니다. **속성**: `--master-keys` 파라미터의 값은 다음 속성으로 구성됩니다. 형식은 `attribute_name=value`입니다. **key** 작업에 사용된 [래핑 키](concepts.md#master-key)를 식별합니다. 형식은 **key**=ID 페어입니다. **key** 속성은 모든 암호화 명령에 반드시 필요합니다. 암호화 명령 AWS KMS key 에서를 사용하는 경우 **키** 속성의 값은 키 ID, 키 ARN, 별칭 이름 또는 별칭 ARN일 수 있습니다. AWS KMS 키 식별자에 대한 자세한 내용은 *AWS Key Management Service 개발자 안내서*의 [키 식별자](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id)를 참조하세요. **key** 속성은 마스터 키 공급자가 AWS KMS가 아닐 때 복호화 명령에서 필수 사항입니다. **key** 속성은 AWS KMS key에서 암호화된 데이터를 복호화하는 명령에는 허용되지 않습니다. 각 `--master-keys` 파라미터 값에 여러 **key** 속성을 지정할 수 있습니다. 그러나 모든 **provider**, **region** 및 **profile** 속성은 해당 파라미터 값의 모든 마스터 키에 적용됩니다. 서로 다른 속성 값으로 마스터 키를 지정하려면 명령에서 여러 `--master-keys` 파라미터를 사용합니다. **provider** [마스터 키 공급자](concepts.md#master-key-provider)를 식별합니다. 형식은 **provider**=ID 페어입니다. 기본값인 **aws-kms**는를 나타냅니다 AWS KMS. 이 속성은 마스터 키 공급자가가 아닌 경우에만 필요합니다 AWS KMS. **리전** AWS 리전 의를 식별합니다 AWS KMS key. 이 속성은 에만 유효합니다 AWS KMS keys. 이 속성은 **key** 식별자에 리전이 지정되지 않을 때만 사용되며, 그렇지 않은 경우에는 무시됩니다. 사용 시 AWS CLI 명명된 프로파일의 기본 리전을 재정의합니다. **profile** AWS CLI [이름이 지정된 프로파일을 식별합니다](https://docs.aws.amazon.com/cli/latest/userguide/cli-multiple-profiles.html). 이 속성은 에만 유효합니다 AWS KMS keys. 이 프로필의 리전은 키 식별자에 리전이 지정되지 않고 이 명령에 **region** 속성이 없을 때만 사용됩니다. ## 고급 파라미터 **--algorithm** 대체 [알고리즘 제품군](concepts.md#crypto-algorithm)을 지정합니다. 이 파라미터는 선택 사항이며 암호화 명령에서만 유효합니다. 이 파라미터를 생략하면 AWS Encryption CLI는 버전 1.8.*x*에 AWS Encryption SDK 도입된에 대한 기본 알고리즘 제품군 중 하나를 사용합니다. 두 기본 알고리즘 모두 [HKDF](https://en.wikipedia.org/wiki/HKDF), ECDSA 서명 및 256비트 암호화 키와 함께 AES-GCM을 사용합니다. 하나는 키 커밋을 사용하고 다른 하나는 사용하지 않습니다. 기본 알고리즘 제품군 선택은 명령에 대한 [커밋 정책](concepts.md#commitment-policy)에 따라 결정됩니다. 대부분의 암호화 작업에는 기본 알고리즘 제품군이 권장됩니다. 유효한 값 목록은 [문서 읽기](https://aws-encryption-sdk-cli.readthedocs.io/en/latest/index.html#execution)에서 `algorithm` 파라미터 값을 참조하세요. **--frame-length** 지정된 프레임 길이로 출력을 생성합니다. 이 파라미터는 선택 사항이며 암호화 명령에서만 유효합니다. 값을 바이트 단위로 입력합니다. 유효한 값은 0 및 1\$12^31 - 1입니다. 값이 0이면 프레임 처리되지 않은 데이터를 나타냅니다. 기본값은 4096(바이트)입니다. 가능하면 프레임 처리된 데이터를 사용하세요. 는 레거시 용도로만 프레임 처리되지 않은 데이터를 AWS Encryption SDK 지원합니다. 의 일부 언어 구현은 여전히 프레임 처리되지 않은 사이퍼텍스트를 생성할 AWS Encryption SDK 수 있습니다. 지원되는 모든 언어 구현은 프레임 처리된 사이퍼텍스트와 프레임 처리되지 않은 사이퍼텍스트를 복호화할 수 있습니다. **max-length** 암호화된 메시지에서 읽을 바이트 단위의 최대 프레임 크기(또는 프레임 처리되지 않은 메시지의 경우 최대 콘텐츠 길이)를 지정합니다. 이 파라미터는 선택 사항이며 복호화 명령에서만 유효합니다. 매우 큰 악성 사이퍼텍스트를 복호화하지 못하도록 보호하기 위해 설계되었습니다. 값을 바이트 단위로 입력합니다. 이 파라미터를 생략하면는 복호화 시 프레임 크기를 제한하지 AWS Encryption SDK 않습니다. **--caching** 각 입력 파일에 대해 새 데이터 키를 생성하는 대신 데이터 키를 재사용하는 [데이터 키 캐싱](data-key-caching.md) 기능을 활성화합니다. 이 파라미터는 고급 시나리오를 지원합니다. 이 기능을 사용하기 전에 [데이터 키 캐싱](data-key-caching.md) 설명서를 읽어보세요. `--caching` 파라미터에는 다음 속성이 있습니다. **용량(필수)** 캐시의 최대 항목 수를 결정합니다. 최소값은 1입니다. 최대값은 없습니다. **max\$1age(필수)** 캐시 항목이 캐시에 추가된 시점부터 시작하여 캐시 항목의 사용 시간(초)을 결정합니다. 0보다 큰 값을 입력합니다. 최대값은 없습니다. **max\$1messages\$1encrypted(선택 사항)** 캐시된 항목이 암호화할 수 있는 최대 메시지 수를 결정합니다. 유효한 값은 1\$12^32입니다. 기본값은 메시지 2^32개입니다. **max\$1bytes\$1encrypted(선택 사항)** 캐시된 항목이 암호화할 수 있는 최대 바이트 수를 결정합니다. 유효한 값은 0 및 1\$12^63 - 1입니다. 기본값은 메시지 2^63 - 1개입니다. 값이 0이면 빈 메시지 문자열을 암호화하는 경우에만 데이터 키 캐싱을 사용할 수 있습니다. # AWS 암호화 CLI 버전 최신 버전의 AWS Encryption CLI를 사용하는 것이 좋습니다. **참고** 4.0.0 이전의 AWS Encryption CLI 버전은 [end-of-support 단계에](https://docs.aws.amazon.com/sdkref/latest/guide/maint-policy.html#version-life-cycle) 있습니다. 코드나 데이터를 변경하지 않고 버전 2.1.*x* 이상에서 AWS Encryption CLI의 최신 버전으로 안전하게 업데이트할 수 있습니다. 그러나 버전 2.1.*x*에 도입된 [새로운 보안 기능](about-versions.md#version-2)은 이하 버전과 호환되지 않습니다. 버전 1.7.*x* 이하에서 업데이트하려면 먼저 AWS Encryption CLI의 최신 1.*x* 버전으로 업데이트해야 합니다. 자세한 내용은 [마이그레이션 AWS Encryption SDK](migration.md)을 참조하세요. 새로운 보안 기능은 원래 AWS Encryption CLI 버전 1.7.*x* 및 2.0.*x*에서 릴리스되었습니다. 그러나 AWS Encryption CLI 버전 1.8.*x*는 버전 1.7.*x*를 대체하고 AWS Encryption CLI 2.1.*x*는 2.0.*x*를 대체합니다. 자세한 내용은 GitHub의 [aws-encryption-sdk-cli](https://github.com/aws/aws-encryption-sdk-cli/) 리포지토리에서 관련 [보안 권고](https://github.com/aws/aws-encryption-sdk-cli/security/advisories/GHSA-2xwp-m7mq-7q3r)를 참조하세요. 의 중요 버전에 대한 자세한 내용은 섹션을 AWS Encryption SDK참조하세요[의 버전 AWS Encryption SDK](about-versions.md). **어떤 버전을 사용해야 하나요?** AWS Encryption CLI를 처음 사용하는 경우 최신 버전을 사용합니다. AWS Encryption SDK 이전 버전 1.7.*x*로 암호화된 데이터를 해독하려면 먼저 최신 버전의 AWS Encryption CLI로 마이그레이션합니다. 버전 2.1.*x* 이상으로 업데이트하기 전에 [모든 권장 사항을 변경](migration-guide.md)합니다. 자세한 내용은 [마이그레이션 AWS Encryption SDK](migration.md)을 참조하세요. **자세히 알아보기** + 변경 사항에 대한 자세한 내용과, 새 버전으로 마이그레이션하기 위한 지침은 [마이그레이션 AWS Encryption SDK](migration.md) 섹션을 참조하세요. + 새로운 AWS Encryption CLI 파라미터 및 속성에 대한 설명은 섹션을 참조하세요[AWS Encryption SDK CLI 구문 및 파라미터 참조](crypto-cli-reference.md). 다음 목록은 버전 1.8.*x* 및 2.1.*x*에서 AWS Encryption CLI의 변경 사항을 설명합니다. ## AWS 암호화 CLI 버전 1.8.*x* 변경 사항 + `--master-keys` 파라미터를 더 이상 사용하지 않습니다. 대신 `--wrapping-keys` 파라미터를 사용합니다. + `--wrapping-keys`(`-w`) 파라미터를 추가합니다. `--master-keys` 파라미터의 모든 속성을 지원합니다. 또한 AWS KMS keys를 사용하여 복호화할 때만 유효한 다음과 같은 선택적 속성을 추가합니다. + **discovery** + **discovery-partition** + **discovery-account** 사용자 지정 마스터 키 공급자의 경우 `--encrypt` 및 -`-decrypt` 명령에는 `--wrapping-keys` 또는 `--master-keys` 파라미터가 필요합니다(둘 다는 아님). 또한를 사용하는 `--encrypt` 명령에는 `--wrapping-keys` 파라미터 또는 `--master-keys` 파라미터(둘 다 아님)가 AWS KMS keys 필요합니다. 를 사용하는 `--decrypt` 명령에서 AWS KMS keys`--wrapping-keys` 파라미터는 선택 사항이지만 버전 2.1.*x*에서 필요하므로 권장됩니다. 이를 사용하는 경우 **key** 속성 또는 **discovery** 속성 중 하나를 `true` 값으로 지정해야 합니다(둘 다는 아님). + `--commitment-policy` 파라미터를 추가합니다. 유일한 유효 값은 `forbid-encrypt-allow-decrypt`입니다. `forbid-encrypt-allow-decrypt` 커밋 정책은 모든 암호화 및 복호화 명령에 사용됩니다. 버전 1.8.*x*에서 `--wrapping-keys` 파라미터를 사용할 때는 `forbid-encrypt-allow-decrypt` 값이 있는 `--commitment-policy` 파라미터가 필요합니다. 이 값을 명시적으로 설정하면 버전 2.1.*x*로 업그레이드할 때 [커밋 정책](concepts.md#commitment-policy)이 자동으로 `require-encrypt-require-decrypt`로 변경되는 것을 방지할 수 있습니다. ## AWS 암호화 CLI에 대한 버전 2.1.*x* 변경 사항 + `--master-keys` 파라미터를 제거합니다. 대신 `--wrapping-keys` 파라미터를 사용합니다. + `--wrapping-keys` 파라미터는 모든 암호화 및 복호화 명령에 반드시 필요합니다. **key** 속성 또는 **discovery** 속성 중 하나를 `true` 값으로 지정해야 합니다(둘 다는 아님). + `--commitment-policy` 파라미터는 다음과 같은 값을 지원합니다. 자세한 내용은 [커밋 정책 설정](migrate-commitment-policy.md)을 참조하세요. + `forbid-encrypt-allow-decrypt` + `require-encrypt-allow-decrypt` + `require-encrypt-require decrypt`(기본값) + `--commitment-policy` 파라미터는 버전 2.1*x*에서 선택 사항입니다. 기본값은 `require-encrypt-require-decrypt`입니다. ## AWS Encryption CLI 버전 1.9.*x* 및 2.2.*x* 변경 사항 + `--decrypt-unsigned` 파라미터를 추가합니다. 자세한 내용은 [버전 2.2.*x*](about-versions.md#version2.2.x)을 참조하세요. + `--buffer` 파라미터를 추가합니다. 자세한 내용은 [버전 2.2.*x*](about-versions.md#version2.2.x)을 참조하세요. + `--max-encrypted-data-keys` 파라미터를 추가합니다. 자세한 내용은 [암호화된 데이터 키 제한](configure.md#config-limit-keys)을 참조하세요. ## AWS 암호화 CLI 버전 3.0.*x* 변경 사항 + AWS KMS 다중 리전 키에 대한 지원을 추가합니다. 자세한 내용은 [다중 리전 사용 AWS KMS keys](configure.md#config-mrks) 섹션을 참조하십시오.