Repository files navigation

The Amazon Corretto Crypto Provider (ACCP) is a collection of high-performance cryptographic implementations exposed via the standardJCA/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 aredocumented here.)As of 2.0.0, algorithms exposed by ACCP are primarily backed byAWS-LC's implementations.

Security issue notifications

Build Name	main branch
Linux x86_64
Linux aarch64

We provide complete benchmarking data from ourbenchmarking suite for the current tip ofmain.

MessageDigest algorithms:

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

Mac algorithms:

• HmacSHA512
• HmacSHA384
• HmacSHA256
• HmacSHA1
• HmacMD5

Cipher algorithms:

• AES/GCM/NoPadding
• AES_<n>/GCM/NoPadding, where n can be 128, or 256
• AES/KWP/NoPadding
• AES/XTS/NoPadding
• AES/CBC/NoPadding
  • AES_<n>/CBC/NoPadding, where n can be 128, 192, or 256
• AES/CBC/PKCS5Padding
  • AES_<n>/CBC/PKCS5Padding, where n can be 128, 192, or 256
  • PKCS7Padding is also accepted with AES/CBC and it is treated the same as PKCS5.
• AES/CBC/ISO10126Padding
  • AES_<n>/CBC/ISO10126Padding, where n can be 128, 192, or 256
• AES/CFB/NoPadding
  • AES_<n>/CFB/NoPadding, where n can be 128 or 256
• RSA/ECB/NoPadding
• RSA/ECB/PKCS1Padding
• RSA/ECB/OAEPPadding
• RSA/ECB/OAEPWithSHA-1AndMGF1Padding
• RSA/ECB/OAEPWithSHA1AndMGF1Padding

Signature algorithms:

• SHA1withRSA
• SHA224withRSA
• SHA256withRSA
• SHA384withRSA
• SHA512withRSA
• NONEwithECDSA
• SHA1withECDSA
• SHA1withECDSAinP1363Format
• SHA224withECDSA
• SHA224withECDSAinP1363Format
• SHA256withECDSA
• SHA256withECDSAinP1363Format
• SHA384withECDSA
• SHA384withECDSAinP1363Format
• SHA512withECDSA
• SHA512withECDSAinP1363Format
• RSASSA-PSS
• ED25519 (JDK 15+)
• ED25519ph (JDK 15+)
• ML-DSA
• ML-DSA-ExtMu

KeyPairGenerator:

• EC
• RSA
• ED25519 (JDK 15+)

KeyGenerator:

• AES

KeyAgreement:

• ECDH

SecretKeyFactory:

• HkdfWithHmacSHA1
• HkdfWithHmacSHA256
• HkdfWithHmacSHA384
• HkdfWithHmacSHA512
• ConcatenationKdfWithSHA256
• ConcatenationKdfWithSHA384
• ConcatenationKdfWithSHA512
• ConcatenationKdfWithHmacSHA256
• ConcatenationKdfWithHmacSHA512
• CounterKdfWithHmacSHA256
• CounterKdfWithHmacSHA384
• CounterKdfWithHmacSHA512

SecureRandom:

• ACCP's SecureRandom usesAWS-LC's DRBG implementation.

KeyFactory:

• EC
• RSA
• ED25519 (JDK 15+). Please refer tosystem properties for more information.

AlgorithmParameters:

• EC. Please refer tosystem properties for more information.

Mac algorithms with precomputed key and associated secret key factories (expert use only, refer toHMAC with Precomputed Key for more information):

• HmacSHA512WithPrecomputedKey
• HmacSHA384WithPrecomputedKey
• HmacSHA256WithPrecomputedKey
• HmacSHA1WithPrecomputedKey
• HmacMD5WithPrecomputedKey

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 FIPS certificate4816.

Version 2.3.0 is the first release of ACCP-FIPS. The Maven coordinates forACCP-FIPS are the same as ACCP with one difference that ACCP-FIPS'sartifact ID isAmazonCorrettoCryptoProvider-FIPS.

The table below shows which AWS-LC and AWS-LC-FIPS release versions are used in each ACCP(-FIPS) release.ACCP did not track a FIPS branch/release version of AWS-LC until ACCP v2.3.0. Before then, ACCP-FIPS simply built its tracked AWS-LC commit in FIPS mode.

Notable differences between ACCP and ACCP-FIPS:

