Note: The AWS Cryptographic Material Providers Library is released as a developer preview and is subject to change. The current release is not intended to be used in production environments.
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 or master 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(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 Java provides methods for encrypting and decrypting cryptographic materials used in higher level client side encryption libraries.
If you discover a potential security issue in this project we ask that you notify AWS/Amazon Security via our vulnerability reporting page. Please do not create a public GitHub issue.
To use the AWS Cryptographic Material Providers Library for Java you must have:
-
A Java 8 or newer development environment
If you do not have one, we recommend Amazon Corretto.
Note: If you use the Oracle JDK, you must also download and install the Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files.
-
Bouncy Castle or Bouncy Castle FIPS
The AWS Cryptographic Material Providers Library for Java uses Bouncy Castle to serialize and deserialize cryptographic objects. It does not explicitly use Bouncy Castle (or any other JCA Provider) for the underlying cryptography. Instead, it uses the platform default, which you can configure or override as documented in the Java Cryptography Architecture (JCA) Reference Guide.
If you do not have Bouncy Castle, go to https://bouncycastle.org/latest_releases.html, then download the provider file that corresponds to your JDK. Or, you can pick it up from Maven (groupId:
org.bouncycastle, artifactId:bcprov-ext-jdk18on).
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, an AWS DynamoDB Table, and the AWS SDK for Java V2. Note that 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 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.
-
To download and install the AWS SDK for Java 2.x, see Installing the AWS SDK for Java 2.x.
Many users find that the Amazon Corretto Crypto Provider (ACCP) significantly improves the performance of the AWS Encryption SDK. For help installing and using ACCP, see the amazon-corretto-crypto-provider repository.
You can get the latest release from Maven or Gradle:
<dependency>
<groupId>software.amazon.cryptography</groupId>
<artifactId>aws-cryptographic-material-providers</artifactId>
<version>1.0.0-preview-4</version>
</dependency>dependencies {
implementation("software.amazon.cryptography:aws-cryptographic-material-providers:1.0.0-preview-4")
}
Our versioning policy applies to all public and protected classes/methods/fields
in the software.amazon.cryptography.materialproviders package unless otherwise documented.
The software.amazon.cryptography.materialproviders.internaldafny package is not included in this public API.
See the Frequently Asked Questions page in the official documentation.
