Skip to content

Commit 2c1f31a

Browse files
lucasmcdonald3lucasmcdonald3
authored
chore: Update READMEs, create top-level project READMEs (#221)
1 parent 248b684 commit 2c1f31a

File tree

10 files changed

+357
-23
lines changed

10 files changed

+357
-23
lines changed

Diff for: ‎CONTRIBUTING.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -56,4 +56,4 @@ If you discover a potential security issue in this project we ask that you notif
5656

5757
## Licensing
5858

59-
See the [LICENSE](LICENSE) file for our project's licensing. We will ask you to confirm the licensing of your contribution.
59+
See the [LICENSE](LICENSE.txt) file for our project's licensing. We will ask you to confirm the licensing of your contribution.

Diff for: ‎DynamoDbEncryption/README.md

+6-3
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,10 @@
1-
## DynamoDb Encryption
1+
## DynamoDbEncryption
2+
3+
This project implements the AWS Database Encryption SDK for DynamoDB.
24

35
### Code Organization
46

5-
DynamoDb Encryption is a project containing the following Dafny 'localServices' under `dafny`:
7+
DynamoDbEncryption is a project containing the following Dafny 'localServices' under `dafny`:
68
- DynamoDbEncryption: A config-less entry point for shared structures and helper methods related to DDB Encryption.
79
- DynamoDbItemEncryptor: A client responsible for the encryption and decryption of DDB Items (sans any DDB API call).
810
- DynamoDbEncryptionTransforms: An internal interface responsible for appropriately adding encryption to DDB APIs.
@@ -63,7 +65,8 @@ Common Makefile targets are:
6365

6466
### Development Requirements
6567

66-
TODO
68+
* Dafny 4.1.0: https://github.com/dafny-lang/dafny
69+
* A Java 8 or newer development environment
6770

6871
#### (Optional) Dafny Report Generator Requirements
6972

Diff for: ‎Examples/runtimes/java/DynamoDbEncryption/README.md

+40
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,43 @@
11
# AWS Database Encryption SDK for DynamoDb Java Examples
22

33
This project contains examples for using the AWS Database Encryption SDK for DynamoDb in Java.
4+
5+
Overview:
6+
7+
```
8+
├── ..
9+
├── src
10+
│ ├── main/java/software/amazon/cryptography/examples: Examples source
11+
│ │ ├── BasicPutGetExample: Example using AWS DB ESDK to Put and Get an encrypted item from DynamoDB
12+
│ │ ├── CreateKeyStoreTableExample: Example creating a Keystore DynamoDB table for use with a hierarchical keyring
13+
│ │ ├── CreateKeyStoreKeyExample: Example creating a branch key in a Keystore DynamoDB table
14+
│ │ ├── clientsupplier: Examples using a custom KMS ClientSupplier
15+
│ │ ├── enhanced: Examples using the DynamoDbEnhancedClient
16+
│ │ ├── itemencryptor: Examples using the DynamoDbItemEncryptor
17+
│ │ ├── keyring: Examples creating and using different keyrings
18+
│ │ └── searchableencryption: Examples demonstrating searchable encryption configuration and usage
19+
└── └── test: Our tests that run these examples
20+
```
21+
22+
## Getting Started
23+
24+
### Development Requirements
25+
26+
* A Java 8 or newer development environment
27+
28+
### Building and Running
29+
30+
Each example includes a runnable `main` method
31+
and a description of the required command line arguments.
32+
To run a given example, inspect its particular setup requirements,
33+
create and/or grant access to any required AWS resources,
34+
and run the example as specified in the file.
35+
36+
## Security
37+
38+
See [CONTRIBUTING](CONTRIBUTING.md#security-issue-notifications) for more information.
39+
40+
## License
41+
42+
This project is licensed under the Apache-2.0 License.
43+

Diff for: ‎Examples/runtimes/java/Migration/PlaintextToAWSDBE/src/main/java/software/amazon/cryptography/examples/plaintext/CreateSimpleTable.java

+49
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
// Copyright Amazon.com Inc. or its affiliates. All Rights Reserved.
2+
// SPDX-License-Identifier: Apache-2.0
3+
package software.amazon.cryptography.examples.plaintext;
4+
5+
import software.amazon.awssdk.services.dynamodb.DynamoDbClient;
6+
import software.amazon.awssdk.services.dynamodb.model.AttributeDefinition;
7+
import software.amazon.awssdk.services.dynamodb.model.CreateTableRequest;
8+
import software.amazon.awssdk.services.dynamodb.model.CreateTableResponse;
9+
import software.amazon.awssdk.services.dynamodb.model.KeySchemaElement;
10+
import software.amazon.awssdk.services.dynamodb.model.KeyType;
11+
import software.amazon.awssdk.services.dynamodb.model.ScalarAttributeType;
12+
13+
/**
14+
* This class is referenced by the README.
15+
*/
16+
@SuppressWarnings("unused")
17+
public class CreateSimpleTable {
18+
19+
public static void Create(DynamoDbClient ddbClient, String ddbTableName) {
20+
CreateTableRequest request = CreateTableRequest.builder()
21+
.tableName(ddbTableName)
22+
.keySchema(
23+
KeySchemaElement.builder()
24+
.keyType(KeyType.HASH)
25+
.attributeName("partition_key")
26+
.build(),
27+
KeySchemaElement.builder()
28+
.keyType(KeyType.RANGE)
29+
.attributeName("sort_key")
30+
.build())
31+
.attributeDefinitions(
32+
AttributeDefinition.builder()
33+
.attributeName("partition_key")
34+
.attributeType(ScalarAttributeType.S)
35+
.build(),
36+
AttributeDefinition.builder()
37+
.attributeName("sort_key")
38+
.attributeType(ScalarAttributeType.N)
39+
.build())
40+
.build();
41+
CreateTableResponse response = ddbClient.createTable(request);
42+
if (!response.sdkHttpResponse().isSuccessful()) {
43+
throw new RuntimeException(
44+
String.format(
45+
"Create Table Failed. HTTP response: %s",
46+
response.sdkHttpResponse()));
47+
}
48+
}
49+
}

Diff for: ‎Examples/runtimes/java/Migration/PlaintextToAWSDBE/src/main/java/software/amazon/cryptography/examples/plaintext/EnhancedPlaintextPutGetExample.java

+35
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
// Copyright Amazon.com Inc. or its affiliates. All Rights Reserved.
2+
// SPDX-License-Identifier: Apache-2.0
3+
package software.amazon.cryptography.examples.plaintext;
4+
5+
import software.amazon.awssdk.enhanced.dynamodb.DynamoDbEnhancedClient;
6+
import software.amazon.awssdk.enhanced.dynamodb.DynamoDbTable;
7+
import software.amazon.awssdk.enhanced.dynamodb.TableSchema;
8+
import software.amazon.awssdk.services.dynamodb.DynamoDbClient;
9+
10+
/**
11+
* This class is referenced by the README.
12+
*/
13+
@SuppressWarnings("unused")
14+
public class EnhancedPlaintextPutGetExample {
15+
public static void PutItemGetItem(DynamoDbClient ddb, String ddbTableName) {
16+
DynamoDbEnhancedClient enhancedClient = DynamoDbEnhancedClient.builder()
17+
.dynamoDbClient(ddb)
18+
.build();
19+
20+
final TableSchema<SimpleClass> tableSchema = TableSchema.fromBean(SimpleClass.class);
21+
final DynamoDbTable<SimpleClass> table = enhancedClient.table(ddbTableName, tableSchema);
22+
23+
SimpleClass itemToPut = new SimpleClass();
24+
itemToPut.setPartitionKey("anyKey");
25+
itemToPut.setSortKey(0);
26+
itemToPut.setAttribute1("this is not encrypted");
27+
table.putItem(itemToPut);
28+
29+
// Load the item back from DynamoDB
30+
SimpleClass itemToGet = new SimpleClass();
31+
itemToGet.setPartitionKey("anyKey");
32+
itemToGet.setSortKey(0);
33+
SimpleClass returnedItem = table.getItem(itemToGet);
34+
}
35+
}

Diff for: ‎Examples/runtimes/java/Migration/README.md

+21-8
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,27 @@
11
# DynamoDb Encryption Client to AWS Database Encryption SDK for DynamoDb Migration
22

3-
This project contains example projects demonstrating how to safely upgrade
4-
from different configurations to the AWS Database Encryption SDK for DynamoDb (v3.0.0).
3+
This project contains an example project demonstrating how to safely upgrade
4+
from the DynamoDb Encryption Client (v2.0.1) to the AWS Database Encryption SDK for DynamoDb (v3.0.0).
55

6-
File directory:
6+
## Getting Started
77

8-
```
9-
.
10-
├── DDBECToAWSDBE - Example for upgrading from the DynamoDb Encryption Client (v2.0.1) to DB ESDK
11-
└── PlaintextToAWSDBE - Example for setting up DB ESDK on a plaintext DDB table
12-
```
8+
### Development Requirements
139

10+
* A Java 8 or newer development environment
11+
12+
### Building and Running
13+
14+
Each example includes a runnable `main` method
15+
and a description of the required command line arguments.
16+
To run a given example, inspect its particular setup requirements,
17+
create and/or grant access to any required AWS resources,
18+
and run the example as specified in the file.
19+
20+
## Security
21+
22+
See [CONTRIBUTING](CONTRIBUTING.md#security-issue-notifications) for more information.
23+
24+
## License
25+
26+
This project is licensed under the Apache-2.0 License.
1427

Diff for: ‎Examples/runtimes/java/README.md

+9
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
## Examples (Java)
2+
3+
This project contains examples demonstrating how to use the AWS Database Encryption SDK.
4+
5+
```
6+
├── ..
7+
├── DynamoDbEncryption: Examples for using features in the AWS Database Encryption SDK
8+
└── Migration: Examples for migrating from a plaintext table or the DynamoDB Encryption Client 2.0 to AWS DB ESDK
9+
```

Diff for: ‎README.md

+138-11
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,147 @@
1-
## DynamoDB Encryption Client for Dafny
1+
# AWS Database Encryption SDK for DynamoDB in Java
22

3-
TODO landing page info for the DDBEC.
3+
The AWS Database Encryption SDK (DB-ESDK) for DynamoDB in Java is a client-side encryption
4+
library that allows you to perform attribute-level encryption, enabling you to encrypt specific
5+
attribute values within items before storing them in your DynamoDB table. All encryption and
6+
decryption are performed within your application. This lets you protect sensitive data in-transit
7+
and at-rest, as data cannot be exposed unless decrypted by your application.
48

5-
### Development
9+
For more details about the design and architecture of the DB-ESDK for DynamoDB,
10+
see the [AWS Database Encryption SDK Developer Guide](https://docs.aws.amazon.com/database-encryption-sdk/latest/devguide/).
611

7-
This repo contains several projects:
8-
- DynamoDbEncryption: Contains the implementation of the DynamoDb Encryption Client in all target languages
9-
- TODO test vectors
10-
- TODO examples
12+
# Security
13+
If you discover a potential security issue in this project
14+
we ask that you notify AWS/Amazon Security via our
15+
[vulnerability reporting page](http://aws.amazon.com/security/vulnerability-reporting/).
16+
Please **do not** create a public GitHub issue.
1117

12-
A specification of all these projects exists at `specification`.
18+
# Support Policy
19+
See [Support Policy](./SUPPORT_POLICY.rst) for details
20+
on the current support status of all major versions of this library.
1321

14-
## Security
22+
## Giving Feedback
23+
We need your help in making this SDK great.
24+
Please participate in the community and contribute to this effort by
25+
submitting issues,
26+
participating in discussion forums and
27+
submitting pull requests through the following channels:
1528

16-
See [CONTRIBUTING](CONTRIBUTING.md#security-issue-notifications) for more information.
29+
* Submit [issues](https://github.com/aws/aws-database-encryption-sdk-dynamodb-java/issues)
30+
\- this is the **preferred** channel to interact with our team
31+
* Articulate your
32+
[feature request](https://github.com/aws/aws-database-encryption-sdk-dynamodb-java/issues?q=is%3Aopen+is%3Aissue+label%3A%22feature-request%22)
33+
or upvote existing ones
34+
* Ask [questions](https://repost.aws/tags/TAc3VKZnkNQyimpHnCHetNOQ/aws-crypto-tools) on AWS re:Post under AWS Crypto Tools tag
1735

18-
## License
36+
# Getting Started
37+
38+
## Required Prerequisites
39+
To use the DB-ESDK for DynamoDB in Java, you must have:
40+
41+
* **A Java 8 or newer development environment**
42+
If you do not have one,
43+
go to [Java SE Downloads](https://www.oracle.com/technetwork/java/javase/downloads/index.html) on the Oracle website,
44+
then download and install the Java SE Development Kit (JDK).
45+
Java 8 or higher is required.
46+
47+
**Note:** If you use the Oracle JDK,
48+
you must also download and install
49+
the [Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files](http://www.oracle.com/technetwork/java/javase/downloads/jce8-download-2133166.html).
50+
51+
* **Declare a Dependency on the DB-ESDK for DynamoDB in Java and it's dependencies**
52+
This library requires the DynamoDB client
53+
from the AWS SDK for Java V2
54+
and the AwsCryptographicMaterialProviders library.
55+
56+
The KMS and DynamoDB-Enhanced Clients from the AWS SDK For Java V2
57+
are **optional** dependencies.
58+
59+
* **Via Gradle Kotlin**
60+
In a Gradle Java Project, add the following to the _dependencies_ section:
61+
```kotlin
62+
implementation("software.amazon.cryptography:aws-database-encryption-sdk-dynamodb:3.0.0")
63+
implementation("software.amazon.cryptography:aws-cryptographic-material-providers:1.0.0")
64+
implementation(platform("software.amazon.awssdk:bom:2.19.1"))
65+
implementation("software.amazon.awssdk:dynamodb-enhanced")
66+
// The following are optional:
67+
implementation("software.amazon.awssdk:dynamodb")
68+
implementation("software.amazon.awssdk:kms")
69+
```
70+
71+
* **Via Apache Maven**
72+
Add the following to your project's `pom.xml`.
73+
```xml
74+
<project>
75+
...
76+
<dependencyManagement>
77+
<dependencies>
78+
<dependency>
79+
<groupId>software.amazon.awssdk</groupId>
80+
<artifactId>bom</artifactId>
81+
<version>2.19.1</version>
82+
<type>pom</type>
83+
<scope>import</scope>
84+
</dependency>
85+
</dependencies>
86+
</dependencyManagement>
87+
<dependencies>
88+
<dependency>
89+
<groupId>software.amazon.awssdk</groupId>
90+
<artifactId>dynamodb-enhanced</artifactId>
91+
</dependency>
92+
<dependency>
93+
<groupId>software.amazon.cryptography</groupId>
94+
<artifactId>aws-database-encryption-sdk-dynamodb</artifactId>
95+
<version>3.0.0</version>
96+
</dependency>
97+
<dependency>
98+
<groupId>software.amazon.cryptography</groupId>
99+
<artifactId>aws-cryptographic-material-providers</artifactId>
100+
<version>1.0.0</version>
101+
</dependency>
102+
<!-- The following are optional -->
103+
<dependency>
104+
<groupId>software.amazon.awssdk</groupId>
105+
<artifactId>dynamodb</artifactId>
106+
</dependency>
107+
<dependency>
108+
<groupId>software.amazon.awssdk</groupId>
109+
<artifactId>kms</artifactId>
110+
</dependency>
111+
</dependencies>
112+
...
113+
</project>
114+
```
115+
116+
### AWS Integration
117+
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.
118+
119+
* **To create an AWS account**, go to
120+
[Sign In or Create an AWS Account](https://portal.aws.amazon.com/gp/aws/developer/registration/index.html)
121+
and then choose **I am a new user.**
122+
Follow the instructions to create an AWS account.
123+
124+
* **(Optional) To create a key in AWS KMS**, see
125+
[Creating Keys](https://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html).
126+
127+
### Amazon Corretto Crypto Provider
128+
Many developers find that the Amazon Corretto Crypto Provider (ACCP)
129+
significantly improves the performance of the library.
130+
For help installing and using ACCP, see the
131+
[amazon-corretto-crypto-provider repository](https://github.com/corretto/amazon-corretto-crypto-provider).
132+
133+
## Using the DB-ESDK for DynamoDB in Java
134+
There are several ways to use the library.
135+
More details are provided in the
136+
[AWS Database Encryption SDK Developer Guide](https://docs.aws.amazon.com/database-encryption-sdk/latest/devguide/).
137+
Also see the [Examples](Examples/runtimes/java/DynamoDbEncryption).
138+
139+
# Contributing
140+
141+
See [CONTRIBUTING](CONTRIBUTING.md) for more information.
142+
143+
# License
19144

20145
This project is licensed under the Apache-2.0 License.
146+
147+
[ddbenhanced]: https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/dynamodb-enhanced-client.html

Diff for: ‎SUPPORT_POLICY.rst

+29
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
Overview
2+
========
3+
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.
4+
5+
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.
6+
7+
8+
Major Version Lifecycle
9+
========================
10+
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`_.
11+
12+
Version Support Matrix
13+
======================
14+
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.
15+
16+
.. list-table::
17+
:widths: 30 50 50 50
18+
:header-rows: 1
19+
20+
* - Major version
21+
- Current status
22+
- Next status
23+
- Next status date
24+
* - 3.x
25+
- General Availability
26+
-
27+
-
28+
29+
.. _AWS SDKs and Tools Maintenance Policy: https://docs.aws.amazon.com/sdkref/latest/guide/maint-policy.html#version-life-cycle

0 commit comments

Comments
 (0)