AWS Encryption SDK for Java

The AWS Encryption SDK enables secure client-side encryption. It uses cryptography best practices to protect your data and protect the encryption keys that protect your data. Each data object is protected with a unique data encryption key, and the data encryption key is protected with a key encryption key called awrapping keyormaster key.The encryption method returns a single, portableencrypted messagethat contains the encrypted data and the encrypted data key, so you don't need to keep track of the data encryption keys for your data. You can use KMS keys inAWS Key Management Service(AWS KMS) as wrapping keys. The AWS Encryption SDK also provides APIs to define and use encryption keys from other key providers.

The AWS Encryption SDK for Java provides methods for encrypting and decrypting strings, byte arrays, and byte streams. For details, see theexample codeand theJavadoc.

For more details about the design and architecture of the AWS Encryption SDK, see theAWS Encryption SDK Developer Guide.

Security issue notifications

SeeSupport Policyfor details on the current support status of all major versions of this library.

Getting Started

Required Prerequisites

To use the AWS Encryption SDK for Java you must have:

• A Java 8 or newer development environment

  If you do not have one, we recommendAmazon Corretto.

  Note:If you use the Oracle JDK, you must also download and install theJava Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files.

• Declare a Dependency on the AWS Encryption SDK in Java and its dependencies

  This library requires the AWS Cryptographic Material Providers Library in Java, and the KMS and DynamoDB clients from the AWS Java SDK V2.

  The KMS client from the AWS SDK for Java V1 is anoptionaldependency.

  Note:The AWS Cryptographic Material Providers Library in Java only supports the AWS SDK for Java V2 and requires a HARD dependency on the AWS SDK for Java V2's KMS and DynamoDB clients, regardless of whether a KMS Keyring or Hierarchical Keyring is used.

  • Via Apache Maven
    Add the following to your project'spom.xml.

    <project>
    ...
    <dependencyManagement>
    <dependencies>
    <dependency>
    <groupId>software.amazon.awssdk</groupId>
    <artifactId>bom</artifactId>
    <version>3.0.1</version>
    <type>pom</type>
    <scope>import</scope>
    </dependency>
    </dependencies>
    </dependencyManagement>
    <dependencies>
    <dependency>
    <groupId>com.amazonaws</groupId>
    <artifactId>aws-encryption-sdk-java</artifactId>
    <version>3.0.1</version>
    </dependency>
    <dependency>
    <groupId>software.amazon.cryptography</groupId>
    <artifactId>aws-cryptographic-material-providers</artifactId>
    <version>3.0.1</version>
    </dependency>
    <dependency>
    <groupId>software.amazon.awssdk</groupId>
    <artifactId>dynamodb</artifactId>
    </dependency>
    <dependency>
    <groupId>software.amazon.awssdk</groupId>
    <artifactId>kms</artifactId>
    </dependency>
    <!--The following are optional-->
    <dependency>
    <groupId>com.amazonaws</groupId>
    <artifactId>aws-java-sdk</artifactId>
    <version>3.0.1</version>
    <optional>true</optional>
    </dependency>
    </dependencies>
    ...
    </project>

  • Via Gradle Kotlin
    In a Gradle Java Project, add the following to thedependenciessection:

    implementation("com.amazonaws:aws-encryption-sdk-java:3.0.0")
    implementation("software.amazon.cryptography:aws-cryptographic-material-providers:1.0.2")
    implementation(platform("software.amazon.awssdk:bom:2.20.91"))
    implementation("software.amazon.awssdk:kms")
    implementation("software.amazon.awssdk:dynamodb")
    //The following are optional:
    implementation("com.amazonaws:aws-java-sdk:1.12.394")

