FIPS 140–3 compliance

To achieve FIPS 140-3 compliance, configure the Bouncy Castle FIPS libraries with AM. 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 you must meet the FIPS 140-3 security requirement for regulatory compliance.

Bouncy Castle FIPS is less performant than other keystores. The destroyable keys can’t be cached and must be read from the keystore with every use.

Download the Bouncy Castle libraries

Before you begin, download the following Bouncy Castle FIPS library:

bc-fips-latestVersion.jar

This is the Bouncy Castle FIPS security provider implementation.

Ping Identity supports PingAM and its use of the Bouncy Castle libraries. Ping Identity doesn’t support third-party libraries themselves.

Enable the Bouncy Castle FIPS provider for your web container

These example commands assume you’re using Apache Tomcat. Adjust the examples for your web container.

Create a dedicated folder to house the Bouncy Castle library and copy the downloaded library to that folder. For example:
```
$ mkdir /path/to/bcfips
$ cp ~/Downloads/bc-fips-latestVersion.jar /path/to/bcfips
```
Create a custom java.security file by copying your default JVM security file to the /path/to/bcfips folder. For example:
```
$  cp $JAVA_HOME/conf/security/java.security /path/to/bcfips
```

Add the Bouncy Castle FIPS security provider as the first provider in the custom java.security file:

security.provider.1=org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider
security.provider.2=SUN

The Bouncy Castle security provider must be number 1 in this file.
The Bouncy Castle provider requires the SUN provider, so leave this provider configured even if you remove other providers from the list.
You should only have these providers listed to make sure only FIPS-compliant algorithms are used. Including other providers in the list risks the use of a non-compliant algorithm. Learn more in the Bouncy Castle FIPS Java API User Guide.

Edit Tomcat’s container startup script, for example setenv.sh, to set the FIPs-related JVM system properties and to let Tomcat locate the Bouncy Castle library:
```
export JAVA_OPTS="$JAVA_OPTS -Djava.security.properties==/path/to/bcfips/java.security"
export JAVA_OPTS="$JAVA_OPTS -Dorg.bouncycastle.fips.approved_only=true"
export CLASSPATH=$CLASSPATH:/path/to/bc-fips-latestVersion.jar
```
The == shown for the -Djava.security.properties property is necessary.
Restart Tomcat.

Use a Bouncy Castle keystore

BCFKS (Bouncy Castle FIPS Keystore) is a type of Java keystore designed to work with the Bouncy Castle FIPS cryptographic provider. A BCFKS keystore lets you securely store cryptographic keys and certificates in a format that’s FIPS 140-3-compliant.

To use the Java keytool command to manage BCFKS keystores you must do one of the following:

Set your system JAVA_HOME environment variable to the BCFIPS path. This ensures that any keytool commands you run use the BCFIPS provider.

Add the following parameters to keytool commands:

-providerclass org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider
-providerpath /path/to/bcfips/bc-fips-version.jar \

Aliases in BCFKS keystores are case-sensitive.
If you’re migrating from other keystore types, you might encounter limitations when migrating passwords (as opposed to cryptographic keys) to BCFKS. This is because BCFKS keystores don’t support storing secrets with the RAW algorithm.

Before you migrate passwords from the old keystore, change the storage algorithm to one that doesn’t enforce length restrictions during storage or retrieval of the key, for example, HmacSHA512. There are no length restrictions on using the key, just on storing the key.

For example, this command creates an asymmetric key pair and self-signed certificate, with alias newkey in a new BCFKS keystore named keystore.bcfks:

$ cd /path/to/am/security/keystores/
$ keytool \
-genkeypair \
-providername BCFIPS \
-providerpath /path/to/bcfips/bc-fips-version.jar \
-providerclass org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider \
-alias newkey \
-keyalg RSA \
-keysize 2048 \
-keystore keystore.bcfks \
-validity 365 \
-storetype BCFKS \
-storepass password \
-keypass password \
-dname "CN=newkey"

To use a BCFKS keystore for any global or realm keystore, in the AM admin UI:

Set the Keystore type to BCFKS.
Set the Provider name to BCFIPS.

Also read Use a Bouncy Castle keystore as the AM keystore.

Disable Bouncy Castle FIPS-approved mode

To disable Bouncy Castle FIPS-compliant mode:

Edit your web container’s startup script to remove or comment out the BCFKS-specific Java options. For example, in setenv.sh:

 export JAVA_OPTS="$JAVA_OPTS -Djava.security.properties==/path/to/bcfips/java.security"
 export JAVA_OPTS="$JAVA_OPTS -Dorg.bouncycastle.fips.approved_only=true"
## export CLASSPATH=$CLASSPATH:/path/to/bc-fips-latestVersion.jar

Restart AM.

Allow RSA key multi-use

By default, the Bouncy Castle FIPS module prevents an RSA modulus from being used for both encryption and signing operations. This is a security measure to avoid potential vulnerabilities.

However, specific scenarios might require an RSA key to be used for both purposes. To allow this, set the following JVM property in your web container’s startup script:

export JAVA_OPTS="$JAVA_OPTS -Dorg.bouncycastle.rsa.allow_multi_use=true"

Enabling this property relaxes a security control. Understand the implications before setting org.bouncycastle.rsa.allow_multi_use=true. Consult relevant security best practices and the Bouncy Castle documentation for more information.