FIPS 140-3 compliance

To achieve FIPS 140-3 compliance, configure the Bouncy Castle FIPS libraries with IDM. This enables the use of the Bouncy Castle FIPS key store and security provider in FIPS-approved mode.

Bouncy Castle FIPS is crucial when dealing with government data, where you must meet the FIPS 140-3 security requirement for regulatory compliance.

Bouncy Castle FIPS is less performant than other key stores. The destroyable keys cannot be cached and must be read from the key store with every use.

To configure IDM to use Bouncy Castle FIPS:

Download the Bouncy Castle libraries.
Enable the Bouncy Castle FIPS provider in the JVM.
Create the IDM cryptographic keys.
Provide the JVM to IDM.
Configure the Bouncy Castle key store in secrets.json.

Download the Bouncy Castle libraries

The IDM CLI does not work when using Bouncy Castle FIPS.

To use Bouncy Castle FIPS with IDM, download the libraries:

Download the following libraries from Bouncy Castle to the server/machine where IDM is deployed:

File Description

File	Description
`bc-fips-latestVersionNumber.jar`⁽¹⁾	Contains the Bouncy Castle FIPS security provider implementation.
`bcpkix-fips-latestVersionNumber.jar`⁽²⁾	Provides FIPS support for cert generation.
`bctls-fips-latestVersionNumber.jar`⁽³⁾	Provides TLS support using FIPS compliance.
`bcmail-fips-latestVersionNumber.jar`⁽⁴⁾	The Bouncy Castle Java APIs for doing S/MIME with JavaMail.
`bcutil-fips-latestVersionNumber.jar`⁽⁵⁾	The Bouncy Castle Java APIs for ASN.1 extension and other utility APIs.

bc-fips-latestVersionNumber.jar⁽¹⁾

Contains the Bouncy Castle FIPS security provider implementation.

bcpkix-fips-latestVersionNumber.jar⁽²⁾

Provides FIPS support for cert generation.

bctls-fips-latestVersionNumber.jar⁽³⁾

Provides TLS support using FIPS compliance.

bcmail-fips-latestVersionNumber.jar⁽⁴⁾

The Bouncy Castle Java APIs for doing S/MIME with JavaMail.

bcutil-fips-latestVersionNumber.jar⁽⁵⁾

The Bouncy Castle Java APIs for ASN.1 extension and other utility APIs.

⁽¹⁾ The tested version is bc-fips-2.1.0.jar.

⁽²⁾ The tested version is bcpkix-fips-2.1.9.jar.

⁽³⁾ The tested version is bctls-fips-2.1.20.jar.

⁽⁴⁾ The tested version is bcmail-fips-2.1.6.jar.

⁽⁵⁾ The tested version is bcutil-fips-2.1.4.jar.

Copy the downloaded files to /path/to/openidm/bundle.
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 providers to IDM conf/java.security

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 as the first and second security providers:

security.provider.1=org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider C:HYBRID;ENABLE{All};
security.provider.2=org.bouncycastle.jsse.provider.BouncyCastleJsseProvider

The Bouncy Castle security providers should be 1 and 2. You should add any other security providers necessary for your use case.

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.

Add the Bouncy Castle security providers to /path/to/openidm/conf/java.security:

security.provider.1=org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider C:HYBRID;ENABLE{All};
security.provider.2=org.bouncycastle.jsse.provider.BouncyCastleJsseProvider

This file overrides the $JAVA_HOME/conf/security/java.security file. You should also add any additional security providers from that file which are necessary for your use case.

Create the IDM Bouncy Castle key store and cryptographic keys

Before you create the cryptographic keys, you must Enable the Bouncy Castle FIPS provider in the JVM.

To create the necessary IDM cryptographic keys:

Create the Bouncy Castle key store. This can be done in conjunction with creating the first cryptographic key:

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
-providerpath /path/to/bc-fips-2.1.0.jar

This creates the openidm-sym-default key in a key store 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, 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:

keytool error: java.lang.Exception: Provider "org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider" not found

Create the remaining keys:

Create the openidm-selfservice-key

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
-providerpath /path/to/bc-fips-2.1.0.jar

Create the openidm-jwtsessionhmac-key

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
-providerpath /path/to/bc-fips-2.1.0.jar

Create the openidm-localhost key

keytool \
-genkey \
-alias openidm-localhost \
-keyalg RSA \
-keysize 2048 \
-keystore /location/to/keystore.bcfks \
-storepass changeit \
-storetype BCFKS \
-provider org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider
-providerpath /path/to/bc-fips-2.1.0.jar

Create the selfservice key

keytool \
-genkey \
-alias selfservice \
-keyalg RSA \
-keysize 2048 \
-keystore /location/to/keystore.bcfks \
-storepass changeit \
-storetype BCFKS \
-provider org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider
-providerpath /path/to/bc-fips-2.1.0.jar

Provide the JVM to IDM

If you create a custom JVM location, 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

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

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 key store in `secrets.json`

After you add the Bouncy Castle security providers and create the key store and keys, you must replace the default IDM key store with the new Bouncy Castle key store in /path/to/openidm/conf/secrets.json:

        {
            "name" : "mainKeyStore",
            "class" : "org.forgerock.openidm.secrets.config.KeyStoreSecretStore",
            "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.jwt.session.module.encryption",
                        "types" : [
                            "ENCRYPT",
                            "DECRYPT"
                        ],
                        "aliases" : [
                            "&{openidm.https.keystore.cert.alias|openidm-localhost}"
                        ]
                    },
                    {
                        "secretId" : "idm.jwt.session.module.signing",
                        "types" : [
                            "SIGN",
                            "VERIFY"
                        ],
                        "aliases" : [
                            "&{openidm.config.crypto.jwtsession.hmackey.alias|openidm-jwtsessionhmac-key}"
                        ]
                    },
                    {
                        "secretId" : "idm.selfservice.encryption",
                        "types" : [
                            "ENCRYPT",
                            "DECRYPT"
                        ],
                        "aliases" : [
                            "selfservice"
                        ]
                    },
                    {
                        "secretId" : "idm.selfservice.signing",
                        "types" : [
                            "SIGN",
                            "VERIFY"
                        ],
                        "aliases" : [
                            "&{openidm.config.crypto.selfservice.sharedkey.alias|openidm-selfservice-key}"
                        ]
                    },
                    {
                        "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 key store.

Disable Bouncy Castle FIPS-approved mode

By default, IDM turns on Bouncy Castle in FIPS-approved mode. This makes Bouncy Castle FIPS 140-3 compliant.

IDM sets the configuration in /path/to/openidm/startup.sh and /path/to/openidm/bin/docker-entrypoint.sh using the following property:

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, the org.bouncycastle.jca.enable_jks property enables the JKS-format Java key store for FIPS. In order to maintain compliance, this key store can only be used for reading JKS key stores containing certificates.

By default, this property is false. To enable the key store, set it to true.

These settings must take place early in the IDM start process per Bouncy Castle’s documentation.

PingIDM 8.0.0