• ACCP usesthe latest release of AWS-LC, whereas, ACCP-FIPS usesthe fips-2022-11-02 branch of AWS-LC.
• ACCP-FIPS builds AWS-LC in FIPS mode by passing-DFIPS=1 when configuring AWS-LC's build.
• For details about the FIPS module of AWS-LC in FIPS mode, including the entropy sources used, see theAWS-LC FIPS.md documentation.
• In FIPS-mode, RSA keys are limited to 2048, 3072, or 4096 bits in size with public exponent F4.
• Due to the fact that an older branch of AWS-LC is used in FIPS-mode, there will be performance differences between ACCP and ACCP-FIPS. We highly recommend performing detailed performance testing of your application if you choose to experiment with ACCP-FIPS.
• Between versions 2.1.0 and 2.3.3 (inclusive), ACCP-FIPS does not register SecureRandom by default due to the performance of AWS-LC’s entropy source in FIPS-mode, with older versions of AWS-LC. Since version 2.4.0, ACCP-FIPS behaves as ACCP: it registers SecureRandom from AWS-LC by default.A system property is available to change the default behavior.

ACCP-FIPS is only supported on the following platforms:

ACCP has the following requirements:

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

ACCP comes bundled with AWS-LC'slibcrypto.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.

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

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

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

Add the following to yourpom.xml or wherever you configure your Maven dependencies.This will instruct it to use the latest2.x version of ACCP for Linux x86-64 platform.For more information, please seeVERSIONING.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 isAmazonCorrettoCryptoProvider-FIPS.

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

Add something like following to yourbuild.gradle file.

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

If you already have adependencies block in yourbuild.gradle, you can add the ACCP line to your existing block.

The above sample configuration assumes you're using thelinux-x86_64 platform. If you're using another platform, please refer to the "Installation" parent section above and substitute appropriately.

For Gradle builds, theos-detector plugincan be used to avoid explicitly specifying the platform.Hereis an example.

For more version information, please seeVERSIONING.rst.

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-FIPSas the third argument to bundle the FIPS artifacts. To use these scripts, please setJAVA_HOME tothe 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:

• One needs to run the bundling script only once.
• The bundling is not idempotent: running the script on a JDK that has ACCP bundled in it could result in undefined behavior.
• There is no unbundling. Please do a fresh install of the JDK if you need to remove ACCP from your JDK.

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.

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

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 officialreleases 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
• Go 1.18 or later is required. 1.18 or later is the minimum requiredversion to build AWS-LC, 1.20 or later is needed in order to run AWS-LC's test suite. If notfound by CMake, the go executable may be configured explicitly by settingGO_EXECUTABLE.

1. Download the repository viagit clone --recurse-submodules
2. Run./gradlew release
3. The resulting jar is inbuild/lib

Please be aware that repackaging ACCP's published Jar files from Maven into your own "uber" or "fat" JAR file may notwork on OracleJDK. The OracleJDK requires that JCE providers be cryptographically signed by a trusted certificate. TheJARs we publish via Maven and our officialreleases 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 thefollowing exceptions:

• java.util.jar.JarException: The JCE Provider file is not signed.
• java.lang.SecurityException: JCE cannot authenticate the provider
• java.security.NoSuchProviderException: JCE cannot authenticate the provider

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 asSpring-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.

There are two possible flags which can be provided togradlew to build ACCP in FIPS mode:

• -DFIPS=true: This causes ACCP to be built with AWS-LC-FIPS as its underlying crypto library. The exact version of AWS-LC-FIPS used is specified in ourbuild.gradle file. Refer to theAWS-LC FIPS documentation for the latest FIPS validation and certification status of each version.
• -DEXPERIMENTAL_FIPS=true: This causes ACCP to be built with themain branch of AWS-LC, built in FIPS mode, as its underlying crypto library. This variation of FIPS mode allows one to experiment with the latest APIs and features in AWS-LC that have not yet made it onto a FIPS branch/release.

The following illustration depicts the difference these FIPS mode build options.

                           -DEXPERIMENTAL_FIPS=true                                      |                                      ↓AWS-LC [■]───[■]───[■]───[■]───[■]───[■]  main                 \                  [■]───[■]  AWS-LC-FIPS-X.Y.Z                         ↑                         |                   -DFIPS=true

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

