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 KMS 钥匙圈
所需的加密上下文 CMM
示例

先决条件

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

Java 开发环境

您需要使用 Java 8 或更高版本。在 Oracle 网站上，前往 Java SE 下载，然后下载并安装 Java SE 开发套件 (JDK)。

如果您使用 OracleJDK，则还必须下载并安装 Java Cryptography Extensi JCE on () 无限强度管辖权策略文件。

Bouncy Castle

AWS Encryption SDK for Java 需要充气城堡。

AWS Encryption SDK for Java 1.6.1 及更高版本使用 Bouncy Castle 对加密对象进行序列化和反序列化。你可以使用 Bouncy Castle 或 Bouncy Castle FIPS 来满足这个要求。有关安装和配置 Bouncy Castle 的帮助FIPS，请参阅 BC FIPS 文档，尤其是用户指南和安全策略PDFs。
早期版本 AWS Encryption SDK for Java 使用 Bouncy Castle 的 Java 加密技术API。只有非 FIPS Bouncy Castle 才能满足此要求。

如果你没有 Bouncy Castle，请前往 Bouncy Castle 最新版本下载与你相对应的提供程序文件。JDK你也可以使用 Apache Mav en 获取标准 Bouncy Castle 提供者（bcprov-ext-jdk15 on）的神器或 Bouncy Castle 的神器（bc-fips）。FIPS

AWS SDK for Java

版本 3。 其中 x AWS Encryption SDK for Java 需要 AWS SDK for Java 2.x，即使你不使用 AWS KMS 钥匙圈。

版本 2。 x 或更早版本 AWS Encryption SDK for Java 不需要 AWS SDK for Java。但是 AWS SDK for Java ，必须使用 AWS Key Management Service(AWS KMS) 作为主密钥提供程序。从 2.4.0 AWS Encryption SDK for Java 版本开始，同时 AWS Encryption SDK for Java 支持 1.x 和 2.x 版本的。 AWS SDK for Java AWS Encryption SDK AWS SDK for Java 1.x 和 2.x 的代码是可互操作的。例如，您可以使用支持 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。

将 AWS Encryption SDK for Java 代码从 1.x 更新到时 AWS SDK for Java 2.x，请将 AWS SDK for Java 1.x 中对AWSKMS接口的引用替换为中 AWS SDK for Java 对KmsClient接口的引用。 AWS SDK for Java 2.x AWS Encryption SDK for Java 不支持该KmsAsyncClient接口。此外，更新您的代码以使用kmssdkv2命名空间中的 AWS KMS相关对象，而不是kms命名空间。

要安装，请使用 Apache Maven。 AWS SDK for Java

要导入整个 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 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

您可以安全地从 AWS Encryption SDK for Java 版本 2.0.x 及更高版本更新为最新版本，无需更改任何代码或数据。但是，版本 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

可通过 Apache Maven 获得，依赖关系定义如下。 AWS Encryption SDK for Java


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

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

注意

所需的加密上下文CMM只能与版本 4 互操作。 for AWS Encryption SDK 的 x。 NET。而不能与任何其他编程语言实现互操作。如果您使用所需的加密上下文加密数据CMM，则只能使用版本 3 对其进行解密。 AWS Encryption SDK for Java 或版本的 x。 for AWS Encryption SDK 的 x。 NET。

加密时， 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()
        );

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

文档惯例

示例