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,147 @@
-## 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 (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.
 
-### Development
+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/).
 
-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
+* Ask [questions](https://repost.aws/tags/TAc3VKZnkNQyimpHnCHetNOQ/aws-crypto-tools) on AWS re:Post under AWS Crypto Tools tag
 
-## 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**  
+  This library requires the DynamoDB client
+  from the AWS SDK for Java V2
+  and the AwsCryptographicMaterialProviders library.
+
+  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:
+   ```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 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.
+
+* **(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 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 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
+
+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

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