chore: Update READMEs, create top-level project READMEs

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.

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 Java 8 or newer development environment
 
 #### (Optional) Dafny Report Generator Requirements
 

Examples/runtimes/java/DynamoDbEncryption/README.md

@@ -1,3 +1,43 @@
 # AWS Database Encryption SDK for DynamoDb Java Examples
 
 This project contains examples for using the AWS Database Encryption SDK for DynamoDb in Java. 
+
+Overview:
+
+```
+├── ..
+├── 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
+```
+
+## 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.
+

Examples/runtimes/java/Migration/PlaintextToAWSDBE/src/main/java/software/amazon/cryptography/examples/plaintext/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.plaintext;
+
+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()));
+        }
+    }
+}

Examples/runtimes/java/Migration/PlaintextToAWSDBE/src/main/java/software/amazon/cryptography/examples/plaintext/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.plaintext;
+
+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<SimpleClass> tableSchema = TableSchema.fromBean(SimpleClass.class);
+        final DynamoDbTable<SimpleClass> 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);
+    }
+}

Examples/runtimes/java/Migration/README.md

@@ -1,14 +1,27 @@
 # DynamoDb Encryption Client to AWS Database Encryption SDK for DynamoDb Migration
 
-This project contains example projects demonstrating how to safely upgrade
-from different configurations to the AWS Database Encryption SDK for DynamoDb (v3.0.0).
+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).
 
-File directory:
+## Getting Started
 
-```
-.
-├── DDBECToAWSDBE - Example for upgrading from the DynamoDb Encryption Client (v2.0.1) to DB ESDK
-└── PlaintextToAWSDBE - Example for setting up DB ESDK on a plaintext DDB table
-```
+### 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.
 

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
+```

README.md

@@ -1,20 +1,153 @@
-## 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.
 
-### Development
+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/).
 
-This repo contains several projects:
-- DynamoDbEncryption: Contains the implementation of the DynamoDb Encryption Client in all target languages
-- TODO test vectors
-- TODO examples
+# 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.
 
-A specification of all these projects exists at `specification`.
+# Support Policy
+See [Support Policy](./SUPPORT_POLICY.rst) for details 
+on the current support status of all major versions of this library.
 
-## Security
+## 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:
 
-See [CONTRIBUTING](CONTRIBUTING.md#security-issue-notifications) for more information.
+* 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
 
-## License
+# Getting Started
+
+## 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.
+
+  **Note:** If you use the Oracle JDK, 
+  you must also download and install 
+  the [Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files](http://www.oracle.com/technetwork/java/javase/downloads/jce8-download-2133166.html).
+
+* **Declare a Dependency on the 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.
+
+  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-enhanced")
+   // The following are optional:
+   implementation("software.amazon.awssdk:dynamodb")
+   implementation("software.amazon.awssdk:kms")
+   ```
+
+  * **Via Apache Maven**  
+  Add the following to your project's `pom.xml`.
+  ```xml
+  <project>
+  ...
+  <dependencyManagement>
+   <dependencies>
+      <dependency>
+        <groupId>software.amazon.awssdk</groupId>
+        <artifactId>bom</artifactId>
+        <version>2.19.1</version>
+        <type>pom</type>
+        <scope>import</scope>
+      </dependency>
+   </dependencies>
+  </dependencyManagement>
+  <dependencies>
+    <dependency>
+      <groupId>software.amazon.awssdk</groupId>
+      <artifactId>dynamodb-enhanced</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>software.amazon.cryptography</groupId>
+      <artifactId>aws-database-encryption-sdk-dynamodb</artifactId>
+      <version>3.0.0</version>
+    </dependency>
+    <dependency>
+      <groupId>software.amazon.cryptography</groupId>
+      <artifactId>aws-cryptographic-material-providers</artifactId>
+      <version>1.0.0</version>
+    </dependency>
+    <!-- The following are optional -->
+    <dependency>
+      <groupId>software.amazon.awssdk</groupId>
+      <artifactId>dynamodb</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>software.amazon.awssdk</groupId>
+      <artifactId>kms</artifactId>
+    </dependency>
+  </dependencies>
+  ...
+  </project>
+  ```
+
+### 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).
+
+### 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).
+
+## 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).
+
+# Contributing
+
+See [CONTRIBUTING](CONTRIBUTING.md) for more information.
+
+# License
 
 This project is licensed under the Apache-2.0 License.
+
+[ddbenhanced]: https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/dynamodb-enhanced-client.html