From 19e704148725f7b485cadc9a2a11c58baaca1e64 Mon Sep 17 00:00:00 2001 From: Lucas McDonald Date: Fri, 26 May 2023 09:21:54 -0700 Subject: [PATCH 01/18] work --- README.md | 50 ++++++++++++++++++++++++++++++++++++++++++++-- SUPPORT_POLICY.rst | 29 +++++++++++++++++++++++++++ 2 files changed, 77 insertions(+), 2 deletions(-) create mode 100644 SUPPORT_POLICY.rst diff --git a/README.md b/README.md index 6c02fe7a6..077c554f7 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,52 @@ -## DynamoDB Encryption Client for Dafny +## AWS Database Encryption SDK for DynamoDB in Java -TODO landing page info for the DDBEC. +The AWS Database Encryption SDK for DynamoDB in Java +provides client-side encryption and signing of Amazon DynamoDB items +to help you protect your table's data before you send it to DynamoDB. + +For more details about the design and architecture of the AWS Database Encryption SDK for DynamoDB, see the [AWS Database Encryption SDK Developer Guide](https://docs.aws.amazon.com/database-encryption-sdk/latest/devguide/). + +[Security issue notifications](./CONTRIBUTING.md#security-issue-notifications) + +See [Support Policy](./SUPPORT_POLICY.rst) for details on the current support status of all major versions of this library. + +## Getting Started + +### Required Prerequisites +To use the DB ESDK for DynamoDB in Java, you must have: + +* **A Java 8 development environment** + + If you do not have one, go to [Java SE Downloads](https://www.oracle.com/technetwork/java/javase/downloads/index.html) on the Oracle website, then download and install the Java SE Development Kit (JDK). Java 8 or higher is required. + + **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). + +### Optional Prerequisites + +#### AWS Integration +You don't need an Amazon Web Services (AWS) account to use the AWS Encryption SDK, but some [example code][examples] require an AWS account, an AWS KMS key, and the AWS SDK for Java (either 1.x or 2.x). Note that the `KmsAsyncClient` is not supported, only the synchronous client. + +* **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). + +### Get Started + +### Downloads + +You can get the latest release from Maven: + +```xml + + software.amazon.cryptography + aws-database-encryption-sdk-dynamodb + 3.0.0 + +``` ### Development diff --git a/SUPPORT_POLICY.rst b/SUPPORT_POLICY.rst new file mode 100644 index 000000000..bfbaeb572 --- /dev/null +++ b/SUPPORT_POLICY.rst @@ -0,0 +1,29 @@ +Overview +======== +This page describes the support policy for the AWS Database Encryption SDK. We regularly provide the AWS Database Encryption SDK with updates that may contain support for new or updated APIs, new features, enhancements, bug fixes, security patches, or documentation updates. Updates may also address changes with dependencies, language runtimes, and operating systems. + +We recommend users to stay up-to-date with Database Encryption SDK releases to keep up with the latest features, security updates, and underlying dependencies. Continued use of an unsupported SDK version is not recommended and is done at the user’s discretion. + + +Major Version Lifecycle +======================== +The AWS Database Encryption SDK follows the same major version lifecycle as the AWS SDK. For details on this lifecycle, see `AWS SDKs and Tools Maintenance Policy`_. + +Version Support Matrix +====================== +This table describes the current support status of each major version of the AWS Database Encryption SDK for DynamoDB in Java. It also shows the next status each major version will transition to, and the date at which that transition will happen. + +.. list-table:: + :widths: 30 50 50 50 + :header-rows: 1 + + * - Major version + - Current status + - Next status + - Next status date + * - 3.x + - General Availability + - + - + +.. _AWS SDKs and Tools Maintenance Policy: https://docs.aws.amazon.com/sdkref/latest/guide/maint-policy.html#version-life-cycle \ No newline at end of file From 2b604b5badad2aa4c3a068e8929f689848a12f50 Mon Sep 17 00:00:00 2001 From: Lucas McDonald Date: Fri, 26 May 2023 10:28:19 -0700 Subject: [PATCH 02/18] example --- README.md | 153 ++++++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 137 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index 077c554f7..dcceeb06f 100644 --- a/README.md +++ b/README.md @@ -15,26 +15,145 @@ See [Support Policy](./SUPPORT_POLICY.rst) for details on the current support st ### Required Prerequisites To use the DB ESDK for DynamoDB in Java, you must have: -* **A Java 8 development environment** +* **A Java 8 or newer development environment** If you do not have one, go to [Java SE Downloads](https://www.oracle.com/technetwork/java/javase/downloads/index.html) on the Oracle website, then download and install the Java SE Development Kit (JDK). Java 8 or higher is required. **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). -### Optional Prerequisites - -#### AWS Integration -You don't need an Amazon Web Services (AWS) account to use the AWS Encryption SDK, but some [example code][examples] require an AWS account, an AWS KMS key, and the AWS SDK for Java (either 1.x or 2.x). Note that the `KmsAsyncClient` is not supported, only the synchronous client. - -* **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. +### Get Started -* **To create a symmetric encryption KMS key in AWS KMS**, see [Creating Keys](https://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html). +Suppose you have created ([sample code][createtable]) and a DynamoDB table, and want to store some objects. +The security requirement involves classifying particular attributes as sensitive information. +This is how the annotated class may look like: + +```java +@DynamoDbBean +public class SimpleClass { + + private String partitionKey; + private int sortKey; + // The next three fields represent attributes that we will perform cryptographic operations on. + + // attribute1: Encrypt the data and sign it for authenticity + private String attribute1; + // attribute2: Do not encrypt but sign for authenticity + private String attribute2; + // attribute3: Do not encrypt and do not sign + private String attribute3; + + @DynamoDbPartitionKey + @DynamoDbAttribute(value = "partition_key") + public String getPartitionKey() { return this.partitionKey; } + public void setPartitionKey(String partitionKey) { this.partitionKey = partitionKey; } + + @DynamoDbSortKey + @DynamoDbAttribute(value = "sort_key") + public int getSortKey() { return this.sortKey; } + public void setSortKey(int sortKey) { this.sortKey = sortKey; } + + @DynamoDbAttribute(value = "encrypt_and_sign") + public String getAttribute1() { return this.attribute1; } + public void setAttribute1(String attribute1) { this.attribute1 = attribute1; } + + @DynamoDbEncryptionSignOnly + @DynamoDbAttribute(value = "sign_only") + public String getAttribute2() { return this.attribute2; } + public void setAttribute2(String attribute2) { this.attribute2 = attribute2; } + + @DynamoDbEncryptionDoNothing + @DynamoDbAttribute(value = "do_nothing") + public String getAttribute3() { return this.attribute3; } + public void setAttribute3(String attribute3) { this.attribute3 = attribute3; } +} +``` -* **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). +As a typical use case of the [DynamoDBEnhancedClient][ddbenhanced], you can easily save and retrieve a SimpleClass object to and from Amazon DynamoDB _without encryption (nor signing)_. For example, + +```java + // Create the DynamoDBEnhancedClient and our table + DynamoDbClient ddb = DynamoDbClient.builder()...build(); + DynamoDbEnhancedClient enhancedClient = DynamoDbEnhancedClient.builder() + .dynamoDbClient(ddb) + .build(); + final TableSchema tableSchema = TableSchema.fromBean(SimpleClass.class); + final DynamoDbTable table = enhancedClient.table(ddbTableName, tableSchema); + + // Save the unencrypted item to DynamoDB + SimpleClass itemToPut = new SimpleClass(); + itemToPut.setPartitionKey("anyKey"); + itemToPut.setSortKey(0); + itemToPut.setAttribute1("this is not encrypted"); + table.putItem(itemToPut); + + // Load the item back from DynamoDB + SimpleClass itemToGet = new SimpleClass(); + itemToGet.setPartitionKey("anyKey"); + itemToGet.setSortKey(0); + SimpleClass returnedItem = table.getItem(itemToGet); +``` -* **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 enable transparent encryption and signing, create a keyring and a DynamoDbEncryptionInterceptor, then add it to the client. For example: + +```java + // Use an example KMS key for encrypting your data + String encryptingKmsKeyArn = ...; + + // Create encryption materials provider using your example KMS key + MaterialProviders matProv = MaterialProviders.builder() + .MaterialProvidersConfig(MaterialProvidersConfig.builder().build()) + .build(); + CreateAwsKmsMrkMultiKeyringInput keyringInput = CreateAwsKmsMrkMultiKeyringInput.builder() + .generator(encryptingKmsKeyArn) + .build(); + IKeyring kmsKeyring = matProv.CreateAwsKmsMrkMultiKeyring(keyringInput); + + + // Create your encrypted table config + Map tableConfigs = new HashMap<>(); + tableConfigs.put(ddbTableName, + DynamoDbEnhancedTableEncryptionConfig.builder() + .logicalTableName(ddbTableName) + .keyring(kmsKeyring) + .schemaOnEncrypt(tableSchema) + .allowedUnsignedAttributes(Arrays.asList("do_nothing")) + .build()); + + // Create an interceptor to pass into the DDB client + DynamoDbEncryptionInterceptor interceptor = + DynamoDbEnhancedClientEncryption.CreateDynamoDbEncryptionInterceptor( + CreateDynamoDbEncryptionInterceptorInput.builder() + .tableEncryptionConfigs(tableConfigs) + .build()); + + // Create the DDB client with our encryption interceptor + DynamoDbClient ddb = DynamoDbClient.builder() + .region(Region.US_WEST_2) + .overrideConfiguration( + ClientOverrideConfiguration.builder() + .addExecutionInterceptor(interceptor) + .build()) + .build(); + DynamoDbEnhancedClient enhancedClient = DynamoDbEnhancedClient.builder() + .dynamoDbClient(ddb) + .build(); + final DynamoDbTable table = enhancedClient.table(ddbTableName, tableSchema); + + // Save the encrypted item to DynamoDB + SimpleClass itemToPut = new SimpleClass(); + itemToPut.setPartitionKey("anyKey"); + itemToPut.setSortKey(0); + itemToPut.setAttribute1("this is encrypted client-side"); + table.putItem(itemToPut); + + // Load the item back from DynamoDB and decrypt client-side + SimpleClass itemToGet = new SimpleClass(); + itemToGet.setPartitionKey("anyKey"); + itemToGet.setSortKey(0); + SimpleClass returnedItem = table.getItem(itemToGet); +``` -### Get Started +See a related [example][] for more context and description. ### Downloads @@ -51,11 +170,10 @@ You can get the latest release from Maven: ### Development This repo contains several projects: -- DynamoDbEncryption: Contains the implementation of the DynamoDb Encryption Client in all target languages -- TODO test vectors -- TODO examples - -A specification of all these projects exists at `specification`. +- `DynamoDbEncryption`: Contains the implementation of the Database Encryption SDK for DynamoDB in Java. +A specification of this project exists at `specification`. +- `Examples`: Contains example projects that demonstrate use of the features of the Database Encryption SDK for DynamoDB +- `TestVectors`: Contains project that encrypts and decrypts a suite of DynamoDB items to validate the Database Encryption SDK's cross-version compatibility ## Security @@ -64,3 +182,6 @@ See [CONTRIBUTING](CONTRIBUTING.md#security-issue-notifications) for more inform ## License This project is licensed under the Apache-2.0 License. + +[createtable]: todofix +[ddbenhanced]: https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/dynamodb-enhanced-client.html From 88fcf771171fa270877f5a186b6d16c76105c843 Mon Sep 17 00:00:00 2001 From: Lucas McDonald Date: Fri, 26 May 2023 10:42:32 -0700 Subject: [PATCH 03/18] work --- DynamoDbEncryption/README.md | 9 ++++++--- README.md | 2 +- 2 files changed, 7 insertions(+), 4 deletions(-) diff --git a/DynamoDbEncryption/README.md b/DynamoDbEncryption/README.md index c434f07eb..c64a155fa 100644 --- a/DynamoDbEncryption/README.md +++ b/DynamoDbEncryption/README.md @@ -1,8 +1,10 @@ -## DynamoDb Encryption +## DynamoDbEncryption + +This project implements the AWS Database Encryption SDK for DynamoDB. ### Code Organization -DynamoDb Encryption is a project containing the following Dafny 'localServices' under `dafny`: +DynamoDbEncryption is a project containing the following Dafny 'localServices' under `dafny`: - DynamoDbEncryption: A config-less entry point for shared structures and helper methods related to DDB Encryption. - DynamoDbItemEncryptor: A client responsible for the encryption and decryption of DDB Items (sans any DDB API call). - DynamoDbEncryptionTransforms: An internal interface responsible for appropriately adding encryption to DDB APIs. @@ -63,7 +65,8 @@ Common Makefile targets are: ### Development Requirements -TODO +* Dafny 4.1.0: https://github.com/dafny-lang/dafny +* A #### (Optional) Dafny Report Generator Requirements diff --git a/README.md b/README.md index dcceeb06f..3efe1e818 100644 --- a/README.md +++ b/README.md @@ -153,7 +153,7 @@ To enable transparent encryption and signing, create a keyring and a DynamoDbEnc SimpleClass returnedItem = table.getItem(itemToGet); ``` -See a related [example][] for more context and description. +See a related [example][TODOplaintextexample] for more context and description. ### Downloads From f5009fd2f5af401a95dd19e997869bef1a356c04 Mon Sep 17 00:00:00 2001 From: Lucas McDonald Date: Fri, 26 May 2023 11:15:44 -0700 Subject: [PATCH 04/18] readmes --- DynamoDbEncryption/README.md | 2 +- .../runtimes/java/DynamoDbEncryption/README.md | 15 +++++++++++++++ Examples/runtimes/java/README.md | 9 +++++++++ TestVectors/README.md | 3 +++ 4 files changed, 28 insertions(+), 1 deletion(-) create mode 100644 Examples/runtimes/java/README.md create mode 100644 TestVectors/README.md diff --git a/DynamoDbEncryption/README.md b/DynamoDbEncryption/README.md index c64a155fa..252a565ef 100644 --- a/DynamoDbEncryption/README.md +++ b/DynamoDbEncryption/README.md @@ -66,7 +66,7 @@ Common Makefile targets are: ### Development Requirements * Dafny 4.1.0: https://github.com/dafny-lang/dafny -* A +* A Java 8 or newer development environment #### (Optional) Dafny Report Generator Requirements diff --git a/Examples/runtimes/java/DynamoDbEncryption/README.md b/Examples/runtimes/java/DynamoDbEncryption/README.md index a91b18e68..90361244c 100644 --- a/Examples/runtimes/java/DynamoDbEncryption/README.md +++ b/Examples/runtimes/java/DynamoDbEncryption/README.md @@ -1,3 +1,18 @@ # AWS Database Encryption SDK for DynamoDb Java Examples This project contains examples for using the AWS Database Encryption SDK for DynamoDb in Java. + +``` +├── .. +├── src +│ ├── main/java/software/amazon/cryptography/examples: Examples source +│ │ ├── BasicPutGetExample: Example using AWS DB ESDK to Put and Get an encrypted item from DynamoDB +│ │ ├── CreateKeyStoreTableExample: Example creating a Keystore DynamoDB table for use with a hierarchical keyring +│ │ ├── CreateKeyStoreKeyExample: Example creating a branch key in a Keystore DynamoDB table +│ │ ├── clientsupplier: Examples using a custom KMS ClientSupplier +│ │ ├── enhanced: Examples using the DynamoDbEnhancedClient +│ │ ├── itemencryptor: Examples using the DynamoDbItemEncryptor +│ │ ├── keyring: Examples creating and using different keyrings +│ │ └── searchableencryption: Examples demonstrating searchable encryption configuration and usage +└── └── test: Our tests that run these examples +``` diff --git a/Examples/runtimes/java/README.md b/Examples/runtimes/java/README.md new file mode 100644 index 000000000..06fc828f6 --- /dev/null +++ b/Examples/runtimes/java/README.md @@ -0,0 +1,9 @@ +## Examples (Java) + +This project contains examples demonstrating how to use the AWS Database Encryption SDK. + +``` +├── .. +├── DynamoDbEncryption: Examples for using features in the AWS Database Encryption SDK +└── Migration: Examples for migrating from a plaintext table or the DynamoDB Encryption Client 2.0 to AWS DB ESDK +``` diff --git a/TestVectors/README.md b/TestVectors/README.md new file mode 100644 index 000000000..d37ebef02 --- /dev/null +++ b/TestVectors/README.md @@ -0,0 +1,3 @@ +# AWS Database Encryption SDK for DynamoDb Java Test Vectors + +This project contains code encrypts and decrypts a suite of DynamoDB items to validate the Database Encryption SDK's cross-version compatibility. From 94ec9417992151083b2315db16cd05a16806a3ef Mon Sep 17 00:00:00 2001 From: Lucas McDonald Date: Fri, 26 May 2023 13:46:46 -0700 Subject: [PATCH 05/18] changes --- .../java/DynamoDbEncryption/README.md | 25 +++++++++++++++++ Examples/runtimes/java/Migration/README.md | 23 +++++++++++++++ README.md | 8 +++--- TestVectors/README.md | 28 ++++++++++++++++++- 4 files changed, 79 insertions(+), 5 deletions(-) diff --git a/Examples/runtimes/java/DynamoDbEncryption/README.md b/Examples/runtimes/java/DynamoDbEncryption/README.md index 90361244c..b6c0b32f4 100644 --- a/Examples/runtimes/java/DynamoDbEncryption/README.md +++ b/Examples/runtimes/java/DynamoDbEncryption/README.md @@ -2,6 +2,8 @@ This project contains examples for using the AWS Database Encryption SDK for DynamoDb in Java. +Overview: + ``` ├── .. ├── src @@ -16,3 +18,26 @@ This project contains examples for using the AWS Database Encryption SDK for Dyn │ │ └── searchableencryption: Examples demonstrating searchable encryption configuration and usage └── └── test: Our tests that run these examples ``` + +## Getting Started + +### Development Requirements + +* A Java 8 or newer development environment + +### Building and Running + +Each example includes a runnable `main` method +and a description of the required command line arguments. +To run a given example, inspect its particular setup requirements, +create and/or grant access to any required AWS resources, +and run the example as specified in the file. + +## Security + +See [CONTRIBUTING](CONTRIBUTING.md#security-issue-notifications) for more information. + +## License + +This project is licensed under the Apache-2.0 License. + diff --git a/Examples/runtimes/java/Migration/README.md b/Examples/runtimes/java/Migration/README.md index 9e88ef009..c76d7b6cd 100644 --- a/Examples/runtimes/java/Migration/README.md +++ b/Examples/runtimes/java/Migration/README.md @@ -2,3 +2,26 @@ This project contains an example project demonstrating how to safely upgrade from the DynamoDb Encryption Client (v2.0.1) to the AWS Database Encryption SDK for DynamoDb (v3.0.0). + +## Getting Started + +### Development Requirements + +* A Java 8 or newer development environment + +### Building and Running + +Each example includes a runnable `main` method +and a description of the required command line arguments. +To run a given example, inspect its particular setup requirements, +create and/or grant access to any required AWS resources, +and run the example as specified in the file. + +## Security + +See [CONTRIBUTING](CONTRIBUTING.md#security-issue-notifications) for more information. + +## License + +This project is licensed under the Apache-2.0 License. + diff --git a/README.md b/README.md index 3efe1e818..d4f2a4e21 100644 --- a/README.md +++ b/README.md @@ -33,7 +33,7 @@ public class SimpleClass { private String partitionKey; private int sortKey; - // The next three fields represent attributes that we will perform cryptographic operations on. + // The next three fields represent DynamoDB item attributes that we will perform cryptographic operations on. // attribute1: Encrypt the data and sign it for authenticity private String attribute1; @@ -52,17 +52,17 @@ public class SimpleClass { public int getSortKey() { return this.sortKey; } public void setSortKey(int sortKey) { this.sortKey = sortKey; } - @DynamoDbAttribute(value = "encrypt_and_sign") + @DynamoDbAttribute(value = "attribute1") public String getAttribute1() { return this.attribute1; } public void setAttribute1(String attribute1) { this.attribute1 = attribute1; } @DynamoDbEncryptionSignOnly - @DynamoDbAttribute(value = "sign_only") + @DynamoDbAttribute(value = "attribute2") public String getAttribute2() { return this.attribute2; } public void setAttribute2(String attribute2) { this.attribute2 = attribute2; } @DynamoDbEncryptionDoNothing - @DynamoDbAttribute(value = "do_nothing") + @DynamoDbAttribute(value = "attribute3") public String getAttribute3() { return this.attribute3; } public void setAttribute3(String attribute3) { this.attribute3 = attribute3; } } diff --git a/TestVectors/README.md b/TestVectors/README.md index d37ebef02..544eeb073 100644 --- a/TestVectors/README.md +++ b/TestVectors/README.md @@ -1,3 +1,29 @@ # AWS Database Encryption SDK for DynamoDb Java Test Vectors -This project contains code encrypts and decrypts a suite of DynamoDB items to validate the Database Encryption SDK's cross-version compatibility. +This project contains code encrypts and decrypts a suite of DynamoDB items. +This validates the Database Encryption SDK's cross-version compatibility. + +## Getting Started + +### Development Requirements + +* Dafny 4.1.0: https://github.com/dafny-lang/dafny + + The code that executes the test vectors is written in Dafny. + You must install the Dafny runtime to compile the Dafny tests into Java. +* A Java 8 or newer development environment + +### Building and Running + +1. Start in the root `./TestVectors` directory +2. Run `make build_java` +3. Run `make test_java` + +## Security + +See [CONTRIBUTING](CONTRIBUTING.md#security-issue-notifications) for more information. + +## License + +This project is licensed under the Apache-2.0 License. + From 2e55f742e8afc45ad2b93343d9365e56e38de21d Mon Sep 17 00:00:00 2001 From: texastony <5892063+texastony@users.noreply.github.com> Date: Wed, 31 May 2023 11:46:42 -0500 Subject: [PATCH 06/18] docs: Top README & Examples for it --- .../examples/enhanced/CreateSimpleTable.java | 49 +++++++++ .../EnhancedPlaintextPutGetExample.java | 35 ++++++ README.md | 101 ++++++++++++------ 3 files changed, 154 insertions(+), 31 deletions(-) create mode 100644 Examples/runtimes/java/DynamoDbEncryption/src/main/java/software/amazon/cryptography/examples/enhanced/CreateSimpleTable.java create mode 100644 Examples/runtimes/java/DynamoDbEncryption/src/main/java/software/amazon/cryptography/examples/enhanced/EnhancedPlaintextPutGetExample.java diff --git a/Examples/runtimes/java/DynamoDbEncryption/src/main/java/software/amazon/cryptography/examples/enhanced/CreateSimpleTable.java b/Examples/runtimes/java/DynamoDbEncryption/src/main/java/software/amazon/cryptography/examples/enhanced/CreateSimpleTable.java new file mode 100644 index 000000000..b89b9068c --- /dev/null +++ b/Examples/runtimes/java/DynamoDbEncryption/src/main/java/software/amazon/cryptography/examples/enhanced/CreateSimpleTable.java @@ -0,0 +1,49 @@ +// Copyright Amazon.com Inc. or its affiliates. All Rights Reserved. +// SPDX-License-Identifier: Apache-2.0 +package software.amazon.cryptography.examples.enhanced; + +import software.amazon.awssdk.services.dynamodb.DynamoDbClient; +import software.amazon.awssdk.services.dynamodb.model.AttributeDefinition; +import software.amazon.awssdk.services.dynamodb.model.CreateTableRequest; +import software.amazon.awssdk.services.dynamodb.model.CreateTableResponse; +import software.amazon.awssdk.services.dynamodb.model.KeySchemaElement; +import software.amazon.awssdk.services.dynamodb.model.KeyType; +import software.amazon.awssdk.services.dynamodb.model.ScalarAttributeType; + +/** + * This class is referenced by the README. + */ +@SuppressWarnings("unused") +public class CreateSimpleTable { + + public static void Create(DynamoDbClient ddbClient, String ddbTableName) { + CreateTableRequest request = CreateTableRequest.builder() + .tableName(ddbTableName) + .keySchema( + KeySchemaElement.builder() + .keyType(KeyType.HASH) + .attributeName("partition_key") + .build(), + KeySchemaElement.builder() + .keyType(KeyType.RANGE) + .attributeName("sort_key") + .build()) + .attributeDefinitions( + AttributeDefinition.builder() + .attributeName("partition_key") + .attributeType(ScalarAttributeType.S) + .build(), + AttributeDefinition.builder() + .attributeName("sort_key") + .attributeType(ScalarAttributeType.N) + .build()) + .build(); + CreateTableResponse response = ddbClient.createTable(request); + if (!response.sdkHttpResponse().isSuccessful()) { + throw new RuntimeException( + String.format( + "Create Table Failed. HTTP response: %s", + response.sdkHttpResponse())); + } + } +} diff --git a/Examples/runtimes/java/DynamoDbEncryption/src/main/java/software/amazon/cryptography/examples/enhanced/EnhancedPlaintextPutGetExample.java b/Examples/runtimes/java/DynamoDbEncryption/src/main/java/software/amazon/cryptography/examples/enhanced/EnhancedPlaintextPutGetExample.java new file mode 100644 index 000000000..1bac55fd6 --- /dev/null +++ b/Examples/runtimes/java/DynamoDbEncryption/src/main/java/software/amazon/cryptography/examples/enhanced/EnhancedPlaintextPutGetExample.java @@ -0,0 +1,35 @@ +// Copyright Amazon.com Inc. or its affiliates. All Rights Reserved. +// SPDX-License-Identifier: Apache-2.0 +package software.amazon.cryptography.examples.enhanced; + +import software.amazon.awssdk.enhanced.dynamodb.DynamoDbEnhancedClient; +import software.amazon.awssdk.enhanced.dynamodb.DynamoDbTable; +import software.amazon.awssdk.enhanced.dynamodb.TableSchema; +import software.amazon.awssdk.services.dynamodb.DynamoDbClient; + +/** + * This class is referenced by the README. + */ +@SuppressWarnings("unused") +public class EnhancedPlaintextPutGetExample { + public static void PutItemGetItem(DynamoDbClient ddb, String ddbTableName) { + DynamoDbEnhancedClient enhancedClient = DynamoDbEnhancedClient.builder() + .dynamoDbClient(ddb) + .build(); + + final TableSchema tableSchema = TableSchema.fromBean(SimpleClass.class); + final DynamoDbTable table = enhancedClient.table(ddbTableName, tableSchema); + + SimpleClass itemToPut = new SimpleClass(); + itemToPut.setPartitionKey("anyKey"); + itemToPut.setSortKey(0); + itemToPut.setAttribute1("this is not encrypted"); + table.putItem(itemToPut); + + // Load the item back from DynamoDB + SimpleClass itemToGet = new SimpleClass(); + itemToGet.setPartitionKey("anyKey"); + itemToGet.setSortKey(0); + SimpleClass returnedItem = table.getItem(itemToGet); + } +} diff --git a/README.md b/README.md index d4f2a4e21..fcd6a0ea9 100644 --- a/README.md +++ b/README.md @@ -1,31 +1,68 @@ -## AWS Database Encryption SDK for DynamoDB in Java +# AWS Database Encryption SDK for DynamoDB in Java The AWS Database Encryption SDK for DynamoDB in Java provides client-side encryption and signing of Amazon DynamoDB items to help you protect your table's data before you send it to DynamoDB. -For more details about the design and architecture of the AWS Database Encryption SDK for DynamoDB, see the [AWS Database Encryption SDK Developer Guide](https://docs.aws.amazon.com/database-encryption-sdk/latest/devguide/). +For more details about the design and architecture of the +AWS Database Encryption SDK (DB ESDK) for DynamoDB, +see the [AWS Database Encryption SDK Developer Guide](https://docs.aws.amazon.com/database-encryption-sdk/latest/devguide/). [Security issue notifications](./CONTRIBUTING.md#security-issue-notifications) -See [Support Policy](./SUPPORT_POLICY.rst) for details on the current support status of all major versions of this library. +See [Support Policy](./SUPPORT_POLICY.rst) for details +on the current support status of all major versions of this library. -## Getting Started +# Getting Started -### Required Prerequisites +## Required Prerequisites To use the DB ESDK for DynamoDB in Java, you must have: * **A Java 8 or newer development environment** - If you do not have one, go to [Java SE Downloads](https://www.oracle.com/technetwork/java/javase/downloads/index.html) on the Oracle website, then download and install the Java SE Development Kit (JDK). Java 8 or higher is required. + If you do not have one, + go to [Java SE Downloads](https://www.oracle.com/technetwork/java/javase/downloads/index.html) on the Oracle website, + then download and install the Java SE Development Kit (JDK). + Java 8 or higher is required. - **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). + **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). -### Get Started +* **Declared a Dependency on the DB ESDK for DynamoDB in Java** -Suppose you have created ([sample code][createtable]) and a DynamoDB table, and want to store some objects. -The security requirement involves classifying particular attributes as sensitive information. -This is how the annotated class may look like: + * Via Gradle Kotlin + In a Gradle Java Project, add the following to the _dependencies_ section: + ```kotlin + implementation("software.amazon.cryptography:aws-database-encryption-sdk-dynamodb:3.0.0") + ``` + + * Via Apache Maven + Add the following to the project's `pom.xml`: + ```xml + + software.amazon.cryptography + aws-database-encryption-sdk-dynamodb + 3.0.0 + + ``` + +## Configuring the DB ESDK for DynamoDB in Java +There are several ways to use the +AWS Database Encryption SDK (DB ESDK) for DynamoDB in Java. +More details are provided in the +[AWS Database Encryption SDK Developer Guide](https://docs.aws.amazon.com/database-encryption-sdk/latest/devguide/). +Also see the [Examples](Examples/runtimes/java/DynamoDbEncryption). + +### Using Annotations + +Suppose you have created a DynamoDB table via the request in +[Examples/CreateSimpleTable](Examples/runtimes/java/DynamoDbEncryption/src/main/java/software/amazon/cryptography/examples/enhanced/CreateSimpleTable.java), +and want to store some objects. +The security requirements for these objects involves classifying particular +attributes as sensitive information. +You can use annotations from the Enhanced DynamoDB Client and the DB ESDK to define +the objects types and which fields are encrypted: ```java @DynamoDbBean @@ -68,7 +105,10 @@ public class SimpleClass { } ``` -As a typical use case of the [DynamoDBEnhancedClient][ddbenhanced], you can easily save and retrieve a SimpleClass object to and from Amazon DynamoDB _without encryption (nor signing)_. For example, +As a typical use case of the [DynamoDBEnhancedClient][ddbenhanced], +you can easily save and retrieve a SimpleClass object +to and from Amazon DynamoDB _without encryption (nor signing)_. +For example, ```java // Create the DynamoDBEnhancedClient and our table @@ -93,7 +133,13 @@ As a typical use case of the [DynamoDBEnhancedClient][ddbenhanced], you can easi SimpleClass returnedItem = table.getItem(itemToGet); ``` -To enable transparent encryption and signing, create a keyring and a DynamoDbEncryptionInterceptor, then add it to the client. For example: +See +[EnhancedPlaintextPutGetExample](Examples/runtimes/java/DynamoDbEncryption/src/main/java/software/amazon/cryptography/examples/enhanced/EnhancedPlaintextPutGetExample.java). + +To enable transparent encryption and signing, +create a keyring and a DynamoDbEncryptionInterceptor, +then add it to the client. +For example: ```java // Use an example KMS key for encrypting your data @@ -153,27 +199,21 @@ To enable transparent encryption and signing, create a keyring and a DynamoDbEnc SimpleClass returnedItem = table.getItem(itemToGet); ``` -See a related [example][TODOplaintextexample] for more context and description. - -### Downloads - -You can get the latest release from Maven: - -```xml - - software.amazon.cryptography - aws-database-encryption-sdk-dynamodb - 3.0.0 - -``` +See +[EnhancedPutGetExample](Examples/runtimes/java/DynamoDbEncryption/src/main/java/software/amazon/cryptography/examples/enhanced/EnhancedPutGetExample.java) +for more context and description. ### Development This repo contains several projects: -- `DynamoDbEncryption`: Contains the implementation of the Database Encryption SDK for DynamoDB in Java. -A specification of this project exists at `specification`. -- `Examples`: Contains example projects that demonstrate use of the features of the Database Encryption SDK for DynamoDB -- `TestVectors`: Contains project that encrypts and decrypts a suite of DynamoDB items to validate the Database Encryption SDK's cross-version compatibility +- `DynamoDbEncryption`: Contains the implementation of the Database Encryption + SDK for DynamoDB in Java. +- A specification of this project exists at `specification`. +- `Examples`: Contains example projects that demonstrate use of + the features of the Database Encryption SDK for DynamoDB +- `TestVectors`: Contains project that encrypts and decrypts + a suite of DynamoDB items to validate the Database Encryption + SDK's cross-version compatibility ## Security @@ -183,5 +223,4 @@ See [CONTRIBUTING](CONTRIBUTING.md#security-issue-notifications) for more inform This project is licensed under the Apache-2.0 License. -[createtable]: todofix [ddbenhanced]: https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/dynamodb-enhanced-client.html From 2274fcea7c7bc80936438e312d2accda018702f2 Mon Sep 17 00:00:00 2001 From: texastony <5892063+texastony@users.noreply.github.com> Date: Wed, 31 May 2023 11:54:26 -0500 Subject: [PATCH 07/18] docs: Top README & Examples for it --- README.md | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index fcd6a0ea9..ef95f33d1 100644 --- a/README.md +++ b/README.md @@ -8,8 +8,13 @@ For more details about the design and architecture of the AWS Database Encryption SDK (DB ESDK) for DynamoDB, see the [AWS Database Encryption SDK Developer Guide](https://docs.aws.amazon.com/database-encryption-sdk/latest/devguide/). -[Security issue notifications](./CONTRIBUTING.md#security-issue-notifications) +# Security +If you discover a potential security issue in this project +we ask that you notify AWS/Amazon Security via our +[vulnerability reporting page](http://aws.amazon.com/security/vulnerability-reporting/). +Please do **not** create a public GitHub issue. +# Support Policy See [Support Policy](./SUPPORT_POLICY.rst) for details on the current support status of all major versions of this library. @@ -203,8 +208,9 @@ See [EnhancedPutGetExample](Examples/runtimes/java/DynamoDbEncryption/src/main/java/software/amazon/cryptography/examples/enhanced/EnhancedPutGetExample.java) for more context and description. -### Development +# Development +[//]: # (TODO: Post-GA? Development Instructions) This repo contains several projects: - `DynamoDbEncryption`: Contains the implementation of the Database Encryption SDK for DynamoDB in Java. @@ -215,11 +221,11 @@ This repo contains several projects: a suite of DynamoDB items to validate the Database Encryption SDK's cross-version compatibility -## Security +# Contributing See [CONTRIBUTING](CONTRIBUTING.md#security-issue-notifications) for more information. -## License +# License This project is licensed under the Apache-2.0 License. From a099ef1fc09707fc2aecac4ddbb94c1fbaf8fda5 Mon Sep 17 00:00:00 2001 From: texastony <5892063+texastony@users.noreply.github.com> Date: Wed, 31 May 2023 11:56:44 -0500 Subject: [PATCH 08/18] docs: Top README & Examples for it --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index ef95f33d1..f14b7018a 100644 --- a/README.md +++ b/README.md @@ -223,7 +223,7 @@ This repo contains several projects: # Contributing -See [CONTRIBUTING](CONTRIBUTING.md#security-issue-notifications) for more information. +See [CONTRIBUTING](CONTRIBUTING.md) for more information. # License From 0f53dbba7e549a5d585e91a08b796a2ed1ef22c6 Mon Sep 17 00:00:00 2001 From: texastony <5892063+texastony@users.noreply.github.com> Date: Wed, 31 May 2023 13:35:28 -0500 Subject: [PATCH 09/18] docs: fix Contributing --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7e6f68d01..b24a9e196 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -56,4 +56,4 @@ If you discover a potential security issue in this project we ask that you notif ## Licensing -See the [LICENSE](LICENSE) file for our project's licensing. We will ask you to confirm the licensing of your contribution. +See the [LICENSE](LICENSE.txt) file for our project's licensing. We will ask you to confirm the licensing of your contribution. From 47620aaf3abf35a3353451c1915a5268fb4e7fcd Mon Sep 17 00:00:00 2001 From: texastony <5892063+texastony@users.noreply.github.com> Date: Wed, 31 May 2023 14:18:40 -0500 Subject: [PATCH 10/18] docs(READM): add Dependencies, AWS Account, & KMS Key --- README.md | 77 ++++++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 65 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index f14b7018a..d9c3d060e 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@ provides client-side encryption and signing of Amazon DynamoDB items to help you protect your table's data before you send it to DynamoDB. For more details about the design and architecture of the -AWS Database Encryption SDK (DB ESDK) for DynamoDB, +AWS Database Encryption SDK (DB-ESDK) for DynamoDB, see the [AWS Database Encryption SDK Developer Guide](https://docs.aws.amazon.com/database-encryption-sdk/latest/devguide/). # Security @@ -21,7 +21,7 @@ on the current support status of all major versions of this library. # Getting Started ## Required Prerequisites -To use the DB ESDK for DynamoDB in Java, you must have: +To use the DB-ESDK for DynamoDB in Java, you must have: * **A Java 8 or newer development environment** @@ -34,27 +34,80 @@ To use the DB ESDK for DynamoDB in Java, you must have: 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). -* **Declared a Dependency on the DB ESDK for DynamoDB in Java** +* **Declared a Dependency on the DB-ESDK for DynamoDB in Java and it's dependencies** * Via Gradle Kotlin In a Gradle Java Project, add the following to the _dependencies_ section: ```kotlin implementation("software.amazon.cryptography:aws-database-encryption-sdk-dynamodb:3.0.0") + implementation("software.amazon.cryptography:AwsCryptographicMaterialProviders:3.0.0") + implementation(platform("software.amazon.awssdk:bom:2.19.1")) + implementation("software.amazon.awssdk:dynamodb") + implementation("software.amazon.awssdk:dynamodb-enhanced") + implementation("software.amazon.awssdk:kms") ``` * Via Apache Maven - Add the following to the project's `pom.xml`: + The DB-ESDK for DynamoDB in Java requires the DynamoDB, + Dynamodb-Enhanced, and KMS clients from the AWS SDK for Java V2. + It also requires the AwsCryptographicMaterialProviders library. + your project's `pom.xml`. ```xml - - software.amazon.cryptography - aws-database-encryption-sdk-dynamodb - 3.0.0 - + + + + + software.amazon.awssdk + bom + 2.19.1 + pom + import + + + + + + software.amazon.awssdk + dynamodb-enhanced + + + software.amazon.awssdk + dynamodb + + + software.amazon.awssdk + kms + + + software.amazon.cryptography + aws-database-encryption-sdk-dynamodb + 3.0.0 + + + software.amazon.cryptography + AwsCryptographicMaterialProviders + 3.0.0 + + + ... + ``` -## Configuring the DB ESDK for DynamoDB in Java +### AWS Integration +You need an Amazon Web Services (AWS) account to use +the AWS Database Encryption SDK for DynamoDB +(a KMS Key is optional). + +* **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 key in AWS KMS**, see + [Creating Keys](https://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html). +## Configuring the DB-ESDK for DynamoDB in Java There are several ways to use the -AWS Database Encryption SDK (DB ESDK) for DynamoDB in Java. +AWS Database Encryption SDK (DB-ESDK) for DynamoDB in Java. More details are provided in the [AWS Database Encryption SDK Developer Guide](https://docs.aws.amazon.com/database-encryption-sdk/latest/devguide/). Also see the [Examples](Examples/runtimes/java/DynamoDbEncryption). @@ -66,7 +119,7 @@ Suppose you have created a DynamoDB table via the request in and want to store some objects. The security requirements for these objects involves classifying particular attributes as sensitive information. -You can use annotations from the Enhanced DynamoDB Client and the DB ESDK to define +You can use annotations from the Enhanced DynamoDB Client and the DB-ESDK to define the objects types and which fields are encrypted: ```java From 91b371cc8ec0bfa03e19a7e26430533671000554 Mon Sep 17 00:00:00 2001 From: texastony <5892063+texastony@users.noreply.github.com> Date: Wed, 31 May 2023 14:21:07 -0500 Subject: [PATCH 11/18] docs(READM): formatting --- README.md | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index d9c3d060e..799fa0d69 100644 --- a/README.md +++ b/README.md @@ -34,9 +34,12 @@ To use the DB-ESDK for DynamoDB in Java, you must have: 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). -* **Declared a Dependency on the DB-ESDK for DynamoDB in Java and it's dependencies** +* **Declared a Dependency on the DB-ESDK for DynamoDB in Java and it's dependencies** + The DB-ESDK for DynamoDB in Java requires the DynamoDB, + Dynamodb-Enhanced, and KMS clients from the AWS SDK for Java V2. + It also requires the AwsCryptographicMaterialProviders library. - * Via Gradle Kotlin + * **Via Gradle Kotlin** In a Gradle Java Project, add the following to the _dependencies_ section: ```kotlin implementation("software.amazon.cryptography:aws-database-encryption-sdk-dynamodb:3.0.0") @@ -47,13 +50,11 @@ To use the DB-ESDK for DynamoDB in Java, you must have: implementation("software.amazon.awssdk:kms") ``` - * Via Apache Maven - The DB-ESDK for DynamoDB in Java requires the DynamoDB, - Dynamodb-Enhanced, and KMS clients from the AWS SDK for Java V2. - It also requires the AwsCryptographicMaterialProviders library. - your project's `pom.xml`. + * **Via Apache Maven** + Add the following to your project's `pom.xml`. ```xml + ... From a06f9b426d7cd636aad07dec760fe6f81e221032 Mon Sep 17 00:00:00 2001 From: texastony <5892063+texastony@users.noreply.github.com> Date: Wed, 31 May 2023 14:25:26 -0500 Subject: [PATCH 12/18] docs(READM): ACCP --- README.md | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 799fa0d69..3a0608968 100644 --- a/README.md +++ b/README.md @@ -43,7 +43,7 @@ To use the DB-ESDK for DynamoDB in Java, you must have: In a Gradle Java Project, add the following to the _dependencies_ section: ```kotlin implementation("software.amazon.cryptography:aws-database-encryption-sdk-dynamodb:3.0.0") - implementation("software.amazon.cryptography:AwsCryptographicMaterialProviders:3.0.0") + implementation("software.amazon.cryptography:AwsCryptographicMaterialProviders:1.0.0") implementation(platform("software.amazon.awssdk:bom:2.19.1")) implementation("software.amazon.awssdk:dynamodb") implementation("software.amazon.awssdk:dynamodb-enhanced") @@ -87,7 +87,7 @@ To use the DB-ESDK for DynamoDB in Java, you must have: software.amazon.cryptography AwsCryptographicMaterialProviders - 3.0.0 + 1.0.0 ... @@ -106,6 +106,14 @@ the AWS Database Encryption SDK for DynamoDB * **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 Database Encryption SDK for DynamoDB in Java. +For help installing and using ACCP, see the +[amazon-corretto-crypto-provider repository](https://github.com/corretto/amazon-corretto-crypto-provider). + ## Configuring the DB-ESDK for DynamoDB in Java There are several ways to use the AWS Database Encryption SDK (DB-ESDK) for DynamoDB in Java. From 9ea8a821d433f2d06bbd57f4c697cb011da17b8f Mon Sep 17 00:00:00 2001 From: texastony <5892063+texastony@users.noreply.github.com> Date: Wed, 31 May 2023 14:35:47 -0500 Subject: [PATCH 13/18] docs(READM): Feedback --- README.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/README.md b/README.md index 3a0608968..0eff12f75 100644 --- a/README.md +++ b/README.md @@ -18,6 +18,19 @@ Please do **not** create a public GitHub issue. See [Support Policy](./SUPPORT_POLICY.rst) for details on the current support status of all major versions of this library. +## Giving Feedback +We need your help in making this SDK great. +Please participate in the community and contribute to this effort by +submitting issues, +participating in discussion forums and +submitting pull requests through the following channels: + +* Submit [issues](https://github.com/aws/aws-database-encryption-sdk-dynamodb-java/issues) + \- this is the **preferred** channel to interact with our team +* Articulate your + [feature request](https://github.com/aws/aws-database-encryption-sdk-dynamodb-java/issues?q=is%3Aopen+is%3Aissue+label%3A%22feature-request%22) + or upvote existing ones + # Getting Started ## Required Prerequisites From 0d8991a1f50cafc087c780ee4c7d4500ded166ad Mon Sep 17 00:00:00 2001 From: texastony <5892063+texastony@users.noreply.github.com> Date: Wed, 31 May 2023 14:39:39 -0500 Subject: [PATCH 14/18] docs(READM): formatting --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 0eff12f75..59c7fa3c4 100644 --- a/README.md +++ b/README.md @@ -287,12 +287,12 @@ for more context and description. [//]: # (TODO: Post-GA? Development Instructions) This repo contains several projects: -- `DynamoDbEncryption`: Contains the implementation of the Database Encryption +- `DynamoDbEncryption`: The implementation of the Database Encryption SDK for DynamoDB in Java. - A specification of this project exists at `specification`. -- `Examples`: Contains example projects that demonstrate use of +- `Examples`: Example projects that demonstrate use of the features of the Database Encryption SDK for DynamoDB -- `TestVectors`: Contains project that encrypts and decrypts +- `TestVectors`: Project that encrypts and decrypts a suite of DynamoDB items to validate the Database Encryption SDK's cross-version compatibility From 7f3ede7f0e06081541ef0e9623725b834eadbdba Mon Sep 17 00:00:00 2001 From: texastony <5892063+texastony@users.noreply.github.com> Date: Wed, 31 May 2023 14:47:31 -0500 Subject: [PATCH 15/18] docs(README): move plaintext examples to plaintext --- .../cryptography/examples/plaintext}/CreateSimpleTable.java | 2 +- .../examples/plaintext}/EnhancedPlaintextPutGetExample.java | 2 +- README.md | 4 ++-- 3 files changed, 4 insertions(+), 4 deletions(-) rename Examples/runtimes/java/{DynamoDbEncryption/src/main/java/software/amazon/cryptography/examples/enhanced => Migration/PlaintextToAWSDBE/src/main/java/software/amazon/cryptography/examples/plaintext}/CreateSimpleTable.java (97%) rename Examples/runtimes/java/{DynamoDbEncryption/src/main/java/software/amazon/cryptography/examples/enhanced => Migration/PlaintextToAWSDBE/src/main/java/software/amazon/cryptography/examples/plaintext}/EnhancedPlaintextPutGetExample.java (96%) diff --git a/Examples/runtimes/java/DynamoDbEncryption/src/main/java/software/amazon/cryptography/examples/enhanced/CreateSimpleTable.java b/Examples/runtimes/java/Migration/PlaintextToAWSDBE/src/main/java/software/amazon/cryptography/examples/plaintext/CreateSimpleTable.java similarity index 97% rename from Examples/runtimes/java/DynamoDbEncryption/src/main/java/software/amazon/cryptography/examples/enhanced/CreateSimpleTable.java rename to Examples/runtimes/java/Migration/PlaintextToAWSDBE/src/main/java/software/amazon/cryptography/examples/plaintext/CreateSimpleTable.java index b89b9068c..3b581000f 100644 --- a/Examples/runtimes/java/DynamoDbEncryption/src/main/java/software/amazon/cryptography/examples/enhanced/CreateSimpleTable.java +++ b/Examples/runtimes/java/Migration/PlaintextToAWSDBE/src/main/java/software/amazon/cryptography/examples/plaintext/CreateSimpleTable.java @@ -1,6 +1,6 @@ // Copyright Amazon.com Inc. or its affiliates. All Rights Reserved. // SPDX-License-Identifier: Apache-2.0 -package software.amazon.cryptography.examples.enhanced; +package software.amazon.cryptography.examples.plaintext; import software.amazon.awssdk.services.dynamodb.DynamoDbClient; import software.amazon.awssdk.services.dynamodb.model.AttributeDefinition; diff --git a/Examples/runtimes/java/DynamoDbEncryption/src/main/java/software/amazon/cryptography/examples/enhanced/EnhancedPlaintextPutGetExample.java b/Examples/runtimes/java/Migration/PlaintextToAWSDBE/src/main/java/software/amazon/cryptography/examples/plaintext/EnhancedPlaintextPutGetExample.java similarity index 96% rename from Examples/runtimes/java/DynamoDbEncryption/src/main/java/software/amazon/cryptography/examples/enhanced/EnhancedPlaintextPutGetExample.java rename to Examples/runtimes/java/Migration/PlaintextToAWSDBE/src/main/java/software/amazon/cryptography/examples/plaintext/EnhancedPlaintextPutGetExample.java index 1bac55fd6..8e3710312 100644 --- a/Examples/runtimes/java/DynamoDbEncryption/src/main/java/software/amazon/cryptography/examples/enhanced/EnhancedPlaintextPutGetExample.java +++ b/Examples/runtimes/java/Migration/PlaintextToAWSDBE/src/main/java/software/amazon/cryptography/examples/plaintext/EnhancedPlaintextPutGetExample.java @@ -1,6 +1,6 @@ // Copyright Amazon.com Inc. or its affiliates. All Rights Reserved. // SPDX-License-Identifier: Apache-2.0 -package software.amazon.cryptography.examples.enhanced; +package software.amazon.cryptography.examples.plaintext; import software.amazon.awssdk.enhanced.dynamodb.DynamoDbEnhancedClient; import software.amazon.awssdk.enhanced.dynamodb.DynamoDbTable; diff --git a/README.md b/README.md index 59c7fa3c4..7bc19a812 100644 --- a/README.md +++ b/README.md @@ -137,7 +137,7 @@ Also see the [Examples](Examples/runtimes/java/DynamoDbEncryption). ### Using Annotations Suppose you have created a DynamoDB table via the request in -[Examples/CreateSimpleTable](Examples/runtimes/java/DynamoDbEncryption/src/main/java/software/amazon/cryptography/examples/enhanced/CreateSimpleTable.java), +[Examples/CreateSimpleTable](Examples/runtimes/java/Migration/PlaintextToAWSDBE/src/main/java/software/amazon/cryptography/examples/plaintext/CreateSimpleTable.java), and want to store some objects. The security requirements for these objects involves classifying particular attributes as sensitive information. @@ -214,7 +214,7 @@ For example, ``` See -[EnhancedPlaintextPutGetExample](Examples/runtimes/java/DynamoDbEncryption/src/main/java/software/amazon/cryptography/examples/enhanced/EnhancedPlaintextPutGetExample.java). +[EnhancedPlaintextPutGetExample](Examples/runtimes/java/Migration/PlaintextToAWSDBE/src/main/java/software/amazon/cryptography/examples/plaintext/EnhancedPlaintextPutGetExample.java). To enable transparent encryption and signing, create a keyring and a DynamoDbEncryptionInterceptor, From 77c655718540792b5addc7403d1a0b942b2e1839 Mon Sep 17 00:00:00 2001 From: texastony <5892063+texastony@users.noreply.github.com> Date: Wed, 31 May 2023 16:07:55 -0500 Subject: [PATCH 16/18] docs(README): fix MPL name --- README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 7bc19a812..bf51200e4 100644 --- a/README.md +++ b/README.md @@ -47,16 +47,16 @@ To use the DB-ESDK for DynamoDB in Java, you must have: 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). -* **Declared a Dependency on the DB-ESDK for DynamoDB in Java and it's dependencies** +* **Declare a Dependency on the DB-ESDK for DynamoDB in Java and it's dependencies** The DB-ESDK for DynamoDB in Java requires the DynamoDB, Dynamodb-Enhanced, and KMS clients from the AWS SDK for Java V2. - It also requires the AwsCryptographicMaterialProviders library. + It also requires the AWS Cryptographic Material Providers library. * **Via Gradle Kotlin** In a Gradle Java Project, add the following to the _dependencies_ section: ```kotlin implementation("software.amazon.cryptography:aws-database-encryption-sdk-dynamodb:3.0.0") - implementation("software.amazon.cryptography:AwsCryptographicMaterialProviders:1.0.0") + implementation("software.amazon.cryptography:aws-cryptographic-material-providers:1.0.0") implementation(platform("software.amazon.awssdk:bom:2.19.1")) implementation("software.amazon.awssdk:dynamodb") implementation("software.amazon.awssdk:dynamodb-enhanced") @@ -99,7 +99,7 @@ To use the DB-ESDK for DynamoDB in Java, you must have: software.amazon.cryptography - AwsCryptographicMaterialProviders + aws-cryptographic-material-providers 1.0.0 From d3e7920a2b2ec788977f9d440c20dedccdeadbbc Mon Sep 17 00:00:00 2001 From: texastony <5892063+texastony@users.noreply.github.com> Date: Wed, 31 May 2023 17:24:34 -0500 Subject: [PATCH 17/18] docs(README): remove example & fix optional deps --- README.md | 200 +++++++----------------------------------------------- 1 file changed, 23 insertions(+), 177 deletions(-) diff --git a/README.md b/README.md index bf51200e4..33499b6ea 100644 --- a/README.md +++ b/README.md @@ -48,18 +48,21 @@ To use the DB-ESDK for DynamoDB in Java, you must have: 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 DB-ESDK for DynamoDB in Java and it's dependencies** - The DB-ESDK for DynamoDB in Java requires the DynamoDB, - Dynamodb-Enhanced, and KMS clients from the AWS SDK for Java V2. + The DB-ESDK for DynamoDB in Java requires the Dynamodb-Enhanced client + from the AWS SDK for Java V2. It also requires the AWS Cryptographic Material Providers library. + The KMS and DynamoDB Clients are **optional** dependencies. + * **Via Gradle Kotlin** In a Gradle Java Project, add the following to the _dependencies_ section: ```kotlin implementation("software.amazon.cryptography:aws-database-encryption-sdk-dynamodb:3.0.0") implementation("software.amazon.cryptography:aws-cryptographic-material-providers:1.0.0") implementation(platform("software.amazon.awssdk:bom:2.19.1")) - implementation("software.amazon.awssdk:dynamodb") implementation("software.amazon.awssdk:dynamodb-enhanced") + // The following are optional: + implementation("software.amazon.awssdk:dynamodb") implementation("software.amazon.awssdk:kms") ``` @@ -84,14 +87,6 @@ To use the DB-ESDK for DynamoDB in Java, you must have: software.amazon.awssdk dynamodb-enhanced - - software.amazon.awssdk - dynamodb - - - software.amazon.awssdk - kms - software.amazon.cryptography aws-database-encryption-sdk-dynamodb @@ -102,6 +97,15 @@ To use the DB-ESDK for DynamoDB in Java, you must have: aws-cryptographic-material-providers 1.0.0 + + + software.amazon.awssdk + dynamodb + + + software.amazon.awssdk + kms + ... @@ -127,174 +131,16 @@ the AWS Database Encryption SDK for DynamoDB in Java. For help installing and using ACCP, see the [amazon-corretto-crypto-provider repository](https://github.com/corretto/amazon-corretto-crypto-provider). -## Configuring the DB-ESDK for DynamoDB in Java +## Using the DB-ESDK for DynamoDB in Java There are several ways to use the AWS Database Encryption SDK (DB-ESDK) for DynamoDB in Java. -More details are provided in the -[AWS Database Encryption SDK Developer Guide](https://docs.aws.amazon.com/database-encryption-sdk/latest/devguide/). -Also see the [Examples](Examples/runtimes/java/DynamoDbEncryption). - -### Using Annotations - -Suppose you have created a DynamoDB table via the request in -[Examples/CreateSimpleTable](Examples/runtimes/java/Migration/PlaintextToAWSDBE/src/main/java/software/amazon/cryptography/examples/plaintext/CreateSimpleTable.java), -and want to store some objects. -The security requirements for these objects involves classifying particular -attributes as sensitive information. -You can use annotations from the Enhanced DynamoDB Client and the DB-ESDK to define -the objects types and which fields are encrypted: - -```java -@DynamoDbBean -public class SimpleClass { - - private String partitionKey; - private int sortKey; - // The next three fields represent DynamoDB item attributes that we will perform cryptographic operations on. - - // attribute1: Encrypt the data and sign it for authenticity - private String attribute1; - // attribute2: Do not encrypt but sign for authenticity - private String attribute2; - // attribute3: Do not encrypt and do not sign - private String attribute3; - - @DynamoDbPartitionKey - @DynamoDbAttribute(value = "partition_key") - public String getPartitionKey() { return this.partitionKey; } - public void setPartitionKey(String partitionKey) { this.partitionKey = partitionKey; } - - @DynamoDbSortKey - @DynamoDbAttribute(value = "sort_key") - public int getSortKey() { return this.sortKey; } - public void setSortKey(int sortKey) { this.sortKey = sortKey; } - - @DynamoDbAttribute(value = "attribute1") - public String getAttribute1() { return this.attribute1; } - public void setAttribute1(String attribute1) { this.attribute1 = attribute1; } - - @DynamoDbEncryptionSignOnly - @DynamoDbAttribute(value = "attribute2") - public String getAttribute2() { return this.attribute2; } - public void setAttribute2(String attribute2) { this.attribute2 = attribute2; } - - @DynamoDbEncryptionDoNothing - @DynamoDbAttribute(value = "attribute3") - public String getAttribute3() { return this.attribute3; } - public void setAttribute3(String attribute3) { this.attribute3 = attribute3; } -} -``` - -As a typical use case of the [DynamoDBEnhancedClient][ddbenhanced], -you can easily save and retrieve a SimpleClass object -to and from Amazon DynamoDB _without encryption (nor signing)_. -For example, - -```java - // Create the DynamoDBEnhancedClient and our table - DynamoDbClient ddb = DynamoDbClient.builder()...build(); - DynamoDbEnhancedClient enhancedClient = DynamoDbEnhancedClient.builder() - .dynamoDbClient(ddb) - .build(); - final TableSchema tableSchema = TableSchema.fromBean(SimpleClass.class); - final DynamoDbTable table = enhancedClient.table(ddbTableName, tableSchema); - - // Save the unencrypted item to DynamoDB - SimpleClass itemToPut = new SimpleClass(); - itemToPut.setPartitionKey("anyKey"); - itemToPut.setSortKey(0); - itemToPut.setAttribute1("this is not encrypted"); - table.putItem(itemToPut); - - // Load the item back from DynamoDB - SimpleClass itemToGet = new SimpleClass(); - itemToGet.setPartitionKey("anyKey"); - itemToGet.setSortKey(0); - SimpleClass returnedItem = table.getItem(itemToGet); -``` - -See -[EnhancedPlaintextPutGetExample](Examples/runtimes/java/Migration/PlaintextToAWSDBE/src/main/java/software/amazon/cryptography/examples/plaintext/EnhancedPlaintextPutGetExample.java). - -To enable transparent encryption and signing, -create a keyring and a DynamoDbEncryptionInterceptor, -then add it to the client. -For example: - -```java - // Use an example KMS key for encrypting your data - String encryptingKmsKeyArn = ...; - - // Create encryption materials provider using your example KMS key - MaterialProviders matProv = MaterialProviders.builder() - .MaterialProvidersConfig(MaterialProvidersConfig.builder().build()) - .build(); - CreateAwsKmsMrkMultiKeyringInput keyringInput = CreateAwsKmsMrkMultiKeyringInput.builder() - .generator(encryptingKmsKeyArn) - .build(); - IKeyring kmsKeyring = matProv.CreateAwsKmsMrkMultiKeyring(keyringInput); - - - // Create your encrypted table config - Map tableConfigs = new HashMap<>(); - tableConfigs.put(ddbTableName, - DynamoDbEnhancedTableEncryptionConfig.builder() - .logicalTableName(ddbTableName) - .keyring(kmsKeyring) - .schemaOnEncrypt(tableSchema) - .allowedUnsignedAttributes(Arrays.asList("do_nothing")) - .build()); - - // Create an interceptor to pass into the DDB client - DynamoDbEncryptionInterceptor interceptor = - DynamoDbEnhancedClientEncryption.CreateDynamoDbEncryptionInterceptor( - CreateDynamoDbEncryptionInterceptorInput.builder() - .tableEncryptionConfigs(tableConfigs) - .build()); - - // Create the DDB client with our encryption interceptor - DynamoDbClient ddb = DynamoDbClient.builder() - .region(Region.US_WEST_2) - .overrideConfiguration( - ClientOverrideConfiguration.builder() - .addExecutionInterceptor(interceptor) - .build()) - .build(); - DynamoDbEnhancedClient enhancedClient = DynamoDbEnhancedClient.builder() - .dynamoDbClient(ddb) - .build(); - final DynamoDbTable table = enhancedClient.table(ddbTableName, tableSchema); - - // Save the encrypted item to DynamoDB - SimpleClass itemToPut = new SimpleClass(); - itemToPut.setPartitionKey("anyKey"); - itemToPut.setSortKey(0); - itemToPut.setAttribute1("this is encrypted client-side"); - table.putItem(itemToPut); - - // Load the item back from DynamoDB and decrypt client-side - SimpleClass itemToGet = new SimpleClass(); - itemToGet.setPartitionKey("anyKey"); - itemToGet.setSortKey(0); - SimpleClass returnedItem = table.getItem(itemToGet); -``` - -See -[EnhancedPutGetExample](Examples/runtimes/java/DynamoDbEncryption/src/main/java/software/amazon/cryptography/examples/enhanced/EnhancedPutGetExample.java) -for more context and description. - -# Development - -[//]: # (TODO: Post-GA? Development Instructions) -This repo contains several projects: -- `DynamoDbEncryption`: The implementation of the Database Encryption - SDK for DynamoDB in Java. -- A specification of this project exists at `specification`. -- `Examples`: Example projects that demonstrate use of - the features of the Database Encryption SDK for DynamoDB -- `TestVectors`: Project that encrypts and decrypts - a suite of DynamoDB items to validate the Database Encryption - SDK's cross-version compatibility +Please read the +[AWS Database Encryption SDK Developer Guide](https://docs.aws.amazon.com/database-encryption-sdk/latest/devguide/) +for guidance. +Also see the +[DynamoDbEncryption Examples](Examples/runtimes/java/DynamoDbEncryption) +and the +[Migration Examples](Examples/runtimes/java/Migration). # Contributing From 14bc6adf09feac59bea734d7d3e771c776631239 Mon Sep 17 00:00:00 2001 From: lavaleri <49660121+lavaleri@users.noreply.github.com> Date: Thu, 1 Jun 2023 17:15:37 -0700 Subject: [PATCH 18/18] Readme edits (#227) Co-authored-by: Kevin Lee <61167022+kumo-hiyori@users.noreply.github.com> --- README.md | 48 +++++++++++++++++++++--------------------------- 1 file changed, 21 insertions(+), 27 deletions(-) diff --git a/README.md b/README.md index 33499b6ea..2d676bbcc 100644 --- a/README.md +++ b/README.md @@ -1,18 +1,19 @@ # AWS Database Encryption SDK for DynamoDB in Java -The AWS Database Encryption SDK for DynamoDB in Java -provides client-side encryption and signing of Amazon DynamoDB items -to help you protect your table's data before you send it to DynamoDB. +The AWS Database Encryption SDK (DB-ESDK) for DynamoDB in Java is a client-side encryption +library that allows you to perform attribute-level encryption, enabling you to encrypt specific +attribute values within items before storing them in your DynamoDB table. All encryption and +decryption are performed within your application. This lets you protect sensitive data in-transit +and at-rest, as data cannot be exposed unless decrypted by your application. -For more details about the design and architecture of the -AWS Database Encryption SDK (DB-ESDK) for DynamoDB, +For more details about the design and architecture of the DB-ESDK for DynamoDB, see the [AWS Database Encryption SDK Developer Guide](https://docs.aws.amazon.com/database-encryption-sdk/latest/devguide/). # Security If you discover a potential security issue in this project we ask that you notify AWS/Amazon Security via our [vulnerability reporting page](http://aws.amazon.com/security/vulnerability-reporting/). -Please do **not** create a public GitHub issue. +Please **do not** create a public GitHub issue. # Support Policy See [Support Policy](./SUPPORT_POLICY.rst) for details @@ -30,6 +31,7 @@ submitting pull requests through the following channels: * Articulate your [feature request](https://github.com/aws/aws-database-encryption-sdk-dynamodb-java/issues?q=is%3Aopen+is%3Aissue+label%3A%22feature-request%22) or upvote existing ones +* Ask [questions](https://repost.aws/tags/TAc3VKZnkNQyimpHnCHetNOQ/aws-crypto-tools) on AWS re:Post under AWS Crypto Tools tag # Getting Started @@ -37,7 +39,6 @@ submitting pull requests through the following channels: To use the DB-ESDK for DynamoDB in Java, you must have: * **A Java 8 or newer development environment** - If you do not have one, go to [Java SE Downloads](https://www.oracle.com/technetwork/java/javase/downloads/index.html) on the Oracle website, then download and install the Java SE Development Kit (JDK). @@ -48,11 +49,12 @@ To use the DB-ESDK for DynamoDB in Java, you must have: 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 DB-ESDK for DynamoDB in Java and it's dependencies** - The DB-ESDK for DynamoDB in Java requires the Dynamodb-Enhanced client - from the AWS SDK for Java V2. - It also requires the AWS Cryptographic Material Providers library. + This library requires the DynamoDB client + from the AWS SDK for Java V2 + and the AwsCryptographicMaterialProviders library. - The KMS and DynamoDB Clients are **optional** dependencies. + The KMS and DynamoDB-Enhanced Clients from the AWS SDK For Java V2 + are **optional** dependencies. * **Via Gradle Kotlin** In a Gradle Java Project, add the following to the _dependencies_ section: @@ -112,35 +114,27 @@ To use the DB-ESDK for DynamoDB in Java, you must have: ``` ### AWS Integration -You need an Amazon Web Services (AWS) account to use -the AWS Database Encryption SDK for DynamoDB -(a KMS Key is optional). +You need an Amazon Web Services (AWS) account to use the DB-ESDK for DynamoDB as it's specifically designed to work with Amazon DynamoDB. Optionally, you can use AWS Key Management Service (AWS KMS) as your main keyring provider. * **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 key in AWS KMS**, see +* **(Optional) 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 Database Encryption SDK for DynamoDB in Java. +Many developers find that the Amazon Corretto Crypto Provider (ACCP) +significantly improves the performance of the library. For help installing and using ACCP, see the [amazon-corretto-crypto-provider repository](https://github.com/corretto/amazon-corretto-crypto-provider). ## Using the DB-ESDK for DynamoDB in Java -There are several ways to use the -AWS Database Encryption SDK (DB-ESDK) for DynamoDB in Java. -Please read the -[AWS Database Encryption SDK Developer Guide](https://docs.aws.amazon.com/database-encryption-sdk/latest/devguide/) -for guidance. -Also see the -[DynamoDbEncryption Examples](Examples/runtimes/java/DynamoDbEncryption) -and the -[Migration Examples](Examples/runtimes/java/Migration). +There are several ways to use the library. +More details are provided in the +[AWS Database Encryption SDK Developer Guide](https://docs.aws.amazon.com/database-encryption-sdk/latest/devguide/). +Also see the [Examples](Examples/runtimes/java/DynamoDbEncryption). # Contributing