Chainguard Image for jdk-fips

Chainguard Images are regularly-updated, minimal container images with low-to-zero CVEs.

Download this Image

This 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 certified version of Bouncy Castle (CMVP [#4743]) 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]
• [Bouncy Castle FIPS Java API Upgrade Guide]

Note: In this document, the registry and repository path will be referred as cgr.dev/ORGANIZATION. 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:

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

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

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: ```dockerfile 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"]

[#4743]: https://csrc.nist.gov/projects/cryptographic-module-validation-program/certificate/4743
[Bouncy Castle Security Policy]: https://csrc.nist.gov/CSRC/media/projects/cryptographic-module-validation-program/documents/security-policies/140sp4743.pdf
[Bouncy Castle FIPS Java API User Guide]: https://downloads.bouncycastle.org/fips-java/BC-FJA-UserGuide-2.0.0.pdf
[Bouncy Castle FIPS Java API Upgrade Guide]: https://downloads.bouncycastle.org/fips-java/docs/BC-FJA%202.0.0%20Porting%20Guide.pdf

## Contact Support

If you have a Zendesk account (typically set up for you by your Customer Success Manager) you can reach out to Chainguard's Customer Success team through our [Zendesk portal](https://support.chainguard.dev/hc/en-us).

## What are Chainguard Images?

[Chainguard Images](https://www.chainguard.dev/chainguard-images?utm_source=readmes) are a collection of container images designed for security and minimalism.

Many Chainguard Images are [distroless](https://edu.chainguard.dev/chainguard/chainguard-images/getting-started-distroless/); they contain only an open-source application and its runtime dependencies. These images do not even contain a shell or package manager. Chainguard Images are built with [Wolfi](https://edu.chainguard.dev/open-source/wolfi/overview), our Linux _undistro_ designed to produce container images that meet the requirements of a secure software supply chain.

The main features of Chainguard Images include:

* Minimal design, with no unnecessary software bloat
* Automated nightly builds to ensure Images are completely up-to-date and contain all available security patches
* [High quality build-time SBOMs](https://edu.chainguard.dev/chainguard/chainguard-images/working-with-images/retrieve-image-sboms/) (software bills of materials) attesting the provenance of all artifacts within the Image
* [Verifiable signatures](https://edu.chainguard.dev/chainguard/chainguard-images/working-with-images/retrieve-image-sboms/) provided by [Sigstore](https://edu.chainguard.dev/open-source/sigstore/cosign/an-introduction-to-cosign/)
* Reproducible builds with Cosign and apko ([read more about reproducibility](https://www.chainguard.dev/unchained/reproducing-chainguards-reproducible-image-builds))

### `-dev` Variants

As mentioned previously, Chainguard’s distroless Images have no shell or package manager by default. This is great for security, but sometimes you need these things, especially in builder images. For those cases, most (but not all) Chainguard Images come paired with a `-dev` variant which does include a shell and package manager.

Although the `-dev` image variants have similar security features as their distroless versions, such as complete SBOMs and signatures, they feature additional software that is typically not necessary in production environments. The general recommendation is to use the `-dev` variants only to build the application and then copy all application artifacts into a distroless image, which will result in a final container image that has a minimal attack surface and won’t allow package installations or logins.

That being said, it’s worth noting that `-dev` variants of Chainguard Images are completely fine to run in production environments. After all, the `-dev` variants are still **more secure** than many popular container images based on fully-featured operating systems such as Debian and Ubuntu since they carry less software, follow a more frequent patch cadence, and offer attestations for what they include.

## Learn More

To better understand how to work with Chainguard Images, we encourage you to visit [Chainguard Academy](https://edu.chainguard.dev/), our documentation and education platform.