Skip to content

Commit 7a0899e

Browse files
imabhichowimabhichow
authored
chore(README): update README.md (#1940)
1 parent 1890ebb commit 7a0899e

File tree

1 file changed

+96
-39
lines changed

1 file changed

+96
-39
lines changed

‎README.md

+96-39
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,73 @@ To use the AWS Encryption SDK for Java you must have:
2121

2222
**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).
2323

24+
* **Declare a Dependency on the AWS Encryption SDK in Java and its dependencies**
25+
26+
This library requires the AWS Cryptographic Material Providers Library in Java, and the KMS and DynamoDB clients from the AWS Java SDK V2.
27+
28+
The KMS client from the AWS SDK for Java V1 is an **optional** dependency.
29+
30+
**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.
31+
32+
* **Via Apache Maven**
33+
Add the following to your project's `pom.xml`.
34+
```xml
35+
<project>
36+
...
37+
<dependencyManagement>
38+
<dependencies>
39+
<dependency>
40+
<groupId>software.amazon.awssdk</groupId>
41+
<artifactId>bom</artifactId>
42+
<version>2.20.91</version>
43+
<type>pom</type>
44+
<scope>import</scope>
45+
</dependency>
46+
</dependencies>
47+
</dependencyManagement>
48+
<dependencies>
49+
<dependency>
50+
<groupId>com.amazonaws</groupId>
51+
<artifactId>aws-encryption-sdk-java</artifactId>
52+
<version>3.0.0</version>
53+
</dependency>
54+
<dependency>
55+
<groupId>software.amazon.cryptography</groupId>
56+
<artifactId>aws-cryptographic-material-providers</artifactId>
57+
<version>1.0.2</version>
58+
</dependency>
59+
<dependency>
60+
<groupId>software.amazon.awssdk</groupId>
61+
<artifactId>dynamodb</artifactId>
62+
</dependency>
63+
<dependency>
64+
<groupId>software.amazon.awssdk</groupId>
65+
<artifactId>kms</artifactId>
66+
</dependency>
67+
<!-- The following are optional -->
68+
<dependency>
69+
<groupId>com.amazonaws</groupId>
70+
<artifactId>aws-java-sdk</artifactId>
71+
<version>1.12.394</version>
72+
<optional>true</optional>
73+
</dependency>
74+
</dependencies>
75+
...
76+
</project>
77+
```
78+
79+
* **Via Gradle Kotlin**
80+
In a Gradle Java Project, add the following to the _dependencies_ section:
81+
```kotlin
82+
implementation("com.amazonaws:aws-encryption-sdk-java:3.0.0")
83+
implementation("software.amazon.cryptography:aws-cryptographic-material-providers:1.0.2")
84+
implementation(platform("software.amazon.awssdk:bom:2.20.91"))
85+
implementation("software.amazon.awssdk:kms")
86+
implementation("software.amazon.awssdk:dynamodb")
87+
// The following are optional:
88+
implementation("com.amazonaws:aws-java-sdk:1.12.394")
89+
```
90+
2491
* **Bouncy Castle** or **Bouncy Castle FIPS**
2592

2693
The AWS Encryption SDK for Java uses Bouncy Castle to serialize and deserialize cryptographic objects.
@@ -41,7 +108,7 @@ You don't need an Amazon Web Services (AWS) account to use the AWS Encryption SD
41108

42109
* **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.
43110

