From 2a3c3c4b6b91ef87ac527330b0dc71e490c1cbdd Mon Sep 17 00:00:00 2001 From: Darwin Chowdary Date: Tue, 9 Jan 2024 16:41:19 -0800 Subject: [PATCH 1/8] chore: update README.md --- README.md | 136 ++++++++++++++++++++++++++++++++++++------------------ 1 file changed, 92 insertions(+), 44 deletions(-) diff --git a/README.md b/README.md index be809cce..df088f88 100644 --- a/README.md +++ b/README.md @@ -21,6 +21,68 @@ To use the AWS Encryption SDK for Java you must have: **Note:** If you use the Oracle JDK, you must also download and install the [Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files](http://www.oracle.com/technetwork/java/javase/downloads/jce8-download-2133166.html). +* **Declare a Dependency on the AWS Encryption SDK in Java and it's dependencies** + + This library requires the AwsCryptographicMaterialProviders library and KMS client from the AWS SDK for Java V2. + + The KMS client from the AWS SDK for Java V1 is an **optional** dependency. + + **Note:** The AwsCryptographicMaterialProviders library only supports the AWS SDK for Java V2 and requires a HARD dependency on the AWS SDK for Java V2's KMS module, regardless of whether a KMS Keyring is used. + + * **Via Apache Maven** + Add the following to your project's `pom.xml`. + ```xml + + ... + + + + software.amazon.awssdk + bom + 2.20.91 + pom + import + + + + + + com.amazonaws + aws-encryption-sdk-java + 3.0.0 + + + software.amazon.cryptography + aws-cryptographic-material-providers + 1.0.2 + + + software.amazon.awssdk + kms + + + + com.amazonaws + aws-java-sdk + 1.12.394 + true + + + ... + + ``` + +* **Via Gradle Kotlin** + In a Gradle Java Project, add the following to the _dependencies_ section: + ```kotlin + implementation("com.amazonaws:aws-encryption-sdk-java:3.0.0") + implementation("software.amazon.cryptography:aws-cryptographic-material-providers:1.0.2") + implementation(platform("software.amazon.awssdk:bom:2.20.91")) + implementation("software.amazon.awssdk:kms") + // The following are optional: + implementation("com.amazonaws:aws-java-sdk:1.12.394") + ``` + * **Bouncy Castle** or **Bouncy Castle FIPS** The AWS Encryption SDK for Java uses Bouncy Castle to serialize and deserialize cryptographic objects. @@ -41,32 +103,17 @@ You don't need an Amazon Web Services (AWS) account to use the AWS Encryption SD * **To create an AWS account**, go to [Sign In or Create an AWS Account](https://portal.aws.amazon.com/gp/aws/developer/registration/index.html) and then choose **I am a new user.** Follow the instructions to create an AWS account. -* **To create a symmetric encryption KMS key in AWS KMS**, see [Creating Keys](https://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html). - -* **To download and install the AWS SDK for Java 2.x**, see [Installing the AWS SDK for Java 2.x](https://docs.aws.amazon.com/sdk-for-java/v2/developer-guide/getting-started.html). - -* **To download and install the AWS SDK for Java 1.x**, see [Installing the AWS SDK for Java 1.x](https://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/getting-started.html). +* **To create a key in AWS KMS**, see [Creating Keys](https://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html). #### Amazon Corretto Crypto Provider Many users find that the Amazon Corretto Crypto Provider (ACCP) significantly improves the performance of the AWS Encryption SDK. For help installing and using ACCP, see the [amazon-corretto-crypto-provider repository](https://github.com/corretto/amazon-corretto-crypto-provider). -### Download the AWS Encryption SDK for Java -You can get the latest release from Maven: - -```xml - - com.amazonaws - aws-encryption-sdk-java - 3.0.0 - -``` - ### Get Started To get started with the AWS Encryption SDK for Java 1. Instantiate the AWS Encryption SDK. -2. Define the master key provider. +2. Create a Keyring from AwsCryptographicMaterialProviders Library. 3. Encrypt and decrypt data. ```java @@ -74,17 +121,19 @@ To get started with the AWS Encryption SDK for Java // You provide the KMS key ARN and plaintext string as arguments. package com.amazonaws.crypto.examples; +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; -import com.amazonaws.encryptionsdk.AwsCrypto; -import com.amazonaws.encryptionsdk.CommitmentPolicy; -import com.amazonaws.encryptionsdk.CryptoResult; -import com.amazonaws.encryptionsdk.kms.KmsMasterKey; -import com.amazonaws.encryptionsdk.kms.KmsMasterKeyProvider; - public class StringExample { private static String keyArn; private static String plaintext; @@ -95,37 +144,36 @@ public class StringExample { // Instantiate the SDK final AwsCrypto crypto = AwsCrypto.standard(); - - // Set up the master key provider - final KmsMasterKeyProvider prov = KmsMasterKeyProvider.builder().buildStrict(keyArn); - + + // Create the AWS KMS keyring. + // We create a multi keyring, as this interface creates the KMS client for us automatically. + final MaterialProviders materialProviders = MaterialProviders.builder() + .MaterialProvidersConfig(MaterialProvidersConfig.builder().build()) + .build(); + final CreateAwsKmsMultiKeyringInput keyringInput = + CreateAwsKmsMultiKeyringInput.builder().generator(keyArn).build(); + final IKeyring kmsKeyring = materialProviders.CreateAwsKmsMultiKeyring(keyringInput); + // Set up the encryption context // NOTE: Encrypted data should have associated encryption context // to protect its integrity. This example uses placeholder values. // For more information about the encryption context, see // https://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/concepts.html#encryption-context - final Map context = Collections.singletonMap("ExampleContextKey", "ExampleContextValue"); + final Map encryptionContext = Collections.singletonMap("ExampleContextKey", "ExampleContextValue"); // Encrypt the data - // - final CryptoResult encryptResult = crypto.encryptData(prov, plaintext.getBytes(StandardCharsets.UTF_8), context); + final CryptoResult encryptResult = crypto.encryptData(kmsKeyring, plaintext.getBytes(StandardCharsets.UTF_8), encryptionContext); final byte[] ciphertext = encryptResult.getResult(); System.out.println("Ciphertext: " + Arrays.toString(ciphertext)); - // Decrypt the data - final CryptoResult decryptResult = crypto.decryptData(prov, ciphertext); - // Your application should verify the encryption context and the KMS key to - // ensure this is the expected ciphertext before returning the plaintext - if (!decryptResult.getMasterKeyIds().get(0).equals(keyArn)) { - throw new IllegalStateException("Wrong key id!"); - } - - // The AWS Encryption SDK may add information to the encryption context, so check to - // ensure all of the values that you specified when encrypting are *included* in the returned encryption context. - if (!context.entrySet().stream() - .allMatch( e -> e.getValue().equals(decryptResult.getEncryptionContext().get(e.getKey())))) { - throw new IllegalStateException("Wrong Encryption Context!"); - } + // 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); assert Arrays.equals(decryptResult.getResult(), plaintext.getBytes(StandardCharsets.UTF_8)); From 0091cdeb101c4e262894edfe32d7c27503a2cb3f Mon Sep 17 00:00:00 2001 From: Darwin Chowdary Date: Tue, 9 Jan 2024 16:44:37 -0800 Subject: [PATCH 2/8] chore: update README.md --- README.md | 116 +++++++++++++++++++++++++++--------------------------- 1 file changed, 58 insertions(+), 58 deletions(-) diff --git a/README.md b/README.md index df088f88..36e042f9 100644 --- a/README.md +++ b/README.md @@ -21,67 +21,67 @@ To use the AWS Encryption SDK for Java you must have: **Note:** If you use the Oracle JDK, you must also download and install the [Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files](http://www.oracle.com/technetwork/java/javase/downloads/jce8-download-2133166.html). -* **Declare a Dependency on the AWS Encryption SDK in Java and it's dependencies** - - This library requires the AwsCryptographicMaterialProviders library and KMS client from the AWS SDK for Java V2. - - The KMS client from the AWS SDK for Java V1 is an **optional** dependency. - - **Note:** The AwsCryptographicMaterialProviders library only supports the AWS SDK for Java V2 and requires a HARD dependency on the AWS SDK for Java V2's KMS module, regardless of whether a KMS Keyring is used. - - * **Via Apache Maven** - Add the following to your project's `pom.xml`. - ```xml - - ... - - + * **Declare a Dependency on the AWS Encryption SDK in Java and it's dependencies** + + This library requires the AwsCryptographicMaterialProviders library and KMS client from the AWS SDK for Java V2. + + The KMS client from the AWS SDK for Java V1 is an **optional** dependency. + + **Note:** The AwsCryptographicMaterialProviders library only supports the AWS SDK for Java V2 and requires a HARD dependency on the AWS SDK for Java V2's KMS module, regardless of whether a KMS Keyring is used. + + * **Via Apache Maven** + Add the following to your project's `pom.xml`. + ```xml + + ... + + + + software.amazon.awssdk + bom + 2.20.91 + pom + import + + + + + + com.amazonaws + aws-encryption-sdk-java + 3.0.0 + + + software.amazon.cryptography + aws-cryptographic-material-providers + 1.0.2 + software.amazon.awssdk - bom - 2.20.91 - pom - import + kms - - - - - com.amazonaws - aws-encryption-sdk-java - 3.0.0 - - - software.amazon.cryptography - aws-cryptographic-material-providers - 1.0.2 - - - software.amazon.awssdk - kms - - - - com.amazonaws - aws-java-sdk - 1.12.394 - true - - - ... - - ``` - -* **Via Gradle Kotlin** - In a Gradle Java Project, add the following to the _dependencies_ section: - ```kotlin - implementation("com.amazonaws:aws-encryption-sdk-java:3.0.0") - implementation("software.amazon.cryptography:aws-cryptographic-material-providers:1.0.2") - implementation(platform("software.amazon.awssdk:bom:2.20.91")) - implementation("software.amazon.awssdk:kms") - // The following are optional: - implementation("com.amazonaws:aws-java-sdk:1.12.394") - ``` + + + com.amazonaws + aws-java-sdk + 1.12.394 + true + + + ... + + ``` + + * **Via Gradle Kotlin** + In a Gradle Java Project, add the following to the _dependencies_ section: + ```kotlin + implementation("com.amazonaws:aws-encryption-sdk-java:3.0.0") + implementation("software.amazon.cryptography:aws-cryptographic-material-providers:1.0.2") + implementation(platform("software.amazon.awssdk:bom:2.20.91")) + implementation("software.amazon.awssdk:kms") + // The following are optional: + implementation("com.amazonaws:aws-java-sdk:1.12.394") + ``` * **Bouncy Castle** or **Bouncy Castle FIPS** From 04bf2e308b76c9b3c2c58fb88ad0556331a21c8b Mon Sep 17 00:00:00 2001 From: Darwin Chowdary Date: Tue, 9 Jan 2024 16:48:12 -0800 Subject: [PATCH 3/8] chore: update README.md --- README.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 36e042f9..643e7381 100644 --- a/README.md +++ b/README.md @@ -21,16 +21,16 @@ To use the AWS Encryption SDK for Java you must have: **Note:** If you use the Oracle JDK, you must also download and install the [Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files](http://www.oracle.com/technetwork/java/javase/downloads/jce8-download-2133166.html). - * **Declare a Dependency on the AWS Encryption SDK in Java and it's dependencies** +* **Declare a Dependency on the AWS Encryption SDK in Java and it's dependencies** - This library requires the AwsCryptographicMaterialProviders library and KMS client from the AWS SDK for Java V2. + This library requires the AwsCryptographicMaterialProviders library and KMS client from the AWS SDK for Java V2. - The KMS client from the AWS SDK for Java V1 is an **optional** dependency. + The KMS client from the AWS SDK for Java V1 is an **optional** dependency. - **Note:** The AwsCryptographicMaterialProviders library only supports the AWS SDK for Java V2 and requires a HARD dependency on the AWS SDK for Java V2's KMS module, regardless of whether a KMS Keyring is used. + **Note:** The AwsCryptographicMaterialProviders library only supports the AWS SDK for Java V2 and requires a HARD dependency on the AWS SDK for Java V2's KMS module, regardless of whether a KMS Keyring is used. - * **Via Apache Maven** - Add the following to your project's `pom.xml`. + * **Via Apache Maven** + Add the following to your project's `pom.xml`. ```xml ... @@ -72,8 +72,8 @@ To use the AWS Encryption SDK for Java you must have: ``` - * **Via Gradle Kotlin** - In a Gradle Java Project, add the following to the _dependencies_ section: + * **Via Gradle Kotlin** + In a Gradle Java Project, add the following to the _dependencies_ section: ```kotlin implementation("com.amazonaws:aws-encryption-sdk-java:3.0.0") implementation("software.amazon.cryptography:aws-cryptographic-material-providers:1.0.2") From c20682f6073cfdb6bfc7e52ae6f6c8c2e5cdf045 Mon Sep 17 00:00:00 2001 From: Darwin Chowdary Date: Tue, 9 Jan 2024 16:49:51 -0800 Subject: [PATCH 4/8] chore: update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 643e7381..6b09db72 100644 --- a/README.md +++ b/README.md @@ -166,7 +166,7 @@ public class StringExample { final byte[] ciphertext = encryptResult.getResult(); System.out.println("Ciphertext: " + Arrays.toString(ciphertext)); - // 5. Decrypt the data + // Decrypt the data final CryptoResult decryptResult = crypto.decryptData( kmsKeyring, From 5aaee172cccd11a1d13051bad226584f56e65997 Mon Sep 17 00:00:00 2001 From: Darwin Chowdary Date: Tue, 9 Jan 2024 16:59:20 -0800 Subject: [PATCH 5/8] chore: update README.md --- README.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/README.md b/README.md index 6b09db72..c2b78f01 100644 --- a/README.md +++ b/README.md @@ -105,6 +105,10 @@ You don't need an Amazon Web Services (AWS) account to use the AWS Encryption SD * **To create a key in AWS KMS**, see [Creating Keys](https://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html). +* **To download and install the AWS SDK for Java 2.x**, see [Installing the AWS SDK for Java 2.x](https://docs.aws.amazon.com/sdk-for-java/v2/developer-guide/getting-started.html). + +* **To download and install the AWS SDK for Java 1.x**, see [Installing the AWS SDK for Java 1.x](https://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/getting-started.html). + #### Amazon Corretto Crypto Provider Many users find that the Amazon Corretto Crypto Provider (ACCP) significantly improves the performance of the AWS Encryption SDK. For help installing and using ACCP, see the [amazon-corretto-crypto-provider repository](https://github.com/corretto/amazon-corretto-crypto-provider). From b7f40a83bc0e15f4ba1a1075ad74e1d48bae3859 Mon Sep 17 00:00:00 2001 From: Darwin Chowdary Date: Fri, 26 Jan 2024 03:12:56 -0800 Subject: [PATCH 6/8] address feedback --- README.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index c2b78f01..bc601bde 100644 --- a/README.md +++ b/README.md @@ -23,11 +23,11 @@ To use the AWS Encryption SDK for Java you must have: * **Declare a Dependency on the AWS Encryption SDK in Java and it's dependencies** - This library requires the AwsCryptographicMaterialProviders library and KMS client from the AWS SDK for Java V2. + This library requires the AWS Material Providers Library in Java, and the KMS and DynamoDB clients from the AWS Java SDK V2. The KMS client from the AWS SDK for Java V1 is an **optional** dependency. - **Note:** The AwsCryptographicMaterialProviders library only supports the AWS SDK for Java V2 and requires a HARD dependency on the AWS SDK for Java V2's KMS module, regardless of whether a KMS Keyring is used. + **Note:** The AWS Material Providers Library in Java only supports the AWS SDK for Java V2 and requires a HARD dependency on the AWS SDK for Java V2's KMS and DynamoDB clients, regardless of whether a KMS Keyring or Hierarchical Keyring is used. * **Via Apache Maven** Add the following to your project's `pom.xml`. @@ -56,6 +56,10 @@ To use the AWS Encryption SDK for Java you must have: aws-cryptographic-material-providers 1.0.2 + + software.amazon.awssdk + dynamodb + software.amazon.awssdk kms @@ -79,6 +83,7 @@ To use the AWS Encryption SDK for Java you must have: implementation("software.amazon.cryptography:aws-cryptographic-material-providers:1.0.2") implementation(platform("software.amazon.awssdk:bom:2.20.91")) implementation("software.amazon.awssdk:kms") + implementation("software.amazon.awssdk:dynamodb") // The following are optional: implementation("com.amazonaws:aws-java-sdk:1.12.394") ``` From a31e0155577e9cc76b952ec74dd1cff5b6e8263d Mon Sep 17 00:00:00 2001 From: Darwin Chowdary Date: Fri, 26 Jan 2024 03:40:34 -0800 Subject: [PATCH 7/8] address feedback --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index bc601bde..16404e42 100644 --- a/README.md +++ b/README.md @@ -23,11 +23,11 @@ To use the AWS Encryption SDK for Java you must have: * **Declare a Dependency on the AWS Encryption SDK in Java and it's dependencies** - This library requires the AWS Material Providers Library in Java, and the KMS and DynamoDB clients from the AWS Java SDK V2. + This library requires the AWS Cryptographic Material Providers Library in Java, and the KMS and DynamoDB clients from the AWS Java SDK V2. The KMS client from the AWS SDK for Java V1 is an **optional** dependency. - **Note:** The AWS Material Providers Library in Java only supports the AWS SDK for Java V2 and requires a HARD dependency on the AWS SDK for Java V2's KMS and DynamoDB clients, regardless of whether a KMS Keyring or Hierarchical Keyring is used. + **Note:** The AWS Cryptographic Material Providers Library in Java only supports the AWS SDK for Java V2 and requires a HARD dependency on the AWS SDK for Java V2's KMS and DynamoDB clients, regardless of whether a KMS Keyring or Hierarchical Keyring is used. * **Via Apache Maven** Add the following to your project's `pom.xml`. @@ -122,7 +122,7 @@ For help installing and using ACCP, see the [amazon-corretto-crypto-provider rep To get started with the AWS Encryption SDK for Java 1. Instantiate the AWS Encryption SDK. -2. Create a Keyring from AwsCryptographicMaterialProviders Library. +2. Create a Keyring from the AWS Cryptographic Material Providers Library. 3. Encrypt and decrypt data. ```java From e09e2bacb70d47328d54d7294c6ded574aefd109 Mon Sep 17 00:00:00 2001 From: Darwin Chowdary Date: Mon, 5 Feb 2024 10:09:56 -0800 Subject: [PATCH 8/8] address feedback --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 16404e42..6d3e82bf 100644 --- a/README.md +++ b/README.md @@ -21,7 +21,7 @@ To use the AWS Encryption SDK for Java you must have: **Note:** If you use the Oracle JDK, you must also download and install the [Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files](http://www.oracle.com/technetwork/java/javase/downloads/jce8-download-2133166.html). -* **Declare a Dependency on the AWS Encryption SDK in Java and it's dependencies** +* **Declare a Dependency on the AWS Encryption SDK in Java and its dependencies** This library requires the AWS Cryptographic Material Providers Library in Java, and the KMS and DynamoDB clients from the AWS Java SDK V2.