AWS Encryption SDK for Java

이 주제에서는 AWS Encryption SDK for Java를 설치 및 사용하는 방법을 설명합니다. 를 사용한 프로그래밍에 대한 자세한 내용은 의 aws-encryption-sdk-java저장소를 참조하십시오 GitHub. AWS Encryption SDK for Java API 설명서를 보려면 AWS Encryption SDK for Java용 Javadoc을 참조하세요.

주제

사전 조건
설치
AWS KMS 키링
필수 암호화 컨텍스트 CMM
예제

사전 조건

AWS Encryption SDK for Java를 설치하려면 먼저 다음 사전 조건이 충족되어야 합니다.

Java 개발 환경

Java 8 이상이 필요합니다. Oracle 웹 사이트에서 Java SE 다운로드로 이동한 다음 Java SE Development Kit(JDK)를 다운로드하여 설치합니다.

Oracle JDK를 사용하는 경우 Java Cryptography Extension(JCE) Unlimited Strength Jurisdiction Policy File도 다운로드하여 설치해야 합니다.

Bouncy Castle

AWS Encryption SDK for Java에는 Bouncy Castle이 필요합니다.

AWS Encryption SDK for Java 버전 1.6.1 이상은 Bouncy Castle을 사용하여 암호화 객체를 직렬화하고 역직렬화합니다. 이 요구 사항을 충족하기 위해 Bouncy Castle 또는 Bouncy Castle FIPS를 사용할 수 있습니다. Bouncy Castle FIPS 설치 및 구성에 대한 도움말은 BC FIPS 설명서, 특히 사용 설명서 및 보안 정책 PDF를 참조하세요.
AWS Encryption SDK for Java의 이하 버전은 Bouncy Castle의 Java용 암호화 API를 사용합니다. 이 요구 사항은 비 FIPS Bouncy Castle만 만족합니다.

Bouncy Castle이 없다면 Bouncy Castle 최신 릴리스로 이동하여 사용자의 JDK에 해당하는 공급자 파일을 다운로드하세요. 아파치 메이븐을 사용하여 표준 바운시 캐슬 제공자 (bcprov-ext-jdk15on) 용 아티팩트 또는 바운시 캐슬 FIPS (bc-fips) 용 아티팩트를 가져올 수도 있습니다.

AWS SDK for Java

버전 3. x 중 x에는 AWS SDK for Java 2.x AWS KMS 키링을 사용하지 않는 경우에도 AWS Encryption SDK for Java 필요합니다.

버전 2. x 또는 이전 버전에는 필요하지 AWS Encryption SDK for Java 않습니다AWS SDK for Java. 하지만 AWS SDK for Java는 AWS Key Management Service(AWS KMS)를 마스터 키 공급자로 사용해야 합니다. AWS Encryption SDK for Java 버전 2.4.0부터 AWS Encryption SDK for Java는 AWS SDK for Java의 버전 1.x와 2.x 버전을 모두 지원합니다. AWS SDK for Java 1.x 및 2.x에 대한 AWS Encryption SDK 코드는 상호 연동이 가능합니다. 예를 들어 AWS SDK for Java 1.x를 지원하는 AWS Encryption SDK 코드로 데이터를 암호화하고 AWS SDK for Java 2.x를 지원하는 코드를 사용하여 복호화할 수 있습니다(반대의 경우도 마찬가지). AWS Encryption SDK for Java의 2.4.0 이하 버전은 AWS SDK for Java 1.x만 지원합니다. AWS Encryption SDK의 버전 업데이트에 대한 자세한 내용은 AWS Encryption SDK 마이그레이션 섹션을 참조하세요.

AWS Encryption SDK for Java 코드를 AWS SDK for Java 1.x에서 AWS SDK for Java 2.x로 업데이트할 경우 AWS SDK for Java 1.x의 AWSKMS 인터페이스에 대한 참조를 AWS SDK for Java 2.x의 KmsClient 인터페이스에 대한 참조로 바꾸세요. AWS Encryption SDK for Java는 KmsAsyncClient 인터페이스를 지원하지 않습니다. 또한 kms 네임스페이스 대신 kmssdkv2 네임스페이스의 AWS KMS 관련 객체를 사용하도록 코드를 업데이트하세요.

AWS SDK for Java를 설치하려면 Apache Maven을 사용합니다.