44-
* **To create a symmetric encryption KMS key in AWS KMS**, see [Creating Keys](https://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html).
111+
* **To create a key in AWS KMS**, see [Creating Keys](https://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html).
45112

46113
* **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).
47114

@@ -51,40 +118,31 @@ You don't need an Amazon Web Services (AWS) account to use the AWS Encryption SD
51118
Many users find that the Amazon Corretto Crypto Provider (ACCP) significantly improves the performance of the AWS Encryption SDK.
52119
For help installing and using ACCP, see the [amazon-corretto-crypto-provider repository](https://github.com/corretto/amazon-corretto-crypto-provider).
53120

54-
### Download the AWS Encryption SDK for Java
55-
You can get the latest release from Maven:
56-
57-
```xml
58-
<dependency>
59-
<groupId>com.amazonaws</groupId>
60-
<artifactId>aws-encryption-sdk-java</artifactId>
61-
<version>3.0.0</version>
62-
</dependency>
63-
```
64-
65121
### Get Started
66122
To get started with the AWS Encryption SDK for Java
67123

68124
1. Instantiate the AWS Encryption SDK.
69-
2. Define the master key provider.
125+
2. Create a Keyring from the AWS Cryptographic Material Providers Library.
70126
3. Encrypt and decrypt data.
71127

72128
```java
73129
// This sample code encrypts and then decrypts a string using an AWS KMS key.
74130
// You provide the KMS key ARN and plaintext string as arguments.
75131
package com.amazonaws.crypto.examples;
76132

133+
import com.amazonaws.encryptionsdk.AwsCrypto;
134+
import com.amazonaws.encryptionsdk.CommitmentPolicy;
135+
import com.amazonaws.encryptionsdk.CryptoResult;
136+
import software.amazon.cryptography.materialproviders.IKeyring;
137+
import software.amazon.cryptography.materialproviders.MaterialProviders;
138+
import software.amazon.cryptography.materialproviders.model.CreateAwsKmsMultiKeyringInput;
139+
import software.amazon.cryptography.materialproviders.model.MaterialProvidersConfig;
140+
77141
import java.nio.charset.StandardCharsets;
78142
import java.util.Arrays;
79143
import java.util.Collections;
80144
import java.util.Map;
81145

82-
import com.amazonaws.encryptionsdk.AwsCrypto;
83-
import com.amazonaws.encryptionsdk.CommitmentPolicy;
84-
import com.amazonaws.encryptionsdk.CryptoResult;
85-
import com.amazonaws.encryptionsdk.kms.KmsMasterKey;
86-
import com.amazonaws.encryptionsdk.kms.KmsMasterKeyProvider;
87-
88146
public class StringExample {
89147
private static String keyArn;
90148
private static String plaintext;
@@ -95,37 +153,36 @@ public class StringExample {
95153

96154
// Instantiate the SDK
97155
final AwsCrypto crypto = AwsCrypto.standard();
98-
99-
// Set up the master key provider
100-
final KmsMasterKeyProvider prov = KmsMasterKeyProvider.builder().buildStrict(keyArn);
101-
156+
157+
// Create the AWS KMS keyring.
158+
// We create a multi keyring, as this interface creates the KMS client for us automatically.
159+
final MaterialProviders materialProviders = MaterialProviders.builder()
160+
.MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
161+
.build();
162+
final CreateAwsKmsMultiKeyringInput keyringInput =
163+
CreateAwsKmsMultiKeyringInput.builder().generator(keyArn).build();
164+
final IKeyring kmsKeyring = materialProviders.CreateAwsKmsMultiKeyring(keyringInput);
165+
102166
// Set up the encryption context
103167
// NOTE: Encrypted data should have associated encryption context
104168
// to protect its integrity. This example uses placeholder values.
105169
// For more information about the encryption context, see
106170
// https://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/concepts.html#encryption-context
107-
final Map<String, String> context = Collections.singletonMap("ExampleContextKey", "ExampleContextValue");
171+
final Map<String, String> encryptionContext = Collections.singletonMap("ExampleContextKey", "ExampleContextValue");
108172

109173
// Encrypt the data
110-
//
111-
final CryptoResult<byte[], KmsMasterKey> encryptResult = crypto.encryptData(prov, plaintext.getBytes(StandardCharsets.UTF_8), context);
174+
final CryptoResult<byte[], ?> encryptResult = crypto.encryptData(kmsKeyring, plaintext.getBytes(StandardCharsets.UTF_8), encryptionContext);
112175
final byte[] ciphertext = encryptResult.getResult();
113176
System.out.println("Ciphertext: " + Arrays.toString(ciphertext));
114177

115178
// Decrypt the data
116-
final CryptoResult<byte[], KmsMasterKey> decryptResult = crypto.decryptData(prov, ciphertext);
117-
// Your application should verify the encryption context and the KMS key to
118-
// ensure this is the expected ciphertext before returning the plaintext
119-
if (!decryptResult.getMasterKeyIds().get(0).equals(keyArn)) {
120-
throw new IllegalStateException("Wrong key id!");
121-
}
122-
123-
// The AWS Encryption SDK may add information to the encryption context, so check to
124-
// ensure all of the values that you specified when encrypting are *included* in the returned encryption context.
125-
if (!context.entrySet().stream()
126-
.allMatch( e -> e.getValue().equals(decryptResult.getEncryptionContext().get(e.getKey())))) {
127-
throw new IllegalStateException("Wrong Encryption Context!");
128-
}
179+
final CryptoResult<byte[], ?> decryptResult =
180+
crypto.decryptData(
181+
kmsKeyring,
182+
ciphertext,
183+
// Verify that the encryption context in the result contains the
184+
// encryption context supplied to the encryptData method
185+
encryptionContext);
129186

130187
assert Arrays.equals(decryptResult.getResult(), plaintext.getBytes(StandardCharsets.UTF_8));
131188

0 commit comments

Comments
 (0)