• Bouncy CastleorBouncy Castle FIPS

  The AWS Encryption SDK for Java uses Bouncy Castle to serialize and deserialize cryptographic objects. It does not explicitly use Bouncy Castle (or any otherJCA 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 tohttps://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-jdk18on).

  Beginning in version 1.6.1, the AWS Encryption SDK for Java also works with Bouncy Castle FIPS (groupId:org.bouncycastle,artifactId:bc-fips) as an alternative to non-FIPS Bouncy Castle. For help installing and configuring Bouncy Castle FIPS, seeBC FIPS documentation,in particular,User GuidesandSecurity Policy.

Optional Prerequisites

AWS Integration

You don't need an Amazon Web Services (AWS) account to use the AWS Encryption SDK, but someexample coderequire an AWS account, an AWS KMS key, and the AWS SDK for Java (either 1.x or 2.x). Note that theKmsAsyncClientis not supported, only the synchronous client.

• To create an AWS account,go toSign In or Create an AWS Accountand then chooseI am a new user.Follow the instructions to create an AWS account.

• To create a key in AWS KMS,seeCreating Keys.

• To download and install the AWS SDK for Java 2.x,seeInstalling the AWS SDK for Java 2.x.

• To download and install the AWS SDK for Java 1.x,seeInstalling the AWS SDK for Java 1.x.

Amazon Corretto Crypto Provider

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 theamazon-corretto-crypto-provider repository.

Get Started

To get started with the AWS Encryption SDK for Java

1. Instantiate the AWS Encryption SDK.
2. Create a Keyring from the AWS Cryptographic Material Providers Library.
3. Encrypt and decrypt data.

// This sample code encrypts and then decrypts a string using an AWS KMS key.
// You provide the KMS key ARN and plaintext string as arguments.
packagecom.amazonaws.crypto.examples;

importcom.amazonaws.encryptionsdk.AwsCrypto;
importcom.amazonaws.encryptionsdk.CommitmentPolicy;
importcom.amazonaws.encryptionsdk.CryptoResult;
importsoftware.amazon.cryptography.materialproviders.IKeyring;
importsoftware.amazon.cryptography.materialproviders.MaterialProviders;
importsoftware.amazon.cryptography.materialproviders.model.CreateAwsKmsMultiKeyringInput;
importsoftware.amazon.cryptography.materialproviders.model.MaterialProvidersConfig;

importjava.nio.charset.StandardCharsets;
importjava.util.Arrays;
importjava.util.Collections;
importjava.util.Map;

publicclassStringExample{
privatestaticStringkeyArn;
privatestaticStringplaintext;

publicstaticvoidmain(finalString[]args) {
keyArn=args[0];
plaintext=args[1];

// Instantiate the SDK
finalAwsCryptocrypto=AwsCrypto.standard();

// Create the AWS KMS keyring.
// We create a multi keyring, as this interface creates the KMS client for us automatically.
finalMaterialProvidersmaterialProviders=MaterialProviders.builder()
.MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
.build();
finalCreateAwsKmsMultiKeyringInputkeyringInput=
CreateAwsKmsMultiKeyringInput.builder().generator(keyArn).build();
finalIKeyringkmsKeyring=materialProviders.CreateAwsKmsMultiKeyring(keyringInput);

// Set up the encryption context
// NOTE: Encrypted data should have associated encryption context
// to protect its integrity. This example uses placeholder values.
// For more information about the encryption context, see
// https://docs.aws.amazon /encryption-sdk/latest/developer-guide/concepts.html#encryption-context
finalMap<String,String>encryptionContext=Collections.singletonMap("ExampleContextKey","ExampleContextValue");

// Encrypt the data
finalCryptoResult<byte[],?>encryptResult=crypto.encryptData(kmsKeyring,plaintext.getBytes(StandardCharsets.UTF_8),encryptionContext);
finalbyte[]ciphertext=encryptResult.getResult();
System.out.println("Ciphertext:"+Arrays.toString(ciphertext));

// Decrypt the data
finalCryptoResult<byte[],?>decryptResult=
crypto.decryptData(
kmsKeyring,
ciphertext,
// Verify that the encryption context in the result contains the
// encryption context supplied to the encryptData method
encryptionContext);

assertArrays.equals(decryptResult.getResult(),plaintext.getBytes(StandardCharsets.UTF_8));

// The data is correct, so return it.
System.out.println("Decrypted:"+newString(decryptResult.getResult(),StandardCharsets.UTF_8));
}
}

You can find more examples in theexample directory.

Public API

Ourversioning policyapplies to all public and protected classes/methods/fields in thecom.amazonaws.encryptionsdkpackage unless otherwise documented.

Thecom.amazonaws.encryptionsdk.internalpackage is not included in this public API.

FAQ

See theFrequently Asked Questionspage in the official documentation.