Skip to content

Commit 015fc3c

Browse files
WesleyRosenblumWesleyRosenblum
authored
Merge pull request #173 from aws/keyring
Merge keyring branch into master
2 parents dcbc562 + 5cf7e0c commit 015fc3c

File tree

129 files changed

+11008
-1149
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

129 files changed

+11008
-1149
lines changed

‎README.md

+4-70
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
# AWS Encryption SDK for Java
22

3-
The AWS Encryption SDK enables secure client-side encryption. It uses cryptography best practices to protect your data and the encryption keys used to protect that data. Each data object is protected with a unique data encryption key (DEK), and the DEK is protected with a key encryption key (KEK) called a *master key*. The encrypted DEK is combined with the encrypted data into a single [encrypted message](https://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/message-format.html), so you don't need to keep track of the DEKs for your data. The SDK supports master keys in [AWS Key Management Service](https://aws.amazon.com/kms/) (KMS), and it also provides APIs to define and use other master key providers. The SDK provides methods for encrypting and decrypting strings, byte arrays, and byte streams. For details, see the [example code][examples] and the [Javadoc](https://aws.github.io/aws-encryption-sdk-java/javadoc/).
3+
The AWS Encryption SDK is a client-side encryption library designed to make it easy for everyone to encrypt and decrypt data using industry standards and best practices. It enables you to focus on the core functionality of your application, rather than on how to best encrypt and decrypt your data.
44

5-
For more details about the design and architecture of the SDK, see the [official documentation](https://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/).
5+
For details about the design, architecture and usage of the SDK, see the [official documentation](https://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/), [example code][examples] and the [Javadoc](https://aws.github.io/aws-encryption-sdk-java/javadoc/).
66

77
## Getting Started
88

@@ -58,75 +58,9 @@ You can get the latest release from Maven:
5858
</dependency>
5959
```
6060

61-
### Get Started
62-
63-
The following code sample demonstrates how to get started:
64-
65-
1. Instantiate the SDK.
66-
2. Define the master key provider.
67-
3. Encrypt and decrypt data.
68-
69-
```java
70-
// This sample code encrypts and then decrypts a string using a KMS CMK.
71-
// You provide the KMS key ARN and plaintext string as arguments.
72-
package com.amazonaws.crypto.examples;
73-
74-
import java.util.Collections;
75-
import java.util.Map;
76-
77-
import com.amazonaws.encryptionsdk.AwsCrypto;
78-
import com.amazonaws.encryptionsdk.CryptoResult;
79-
import com.amazonaws.encryptionsdk.kms.KmsMasterKey;
80-
import com.amazonaws.encryptionsdk.kms.KmsMasterKeyProvider;
81-
82-
public class StringExample {
83-
private static String keyArn;
84-
private static String data;
85-
86-
public static void main(final String[] args) {
87-
keyArn = args[0];
88-
data = args[1];
89-
90-
// Instantiate the SDK
91-
final AwsCrypto crypto = new AwsCrypto();
92-
93-
// Set up the master key provider
94-
final KmsMasterKeyProvider prov = new KmsMasterKeyProvider(keyArn);
95-
96-
// Encrypt the data
97-
//
98-
// NOTE: Encrypted data should have associated encryption context
99-
// to protect integrity. For this example, just use a placeholder
100-
// value. For more information about encryption context, see
101-
// https://amzn.to/1nSbe9X (blogs.aws.amazon.com)
102-
final Map<String, String> context = Collections.singletonMap("Example", "String");
103-
104-
final String ciphertext = crypto.encryptString(prov, data, context).getResult();
105-
System.out.println("Ciphertext: " + ciphertext);
106-
107-
// Decrypt the data
108-
final CryptoResult<String, KmsMasterKey> decryptResult = crypto.decryptString(prov, ciphertext);
109-
// Check the encryption context (and ideally the master key) to
110-
// ensure this is the expected ciphertext
111-
if (!decryptResult.getMasterKeyIds().get(0).equals(keyArn)) {
112-
throw new IllegalStateException("Wrong key id!");
113-
}
114-
115-
// The SDK may add information to the encryption context, so check to
116-
// ensure all of the values are present
117-
for (final Map.Entry<String, String> e : context.entrySet()) {
118-
if (!e.getValue().equals(decryptResult.getEncryptionContext().get(e.getKey()))) {
119-
throw new IllegalStateException("Wrong Encryption Context!");
120-
}
121-
}
122-
123-
// The data is correct, so output it.
124-
System.out.println("Decrypted: " + decryptResult.getResult());
125-
}
126-
}
127-
```
61+
### Sample Code
12862

129-
You can find more examples in the [examples directory][examples].
63+
You can find sample code in the [examples directory][examples].
13064

13165
## Public API
13266

‎pom.xml

+57-17
Original file line numberDiff line numberDiff line change
@@ -42,7 +42,7 @@
4242
<dependency>
4343
<groupId>com.amazonaws</groupId>
4444
<artifactId>aws-java-sdk</artifactId>
45-
<version>1.11.561</version>
45+
<version>1.11.677</version>
4646
<optional>true</optional>
4747
</dependency>
4848

@@ -53,16 +53,23 @@
5353
</dependency>
5454

5555
<dependency>
56-
<groupId>org.mockito</groupId>
57-
<artifactId>mockito-core</artifactId>
58-
<version>2.28.1</version>
56+
<groupId>org.junit.jupiter</groupId>
57+
<artifactId>junit-jupiter</artifactId>
58+
<version>5.5.2</version>
59+
<scope>test</scope>
60+
</dependency>
61+
62+
<dependency>
63+
<groupId>org.junit.vintage</groupId>
64+
<artifactId>junit-vintage-engine</artifactId>
65+
<version>5.5.2</version>
5966
<scope>test</scope>
6067
</dependency>
6168

6269
<dependency>
63-
<groupId>junit</groupId>
64-
<artifactId>junit</artifactId>
65-
<version>4.12</version>
70+
<groupId>org.mockito</groupId>
71+
<artifactId>mockito-junit-jupiter</artifactId>
72+
<version>3.1.0</version>
6673
<scope>test</scope>
6774
</dependency>
6875

@@ -73,6 +80,19 @@
7380
<scope>test</scope>
7481
</dependency>
7582

83+
<dependency>
84+
<groupId>com.amazonaws</groupId>
85+
<artifactId>aws-lambda-java-core</artifactId>
86+
<version>1.2.0</version>
87+
<scope>test</scope>
88+
</dependency>
89+
90+
<dependency>
91+
<groupId>com.amazonaws</groupId>
92+
<artifactId>aws-lambda-java-events</artifactId>
93+
<version>2.2.7</version>
94+
<scope>test</scope>
95+
</dependency>
7696

7797
<dependency>
7898
<groupId>com.google.code.findbugs</groupId>
@@ -190,7 +210,7 @@
190210
</profile>
191211

192212
<profile>
193-
<id>full-test-suite</id>
213+
<id>test-suite</id>
194214
<activation>
195215
<activeByDefault>true</activeByDefault>
196216
</activation>
@@ -201,30 +221,50 @@
201221
<artifactId>maven-surefire-plugin</artifactId>
202222
<version>2.22.0</version>
203223
<configuration>
204-
<includes>
205-
<include>**/AllTestsSuite.java</include>
206-
</includes>
224+
<excludedGroups>ad_hoc</excludedGroups>
207225
</configuration>
208226
</plugin>
209227
</plugins>
210228
</build>
211229
</profile>
212230

231+
<!-- This test profile is intended to assist in rapid development; it filters out some of the slower,
232+
more exhaustive tests in the overall test suite to allow for a rapid edit-test cycle. -->
213233
<profile>
214234
<id>fast-tests-only</id>
215-
<activation>
216-
<activeByDefault>false</activeByDefault>
217-
</activation>
218235
<build>
219236
<plugins>
220237
<plugin>
221238
<groupId>org.apache.maven.plugins</groupId>
222239
<artifactId>maven-surefire-plugin</artifactId>
223240
<version>2.22.0</version>
224241
<configuration>
225-
<includes>
226-
<include>**/FastTestsOnlySuite.java</include>
227-
</includes>
242+
<excludedGroups>ad_hoc, integration</excludedGroups>
243+
<systemPropertyVariables>
244+
<fastTestsOnly>true</fastTestsOnly>
245+
</systemPropertyVariables>
246+
<!-- Require that this fast suite completes relatively quickly. If you're seeing
247+
this timeout get hit, it's time to pare down tests some more. As a general rule of
248+
thumb, we should avoid any single test taking more than 10s, and try to keep the
249+
number of such slow tests to a minimum. -->
250+
<forkedProcessTimeoutInSeconds>120</forkedProcessTimeoutInSeconds>
251+
</configuration>
252+
</plugin>
253+
</plugins>
254+
</build>
255+
</profile>
256+
257+
<!-- This test profile will run only the integration tests. -->
258+
<profile>
259+
<id>integration</id>
260+
<build>
261+
<plugins>
262+
<plugin>
263+
<groupId>org.apache.maven.plugins</groupId>
264+
<artifactId>maven-surefire-plugin</artifactId>
265+
<version>2.22.0</version>
266+
<configuration>
267+
<groups>integration</groups>
228268
</configuration>
229269
</plugin>
230270
</plugins>

‎src/examples/README.md

+126
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,126 @@
1+
# AWS Encryption SDK Examples
2+
3+
This section features examples that show you
4+
how to use the AWS Encryption SDK.
5+
We demonstrate how to use the encryption and decryption APIs
6+
and how to set up some common configuration patterns.
7+
8+
## APIs
9+
10+
The AWS Encryption SDK provides two high-level APIs:
11+
one-step APIs that process the entire operation in memory
12+
and streaming APIs.
13+
14+
You can find examples that demonstrate these APIs
15+
in the [`examples`](./java/com/amazonaws/crypto/examples) directory.
16+
17+
## Configuration
18+
19+
To use the encryption and decryption APIs,
20+
you need to describe how you want the library to protect your data keys.
21+
You can do this by configuring
22+
[keyrings](#keyrings) or [cryptographic materials managers](#cryptographic-materials-managers),
23+
or by configuring [master key providers](#master-key-providers).
24+
These examples will show you how to use the configuration tools that we include for you
25+
and how to create some of your own.
26+
We start with AWS KMS examples, then show how to use other wrapping keys.
27+
28+
* Using AWS Key Management Service (AWS KMS)
29+
* How to use one AWS KMS CMK
30+
* [with keyrings](./java/com/amazonaws/crypto/examples/keyring/awskms/SingleCmk.java)
31+
* [with master key providers](./java/com/amazonaws/crypto/examples/masterkeyprovider/awskms/SingleCmk.java)
32+
* How to use multiple AWS KMS CMKs in different regions
33+
* [with keyrings](./java/com/amazonaws/crypto/examples/keyring/awskms/MultipleRegions.java)
34+
* [with master key providers](./java/com/amazonaws/crypto/examples/masterkeyprovider/awskms/MultipleRegions.java)
35+
* How to decrypt when you don't know the CMK
36+
* [with keyrings](./java/com/amazonaws/crypto/examples/keyring/awskms/DiscoveryDecrypt.java)
37+
* [with master key providers](./java/com/amazonaws/crypto/examples/masterkeyprovider/awskms/DiscoveryDecrypt.java)
38+
* How to decrypt within a region
39+
* [with keyrings](./java/com/amazonaws/crypto/examples/keyring/awskms/DiscoveryDecryptInRegionOnly.java)
40+
* How to decrypt with a preferred region but failover to others
41+
* [with keyrings](./java/com/amazonaws/crypto/examples/keyring/awskms/DiscoveryDecryptWithPreferredRegions.java)
42+
* Using raw wrapping keys
43+
* How to use a raw AES wrapping key
44+
* [with keyrings](./java/com/amazonaws/crypto/examples/keyring/rawaes/RawAes.java)
45+
* [with master key providers](./java/com/amazonaws/crypto/examples/masterkeyprovider/rawaes/RawAes.java)
46+
* How to use a raw RSA wrapping key
47+
* [with keyrings](./java/com/amazonaws/crypto/examples/keyring/rawrsa/RawRsa.java)
48+
* [with master key providers](./java/com/amazonaws/crypto/examples/masterkeyprovider/rawrsa/RawRsa.java)
49+
* How to encrypt with a raw RSA public key wrapping key without access to the private key
50+
* [with keyrings](./java/com/amazonaws/crypto/examples/keyring/rawrsa/PublicPrivateKeySeparate.java)
51+
* How to use a raw RSA wrapping key when the key is DER encoded
52+
* [with keyrings](./java/com/amazonaws/crypto/examples/keyring/rawrsa/RawRsaDerEncoded.java)
53+
* Combining wrapping keys
54+
* How to combine AWS KMS with an offline escrow key
55+
* [with keyrings](./java/com/amazonaws/crypto/examples/keyring/multi/AwsKmsWithEscrow.java)
56+
* [with master key providers](./java/com/amazonaws/crypto/examples/masterkeyprovider/multi/AwsKmsWithEscrow.java)
57+
* How to reuse data keys across multiple messages
58+
* [with the caching cryptographic materials manager](./java/com/amazonaws/crypto/examples/cryptomaterialsmanager/caching/SimpleCache.java)
59+
* How to restrict algorithm suites
60+
* [with a custom cryptographic materials manager](./java/com/amazonaws/crypto/examples/cryptomaterialsmanager/custom/AlgorithmSuiteEnforcement.java)
61+
* How to require encryption context fields
62+
* [with a custom cryptographic materials manager](./java/com/amazonaws/crypto/examples/cryptomaterialsmanager/custom/RequiringEncryptionContextFields.java)
63+
64+
### Keyrings
65+
66+
Keyrings are the most common way for you to configure the AWS Encryption SDK.
67+
They determine how the AWS Encryption SDK protects your data.
68+
You can find these examples in ['examples/keyring`](./java/com/amazonaws/crypto/examples/keyring).
69+
70+
### Cryptographic Materials Managers
71+
72+
Keyrings define how your data keys are protected,
73+
but there is more going on here than just protecting data keys.
74+
75+
Cryptographic materials managers give you higher-level controls
76+
over how the AWS Encryption SDK protects your data.
77+
This can include things like
78+
enforcing the use of certain algorithm suites or encryption context settings,
79+
reusing data keys across messages,
80+
or changing how you interact with keyrings.
81+
You can find these examples in
82+
[`examples/crypto_materials_manager`](./java/com/amazonaws/crypto/examples/cryptomaterialsmanager).
83+
84+
### Master Key Providers
85+
86+
Before there were keyrings, there were master key providers.
87+
Master key providers were the original configuration structure
88+
that we provided for defining how you want to protect your data keys.
89+
Keyrings provide a simpler experience and often more powerful configuration options,
90+
but if you need to use master key providers,
91+
need help migrating from master key providers to keyrings,
92+
or simply want to see the difference between these configuration experiences,
93+
you can find these examples in [`examples/masterkeyprovider`](./java/com/amazonaws/crypto/examples/masterkeyprovider).
94+
95+
## Legacy
96+
97+
This section includes older examples,
98+
including examples of using master keys and master key providers.
99+
You can use them as a reference,
100+
but we recommend looking at the newer examples, which explain the preferred ways of using this library.
101+
You can find these examples in [`examples/legacy`](./java/com/amazonaws/crypto/examples/legacy).
102+
103+
# Writing Examples
104+
105+
If you want to contribute a new example, that's awesome!
106+
To make sure that your example is tested in our CI,
107+
please make sure that it meets the following requirements:
108+
109+
1. The example MUST be a distinct class in the [`examples`](./java/com/amazonaws/crypto/examples) directory.
110+
1. Each example file MUST contain exactly one example.
111+
1. Each example file MUST contain a static method called `run` that runs the example.
112+
1. If your `run` method needs any of the following inputs,
113+
the parameters MUST have the following types:
114+
* `com.amazonaws.encryptionsdk.kms.AwsKmsCmkId` : A single AWS KMS CMK ARN.
115+
* NOTE: You can assume that automatically discovered credentials have
116+
`kms:GenerateDataKey`, `kms:Encrypt`, and `kms:Decrypt` permissions on this CMK.
117+
* `List<com.amazonaws.encryptionsdk.kms.AwsKmsCmkId>` :
118+
A list of AWS KMS CMK ARNs to use for encrypting and decrypting data keys.
119+
* NOTE: You can assume that automatically discovered credentials have
120+
`kms:Encrypt` and `kms:Decrypt` permissions on these CMKs.
121+
* `byte[]` : Plaintext data to encrypt.
122+
* `java.io.File` : A path to a file containing plaintext to encrypt.
123+
* NOTE: You can assume that you have write access to the parent directory
124+
and that anything you do in that directory will be cleaned up
125+
by our test runners.
126+
1. Any additional parameters MUST be optional and nullable and not of the same type as the above parameters.

0 commit comments

Comments
 (0)