Chainguard Container for jdk-fips

Chainguard Containers are regularly-updated, secure-by-default container images.

Download this Container Image

For those with access, this container image is available on cgr.dev:

docker pull cgr.dev/ORGANIZATION/jdk-fips:latest

Be sure to replace the ORGANIZATION placeholder with the name used for your organization's private repository within the Chainguard Registry.

This is a base image containing both OpenJDK and the Bouncy Castle crypto libraries for FIPS.

The FIPS validated version of Bouncy Castle is compliant to the FIPS 140-3 standard when used in accordance with the Bouncy Castle Security Policy.

When using the OpenJDK Chainguard Image for FIPS compliance, please make sure to read the security policy and adapt your code as needed. Follow these documents:

• Bouncy Castle FIPS Java API User Guide (PDF)
• Bouncy Castle FIPS Migration Hints (PDF)
• JDK Providers Documentation

OpenSSL FIPS provider is also included for convenience to add any other non-Java applications that use OpenSSL for their cryptographic needs.

Available versions and variants

This image is currently available in the following versions and variants:

How are the java.policy and java.security files configured?

An updated version of the java.security configuration file is shipped under the default location ($JAVA_HOME/conf/security/java.security) in this image and is configured as described below:

• It sets up BouncyCastle FIPS providers at highest priority

• Security providers that implement non-validated cryptography are omitted

• SUN provider is loaded at lowest priority, as it is required to validate the BouncyCastle signed jars

• Detailed services which stock security providers implement are described in JDK Providers Documentation

• Hardening is applied to block security-sensitive usage of algorithms that may leak from the SUN provider

• It loads the java.policy file shipped under /usr/lib/jvm/jdk-fips-config/java.policy as an additional policy file, at position 2, leaving the policy configuration as:

  policy.url.1=file:${java.home}/conf/security/java.policy
  policy.url.2=file:/usr/lib/jvm/jdk-fips-config/java.policy

  The additional policy file is configured as described in the BCFIPS user manual:

  grant {
      permission java.lang.PropertyPermission "java.runtime.name", "read";
  
      permission java.lang.RuntimePermission "accessClassInPackage.sun.security.internal.spec";
      permission java.lang.RuntimePermission "getProtectionDomain";
      permission java.lang.RuntimePermission "accessDeclaredMembers";
  
      permission org.bouncycastle.crypto.CryptoServicesPermission "tlsAlgorithmsEnabled";
      permission org.bouncycastle.crypto.CryptoServicesPermission "exportKeys";
  };

• Supported truststore.type are jks, pkcs12 and bcfks for public CA certificates in approved mode.

• Supported keystore.type is only bcfks, in order for keystores used for private key storage to be FIPS-compliant.

• It sets the algorithms for the KeyManagerFactory and TrustManagerFactory as PKIX:

  ssl.KeyManagerFactory.algorithm=PKIX
  ssl.TrustManagerFactory.algorithm=PKIX

• It sets BCFIPS to approved_only mode:

  org.bouncycastle.fips.approved_only=true

Using the provided Bouncy Castle libraries

Whenever possible ensure to use --module-path /usr/share/java/bouncycastle-fips, as that allows one to execute classes, jars, modules correctly with bouncycastle-fips JCA & JSSE providers available to the JVM.

There are many additional environment variables preset in the image that enable using CLASSPATH instead if desired.

This image ships with the following environment variables exported by default:

• JAVA_FIPS_CLASSPATH=/usr/share/java/bouncycastle-fips/*
• JDK_JAVA_FIPS_OPTIONS="--add-exports=java.base/sun.security.internal.spec=ALL-UNNAMED --add-exports=java.base/sun.security.provider=ALL-UNNAMED"
• JDK_JAVAC_FIPS_OPTIONS="--add-exports=java.base/sun.security.internal.spec=ALL-UNNAMED --add-exports=java.base/sun.security.provider=ALL-UNNAMED"
• JAVA_TRUSTSTORE_OPTIONS="-Djavax.net.ssl.trustStoreType=FIPS"

Warning: These variable values must not be changed. If you need to use custom CLASSPATH or other JDK options, make sure to include these variables in your new variable declarations. Ensure that the JAVA_TRUSTSTORE_OPTIONS is part of your JDK_JAVA_OPTIONS variablee when using this image as a base image.

In addition, the following environment variables are also exported by default and can be updated as needed:

• CLASSPATH=$JAVA_FIPS_CLASSPATH:.:./*
• JDK_JAVA_OPTIONS=$JDK_JAVA_FIPS_OPTIONS $JAVA_TRUSTSTORE_OPTIONS
• JDK_JAVAC_OPTIONS=$JDK_JAVAC_FIPS_OPTIONS

When updating your classpath variable, make sure to keep the path to the bouncycastle-fips folder in your classpath, so the Bouncy Castle libraries are discoverable:

CLASSPATH="${JAVA_FIPS_CLASSPATH}:${CLASSPATH}"

When updating the JDK_JAVA_OPTIONS/JDK_JAVAC_OPTIONS environment variables, make sure to specify the exports options required for Bouncy Castle to work properly:

JDK_JAVA_OPTIONS="${JDK_JAVA_FIPS_OPTIONS} ${JDK_JAVA_OPTIONS}"
JDK_JAVAC_OPTIONS="${JDK_JAVAC_FIPS_OPTIONS} ${JDK_JAVAC_OPTIONS}"

If you need the use of the converted keystore, make sure to also add the JAVA_TRUSTSTORE_OPTIONS variable to your JDK_JAVA_OPTIONS:

JDK_JAVA_OPTIONS="${JAVA_TRUSTSTORE_OPTIONS} ${JDK_JAVA_OPTIONS}"
JDK_JAVAC_OPTIONS="${JDK_JAVAC_OPTIONS}"

Alternatively, these can be also set as an argument to the JVM tools via the --class-path/-cp and -D options. Please note these arguments take precedence over the environment variables:

javac --class-path "${JAVA_FIPS_CLASSPATH}:." ${JDK_JAVAC_FIPS_OPTIONS} TestClass.java
java -cp "${JAVA_FIPS_CLASSPATH}:." ${JDK_JAVA_FIPS_OPTIONS} TestClass
jshell --class-path "${JAVA_FIPS_CLASSPATH}:." ${JDK_JAVAC_FIPS_OPTIONS}

Checking the configuration is being loaded correctly

Execute the org.bouncycastle.util.DumpInfo:

docker run --rm -t --pull=always cgr.dev/ORGANIZATION/jdk-fips java org.bouncycastle.util.DumpInfo

It should provide output similar to the below:

$ docker run --rm -t --pull=always cgr.dev/ORGANIZATION/jdk-fips java org.bouncycastle.util.DumpInfo
latest: Pulling from ORGANIZATION/jdk-fips
Digest: sha256:b9ce5e8d7a8005e8a22e2bc443ec04d24cf01bea28a75803cc15c8e9e817a5f5
Status: Image is up to date for cgr.dev/ORGANIZATION/jdk-fips:latest
NOTE: Picked up JDK_JAVA_OPTIONS: --add-exports=java.base/sun.security.internal.spec=ALL-UNNAMED --add-exports=java.base/sun.security.provider=ALL-UNNAMED -Djavax.net.ssl.trustStoreType=FIPS
Picked up JAVA_TOOL_OPTIONS: --module-path=/usr/share/java/bouncycastle-fips
Version Info: BouncyCastle Security Provider (FIPS edition) v2.1.0
FIPS Ready Status: READY
Native Ready Status: READY
Native Variant: vaes
Native Build Date: 2024-11-15T15:56:42
Native Support: AES/CBC AES/CFB AES/CTR AES/ECB AES/GCM DRBG NRBG SHA2
Module SHA-256 HMAC: 941ebff8db149f871fbbeaf90269c19453b1e9d3777541fda1c0cf9132b426ce

This class is also available to execute from within the codebase of your own applications.

As part of the effort to build this image, a set of tests was created that validates that the BCFIPS and BCJSSE providers are in use.

Some of these tests are shipped in the image in /usr/lib/bcfips-policy-140-3. They validate that allowed algorithms are available, and dissallowed ones are blocked.

Using this as a base image

Java 21 JDK

To consume this image as a base image, add it in the FROM statement of your Dockerfile. One can execute jars like this java --module-path /usr/share/java/bouncycastle-fips -jar. Without the ``-module-pathsetting one will eventually see cryptic runtime errors from JCA or JSSE APIs. Alternatively one can add jars to theCLASSPATH` and invoke the main class directly:

FROM cgr.dev/ORGANIZATION/jdk-fips:openjdk-21

WORKDIR /src
COPY MyClass.java .

RUN javac MyClass.java && \
    jar cvf my-app.jar *.class

This can also be worked into a multistage build using the JRE FIPS variant for running your application:

FROM cgr.dev/ORGANIZATION/jdk-fips:openjdk-21

WORKDIR /src
COPY MyClass.java .

RUN javac MyClass.java && \
    jar cvf my-app.jar *.class

FROM cgr.dev/ORGANIZATION/jre-fips:openjdk-21

WORKDIR /jars
COPY --from=builder /src/my-app.jar .

ENV CLASSPATH="${JAVA_FIPS_CLASSPATH}:/jars/*"
CMD ["MyApp"]

What are Chainguard Containers?

Chainguard Containers are minimal container images that are secure by default.

In many cases, the Chainguard Containers tagged as :latest contain only an open-source application and its runtime dependencies. These minimal container images typically do not contain a shell or package manager. Chainguard Containers are built with Wolfi, our Linux undistro designed to produce container images that meet the requirements of a more secure software supply chain.

The main features of Chainguard Containers include:

• Minimal design, without unnecessary software bloat
• Daily builds to ensure container images are up-to-date with available security patches
• High quality build-time SBOMs attesting to the provenance of all artifacts within the image
• Verifiable signatures provided by Sigstore
• Reproducible builds with Cosign and apko (read more about reproducibility)

For cases where you need container images with shells and package managers to build or debug, most Chainguard Containers come paired with a -dev variant.

Although the -dev container image variants have similar security features as their more minimal versions, they feature additional software that is typically not necessary in production environments. We recommend using multi-stage builds to leverage the -dev variants, copying application artifacts into a final minimal container that offers a reduced attack surface that won’t allow package installations or logins.

Learn More

To better understand how to work with Chainguard Containers, please visit Chainguard Academy and Chainguard Courses.

In addition to Containers, Chainguard offers VMs and Libraries. Contact Chainguard to access additional products.

Trademarks

This software listing is packaged by Chainguard. The trademarks set forth in this offering are owned by their respective companies, and use of them does not imply any affiliation, sponsorship, or endorsement by such companies.