diff --git a/AwsCryptographicMaterialProviders/runtimes/java/README.md b/AwsCryptographicMaterialProviders/runtimes/java/README.md new file mode 100644 index 000000000..04277c696 --- /dev/null +++ b/AwsCryptographicMaterialProviders/runtimes/java/README.md @@ -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 + + ... + + + + software.amazon.awssdk + bom + 2.19.1 + pom + import + + + + + + software.amazon.awssdk + dynamodb + + + software.amazon.awssdk + kms + + + software.amazon.cryptography + aws-cryptographic-material-providers + 1.0.2 + + + ... + + ``` + +### 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. diff --git a/AwsCryptographicMaterialProviders/runtimes/net/README.md b/AwsCryptographicMaterialProviders/runtimes/net/README.md new file mode 100644 index 000000000..7f95224e9 --- /dev/null +++ b/AwsCryptographicMaterialProviders/runtimes/net/README.md @@ -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 + + ``` + + ``` + +### 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 .csproj package AWS.Cryptography.MaterialProviders +``` + +Alternatively, you may directly modify the `.csproj` and add the +AWS Cryptographic Material Providers Library to `PackageReference` `ItemGroup`: + +```xml + +``` + +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. diff --git a/README.md b/README.md index b12c240a6..68ecc7192 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,9 @@ # AWS Cryptographic Material Providers Library +📣 Note: This repository contains the source code and related files for all +language implementations of the AWS Cryptographic Material Providers Library. +See our [supported languages](#supported-languages) section for more information. + 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_. @@ -51,6 +55,12 @@ If you are using the AWS Cryptographic Material Providers Library for .NET you w - **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 .Net 3.x** see [Installing the AWS SDK for .Net v3](https://docs.aws.amazon.com/sdk-for-net/v3/developer-guide/welcome.html) +## Supported Languages + +- Java +- .NET +- Dafny + ## FAQ See the [Frequently Asked Questions](https://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/faq.html) page in the official documentation.