Java Bindings for the AWS Common Runtime
This library is licensed under the Apache 2.0 License.
Jump To:
Requirements:
* Clang 6+ or GCC 4.4+
* cmake 3.9+
* Java: Any JDK8 or above, ensure JAVA_HOME is set
* Maven
Building:
1) apt-get install cmake3 maven openjdk-8-jdk-headless -y
2) git clone https://github.com/awslabs/aws-crt-java.git
3) cd aws-crt-java
4) git submodule update --init --recursive
5) mvn compile
Requirements:
* MacOS: 10.15+
* cmake 3.9+
* ninja
* Java: Any JDK8 or above, ensure JAVA_HOME is set
* Maven
Building:
1) brew install maven cmake (if you have homebrew installed, otherwise install these manually)
2) git clone https://github.com/awslabs/aws-crt-java.git
3) cd aws-crt-java
4) git submodule update --init --recursive
5) mvn compile
Requirements:
* Visual Studio 2015 or above
* CMake 3.9+
* Java: Any JDK8 or above, ensure JAVA_HOME is set
* Maven
Building:
1) choco install maven (if you have chocolatey installed), otherwise install maven and the JDK manually
2) git clone https://github.com/awslabs/aws-crt-java.git
3) cd aws-crt-java
4) git submodule update --init --recursive
5) mvn compile
NOTE: Make sure you run this from a VS Command Prompt or have run VCVARSALL.BAT in your current shell so
CMake can find Visual Studio.
From the aws-crt-java directory:
mvn install
From maven: (https://search.maven.org/artifact/software.amazon.awssdk.crt/aws-crt/)
The aws-crt JAR in Maven Central is a large "uber" jar that contains compiled C libraries for many different platforms (Windows, Linux, etc). If size is an issue, you can pick a smaller platform-specific JAR by setting the <classifier>.
Sample to use classifier from aws-crt:
<dependency>
<groupId>software.amazon.awssdk.crt</groupId>
<artifactId>aws-crt</artifactId>
<version>0.20.5</version>
<classifier>linux-x86_64</classifier>
</dependency>
<dependency>
<groupId>software.amazon.awssdk.crt</groupId>
<artifactId>aws-crt</artifactId>
<version>0.20.5</version>
</dependency>
The os-maven-plugin can automatically detect your platform's classifier at build time.
NOTES: The auto-detected linux-arm_32 platform classifier is not supported, you must specify linux-armv6 or linux-armv7.
Additionally, musl vs glibc detection is not supported either. If you are deploying to a musl-based system and wish to use
a classifier-based jar, you must specify the classifier name yourself.
<build>
<extensions>
<extension>
<groupId>kr.motd.maven</groupId>
<artifactId>os-maven-plugin</artifactId>
<version>1.7.0</version>
</extension>
</extensions>
</build>
<dependencies>
<dependency>
<groupId>software.amazon.awssdk.crt</groupId>
<artifactId>aws-crt</artifactId>
<version>0.20.5</version>
<classifier>${os.detected.classifier}</classifier>
</dependency>
<dependencies>
Currently the classifier fips-where-available provides an "uber" jar with FIPS tested cryptography on some platforms.
Platforms that were not part of the FIPS testing are also included in this jar, for compatibility's sake. Check CRT.isFIPS() at runtime to ensure that AWS-LC is being run in FIPS mode, and follow the security policy of AWS-LC-FIPS 3.0.0 (static).
[!WARNING] The classifier, and platforms with FIPS testing are subject to change in the future.
Refer to the NIST Cryptographic Module Validation Program's Modules In Progress List for the latest status of the static AWS-LC 3.0 Cryptographic Module. A complete list of supported operating environments will be made available in the vendor security policy once the validation certificate has been issued. We will also update our release notes and documentation to reflect any changes in FIPS certification status. Previous versions of AWS-LC have already received FIPS cryptographic module certificates (NIST Certificate #4816 & NIST Certificate #4631).
Since version v0.29.20, GraalVM native image was supported. You can compile your application with AWS CRT in a GraalVM native image project without any additional configuration.
Since version v0.31.1, GraalVM support was updated. Instead of packaging the JNI shared libraries with native image as resources, the corresponding shared lib will be written to the same directory as the native image. In this way, it reduces the native image size around 30% (142 MB to 101 MB for a sample application), and avoids the extra loading time needed for extracting the JNI lib to the temporary path for load. No additional configuration needed.
[!NOTE] The JNI shared lib must be in the same directory as the GraalVM native image. If you move the native image, you must move this file too. It is
aws-crt-jni.dllon Windows,libaws-crt-jni.dylibon macOS, andlibaws-crt-jni.soon Unix.[!IMPORTANT] When adding or modifying JNI bindings (native methods, classes, or interfaces), update jni-config.json to ensure GraalVM compatibility and CI test success.
aws.crt.log.destination or aws.crt.log.level:aws.crt.log.level - Log level. May be: "None", "Fatal", "Error", "Warn" (default), "Info", "Debug", "Trace".aws.crt.log.destination - Log destination. May be: "Stderr" (default), "Stdout", "File", "None".aws.crt.log.filename - File to use when aws.crt.log.destination is "File".aws.crt.libc - (Linux only) Set to "musl" or "glibc" if CRT cannot properly detect which to use.aws.crt.lib.dir - Set directory where CRT may extract its native library (by default, java.io.tmpdir is used)aws.crt.memory.tracing - May be: "0" (default, no tracing), "1" (track bytes), "2" (more detail).
Allows the CRT.nativeMemory() and CRT.dumpNativeMemory() functions to report native memory usage.The CRT uses native libraries for TLS, rather than Java's typical Secure Socket Extension (JSSE), KeyStore, and TrustStore. On Windows, the built-in OS library (Schannel) is used. On Linux/Unix/etc s2n-tls is used. On macOS, the default TLS backend is Apple Secure Transport, but an alternative backend (s2n-tls) can be selected at runtime (see below).
If you need to add certificates to the trust store, add them to your OS trust store. The CRT does not use the Java TrustStore. For more customization options, see TlsContextOptions and TlsConnectionOptions.
AWS_CRT_USE_NON_FIPS_TLS_13 environment variableOn macOS, both Apple Secure Transport and s2n-tls are compiled into the binary. The TLS backend is selected at runtime based on this environment variable:
AWS_CRT_USE_NON_FIPS_TLS_13=1): s2n-tls with aws-lc is used.This variable has no effect on Linux (always uses s2n-tls) or Windows (always uses Schannel).
| Secure Transport (default) | s2n-tls (AWS_CRT_USE_NON_FIPS_TLS_13=1) |
|
|---|---|---|
| TLS versions | Up to TLS 1.2 | Up to TLS 1.3 |
| FIPS compliance | Yes | No |
| macOS Keychain integration | Yes (PKCS#12, system certs) | No |
Please note that on Mac, once a private key is used with a certificate, that certificate-key pair is imported into the Mac Keychain. All subsequent uses of that certificate will use the stored private key and ignore anything passed in programmatically. This applies when using the default Secure Transport backend. Beginning in v0.6.6, when a stored private key from the Keychain is used, the following will be logged at the "info" log level:
static: certificate has an existing certificate-key pair that was previously imported into the Keychain. Using key from Keychain instead of the one provided.
Some tests require pre-configured resources and proper environment variables to be set to run properly. These tests will be quietly skipped if the environment variables they require are not set.
Many IoT related tests require that you have set up an AWS IoT Thing.
AWS_TEST_MQTT311_IOT_CORE_HOST: AWS IoT service endpoint hostname for MQTT3AWS_TEST_MQTT311_IOT_CORE_RSA_CERT: Path to the IoT thing certificate for MQTT3AWS_TEST_MQTT311_IOT_CORE_RSA_KEY: Path to the IoT thing private key for MQTT3AWS_TEST_MQTT311_IOT_CORE_ECC_CERT: Path to the IoT thing with EC-based certificate for MQTT3AWS_TEST_MQTT311_IOT_CORE_ECC_KEY: Path to the IoT thing with ECC private key for MQTT3 (The ECC key file should only contains the ECC Private Key section to working on MacOS.)AWS_TEST_MQTT311_ROOT_CA: Path to the root certificateOther Environment Variables that can be set can be found in the SetupTestProperties() function in CrtTestFixture.java
These can be set persistently via Maven settings (usually in ~/.m2/settings.xml):
<settings>
...
<profiles>
<profile>
<activation>
<activeByDefault>true</activeByDefault>
</activation>
<properties>
<crt.test.endpoint>XXXXXXXXXX-ats.iot.us-east-1.amazonaws.com</crt.test.endpoint>
<crt.test.certificate>/path/to/XXXXXXXX-certificate.pem.crt</crt.test.certificate>
<crt.test.privatekey>/path/to/XXXXXXXX-private.pem.key</crt.test.privatekey>
<crt.test.rootca>/path/to/AmazonRootCA1.pem</crt.test.rootca>
... etc ...
</properties>
</profile>
</profiles>
</settings>%
Most of proxy related tests need pre-configured Proxy host to run the tests properly.
AWS_TEST_HTTP_PROXY_HOST: Hostname of proxyAWS_TEST_HTTP_PROXY_PORT: Port of proxyNETWORK_TESTS_DISABLED: Set this if tests are running in a constrained environment where network access is not guaranteed/allowed.Most of S3 related tests require AWS credentials and a set of pre-configured S3 buckets. There is a helper script from aws-c-s3 that can be used to set up the test environment, here.
Example to use the helper and run the S3 tests:
cd aws-crt-java
python3 -m pip install boto3
export CRT_S3_TEST_BUCKET_NAME=<bucket_name>
python3 crt/aws-c-s3/tests/test_helper/test_helper.py init
# Run S3ClientTest. eg: mvn -Dtest=S3ClientTest test
more details about the helper can be found from here.
CRT_S3_TEST_BUCKET_NAME: The basic bucket name for S3 tests.Tests can be debugged in Java/Kotlin via the built-in tooling in VSCode and IntelliJ. If you need to debug the native code, it's a bit trickier.
To debug native code with VSCode or CLion or any other IDE:
1. Find your mvn launch script(e.g. realpath $(which mvn)) and pull the command line at the bottom from it. This changes between versions
of maven, so it
$ claude mcp add aws-crt-java \
-- python -m otcore.mcp_server <graph>