전체 AWS SDK for Java를 종속성으로 가져오려면 pom.xml 파일에 선언하세요.
AWS SDK for Java 1.x의 AWS KMS 모듈에 대해서만 종속성을 만들려면 특정 모듈 지정에 대한 지침을 따르고 artifactId를 aws-java-sdk-kms로 설정합니다.
AWS SDK for Java 2.x의 AWS KMS 모듈에 대해서만 종속성을 만들려면 특정 모듈 지정에 대한 지침을 따릅니다. groupId를 software.amazon.awssdk로, artifactId를 kms로 설정합니다.

자세한 변경 사항은 AWS SDK for Java 2.x 개발자 가이드의 AWS SDK for Java 1.x와 2.x의 차이점을 참조하세요.

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

코드나 데이터를 변경하지 않고 버전 2.0.x 이상에서 AWS Encryption SDK for Java의 최신 버전으로 안전하게 업데이트할 수 있습니다. 그러나 버전 2.0.x에 도입된 새로운 보안 기능은 이하 버전과 호환되지 않습니다. 1.7.x 이하 버전에서 2.0.x 이상 버전으로 업데이트하려면 먼저 AWS Encryption SDK의 최신 1.x 버전으로 업데이트해야 합니다. 자세한 내용은 AWS Encryption SDK 마이그레이션을(를) 참조하세요.

다음 방법을 사용하여 AWS Encryption SDK for Java를 설치할 수 있습니다.

직접

를 설치하려면 AWS Encryption SDK for Java 리포지토리를 복제하거나 다운로드하십시오. aws-encryption-sdk-java GitHub

Apache Maven 사용

AWS Encryption SDK for Java는 다음 종속성 정의를 사용하여 Apache Maven을 통해 사용할 수 있습니다.


<dependency>
  <groupId>com.amazonaws</groupId>
  <artifactId>aws-encryption-sdk-java</artifactId>
  <version>3.0.0</version>
</dependency>

SDK를 설치한 후 이 가이드의 예제 Java 코드를 살펴보고 Javadoc을 켜서 시작하십시오. GitHub

AWS KMS키링에 들어 있는 AWS Encryption SDK for Java

버전 3. x는 키링을 AWS Encryption SDK for Java 사용하여 봉투 암호화를 수행합니다. 기본 AWS KMS 키링에는 KMS 키가 AWS Encryption SDK for Java 하나만 사용됩니다. 또한 KMS 키에 맞게 AWS 리전에 대한 클라이언트를 구성할 수 있는 AWS KMS 클라이언트가 필요합니다.

하나 이상의 래핑 키로 AWS KMS 키링을 생성하려면 다중 키링을 사용합니다. AWS Encryption SDK for Java에는 하나 이상의 AWS KMS 키를 사용하는 특수 다중 키링과 지원되는 유형의 하나 이상의 키링을 사용하는 표준 다중 키링이 있습니다. 일부 프로그래머는 모든 키링을 만들 때 다중 키링 방법을 사용하는 것을 선호하는데, 이러한 전략을 지원합니다. AWS Encryption SDK for Java

는 다중 지역 키를 비롯한 모든 일반적인 사용 사례에 사용할 수 있는 기본 단일 키 키링과 다중 키링을 AWS Encryption SDK for Java 제공합니다. AWS KMS

예를 들어 하나의 AWS KMS 키로 AWS KMS 키링을 만들려면] 메서드를 사용할 수 있습니다. CreateAwsKmsKeyring()


// Instantiate the AWS Encryption SDK and material providers
final AwsCrypto crypto = AwsCrypto.builder().build();
final MaterialProviders materialProviders = MaterialProviders.builder()
        .MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
        .build();

// Create the keyring
CreateAwsKmsKeyringInput kmsKeyringInput = CreateAwsKmsKeyringInput.builder()
        .kmsKeyId(keyArn)
        .kmsClient(KmsClient.create())
        .build();
IKeyring kmsKeyring = materialProviders.CreateAwsKmsKeyring(kmsKeyringInput);

하나 이상의 AWS KMS 키가 포함된 키링을 만들려면 CreateAwsKmsMultiKeyring() 메서드를 사용합니다. 이 예에서는 두 개의 KMS 키를 사용합니다. 한 개의 KMS 키를 지정하려면 generator 파라미터만 사용합니다. 추가 KMS 키를 지정하는 msKeyIds 파라미터는 선택 사항입니다.

