search

corretto / amazon-corretto-crypto-provider

The Amazon Corretto Crypto Provider is a collection of high-performance cryptographic implementations exposed via standard JCA/JCE interfaces.
Apache License 2.0
233 stars 54 forks source link

readme

Amazon Corretto Crypto Provider

The Amazon Corretto Crypto Provider (ACCP) is a collection of high-performance cryptographic implementations exposed via the standard JCA/JCE interfaces. This means that it can be used as a drop in replacement for many different Java applications. (Differences from the default OpenJDK implementations are documented here.) As of 2.0.0, algorithms exposed by ACCP are primarily backed by AWS-LC's implementations.

Security issue notifications

Build Status

Build Name main branch
Linux x86_64
Linux aarch64

Supported Algorithms

MessageDigest algorithms:

Mac algorithms:

Cipher algorithms:

Signature algorithms:

KeyPairGenerator:

KeyGenerator:

KeyAgreement:

SecretKeyFactory:

SecureRandom:

KeyFactory:

AlgorithmParameters:

Notes on ACCP-FIPS

ACCP-FIPS is a variation of ACCP which uses AWS-LC-FIPS 2.x as its cryptographic module. This version of AWS-LC-FIPS has completed FIPS validation testing by an accredited lab and has been submitted to NIST for certification. Refer to the NIST Cryptographic Module Validation Program's Modules In Progress List for the latest status of the AWS-LC Cryptographic Module. We will also update our release notes and documentation to reflect any changes in FIPS certification status. We provide ACCP-FIPS for experimentation and performance testing in the interim.

Version 2.3.0 is the first release of ACCP-FIPS. The Maven coordinates for ACCP-FIPS are the same as ACCP with one difference that ACCP-FIPS's artifact ID is AmazonCorrettoCryptoProvider-FIPS.

Notable differences between ACCP and ACCP-FIPS:

ACCP-FIPS is only supported on the following platforms:

Platform FIPS support since version
linux-x86_64 2.3.0
linux-aarch_64 2.3.0

Compatibility & Requirements

ACCP has the following requirements:

ACCP comes bundled with AWS-LC's libcrypto.so, so it is not necessary to install AWS-LC on the host or container where you run your application.

If ACCP is used/installed on a system it does not support, it will disable itself and the JVM will behave as if ACCP weren't installed at all.

Using the provider

Installation

Installing via Maven or Gradle is the easiest way to get ACCP and ensure you will always have the most recent version. We strongly recommend you always pull in the latest version for best performance and bug-fixes.

Whether you're using Maven, Gradle, or some other build system that also pulls packages from Maven Central, it's important to specify a classifier, otherwise, one would get an empty package. The possible classifiers are as follows:

Classifier Support since version FIPS support since version
linux-x86_64 1.0.0 2.3.0
linux-aarch_64 2.0.0 2.3.0
osx-x86_64 2.3.2 Not supported
osx-aarch_64 2.3.3 Not supported

Regardless of how you acquire ACCP (Maven, manual build, etc.) you will still need to follow the guidance in the Configuration section to enable ACCP in your application.

Maven

Add the following to your pom.xml or wherever you configure your Maven dependencies. This will instruct it to use the latest 2.x version of ACCP for Linux x86-64 platform. For more information, please see VERSIONING.rst.

<dependency>
  <groupId>software.amazon.cryptools</groupId>
  <artifactId>AmazonCorrettoCryptoProvider</artifactId>
  <version>[2.0, 3.0)</version>
  <classifier>linux-x86_64</classifier>
</dependency>

The artifactId for FIPS builds is AmazonCorrettoCryptoProvider-FIPS.

ACCP artifacts on Maven can be verified using the following PGP keys:

ACCP Version PGP Key ID Key Server
1.x 6F189046CEE0B2C1 keyserver.ubuntu.com
2.x 5EFEEFE6BD0BD916 keyserver.ubuntu.com

Gradle

Add the following to your build.gradle file. If you already have a dependencies block in your build.gradle, you can add the ACCP line to your existing block. For more information, please see VERSIONING.rst.

dependencies {
    implementation 'software.amazon.cryptools:AmazonCorrettoCryptoProvider:2.+:linux-x86_64'
}

For Gradle builds, the os-detector plugin could be used so that one does not have to explicitly specify the platform. Here is an example.

Bundle ACCP with JDK

We provide two scripts that allow one to add ACCP to their JDKs: one for JDK8 and one for JDKs 11+. Please note that these scripts are provided as examples and for testing only.

These scripts take the version of ACCP and the classifier as input. Optionally, one can pass -FIPS as the third argument to bundle the FIPS artifacts. To use these scripts, please set JAVA_HOME to the path of your desired JDK.

Usage example:

./bin/bundle-accp.sh 2.3.3 linux-x86_64

To find the available versions and classifiers, please checkout Maven central.

Some notes on the bundling scripts:

Manual

Manual installation requires acquiring the provider and adding it to your classpath. You can either download a prebuilt version of the provider or build it yourself. Adding a jar to your classpath is highly application and build-system dependent and we cannot provide specific guidance.