• clean: Remove all artifacts except AWS-LC build artifacts
• deep_clean: Remove the entirebuild/ 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
• coverage: Run targettest and collect both Java and C++ coverage metrics (saved inbuild/reports)
• release:Default target depends on build, test, and coverage
• overkill: Runall 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 propertySINGLE_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.)

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

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

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 fromamazon-corretto-crypto-provider.security (for JDK versions older than JDK15)oramazon-corretto-crypto-provider-jdk15.security (for JDK15 or newer)in our repository.

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

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 aRuntimeCryptoException 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();

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.extrachecksAdds extra cryptographic consistency checks which are not necessary on standard systems.These checks may be computationally expensive and are not normally relevant.SeeExtraCheck.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.debugEnables 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.SeeDebugFlag.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.useExternalLibTakes intrue orfalse (defaults tofalse).Iftrue 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.stripesTakespositive integer value which is the requested minimum number of "stripes" used by theJanitor 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.)SeeJanitor.java for more information.
• com.amazon.corretto.crypto.provider.cacheselftestresults Takes intrue orfalse(defaults totrue). If set totrue, the results of running tests are cached,and the subsequent calls toAmazonCorrettoCryptoProvider::runSelfTestswould avoid re-running tests; otherwise, each call toAmazonCorrettoCryptoProvider::runSelfTestsre-run the tests.
• com.amazon.corretto.crypto.provider.registerEcParamsTakes intrue orfalse (defaults tofalse).Iftrue, then ACCP will register its EC-flavored AlgorithmParameters implementation on startup.Else, the JCA will get the implementation from another registered provider (usually stock JCE).Using JCE's implementation is generally recommended unless using ACCP as a standalone providerCallers can choose to register ACCP's implementation at runtime with a call toAmazonCorrettoCryptoProvider.registerEcParams()
• com.amazon.corretto.crypto.provider.registerSecureRandomTakes intrue orfalse (defaults totrue).Iftrue, 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.Before version 2.4.0, default wasfalse for FIPS builds.
• com.amazon.corretto.crypto.provider.nativeContextReleaseStrategyTakes inHYBRID,LAZY, orEAGER (defaults toHYBRID). This property only affectsAES-GCM cipher for now. AES-GCM associates a native object of typeEVP_CIPHER_CTXto eachCipher object. This property allows users to control the strategy for releasingthe native object.
  • HYBRID (default): the structure is released eagerly, unless the same AES key is used. This is thedefault behavior, and it is consistent with prior releases of ACCP.
  • LAZY: preserve the native object and do not release while theCipher object is not garbage collected.
  • EAGER: release the native object as soon as possible, regardless of using the same key or not.Our recommendation is to set this property toEAGER ifCipher objects are discardedafter use and caching ofCipher objects is not needed. When reusing the sameCipherobject, it would be beneficial to set this system property toLAZY so that differentencryption/decryption operations would not require allocation and release ofEVP_CIPHER_CTXstructure. A common use case would be having long-running threads that each would get itsown instance ofCipher class.
• com.amazon.corretto.crypto.provider.tmpdirAllows one to set the temporary directory used by ACCP when loading native libraries.If this system property is not defined, the system propertyjava.io.tmpdir is used.
• com.amazon.corretto.crypto.provider.registerEdKeyFactoryTakes intrue orfalse (defaults tofalse).Iftrue and JDK version is 15+, then ACCP will register its Ed25519 related KeyFactory classes.The keys produced by ACCP's KeyFactory services for Ed25519 do not implementEdECKeyinterface, and as a result, they cannot be used by other providers. Consider setting this propertytotrue if the keys are only used by other ACCP services AND they are not type cast toEdECKey.It is worth noting that the key generated by KeyFactory service of SunEC can be used by ACCP servicessuch as Signature.

EXPERT use only. Most users of ACCP just need normalHmacXXX algorithms and not theirWithPrecomputedKey variants.

The non-standard-JCA/JCE algorithmsHmacXXXWithPrecomputedKey (whereXXX is the digest name, e.g.,SHA384) implement an optimization of HMAC described in NIST-FIPS-198-1 (Section 6) and in RFC2104 (Section 4).They allow to generate a precomputed key for a given original key and a given HMAC algorithm,and then to use this precomputed key to compute HMAC (instead of the original key).Only use these algorithms if you know you absolutely need them.

In more detail, the secret key factoriesHmacXXXWithPrecomputedKey allow to generate a precomputed key from a normal HMAC key.The mac algorithmsHmacXXXWithPrecomputedKey take a precomputed key instead of a normal HMAC key.Precomputed keys must implementSecretKeySpec with formatRAW and algorithmHmacXXXWithPrecomputedKey.

Implementation uses AWS-LC functionsHMAC_set_precomputed_key_export,HMAC_get_precomputed_key, andHMAC_Init_from_precomputed_key.

Seeexample HmacWithPrecomputedKey.

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

As of version 2.0.0, our backing native cryptographic library (now AWS-LC) alsohas some code published underMIT,Google'sISC, and3-clauseBSD licenses (amongothers). Please see AWS-LC'sLICENSE file for full details.