이 키링의 입력에는 AWS KMS 클라이언트를 사용하지 않습니다. 대신 AWS Encryption SDK는 키링의 KMS 키로 표시되는 각 리전의 기본 AWS KMS 클라이언트를 사용합니다. 예를 들어 Generator 파라미터의 값으로 식별되는 KMS 키가 미국 서부(오레곤) 리전(us-west-2) 에 있는 경우 AWS Encryption SDK는 us-west-2 리전의 기본 AWS KMS 클라이언트를 생성합니다. AWS KMS 클라이언트를 사용자 지정해야 하는 경우 CreateAwsKmsKeyring() 메서드를 사용합니다.


// Instantiate the AWS Encryption SDK and material providers
final AwsCrypto crypto = AwsCrypto.builder().build();
final MaterialProviders materialProviders = MaterialProviders.builder()
            .MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
            .build();

String generatorKey = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";
List<String> additionalKey = Collections.singletonList("arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321");
// Create the keyring
final CreateAwsKmsMultiKeyringInput keyringInput = CreateAwsKmsMultiKeyringInput.builder()
        .generator(generatorKey)
        .kmsKeyIds(additionalKey)
        .build();
final IKeyring kmsKeyring = matProv.CreateAwsKmsMultiKeyring(keyringInput);

AWS Encryption SDK for Java대칭 암호화 (SYMMETRIC_DEFAULT) 또는 비대칭 RSA KMS 키를 사용하는 AWS KMS 키링을 지원합니다. AWS KMS비대칭 RSA KMS 키로 만든 키링은 하나의 키 쌍만 포함할 수 있습니다.

비대칭 RSA AWS KMS 키링으로 암호화하려면 kms: GenerateDataKey 또는 KMS:Encrypt가 필요하지 않습니다. 키링을 생성할 때 암호화에 사용할 퍼블릭 키 자료를 지정해야 하기 때문입니다. 이 키링으로 암호화할 때는 AWS KMS 호출이 이루어지지 않습니다. 비대칭 RSA AWS KMS 키링으로 복호화하려면 kms:Decrypt 권한이 필요합니다.

비대칭 RSA AWS KMS 키링을 생성하려면 비대칭 RSA KMS 키에서 퍼블릭 키와 프라이빗 키 ARN을 제공해야 합니다. 퍼블릭 키는 PEM으로 인코딩되어야 합니다. 다음 예제에서는 비대칭 RSA 키 페어를 사용하여 AWS KMS 키링을 생성합니다.


// Instantiate the AWS Encryption SDK and material providers
final AwsCrypto crypto = AwsCrypto.builder()
        // Specify algorithmSuite without asymmetric signing here
        //
        // ALG_AES_128_GCM_IV12_TAG16_NO_KDF("0x0014"),
        // ALG_AES_192_GCM_IV12_TAG16_NO_KDF("0x0046"),
        // ALG_AES_256_GCM_IV12_TAG16_NO_KDF("0x0078"),
        // ALG_AES_128_GCM_IV12_TAG16_HKDF_SHA256("0x0114"),
        // ALG_AES_192_GCM_IV12_TAG16_HKDF_SHA256("0x0146"),
        // ALG_AES_256_GCM_IV12_TAG16_HKDF_SHA256("0x0178")
        .withEncryptionAlgorithm(CryptoAlgorithm.ALG_AES_256_GCM_IV12_TAG16_HKDF_SHA256)
        .build();
                
final MaterialProviders matProv = MaterialProviders.builder()
        .MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
        .build();

// Create a KMS RSA keyring.
//    This keyring takes in:
//     - kmsClient
//     - kmsKeyId: Must be an ARN representing an asymmetric RSA KMS key
//     - publicKey: A ByteBuffer of a UTF-8 encoded PEM file representing the public
//                  key for the key passed into kmsKeyId
//     - encryptionAlgorithm: Must be either RSAES_OAEP_SHA_256 or RSAES_OAEP_SHA_1
final CreateAwsKmsRsaKeyringInput createAwsKmsRsaKeyringInput =
        CreateAwsKmsRsaKeyringInput.builder()
                .kmsClient(KmsClient.create())
                .kmsKeyId(rsaKeyArn)
                .publicKey(publicKey)
                .encryptionAlgorithm(EncryptionAlgorithmSpec.RSAES_OAEP_SHA_256)
                .build();
IKeyring awsKmsRsaKeyring = matProv.CreateAwsKmsRsaKeyring(createAwsKmsRsaKeyringInput);

버전 3.x의 필수 암호화 컨텍스트

