--- title: FIPS 140-2 compliance description: In IDM 7.4.2 and later, the embedded Jetty web server supports Jetty 12. Future releases of IDM 7.4.x are only compatible with Java 17. Jetty 12 requires this change. component: pingidm version: 7.4 page_id: pingidm:security-guide:security-bouncy-castle-fips canonical_url: https://docs.pingidentity.com/pingidm/8.1/security-guide/security-bouncy-castle-fips.html llms_txt: https://docs.pingidentity.com/pingidm/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md keywords: ["Security", "Bouncy Castle FIPS", "Keystores", "Cryptographic Keys", "Secrets", "JSON", "Configuration", "JVM"] superseded_by: https://docs.pingidentity.com/pingidm/8.1/security-guide/security-bouncy-castle-fips.html section_ids: download-bouncy-castle-libraries: Download the Bouncy Castle libraries enable-bouncy-castle-in-jvm: Enable the Bouncy Castle FIPS provider in the JVM add-bouncy-castle-existing-jvm: Add Bouncy Castle providers to the existing JVM add-bouncy-castle-idm-config: Add Bouncy Castle providers to IDM conf/java.security add-bouncy-castle-new-jvm-dist: Build a distribution of the JVM that supports Bouncy Castle create-bouncy-castle-crypto-keys: Create the IDM Bouncy Castle keystore and cryptographic keys bouncy-castle-jvm-to-idm: Provide the JVM to IDM configure-bouncy-castle-keystore: Configure the Bouncy Castle keystore in secrets.json disable_bouncy_castle_fips_approved_mode: Disable Bouncy Castle FIPS-approved mode --- # FIPS 140-2 compliance | | | | - | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | In IDM 7.4.2 and later, the embedded Jetty web server supports Jetty 12. Future releases of IDM 7.4.x are only compatible with Java 17. Jetty 12 requires this change.When serving SSL requests, Jetty 12 checks that the incoming host header matches the server certificate's subject and returns a `400 Bad Request` error on a mismatch. If you're upgrading to IDM 7.4.2 or later, you must ensure your IDM server certificate subject matches the host name used by your deployment.Learn more in [What's new](../release-notes/whats-new.html#jetty-12-support-74). | To achieve [FIPS 140-2](https://csrc.nist.gov/publications/detail/fips/140/2/final) compliance, configure the [Bouncy Castle FIPS libraries](https://www.bouncycastle.org/fips-java/) with IDM. This enables the use of the Bouncy Castle FIPS keystore and security provider in FIPS-approved mode. Bouncy Castle FIPS is useful when dealing with government data, where meeting the FIPS 140-2 security requirement is necessary for regulatory compliance. | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | | Bouncy Castle FIPS is less performant than other keystores. The destroyable keys cannot be cached and must be read from the keystore with every use. | To configure IDM to use Bouncy Castle FIPS: 1. [Download the Bouncy Castle libraries](#download-bouncy-castle-libraries). 2. [Enable the Bouncy Castle FIPS provider in the JVM](#enable-bouncy-castle-in-jvm). 3. [Create the IDM cryptographic keys](#create-bouncy-castle-crypto-keys). 4. [Provide the JVM to IDM](#bouncy-castle-jvm-to-idm). 5. [Configure the Bouncy Castle keystore in `secrets.json`](#configure-bouncy-castle-keystore). ## Download the Bouncy Castle libraries | | | | - | ---------------------------------------------------------------------------------------- | | | The [IDM CLI](../setup-guide/chap-cli.html) does not work when using Bouncy Castle FIPS. | To use Bouncy Castle FIPS with IDM, download the libraries: 1. Download the following libraries from [Bouncy Castle](https://www.bouncycastle.org/fips-java/) to the server/machine where IDM is deployed: | File | Description | | ---------------------------------------- | ----------------------------------------------------------------- | | `bc-fips-latestVersionNumber.jar`(1) | Contains the Bouncy Castle FIPS security provider implementation. | | `bcpkix-fips-latestVersionNumber.jar`(2) | Provides FIPS support for cert generation. | | `bctls-fips-latestVersionNumber.jar`(3) | Provides TLS support using FIPS compliance. | (1) The tested version is `bc-fips-1.0.2.3.jar`. (2) The tested version is `bcpkix-fips-1.0.7.jar`. (3) The tested version is `bctls-fips-1.0.14.jar`. 2. Copy the downloaded files to `/path/to/openidm/bundle`. 3. Restart IDM. ## Enable the Bouncy Castle FIPS provider in the JVM To enable the Bouncy Castle FIPS provider in your JVM, do one of the following: * [Add Bouncy Castle providers to the existing JVM](#add-bouncy-castle-existing-jvm) * [Add Bouncy Castle providers to IDM `conf/java.security`](#add-bouncy-castle-idm-config) * [Build a distribution of the JVM that supports Bouncy Castle](#add-bouncy-castle-new-jvm-dist) ### Add Bouncy Castle providers to the existing JVM If the existing JVM supports Bouncy Castle, then you can add the security providers to the JVM. Add the Bouncy Castle security providers to `$JAVA_HOME/conf/security/java.security`: ```bash security.provider.13=org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider C:HYBRID;ENABLE{All}; security.provider.14=org.bouncycastle.jsse.provider.BouncyCastleJsseProvider ``` | | | | - | ----------------------------------------------------------------------------------------------------------------------------------------- | | | The `security.provider.13` and `security.provider.14` keys are JVM specific and must be the next 2 values in the security providers list. | ### Add Bouncy Castle providers to IDM `conf/java.security` If the existing JVM supports Bouncy Castle, then you can add the security providers to the `/path/to/openidm/conf/java.security`. This file provides additions to the `$JAVA_HOME/conf/security/java.security` file. Add the Bouncy Castle security providers to `/path/to/openidm/conf/java.security`: ```bash security.provider.13=org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider C:HYBRID;ENABLE{All}; security.provider.14=org.bouncycastle.jsse.provider.BouncyCastleJsseProvider ``` | | | | - | ----------------------------------------------------------------------------------------------------------------------------------------- | | | The `security.provider.13` and `security.provider.14` keys are JVM specific and must be the next 2 values in the security providers list. | ### Build a distribution of the JVM that supports Bouncy Castle If the existing JVM doesn't support Bouncy Castle, you must create a new JVM distribution. 1. Build a new distribution: ```bash $JAVA_HOME/bin/jlink \ --no-header-files \ --no-man-pages \ --compress=2 \ --module-path /Users/bjensen/Downloads \ --add-modules java.base,java.compiler,java.datatransfer,java.desktop,java.instrument,java.logging,java.management,java.management.rmi,java.naming,java.net.http,java.prefs,java.rmi,java.scripting,java.se,java.security.jgss,java.security.sasl,java.smartcardio,java.sql,java.sql.rowset,java.transaction.xa,java.xml,java.xml.crypto,jdk.accessibility,jdk.aot,jdk.attach,jdk.charsets,jdk.compiler,jdk.crypto.cryptoki,jdk.crypto.ec,jdk.dynalink,jdk.editpad,jdk.hotspot.agent,jdk.httpserver,jdk.internal.ed,jdk.internal.jvmstat,jdk.internal.le,jdk.internal.opt,jdk.internal.vm.ci,jdk.internal.vm.compiler,jdk.internal.vm.compiler.management,jdk.jartool,jdk.javadoc,jdk.jcmd,jdk.jconsole,jdk.jdeps,jdk.jdi,jdk.jdwp.agent,jdk.jfr,jdk.jlink,jdk.jshell,jdk.jsobject,jdk.jstatd,jdk.localedata,jdk.management,jdk.management.agent,jdk.management.jfr,jdk.naming.dns,jdk.naming.ldap,jdk.naming.rmi,jdk.net,jdk.pack,jdk.rmic,jdk.scripting.nashorn,jdk.scripting.nashorn.shell,jdk.sctp,jdk.security.auth,jdk.security.jgss,jdk.unsupported,jdk.unsupported.desktop,jdk.xml.dom,jdk.zipfs,org.bouncycastle.fips.core,org.bouncycastle.fips.tls \ --output /location/to/bouncy/castle/jvm --ignore-signing-information ``` A customized JVM is created at the output location /location/to/bouncy/castle/jvm you specified. 2. Add the Bouncy Castle security providers to `/location/to/bouncy/castle/jvm/conf/security/java.security`: ```bash security.provider.13=org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider C:HYBRID;ENABLE{All}; security.provider.14=org.bouncycastle.jsse.provider.BouncyCastleJsseProvider ``` | | | | - | ----------------------------------------------------------------------------------------------------------------------------------------- | | | The `security.provider.13` and `security.provider.14` keys are JVM specific and must be the next 2 values in the security providers list. | ## Create the IDM Bouncy Castle keystore and cryptographic keys | | | | - | ------------------------------------------------------------------------------------------------------------------------------------- | | | Before you create the cryptographic keys, you must [Enable the Bouncy Castle FIPS provider in the JVM](#enable-bouncy-castle-in-jvm). | To create the necessary IDM cryptographic keys: 1. Create the Bouncy Castle keystore. This can be done in conjunction with creating the first cryptographic key: ```bash keytool \ -genseckey \ -alias openidm-sym-default \ -keyalg aes \ -keysize 256 \ -keystore /location/to/keystore.bcfks \ -storepass changeit -storetype BCFKS \ -provider org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider ``` This creates the `openidm-sym-default` key in a keystore called /location/to/keystore.bcfks while also creating that keystore if it does not exist. | | | | - | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | You must use the JVM specific keytool that the Bouncy Castle security provider uses.For example, if you enable the security providers in the [system default JVM](#add-bouncy-castle-existing-jvm), you must use the system default keytool command. If you create a custom JVM, you must use the keytool command for where that JVM is located.The keytool command is in the `bin` directory of the JVM Java home.Failure to use the `keytool` command you configure for Bouncy Castle results in the following error:```bash keytool error: java.lang.Exception: Provider "org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider" not found ``` | 2. Create the remaining keys: Create the `openidm-selfservice-key` ```bash keytool \ -genseckey \ -alias openidm-selfservice-key \ -keyalg aes \ -keysize 256 \ -keystore /location/to/keystore.bcfks \ -storepass changeit \ -storetype BCFKS \ -provider org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider ``` Create the `openidm-jwtsessionhmac-key` ```bash keytool \ -genseckey \ -alias openidm-jwtsessionhmac-key \ -keyalg aes \ -keysize 256 \ -keystore /location/to/keystore.bcfks \ -storepass changeit \ -storetype BCFKS \ -provider org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider ``` Create the `openidm-localhost` key ```bash keytool \ -genkey \ -alias openidm-localhost \ -keyalg RSA \ -keysize 2048 \ -keystore /location/to/keystore.bcfks \ -storepass changeit \ -storetype BCFKS \ -provider org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider ``` Create the `selfservice` key ```bash keytool \ -genkey \ -alias selfservice \ -keyalg RSA \ -keysize 2048 \ -keystore /location/to/keystore.bcfks \ -storepass changeit \ -storetype BCFKS \ -provider org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider ``` ## Provide the JVM to IDM If you create a [custom JVM location](#add-bouncy-castle-new-jvm-dist), you must to provide that JVM to IDM in the `/path/to/openidm/startup.sh` file. By default, IDM uses the system Java and falls back to using the `JAVA_HOME` if the system Java is not defined: Default `startup.sh` file ```bash if which java &>/dev/null; then JAVA=java elif [ -n "$JAVA_HOME" ] && [ -x "$JAVA_HOME/bin/java" ]; then JAVA="$JAVA_HOME/bin/java" else echo JAVA_HOME not available, Java is needed to run IDM echo Please install Java and set JAVA_HOME accordingly exit 1 fi ``` To configure IDM to use the `JAVA_HOME` you set, change the `startup.sh` file to the following: Modified `startup.sh` file ```bash if [ -n "$JAVA_HOME" ] && [ -x "$JAVA_HOME/bin/java" ]; then JAVA="$JAVA_HOME/bin/java" else echo JAVA_HOME not available, Java is needed to run IDM echo Please install Java and set JAVA_HOME accordingly exit 1 fi ``` ## Configure the Bouncy Castle keystore in `secrets.json` After you add the [Bouncy Castle security providers](#enable-bouncy-castle-in-jvm) and [create the keystore and keys](#create-bouncy-castle-crypto-keys), you must replace the default IDM keystore with the new Bouncy Castle keystore in `/path/to/openidm/conf/secrets.json`: ```bash { "name" : "mainKeyStore", "class" : "org.forgerock.openidm.secrets.config.FileBasedStore", "config" : { "file" : "&{idm.install.dir}/security/keystore.bcfks", "storetype" : "BCFKS", "providerName" : "BCFIPS", "storePassword" : "changeit", "mappings" : [ { "secretId" : "idm.default", "types" : [ "ENCRYPT", "DECRYPT" ], "aliases" : [ "&{openidm.config.crypto.alias|openidm-sym-default}" ] }, { "secretId" : "idm.config.encryption", "types" : [ "ENCRYPT", "DECRYPT" ], "aliases" : [ "&{openidm.config.crypto.alias|openidm-sym-default}" ] }, { "secretId" : "idm.password.encryption", "types" : [ "ENCRYPT", "DECRYPT" ], "aliases" : [ "&{openidm.config.crypto.alias|openidm-sym-default}" ] }, { "secretId" : "idm.assignment.attribute.encryption", "types" : [ "ENCRYPT", "DECRYPT" ], "aliases" : [ "&{openidm.config.crypto.alias|openidm-sym-default}" ] } ] } }, ``` IDM is now configured to start using the Bouncy Castle keystore. ## Disable Bouncy Castle FIPS-approved mode By default, IDM turns on Bouncy Castle in FIPS-approved mode. This makes Bouncy Castle FIPS 140-2 compliant. IDM sets the configuration in `/path/to/openidm/startup.sh` and `/path/to/openidm/bin/docker-entrypoint.sh` using the following property: ```bash org.bouncycastle.fips.approved_only=true ``` To disable FIPS-approved mode, change `org.bouncycastle.fips.approved_only` to `false`. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | In `startup.sh` and `docker-entrypoint.sh` there is also the property `org.bouncycastle.jca.enable_jks=true`. This property enables the Java keystore (JKS format) for FIPS. In order to maintain compliance, the keystore can only be used for reading a Java keystore that contains certificates. IDM sets this property to `true` by default. | | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------- | | | These settings must take place early in the IDM start process per [Bouncy Castle's documentation](https://www.bouncycastle.org/fips-java/). |