OpenJDK JRE FIPS images with Bouncy Castle

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

The FIPS certified version of Bouncy Castle 2.0.0 (CMVP #4743) is compliant to the FIPS 140-3 standard when used in accordance with the Bouncy Castle Security Policy 2.0.0.

Customers prior to 22 August 2024 may also have access to tags with the FIPS certified version of Bouncy Castle 1.0.2 (CMVP #4616) which is compliant to the FIPS 140-2 standard when used in accordance with the Bouncy Castle Security Policy 1.0.2.

Please check SBOM of individual image tags to verify Bouncy Castle version.

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 2.0.0
• Bouncy Castle FIPS Java API User Guide 1.0.2
• Bouncy Castle FIPS Java API Upgrade Guide

Note: In this document, the registry and repository path will be referred as <registry>/<repository>. Make sure to replace those with the correct path of where your image is located.

Available versions and variants

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

Customers prior to 22 August 2024 may have -140-2 tags available for Java 11 & 17. Upon request either 140-2 or 140-3 variants can be set as default for Java 11 & 17, with existing customer tags defaulting to 140-2.

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 excludes every default security provider except for the SUN provider, leaving only the following configuration:

  security.provider.1=org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider C:DEFRND[SHA256];ENABLE{ALL};
  security.provider.2=org.bouncycastle.jsse.provider.BouncyCastleJsseProvider fips:BCFIPS
  security.provider.3=SUN

• 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";
  };

• It configures the keystore.type as bcfks, in order for Keystores 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

TL;DR: FIPS configuration via environment variables is exported by default, but if the application requires more configuration these must be patched accordingly. All environment variables and/or command-line options must be configured before running the application.

The Bouncy Castle APIs must be used in accordance with the Security Policy provided for compliance. See the [Bouncy Castle Security Policy] for more information.

This image ships with the following components:

• Bouncy Castle libraries for FIPS are shipped under /usr/share/java/bouncycastle-fips:
  • bc-fips.jar
  • bctls-fips.jar
  • bcpkix-fips.jar
  • bcutil-fips.jar

For version numbers please check SBOM.

• Java security configurations tailored to work with Bouncy Castle FIPS as established in the user guides and described in the previous section:
  • $JAVA_HOME/conf/security/java.security
  • /usr/lib/jvm/jdk-fips-config/java.policy

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

• JDK_JAVA_FIPS_OPTIONS="--add-exports java.base/sun.security.internal.spec=ALL-UNNAMED --add-exports=java.base/sun.security.provider=ALL-UNNAMED"
• JAVA_FIPS_CLASSPATH=/usr/share/java/bouncycastle-fips/*
• 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 JAVA_TRUSTSTORE_OPTIONS is part of your JDK_JAVA_OPTIONS variable 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

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 environment variable, make sure to specify the exports options required for Bouncy Castle to work properly:

JDK_JAVA_OPTIONS="${JDK_JAVA_FIPS_OPTIONS} ${JDK_JAVA_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}"

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}

Note: java -jar ignores classpath options. If your target application is a runnable jar, you will need to run it by including the jar in your classpath and invoking the main class. For example:

java -cp "${JAVA_FIPS_CLASSPATH}:.:./*:<path to your jar here>" org.example.Main

Checking the configuration is being loaded correctly

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 and /usr/lib/bcfips-policy-140-2. They validate that allowed algorithms are available, and dissallowed ones are blocked.

Using this as a base image

To consume this image as a base image, add it in the FROM statement of your Dockerfile. In order for the predefined environment variables to be correctly consumed, java -jar must not be used, as it overrides CLASSPATH options. Instead, add your jars to the CLASSPATH and invoke the main class directly:

FROM <registry>/<repository>/jre-fips:openjdk-21

ENV CLASSPATH="${JAVA_FIPS_CLASSPATH}:./*"

CMD ["MyApp"]

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

FROM <registry>/<repository>/jdk-fips:openjdk-21

WORKDIR /src
COPY MyClass.java .

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

FROM <registry>/<repository>/jre-fips:openjdk-21

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

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