-
Notifications
You must be signed in to change notification settings - Fork 8
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
docs(README): update README for repo rename update (#147)
- Loading branch information
1 parent
98a16a8
commit 6d505b4
Showing
3 changed files
with
222 additions
and
0 deletions.
There are no files selected for viewing
118 changes: 118 additions & 0 deletions
118
AwsCryptographicMaterialProviders/runtimes/java/README.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,118 @@ | ||
# AWS Cryptographic Material Providers Library | ||
|
||
The AWS Cryptographic Material Providers Library abstracts lower level cryptographic materials management of encryption and decryption materials. | ||
It uses cryptographic best practices to protect the data keys that protect your data. | ||
The data key is protected with a key encryption key called a _wrapping key_. | ||
The encryption method returns the data key and one or more encrypted data keys. | ||
Supported libraries use this information to perform envelope encryption. | ||
The data key is used to protect your data, | ||
and the encrypted data keys are stored alongside your data | ||
so you don't need to keep track of the data keys separately. | ||
You can use AWS KMS keys in [AWS Key Management Service](https://aws.amazon.com/kms/)(AWS KMS) as wrapping keys. | ||
The AWS Cryptographic Material Providers Library | ||
also provides APIs to define and use wrapping keys from other key providers. | ||
|
||
The AWS Cryptographic Material Providers Library provides methods for encrypting and decrypting cryptographic materials used in higher level client side encryption libraries. | ||
|
||
[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. | ||
|
||
## Getting Started | ||
|
||
### Repository structure | ||
|
||
This repository is a top level repository which houses all source code in order to compile this library into | ||
different runtimes. | ||
|
||
This library is written in Dafny, a formally verifiable programming language that can be compiled into | ||
different runtimes. This library is currently **ONLY** supported in Java and .NET | ||
|
||
### Required Prerequisites | ||
|
||
To use the AWS Material Providers Library 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 AWS Material Providers Library in Java and it's dependencies** | ||
This library requires the DynamoDB and KMS clients | ||
from the AWS SDK for Java V2 | ||
|
||
- **Via Gradle Kotlin** | ||
In a Gradle Java Project, add the following to the _dependencies_ section: | ||
|
||
```kotlin | ||
implementation("software.amazon.cryptography:aws-cryptographic-material-providers:1.0.2") | ||
implementation(platform("software.amazon.awssdk:bom:2.19.1")) | ||
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</artifactId> | ||
</dependency> | ||
<dependency> | ||
<groupId>software.amazon.awssdk</groupId> | ||
<artifactId>kms</artifactId> | ||
</dependency> | ||
<dependency> | ||
<groupId>software.amazon.cryptography</groupId> | ||
<artifactId>aws-cryptographic-material-providers</artifactId> | ||
<version>1.0.2</version> | ||
</dependency> | ||
</dependencies> | ||
... | ||
</project> | ||
``` | ||
### Optional Prerequisites | ||
#### AWS Integration | ||
You don't need an Amazon Web Services (AWS) account to use the AWS Cryptographic Material Providers Library, | ||
but some APIs require an AWS account, an AWS KMS key, or an Amazon DynamoDB Table. | ||
If you are using the AWS Cryptographic Material Providers Library for Java you will need the AWS SDK for Java V2. | ||
|
||
**NOTE**: The `KmsAsyncClient` and `DynamoDBAsyncClient` are not supported, only the synchronous clients. | ||
|
||
- **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). | ||
|
||
## FAQ | ||
|
||
See the [Frequently Asked Questions](https://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/faq.html) page in the official documentation. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,94 @@ | ||
# AWS Cryptographic Material Providers Library for .NET | ||
|
||
The AWS Cryptographic Material Providers Library abstracts lower level cryptographic materials management of encryption and decryption materials. | ||
It uses cryptographic best practices to protect the data keys that protect your data. | ||
The data key is protected with a key encryption key called a _wrapping key_. | ||
The encryption method returns the data key and one or more encrypted data keys. | ||
Supported libraries use this information to perform envelope encryption. | ||
The data key is used to protect your data, | ||
and the encrypted data keys are stored alongside your data | ||
so you don't need to keep track of the data keys separately. | ||
You can use AWS KMS keys in [AWS Key Management Service](https://aws.amazon.com/kms/)(AWS KMS) as wrapping keys. | ||
The AWS Cryptographic Material Providers Library | ||
also provides APIs to define and use wrapping keys from other key providers. | ||
|
||
The AWS Cryptographic Material Providers Library for .NET provides methods for encrypting and decrypting cryptographic materials used in higher level client side encryption libraries. | ||
|
||
## 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. | ||
|
||
## Getting Started | ||
|
||
### Required Prerequisites | ||
|
||
To use the AWS Cryptographic Material Providers Library for .NET you must have: | ||
|
||
- **A .NET Framework 6.0 development environment** | ||
|
||
If you do not have it installed, you can find installation instructions [here](https://dotnet.microsoft.com/en-us/download/dotnet/6.0). | ||
|
||
- **Bouncy Castle** | ||
|
||
The AWS Cryptographic Material Providers Library for .NET uses Bouncy Castle for the underlying cryptography and to serialize and deserialize cryptographic objects. | ||
|
||
If you do not have Bouncy Castle, go to https://www.bouncycastle.org/csharp/ to learn more. | ||
You can also download it from NuGet | ||
|
||
``` | ||
<PackageReference Include="BouncyCastle.Cryptography" Version="2.2.1" /> | ||
``` | ||
|
||
### Optional Prerequisites | ||
|
||
#### AWS Integration | ||
|
||
You don't need an Amazon Web Services (AWS) account to use the AWS Cryptographic Material Providers Library, | ||
but some APIs require an AWS account, an AWS KMS key, or an AWS DynamoDB Table. | ||
However, all APIs require the AWS SDK for .NET V3. | ||
|
||
Note that `Async AmazonKeyManagementServiceClient` and `Async DynamoDBAsyncClient` methods are not supported, only the synchronous methods. | ||
|
||
- **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 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 .NET 3.x**, see [Installing the AWS SDK for .NET 3.x](https://docs.aws.amazon.com/sdk-for-net/v3/developer-guide/net-dg-install-assemblies.html). | ||
|
||
### Download the AWS Cryptographic Material Providers Library for .NET | ||
|
||
The AWS Cryptographic Material Providers Library for .NET is available on NuGet and can be referenced | ||
from an existing .csproj. | ||
|
||
Using the dotnet CLI: | ||
|
||
```shell | ||
dotnet add <your-project-name>.csproj package AWS.Cryptography.MaterialProviders | ||
``` | ||
|
||
Alternatively, you may directly modify the `.csproj` and add the | ||
AWS Cryptographic Material Providers Library to `PackageReference` `ItemGroup`: | ||
|
||
```xml | ||
<PackageReference Include="AWS.Cryptography.MaterialProviders" /> | ||
``` | ||
|
||
The AWS Cryptographic Material Providers Library targets: | ||
|
||
- [.NET Framework](https://docs.microsoft.com/en-us/dotnet/framework/) 4.8. | ||
- [.NET](https://learn.microsoft.com/en-us/dotnet/core/whats-new/dotnet-6) 6.0. | ||
- [.NET Standard](https://learn.microsoft.com/en-us/dotnet/standard/net-standard?tabs=net-standard-2-0) 2.0. | ||
|
||
### Additional setup for macOS only | ||
|
||
If you are using macOS then you must install OpenSSL 1.1, | ||
and the OpenSSL 1.1 `lib` directory must be on the dynamic linker path at runtime. | ||
Also, if using an M1-based Mac, you must install OpenSSL and the .NET SDK for x86-64. | ||
Please refer to [this wiki](https://github.com/aws/aws-encryption-sdk-dafny/wiki/Using-the-AWS-Encryption-SDK-for-.NET-on-macOS) for detailed instructions. | ||
|
||
## License | ||
|
||
This library is licensed under the Apache 2.0 License. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters