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

Please be aware that both "Overkill" and "Dieharder" tests are known to be flakey. Both of these tests are flakey because they include entropy generation tests (specificaly, the Dieharder tests). Entropy tests are unavoidably flakey because there is always a possibility that a high-quality random number generator will output data which looks non-random. (For example, even a fair coin will come up heads ten times in a row about one in a thousand trials.)

Build Name	`main` branch
Linux x86_64
Linux aarch64
Overkill/Dieharder

Supported Algorithms

MessageDigest algorithms:

SHA-512
SHA-384
SHA-256
SHA-1
MD5

Mac algorithms:

HmacSHA512
HmacSHA384
HmacSHA256
HmacSHA1
HmacMD5

Cipher algorithms:

AES/GCM/NoPadding
AES_128/GCM/NoPadding
AES_256/GCM/NoPadding
AES/KWP/NoPadding
RSA/ECB/NoPadding
RSA/ECB/PKCS1Padding
RSA/ECB/OAEPPadding
RSA/ECB/OAEPWithSHA-1AndMGF1Padding

Signature algorithms:

SHA1withRSA
SHA224withRSA
SHA256withRSA
SHA384withRSA
SHA512withRSA
NONEwithECDSA
SHA1withECDSA
SHA1withECDSAinP1363Format
SHA224withECDSA
SHA224withECDSAinP1363Format
SHA256withECDSA
SHA256withECDSAinP1363Format
SHA384withECDSA
SHA384withECDSAinP1363Format
SHA512withECDSA
SHA512withECDSAinP1363Format
RSASSA-PSS

KeyPairGenerator algorithms:

KeyAgreement:

ECDH

SecureRandom algorithms:

ACCP's SecureRandom uses AWS-LC's DRBG implementation, which is described here and here.

KeyFactory algorithms:

EC
RSA
ACCP's SecureRandom uses AWS-LC's DRBG implementation.

Compatibility & Requirements

ACCP has the following requirements:

JDK8 or newer (This includes both OracleJDK and Amazon Corretto)
Linux (x86-64 or arm64) or MacOs running on x86_64 (also known as x64 or AMD64)

ACCP comes bundled with AWS-lC's libcrypto.so, so it is not neccessery 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 linux-x86_64 or linux-aarch_64 as the classifier. You'll get an empty package otherwise. Note that ACCP is not available for MacOS on Maven Central yet.

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 classifier attribute could be set to linux-aarch_64 to use ACCP on Linux ARM64 platforms.

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.

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 dependant 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:

OpenJDK 10 or newer
cmake 3.8 or newer
C++ build chain
lcov for coverage metrics
gcovr for reporting coverage metrics in CodeBuild
dieharder for entropy tests

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

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 only significant difference is that AWS-LC is built with FIPS=1.

For performance reasons, ACCP does not register a SecureRandom implementation in FIPS mode. Relevant operations within the FIPS module boundary (e.g. key generation, non-deterministic signing, etc.) will still use AWS-LC's internal DRBG. Users who require ACCP to provide FIPS-validated pseudo-randomness outside the module boundary via SecureRandom should set registerSecureRandom=true.

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

All targets

clean: Remove all artifacts except AWS-LC build artifacts
deep_clean: Remove the entire build/ directory including build artifacts from AWS-LC dependencies
build: Build the library
test: Run unit tests
test_extra_checks: Run unit tests with extra (slow) cryptographic checks enabled
test_integration: Run integration tests
test_integration_extra_checks: Run integration tests with extra (slow) cryptographic checks enabled
dieharder: Run entropy tests
dieharder_threads: Run entropy threads specifically checking for leaking state across threads (very slow)
dieharder_all: Run all dieharder checks (both dieharder and dieharder_threads)
coverage: Run target test and collect both Java and C++ coverage metrics (saved in build/reports)
release: Default target depends on build, test, and coverage
overkill: Run all tests (no coverage)
generateEclipseClasspath: Generates a .classpath file which is understandable by Eclipse and VS Code to make development easier. (This should ideally be run prior to opening ACCP in your IDE.)
single_test: Runs a single unit test. The test is selected with the Java system property SINGLE_TEST. For example: ./gradlew single_test -DSINGLE_TEST=com.amazon.corretto.crypto.provider.test.EcGenTest (You may need to do a clean build when switching between selected tests.)

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:

Verify that the highest priority provider actually is ACCP:

if (Cipher.getInstance("AES/GCM/NoPadding").getProvider().getName().equals(AmazonCorrettoCryptoProvider.PROVIDER_NAME)) {
    // Successfully installed
}

Ask ACCP about its health

if (AmazonCorrettoCryptoProvider.INSTANCE.getLoadingError() == null && AmazonCorrettoCryptoProvider.INSTANCE.runSelfTests().equals(SelfTestStatus.PASSED)) {
    // Successfully installed
}

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.

com.amazon.corretto.crypto.provider.extrachecks Adds exta cryptographic consistency checks which are not necessary on standard systems. These checks may be computationally expensive and are not normally relevant. See ExtraCheck.java for values and more information. (Also accepts "ALL" as a value to enable all flags and "help" to print out all flags to STDERR.)
com.amazon.corretto.crypto.provider.debug Enables extra debugging behavior. These behaviors may be computationally expensive, produce additional output, or otherwise change the behavior of ACCP. No values here will lower the security of ACCP or cause it to give incorrect results. See DebugFlag.java for values and more information. (Also accepts "ALL" as a value to enable all flags and "help" to print out all flags to STDERR.)
com.amazon.corretto.crypto.provider.useExternalLib Takes in true or false (defaults to false). If true then ACCP skips trying to load the native library bundled within its JAR and goes directly to the system library path.
com.amazon.corretto.crypto.provider.janitor.stripes Takes positive integer value which is the requested minimum number of "stripes" used by the Janitor for dividing cleaning tasks (messes) among its workers. (Current behavior is to default this value to 4 times the CPU core count and then round the value up to the nearest power of two.) See Janitor.java for for more information.
com.amazon.corretto.crypto.provider.cacheselftestresults Takes in true or false (defaults to true). If set to true, the results of running tests are cached, and the subsequent calls to AmazonCorrettoCryptoProvider::runSelfTests would avoid re-running tests; otherwise, each call to AmazonCorrettoCryptoProvider::runSelfTests re-run the tests.
com.amazon.corretto.crypto.provider.registerEcParams Takes in true or false (defaults to false). If true, then ACCP will register its EC-flavoered AlgorithmParameters implementation on startup. Else, the JCA will get the implementation from another registered provider (usually stock JCE). Using JCE's impelmentation is generally recommended unless using ACCP as a standalone provider Callers can choose to register ACCP's implementation at runtime with a call to AmazonCorrettoCryptoProvider.registerEcParams()
com.amazon.corretto.crypto.provider.registerSecureRandom Takes in true or false (defaults to false in FIPS mode, defaults to true in non-FIPS). If true, then ACCP will register a SecureRandom implementation (LibCryptoRng) backed by AWS-LC Else, ACCP will not register a SecureRandom implementation, meaning that the JCA will source SecureRandom instances from another registered provider. AWS-LC will still use its internal DRBG for key generation and other operations requiring secure pseudo-randomness. LibCryptoRng is very fast during steady state operation in all cases. In FIPS mode, however, AWS-LC-FIPS's CPU jitter-based entropy source incurs a ~10ms initialization cost for every new thread. This means that there is a slight "pause" before ACCP FIPS's SecureRandom can produce pseudo-random bytes in highly threaded environments. Because, in extreme cases this could present an availability risk, we do not register LibCryptoRng by default in configurations where this initialization cost is incurred (i.e. FIPS mode). Non-FIPS AWS-LC does not use CPU jitter for its DRBG seed's entropy, and therefore does not incur this initialization cost, therefore we register LibCryptoRng by default when not in FIPS mode.

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 ([email protected]).

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.

corretto/amazon-corretto-crypto-provider

corretto

Reviews

Repository Details