--- title: FIPS 140–3 compliance description: 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. component: pingam version: 8.1 page_id: pingam:security:fips canonical_url: https://docs.pingidentity.com/pingam/8.1/security/fips.html keywords: ["Security", "Bouncy Castle FIPS", "Keystores", "Cryptographic Keys", "Secrets", "JSON", "Configuration", "JVM"] section_ids: download-bouncy-castle-libraries: Download the Bouncy Castle libraries enable-bouncy-castle-for-container: Enable the Bouncy Castle FIPS provider for your web container manage-bcfks-keystores: Use a Bouncy Castle keystore disable_bouncy_castle_fips_approved_mode: Disable Bouncy Castle FIPS-approved mode allow-rsa-key-multi-use: Allow RSA key multi-use --- # FIPS 140–3 compliance To achieve [FIPS 140-3](https://csrc.nist.gov/pubs/fips/140-3/final) compliance, configure the [Bouncy Castle FIPS libraries](https://www.bouncycastle.org/fips-java/) 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](https://www.bouncycastle.org/fips-java/): `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. 1. Create a dedicated folder to house the Bouncy Castle library and copy the downloaded library to that folder. For example: ```bash $ mkdir /path/to/bcfips $ cp ~/Downloads/bc-fips-latestVersion.jar /path/to/bcfips ``` 2. Create a custom `java.security` file by copying your default JVM security file to the `/path/to/bcfips` folder. For example: ```bash $ cp $JAVA_HOME/conf/security/java.security /path/to/bcfips ``` 3. Add the Bouncy Castle FIPS security provider as the first provider in the custom `java.security` file: ```bash 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](https://downloads.bouncycastle.org/fips-java/docs/BC-FJA-UserGuide-2.0.0.pdf). | 4. 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: ```none 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-[.var]_latestVersion_.jar ``` | | | | - | -------------------------------------------------------------------------- | | | The `==` shown for the `-Djava.security.properties` property is necessary. | 5. 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: ```bash -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`: ```bash $ 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](am-keystore.html#bouncy-castle-keystore-as-am-keytore). ## Disable Bouncy Castle FIPS-approved mode To disable Bouncy Castle FIPS-compliant mode: 1. Edit your web container's startup script to remove or comment out the BCFKS-specific Java options. For example, in `setenv.sh`: ```none ## 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-[.var]_latestVersion_.jar ``` 2. 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: ```bash 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](https://www.bouncycastle.org/fips-java/) for more information. |