Skip to content

Commit e9a2a51

Browse files
lucasmcdonald3lucasmcdonald3
authored
feat(Examples): Create KMS RSA keyring example (#188)
1 parent 2654cba commit e9a2a51

File tree

4 files changed

+325
-3
lines changed

4 files changed

+325
-3
lines changed

‎Examples/runtimes/java/DynamoDbEncryption/src/main/java/software/amazon/cryptography/examples/keyring/KmsRsaKeyringExample.java

Lines changed: 298 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,298 @@
1+
package software.amazon.cryptography.examples.keyring;
2+
3+
import java.io.File;
4+
import java.io.FileNotFoundException;
5+
import java.io.FileOutputStream;
6+
import java.io.IOException;
7+
import java.io.StringWriter;
8+
import java.nio.ByteBuffer;
9+
import java.nio.channels.FileChannel;
10+
import java.nio.charset.StandardCharsets;
11+
import java.nio.file.Files;
12+
import java.nio.file.Paths;
13+
import java.util.HashMap;
14+
import java.util.Map;
15+
import org.bouncycastle.util.io.pem.PemObject;
16+
import org.bouncycastle.util.io.pem.PemWriter;
17+
import software.amazon.awssdk.core.client.config.ClientOverrideConfiguration;
18+
import software.amazon.awssdk.services.dynamodb.DynamoDbClient;
19+
import software.amazon.awssdk.services.dynamodb.model.AttributeValue;
20+
import software.amazon.awssdk.services.dynamodb.model.GetItemRequest;
21+
import software.amazon.awssdk.services.dynamodb.model.GetItemResponse;
22+
import software.amazon.awssdk.services.dynamodb.model.PutItemRequest;
23+
import software.amazon.awssdk.services.dynamodb.model.PutItemResponse;
24+
import software.amazon.awssdk.services.kms.KmsClient;
25+
import software.amazon.awssdk.services.kms.model.EncryptionAlgorithmSpec;
26+
import software.amazon.awssdk.services.kms.model.GetPublicKeyRequest;
27+
import software.amazon.awssdk.services.kms.model.GetPublicKeyResponse;
28+
import software.amazon.cryptography.dbencryptionsdk.dynamodb.DynamoDbEncryptionInterceptor;
29+
import software.amazon.cryptography.dbencryptionsdk.dynamodb.model.DynamoDbTableEncryptionConfig;
30+
import software.amazon.cryptography.dbencryptionsdk.dynamodb.model.DynamoDbTablesEncryptionConfig;
31+
import software.amazon.cryptography.dbencryptionsdk.structuredencryption.model.CryptoAction;
32+
import software.amazon.cryptography.materialproviders.IKeyring;
33+
import software.amazon.cryptography.materialproviders.MaterialProviders;
34+
import software.amazon.cryptography.materialproviders.model.CreateAwsKmsRsaKeyringInput;
35+
import software.amazon.cryptography.materialproviders.model.DBEAlgorithmSuiteId;
36+
import software.amazon.cryptography.materialproviders.model.MaterialProvidersConfig;
37+
38+
/*
39+
This example sets up DynamoDb Encryption for the AWS SDK client
40+
using the KMS RSA Keyring. This keyring uses a KMS RSA key pair to
41+
encrypt and decrypt records. The client uses the downloaded public key
42+
to encrypt items it adds to the table.
43+
The keyring uses the private key to decrypt existing table items it retrieves,
44+
by calling KMS' decrypt API.
45+
46+
Running this example requires access to the DDB Table whose name
47+
is provided in CLI arguments.
48+
This table must be configured with the following
49+
primary key configuration:
50+
- Partition key is named "partition_key" with type (S)
51+
- Sort key is named "sort_key" with type (S)
52+
This example also requires access to a KMS RSA key.
53+
Our tests provide a KMS RSA ARN that anyone can use, but you
54+
can also provide your own KMS RSA key.
55+
To use your own KMS RSA key, you must have either:
56+
- Its public key downloaded in a UTF-8 encoded PEM file
57+
- kms:GetPublicKey permissions on that key
58+
If you do not have the public key downloaded, running this example
59+
through its main method will download the public key for you
60+
by calling kms:GetPublicKey.
61+
You must also have kms:Decrypt permissions on the KMS RSA key.
62+
*/
63+
public class KmsRsaKeyringExample {
64+
65+
private static String DEFAULT_EXAMPLE_RSA_PUBLIC_KEY_FILENAME = "KmsRsaKeyringExamplePublicKey.pem";
66+
67+
public static void KmsRsaKeyringGetItemPutItem(String ddbTableName, String rsaKeyArn,
68+
String rsaPublicKeyFilename) {
69+
// 1. Load UTF-8 encoded public key PEM file.
70+
// You may have an RSA public key file already defined.
71+
// If not, the main method in this class will call
72+
// the KMS RSA key, retrieve its public key, and store it
73+
// in a PEM file for example use.
74+
ByteBuffer publicKeyUtf8EncodedByteBuffer;
75+
try {
76+
publicKeyUtf8EncodedByteBuffer = ByteBuffer.wrap(
77+
Files.readAllBytes(Paths.get(rsaPublicKeyFilename)));
78+
} catch (IOException e) {
79+
throw new RuntimeException("IOException while reading public key from file", e);
80+
}
81+
82+
// 2. Create a KMS RSA keyring.
83+
// This keyring takes in:
84+
// - kmsClient
85+
// - kmsKeyId: Must be an ARN representing a KMS RSA key
86+
// - publicKey: A ByteBuffer of a UTF-8 encoded PEM file representing the public
87+
// key for the key passed into kmsKeyId
88+
// - encryptionAlgorithm: Must be either RSAES_OAEP_SHA_256 or RSAES_OAEP_SHA_1
89+
final MaterialProviders matProv = MaterialProviders.builder()
90+
.MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
91+
.build();
92+
final CreateAwsKmsRsaKeyringInput createAwsKmsRsaKeyringInput =
93+
CreateAwsKmsRsaKeyringInput.builder()
94+
.kmsClient(KmsClient.create())
95+
.kmsKeyId(rsaKeyArn)
96+
.publicKey(publicKeyUtf8EncodedByteBuffer)
97+
.encryptionAlgorithm(EncryptionAlgorithmSpec.RSAES_OAEP_SHA_256)
98+
.build();
99+
IKeyring awsKmsRsaKeyring = matProv.CreateAwsKmsRsaKeyring(createAwsKmsRsaKeyringInput);
100+
101+
// 3. Configure which attributes are encrypted and/or signed when writing new items.
102+
// For each attribute that may exist on the items we plan to write to our DynamoDbTable,
103+
// we must explicitly configure how they should be treated during item encryption:
104+
// - ENCRYPT_AND_SIGN: The attribute is encrypted and included in the signature
105+
// - SIGN_ONLY: The attribute not encrypted, but is still included in the signature
106+
// - DO_NOTHING: The attribute is not encrypted and not included in the signature
107+
final Map<String, CryptoAction> attributeActions = new HashMap<>();
108+
attributeActions.put("partition_key", CryptoAction.SIGN_ONLY); // Our partition attribute must be SIGN_ONLY
109+
attributeActions.put("sort_key", CryptoAction.SIGN_ONLY); // Our sort attribute must be SIGN_ONLY
110+
attributeActions.put("sensitive_data", CryptoAction.ENCRYPT_AND_SIGN);
111+
112+
// 4. Configure which attributes we expect to be included in the signature
113+
// when reading items. There are two options for configuring this:
114+
//
115+
// - (Recommended) Configure `allowedUnauthenticatedAttributesPrefix`:
116+
// When defining your DynamoDb schema and deciding on attribute names,
117+
// choose a distinguishing prefix (such as ":") for all attributes that
118+
// you do not want to include in the signature.
119+
// This has two main benefits:
120+
// - It is easier to reason about the security and authenticity of data within your item
121+
// when all unauthenticated data is easily distinguishable by their attribute name.
122+
// - If you need to add new unauthenticated attributes in the future,
123+
// you can easily make the corresponding update to your `attributeActions`
124+
// and immediately start writing to that new attribute, without
125+
// any other configuration update needed.
126+
// Once you configure this field, it is not safe to update it.
127+
//
128+
// - Configure `allowedUnauthenticatedAttributes`: You may also explicitly list
129+
// a set of attributes that should be considered unauthenticated when encountered
130+
// on read. Be careful if you use this configuration. Do not remove an attribute
131+
// name from this configuration, even if you are no longer writing with that attribute,
132+
// as old items may still include this attribute, and our configuration needs to know
133+
// to continue to exclude this attribute from the signature scope.
134+
// If you add new attribute names to this field, you must first deploy the update to this
135+
// field to all readers in your host fleet before deploying the update to start writing
136+
// with that new attribute.
137+
//
138+
// For this example, we currently authenticate all attributes. To make it easier to
139+
// add unauthenticated attributes in the future, we define a prefix ":" for such attributes.
140+
final String unauthAttrPrefix = ":";
141+
142+
// 5. Create the DynamoDb Encryption configuration for the table we will be writing to.
143+
// Note: To use the KMS RSA keyring, your table config must specify an algorithmSuite
144+
// that does not use asymmetric signing.
145+
final Map<String, DynamoDbTableEncryptionConfig> tableConfigs = new HashMap<>();
146+
final DynamoDbTableEncryptionConfig config = DynamoDbTableEncryptionConfig.builder()
147+
.logicalTableName(ddbTableName)
148+
.partitionKeyName("partition_key")
149+
.sortKeyName("sort_key")
150+
.attributeActions(attributeActions)
151+
.keyring(awsKmsRsaKeyring)
152+
.allowedUnauthenticatedAttributePrefix(unauthAttrPrefix)
153+
// Specify algorithmSuite without asymmetric signing here
154+
// As of v3.0.0, the only supported algorithmSuite without asymmetric signing is
155+
// ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY_SYMSIG_HMAC_SHA384.
156+
.algorithmSuiteId(DBEAlgorithmSuiteId.ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY_SYMSIG_HMAC_SHA384)
157+
.build();
158+
tableConfigs.put(ddbTableName, config);
159+
160+
// 6. Create the DynamoDb Encryption Interceptor
161+
DynamoDbEncryptionInterceptor encryptionInterceptor = DynamoDbEncryptionInterceptor.builder()
162+
.config(DynamoDbTablesEncryptionConfig.builder()
163+
.tableEncryptionConfigs(tableConfigs)
164+
.build())
165+
.build();
166+
167+
// 7. Create a new AWS SDK DynamoDb client using the DynamoDb Encryption Interceptor above
168+
final DynamoDbClient ddbClient = DynamoDbClient.builder()
169+
.overrideConfiguration(
170+
ClientOverrideConfiguration.builder()
171+
.addExecutionInterceptor(encryptionInterceptor)
172+
.build())
173+
.build();
174+
175+
// 8. Put an item into our table using the above client.
176+
// Before the item gets sent to DynamoDb, it will be encrypted
177+
// client-side, according to our configuration.
178+
final HashMap<String, AttributeValue> item = new HashMap<>();
179+
item.put("partition_key", AttributeValue.builder().s("awsKmsRsaKeyringItem").build());
180+
item.put("sort_key", AttributeValue.builder().n("0").build());
181+
item.put("sensitive_data", AttributeValue.builder().s("encrypt and sign me!").build());
182+
183+
final PutItemRequest putRequest = PutItemRequest.builder()
184+
.tableName(ddbTableName)
185+
.item(item)
186+
.build();
187+
188+
final PutItemResponse putResponse = ddbClient.putItem(putRequest);
189+
190+
// Demonstrate that PutItem succeeded
191+
assert 200 == putResponse.sdkHttpResponse().statusCode();
192+
193+
// 9. Get the item back from our table using the client.
194+
// The client will decrypt the item client-side using the RSA keyring
195+
// and return the original item.
196+
final HashMap<String, AttributeValue> keyToGet = new HashMap<>();
197+
keyToGet.put("partition_key", AttributeValue.builder().s("awsKmsRsaKeyringItem").build());
198+
keyToGet.put("sort_key", AttributeValue.builder().n("0").build());
199+
200+
final GetItemRequest getRequest = GetItemRequest.builder()
201+
.key(keyToGet)
202+
.tableName(ddbTableName)
203+
.build();
204+
205+
final GetItemResponse getResponse = ddbClient.getItem(getRequest);
206+
207+
// Demonstrate that GetItem succeeded and returned the decrypted item
208+
assert 200 == getResponse.sdkHttpResponse().statusCode();
209+
final Map<String, AttributeValue> returnedItem = getResponse.item();
210+
assert returnedItem.get("sensitive_data").s().equals("encrypt and sign me!");
211+
}
212+
213+
public static void KmsRsaKeyringGetItemPutItem(String ddbTableName, String rsaKeyArn) {
214+
KmsRsaKeyringGetItemPutItem(ddbTableName, rsaKeyArn, DEFAULT_EXAMPLE_RSA_PUBLIC_KEY_FILENAME);
215+
}
216+
217+
public static void main(final String[] args) {
218+
if (args.length <= 1) {
219+
throw new IllegalArgumentException("To run this example, include the ddbTable and rsaKeyArn in args; optionally include rsaPublicKeyFilename");
220+
}
221+
final String ddbTableName = args[0];
222+
final String rsaKeyArn = args[1];
223+
String rsaPublicKeyFilename;
224+
if (args.length == 3) {
225+
rsaPublicKeyFilename = args[2];
226+
} else {
227+
rsaPublicKeyFilename = DEFAULT_EXAMPLE_RSA_PUBLIC_KEY_FILENAME;
228+
}
229+
230+
// You may provide your own RSA public key at EXAMPLE_RSA_PUBLIC_KEY_FILENAME.
231+
// This must be the public key for the RSA key represented at rsaKeyArn.
232+
// If this file is not present, this will write a UTF-8 encoded PEM file for you.
233+
if (shouldGetNewPublicKey(rsaPublicKeyFilename)) {
234+
writePublicKeyPemForRsaKey(rsaKeyArn, rsaPublicKeyFilename);
235+
}
236+
237+
KmsRsaKeyringGetItemPutItem(ddbTableName, rsaKeyArn, rsaPublicKeyFilename);
238+
}
239+
240+
static boolean shouldGetNewPublicKey() {
241+
return shouldGetNewPublicKey(DEFAULT_EXAMPLE_RSA_PUBLIC_KEY_FILENAME);
242+
}
243+
244+
static boolean shouldGetNewPublicKey(String rsaPublicKeyFilename) {
245+
// Check if a public key file already exists
246+
File publicKeyFile = new File(rsaPublicKeyFilename);
247+
248+
// If a public key file already exists: do not overwrite existing file
249+
if (publicKeyFile.exists()) {
250+
return false;
251+
}
252+
253+
// If file is not present, generate a new key pair
254+
return true;
255+
}
256+
257+
static void writePublicKeyPemForRsaKey(String rsaKeyArn) {
258+
writePublicKeyPemForRsaKey(rsaKeyArn, DEFAULT_EXAMPLE_RSA_PUBLIC_KEY_FILENAME);
259+
}
260+
261+
static void writePublicKeyPemForRsaKey(String rsaKeyArn, String rsaPublicKeyFilename) {
262+
// Safety check: Validate file is not present
263+
File publicKeyFile = new File(rsaPublicKeyFilename);
264+
if (publicKeyFile.exists()) {
265+
throw new IllegalStateException("getRsaPublicKey will not overwrite existing PEM files");
266+
}
267+
268+
// This code will call KMS to get the public key for the KMS RSA key.
269+
// You must have kms:GetPublicKey permissions on the key for this to succeed.
270+
// The public key will be written to the file EXAMPLE_RSA_PUBLIC_KEY_FILENAME.
271+
KmsClient getterForPublicKey = KmsClient.create();
272+
GetPublicKeyResponse response = getterForPublicKey.getPublicKey(GetPublicKeyRequest.builder()
273+
.keyId(rsaKeyArn)
274+
.build());
275+
byte[] publicKeyByteArray = response.publicKey().asByteArray();
276+
277+
StringWriter publicKeyStringWriter = new StringWriter();
278+
PemWriter publicKeyPemWriter = new PemWriter(publicKeyStringWriter);
279+
try {
280+
publicKeyPemWriter.writeObject(
281+
new PemObject("PUBLIC KEY", publicKeyByteArray));
282+
publicKeyPemWriter.close();
283+
} catch (IOException e) {
284+
throw new RuntimeException("IOException while writing public key PEM", e);
285+
}
286+
ByteBuffer publicKeyUtf8EncodedByteBufferToWrite = StandardCharsets.UTF_8.encode(publicKeyStringWriter.toString());
287+
288+
try {
289+
FileChannel fc = new FileOutputStream(rsaPublicKeyFilename).getChannel();
290+
fc.write(publicKeyUtf8EncodedByteBufferToWrite);
291+
fc.close();
292+
} catch (FileNotFoundException e) {
293+
throw new RuntimeException("FileNotFoundException while opening public key FileChannel", e);
294+
} catch (IOException e) {
295+
throw new RuntimeException("IOException while writing public key or closing FileChannel", e);
296+
}
297+
}
298+
}

‎Examples/runtimes/java/DynamoDbEncryption/src/main/java/software/amazon/cryptography/examples/keyring/RawRsaKeyringExample.java

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -39,8 +39,8 @@
3939
This example sets up DynamoDb Encryption for the AWS SDK client
4040
using the raw RSA Keyring. This keyring uses an RSA key pair to
4141
encrypt and decrypt records. This keyring accepts PEM encodings of
42-
the key pair as UTF-8 interpreted bytes. The client uses the private key
43-
to encrypt items it adds to the table and uses the public key to decrypt
42+
the key pair as UTF-8 interpreted bytes. The client uses the public key
43+
to encrypt items it adds to the table and uses the private key to decrypt
4444
existing table items it retrieves.
4545
4646
This example loads a key pair from PEM files with paths defined in

‎Examples/runtimes/java/DynamoDbEncryption/src/test/java/software/amazon/cryptography/examples/TestUtils.java

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,10 +10,10 @@ public class TestUtils {
1010
// These are public KMS Keys that MUST only be used for testing, and MUST NOT be used for any production data
1111
public static final String TEST_KMS_KEY_ID = "arn:aws:kms:us-west-2:658956600833:key/b3537ef1-d8dc-4780-9f5a-55776cbb2f7f";
1212
public static final String TEST_MRK_KEY_ID = "arn:aws:kms:us-west-2:658956600833:key/mrk-80bd8ecdcd4342aebd84b7dc9da498a7";
13+
public static final String TEST_KMS_RSA_KEY_ID = "arn:aws:kms:us-west-2:658956600833:key/8b432da4-dde4-4bc3-a794-c7d68cbab5a6";
1314
public static final String TEST_MRK_REPLICA_KEY_ID_US_EAST_1 = "arn:aws:kms:us-east-1:658956600833:key/mrk-80bd8ecdcd4342aebd84b7dc9da498a7";
1415
public static final String TEST_MRK_REPLICA_KEY_ID_EU_WEST_1 = "arn:aws:kms:eu-west-1:658956600833:key/mrk-80bd8ecdcd4342aebd84b7dc9da498a7";
1516

16-
1717
// Our tests require access to DDB Table with this name
1818
public static final String TEST_DDB_TABLE_NAME = "DynamoDbEncryptionInterceptorTestTable";
1919
}

‎Examples/runtimes/java/DynamoDbEncryption/src/test/java/software/amazon/cryptography/examples/keyring/TestKmsRsaKeyringExample.java

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
package software.amazon.cryptography.examples.keyring;
2+
3+
import software.amazon.cryptography.examples.TestUtils;
4+
5+
import static software.amazon.cryptography.examples.keyring.KmsRsaKeyringExample.shouldGetNewPublicKey;
6+
import static software.amazon.cryptography.examples.keyring.KmsRsaKeyringExample.writePublicKeyPemForRsaKey;
7+
8+
import org.testng.annotations.Test;
9+
10+
public class TestKmsRsaKeyringExample {
11+
@Test
12+
public void TestKmsRsaKeyringExample() {
13+
// You may provide your own RSA public key at EXAMPLE_RSA_PUBLIC_KEY_FILENAME.
14+
// This must be the public key for the RSA key represented at rsaKeyArn.
15+
// If this file is not present, this will write a UTF-8 encoded PEM file for you.
16+
if (shouldGetNewPublicKey()) {
17+
writePublicKeyPemForRsaKey(TestUtils.TEST_KMS_RSA_KEY_ID);
18+
}
19+
20+
software.amazon.cryptography.examples.keyring.KmsRsaKeyringExample.KmsRsaKeyringGetItemPutItem(
21+
TestUtils.TEST_DDB_TABLE_NAME,
22+
TestUtils.TEST_KMS_RSA_KEY_ID);
23+
}
24+
}

0 commit comments

Comments
 (0)