Download from GitHub releases

The most recent version of our provider will always be on our official releases page.

Build it yourself

Please be aware that if you build the provider yourself then it will NOT work with OracleJDK. The OracleJDK requires that JCA providers be cryptographically signed by a trusted certificate. The JARs we publish via Maven and our official releases are signed by our private key, but yours will not be.

Building this provider requires a 64 bit Linux or MacOS build system with the following prerequisites installed:

  1. Download the repository via git clone --recurse-submodules
  2. Run ./gradlew release
  3. The resulting jar is in build/lib

Repackaging ACCP into Uber/Fat Jars

Please be aware that repackaging ACCP's published Jar files from Maven into your own "uber" or "fat" JAR file may not work on OracleJDK. The OracleJDK requires that JCE providers be cryptographically signed by a trusted certificate. The JARs we publish via Maven and our official releases are signed by our private key, but yours will not be.

Depending on how ACCP is repackaged, ACCP's existing signature may be invalidated, and you may receive one of the following exceptions:

If you receive one of these exceptions, then you will need to evaluate if any of the following options will work for your application and environment:

  1. Exclude ACCP from your repackaging process, keeping ACCP's jar file unmodified, and deploying both your uber jar and ACCP jar as separate jar files.
  2. Use a non-standard Java ClassLoader that allows loading a "jar of jars" (such as Spring-boot's NestedJarFile), and copy ACCP's Jar file into the parent Jar file so that ACCP's JCE signature remains intact.
  3. Migrate to a different JDK (eg OpenJDK or CorrettoJDK) that does not require that JCE providers be signed.
  4. Obtain your own JCE Code Signing Certificate and sign your repackaged Jar.
FIPS builds

FIPS builds are still experimental and are not yet ready for production use.

By providing -DFIPS=true to gradlew you will cause the entire build to be for a "FIPS mode" build. The FIPS builds use a different version of AWS-LC along with FIPS=1 build flag. Not all releases of AWS-LC will have FIPS certification. As a result, ACCP in FIPS mode only uses a version of AWS-LC that has FIPS certification or it will have in future.

By providing -DEXPERIMENTAL_FIPS=true to gradlew you will cause the entire build to be for a "FIPS mode" build, and it uses the same version of AWS-LC as non-FIPS builds. This allows one to experiment with APIs and features in AWS-LC that have not yet made it into a FIPS branch/release of AWS-LC, but built in FIPS mode.

When changing between FIPS and non-FIPS builds, be sure to do a full clean of your build environment.

All targets

Configuration

There are several ways to configure the ACCP as the highest priority provider in Java.

Code

Run the following method early in program start up: com.amazon.corretto.crypto.provider.AmazonCorrettoCryptoProvider.install()

Via Security Properties

Add the following Java property to your programs command line: -Djava.security.properties=/path/to/amazon-corretto-crypto-provider.security where amazon-corretto-crypto-provider.security is downloaded from amazon-corretto-crypto-provider.security (for JDK versions older than JDK15) or amazon-corretto-crypto-provider-jdk15.security (for JDK15 or newer) in our repository.

Modify the JVM settings

Modify the java.security file provided by your JVM so that the highest priority provider is the Amazon Corretto Crypto Provider. Look at amazon-corretto-crypto-provider.security (JDKs 11 and older) or amazon-corretto-crypto-provider-jdk15.security (for JDKs newer than 11) for an example of what this change will look like.

Verification (Optional)

If you want to check to verify that ACCP is properly working on your system, you can do any of the following:

  1. Verify that the highest priority provider actually is ACCP: 
    if (Cipher.getInstance("AES/GCM/NoPadding").getProvider().getName().equals(AmazonCorrettoCryptoProvider.PROVIDER_NAME)) {
// Successfully installed
}
  2. Ask ACCP about its health 
    if (AmazonCorrettoCryptoProvider.INSTANCE.getLoadingError() == null && AmazonCorrettoCryptoProvider.INSTANCE.runSelfTests().equals(SelfTestStatus.PASSED)) {
// Successfully installed
}
  3. Assert that ACCP is healthy and throw a RuntimeCryptoException if it isn't. We generally do not recommend this solution as we believe that gracefully falling back to other providers is usually the better option. 
    AmazonCorrettoCryptoProvider.INSTANCE.assertHealthy();

Other system properties

ACCP can be configured via several system properties. None of these should be needed for standard deployments, and we recommend not touching them. They are of most use to developers needing to test ACCP or experiment with benchmarking. These are all read early in the load process and may be cached so any changes to them made from within Java may not be respected. Thus, these should all be set on the JVM command line using -D.

License

This library is licensed under the Apache 2.0 license although portions of this product include software licensed under the dual OpenSSL and SSLeay license. This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit (http://www.openssl.org), as well as cryptographic software written by Eric Young (eay@cryptsoft.com).

As of version 2.0.0, our backing native cryptographic library (now AWS-LC) also has some code published under MIT, Google's ISC, and 3-clause BSD licenses (among others). Please see AWS-LC's LICENSE file for full details.