本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

AWS Encryption SDK for Java

本主题介绍了如何安装和使用 AWS Encryption SDK for Java。有关使用编程的详细信息 AWS Encryption SDK for Java，请参阅上的aws-encryption-sdk-java存储库 GitHub。有关API文档，请参阅相关的 Javadoc。 AWS Encryption SDK for Java

先决条件

在安装之前 AWS Encryption SDK for Java，请确保满足以下先决条件。

安装

安装最新版本的 AWS Encryption SDK for Java。

您可以通过以下 AWS Encryption SDK for Java 方式安装。

安装完成后SDK，首先查看本指南中的示例 Java 代码，然后打开 J avadoc。 GitHub

AWS KMS 里面有钥匙圈 AWS Encryption SDK for Java

版本 3。 x AWS Encryption SDK for Java 使用密钥环进行信封加密。里面的基本 AWS KMS 钥匙圈只 AWS Encryption SDK for Java 需要一把KMS钥匙。它们还需要一个 AWS KMS 客户端，这使您有机会为KMS密钥配置客户端。 AWS 区域

要创建带有一个或多个包装密 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)，则会为该us-west-2区域 AWS Encryption SDK 创建默认 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 = materialProviders.CreateAwsKmsMultiKeyring(keyringInput);

AWS Encryption SDK for Java 支持使用对称加密 (SYMMETRIC_DEFAULT) 或非RSAKMS对称密 AWS KMS 钥的密钥环。 AWS KMS 使用非对称RSAKMS密钥创建的密钥环只能包含一个密钥对。

要使用非对称RSA AWS KMS 密钥环进行加密，您不需要 kms: GenerateDataKey 或 kms: E ncrypt，因为在创建密钥环时，必须指定要用于加密的公钥材料。使用此密钥环加密时不会 AWS KMS 发出任何呼叫。要使用非对称密RSA AWS KMS 钥环进行解密，你需要 kms: Decrypt 权限。

要创建非对称RSA AWS KMS 密钥环，必须提供非对称RSAKMS密钥中的公钥和私钥ARN。必须对公钥进行PEM编码。以下示例使用非对称 AWS KMS 密钥对创建RSA密钥环。

// 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，可以指定一个或多个必需的加密上下文密钥（必需的密钥），这些密钥必须包含在所有加密和解密调用中。

加密时， AWS Encryption SDK 验证所有必需的加密上下文密钥是否包含在您指定的加密上下文中。对您指定的加密上下文进行 AWS Encryption SDK 签名。只有非所需密钥的键值对才会序列化并以明文格式存储在加密操作返回的加密消息的标头中。

解密时，必须提供包含代表所需密钥的所有键值对的加密上下文。 AWS Encryption SDK 使用此加密上下文和存储在加密邮件标头中的键值对来重建您在加密操作中指定的原始加密上下文。如果 AWS Encryption SDK 无法重建原始加密上下文，则解密操作将失败。如果您提供的键值对包含值不正确的所需密钥，则无法解密加密消息。您提供的键值对必须与加密时指定的相同。

以下示例使用所需的加密上下文初始化 AWS KMS 密钥环。CMM

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