버전 3 사용 시. x에서는 AWS Encryption SDK for Java 필수 암호화 컨텍스트 CMM을 사용하여 암호화 작업에 암호화 컨텍스트를 요구할 수 있습니다. 암호화 컨텍스트는 비밀이 아닌 키-값 페어 세트입니다. 암호화 컨텍스트는 암호화된 데이터에 암호적으로 바인딩되므로 필드를 복호화하는 데 동일한 암호화 컨텍스트가 필요합니다. 필수 암호화 컨텍스트 CMM을 사용하는 경우 모든 암호화 및 복호화 호출에 포함되어야 하는 필수 암호화 컨텍스트 키(필수 키)를 하나 이상 지정할 수 있습니다.

참고

필수 암호화 컨텍스트 CMM은 버전 4와만 상호 운용할 수 있습니다. .NET용 x입니다. AWS Encryption SDK 다른 프로그래밍 언어 구현과는 상호 운용되지 않습니다. 필수 암호화 컨텍스트 CMM을 사용하여 데이터를 암호화하는 경우 버전 3에서만 복호화할 수 있습니다. 또는 버전 4의 AWS Encryption SDK for Java x. AWS Encryption SDK.NET용 x입니다.

암호화 시, AWS Encryption SDK는 필요한 모든 암호화 컨텍스트 키가 지정된 암호화 컨텍스트에 포함되어 있는지 확인합니다. AWS Encryption SDK는 지정한 암호화 컨텍스트에 서명합니다. 필수 키가 아닌 키-값 페어만 직렬화되어, 암호화 작업에서 반환되는 암호화된 메시지의 헤더에 일반 텍스트로 저장됩니다.

복호화 시, 필수 키를 나타내는 모든 키-값 페어가 포함된 암호화 컨텍스트를 제공해야 합니다. AWS Encryption SDK에서는 이 암호화 컨텍스트와, 암호화된 메시지의 헤더에 저장된 키-값 페어를 사용하여 암호화 작업에서 지정한 원래 암호화 컨텍스트를 재구성합니다. AWS Encryption SDK에서 원래 암호화 컨텍스트를 재구성할 수 없는 경우 복호화 작업이 실패합니다. 필수 키가 포함된 키-값 페어에 잘못된 값을 입력하면 암호화된 메시지를 복호화할 수 없습니다. 암호화 시 지정한 것과 동일한 키-값 페어를 제공해야 합니다.

중요

암호화 컨텍스트에서 필수 키에 어떤 값을 선택할지 신중하게 고려하세요. 복호화 시 동일한 키와 해당 값을 다시 제공할 수 있어야 합니다. 필수 키를 재생성할 수 없는 경우 암호화된 메시지를 복호화할 수 없습니다.

다음 예제에서는 필수 암호화 컨텍스트 CMM을 사용하여 AWS KMS 키링을 초기화합니다.


// Instantiate the AWS Encryption SDK
final AwsCrypto crypto = AwsCrypto.builder()
        .withCommitmentPolicy(CommitmentPolicy.RequireEncryptRequireDecrypt)
        .build();
    
// Create your encryption context
final Map<String, String> encryptionContext = new HashMap<>();
encryptionContext.put("encryption", "context");
encryptionContext.put("is not", "secret");
encryptionContext.put("but adds", "useful metadata");
encryptionContext.put("that can help you", "be confident that");
encryptionContext.put("the data you are handling", "is what you think it is");    

// Create a list of required encryption contexts
final List<String> requiredEncryptionContextKeys = Arrays.asList("encryption", "context");
    
// Create the keyring
final MaterialProviders materialProviders = MaterialProviders.builder()
        .MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
        .build();
final CreateAwsKmsKeyringInput keyringInput = CreateAwsKmsKeyringInput.builder()
        .kmsKeyId(keyArn)
        .kmsClient(KmsClient.create())
        .build();
IKeyring kmsKeyring = materialProviders.CreateAwsKmsKeyring(keyringInput);
    
// Create the required encryption context CMM
ICryptographicMaterialsManager cmm = 
    materialProviders.CreateDefaultCryptographicMaterialsManager(
        CreateDefaultCryptographicMaterialsManagerInput.builder()
            .keyring(kmsKeyring)
            .build()
    );
ICryptographicMaterialsManager requiredCMM = 
    materialProviders.CreateRequiredEncryptionContextCMM(
        CreateRequiredEncryptionContextCMMInput.builder()
            .requiredEncryptionContextKeys(requiredEncryptionContextKeys)
            .underlyingCMM(cmm)
            .build()
        );

javascript가 브라우저에서 비활성화되거나 사용이 불가합니다.

AWS 설명서를 사용하려면 Javascript가 활성화되어야 합니다. 지침을 보려면 브라우저의 도움말 페이지를 참조하십시오.

문서 규칙

예제