PingDS

FIPS 140–3 compliance

To achieve FIPS 140–3 compliance, configure the Bouncy Castle FIPS libraries with DS. 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–3 security requirements is necessary for regulatory compliance. Bouncy Castle FIPS doesn’t require use of an HSM through a PKCS#11 interface.

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.

To configure DS to use Bouncy Castle FIPS:

  1. Download the Bouncy Castle libraries.

  2. Set up DS.

  3. Configure DS to use Bouncy Castle FIPS support.

  4. Enable the Bouncy Castle FIPS provider.

  5. Start DS.

For information on running DS commands after configuring Bouncy Castle FIPS, read Command support for Bouncy Castle FIPS.

Download the Bouncy Castle libraries

Before you begin, download the Bouncy Castle FIPS libraries:

File Description Tested version

bc-fips-latestVersion.jar

Bouncy Castle FIPS security provider implementation

bc-fips-2.0.0.jar

bcpkix-fips-latestVersion.jar

Certificate generation support

bcpkix-fips-2.0.7.jar

bctls-fips-latestVersion.jar

TLS support

bctls-fips-2.0.19.jar

bcutil-fips-latestVersion.jar

ASN.1 Utility Classes

bcutil-fips-2.0.3.jar

Set up DS

Set up but don’t start DS before you enable the Bouncy Castle FIPS provider in the JVM.

  1. Set up DS for your use case and omit the --start option.

    The following example command uses the evaluation setup profile but doesn’t start the server:

    $ ./opendj/setup \
 --serverId evaluation-only \
 --deploymentId $DEPLOYMENT_ID \
 --deploymentIdPassword password \
 --rootUserDN uid=admin \
 --rootUserPassword StrongPassword \
 --monitorUserPassword StrongPassword \
 --hostname localhost \
 --adminConnectorPort 4444 \
 --ldapPort 1389 \
 --enableStartTls \
 --ldapsPort 1636 \
 --httpsPort 8443 \
 --replicationPort 8989 \
 --bootstrapReplicationServer localhost:8989 \
 --profile ds-evaluation \
 --acceptLicense

    As in the example command, make sure passwords used to connect are at least 14 characters (14 bytes) long. If the passwords are too short, commands display the following error message:

    Other: password must be at least 112 bits

    This example uses deployment ID-based PKI. For most FIPS-compliant deployments, use your own cryptographic keys.

  2. Copy the Bouncy Castle libraries you downloaded to the DS extlib folder:

    $ ~/Downloads/bc*jar opendj/extlib/

  3. Create a Bouncy Castle FIPS format keystore from the DS default keystore:

    $ keytool \
-importkeystore \
-srckeystore opendj/config/keystore \
-srcstoretype PKCS12 \
-srcstorepass:file opendj/config/keystore.pin \
-destkeystore opendj/config/keystore.bcfks \
-deststoretype BCFKS \
-deststorepass:file opendj/config/keystore.pin \
-providerpath opendj/extlib/bc-fips-2.0.0.jar \
-providerclass org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider \
-noprompt

    The new keystore holds the same keys created at setup time.

  4. (Optional) Perform other offline configuration required before starting DS.

    This step depends on the deployment. For the evaluation profile, there’s nothing to do.

Configure DS to use Bouncy Castle FIPS support

Before you start DS, configure the server offline to use the Bouncy Castle FIPS format keystore.

Create key providers

Create key providers for the Bouncy Castle FIPS format keystore.

  1. Create a key manager provider:

    $ ./opendj/bin/dsconfig \
create-key-manager-provider \
--provider-name BCFIPS \
--type file-based \
--set enabled:true \
--set key-store-file:/path/to/opendj/config/keystore.bcfks \
--set "key-store-pin:&{file:config/keystore.pin}" \
--set key-store-type:BCFKS \
--offline \
--no-prompt

    Here, /path/to/opendj is the path to the folder where you installed DS.

  2. Create a trust manager provider:

    $ ./opendj/bin/dsconfig \
create-trust-manager-provider \
--provider-name BCFIPS \
--type file-based \
--set enabled:true \
--set trust-store-file:/path/to/opendj/config/keystore.bcfks \
--set "trust-store-pin:&{file:config/keystore.pin}" \
--set trust-store-type:BCFKS \
--offline \
--no-prompt

    Here, /path/to/opendj is the path to the folder where you installed DS.

Use the new key providers

  1. Update DS connection handlers to use the new key providers.

    The following commands correspond to the connection handlers created by the example setup command in Set up DS. If DS uses other connection handlers in your deployment, update them as well.

    1. Update the LDAP connection handler:

      $ ./opendj/bin/dsconfig \
set-connection-handler-prop \
--handler-name LDAP \
--set key-manager-provider:BCFIPS \
--set trust-manager-provider:BCFIPS \
--offline \
--no-prompt

    2. Update the LDAPS connection handler:

      $ ./opendj/bin/dsconfig \
set-connection-handler-prop \
--handler-name LDAPS \
--set key-manager-provider:BCFIPS \
--set trust-manager-provider:BCFIPS \
--offline \
--no-prompt

    3. Update the HTTPS connection handler:

      $ ./opendj/bin/dsconfig \
set-connection-handler-prop \
--handler-name HTTPS \
--set key-manager-provider:BCFIPS \
--set trust-manager-provider:BCFIPS \
--offline \
--no-prompt

  2. Update the administration connector to use the new key providers:

    $ ./opendj/bin/dsconfig \
set-administration-connector-prop \
--set key-manager-provider:BCFIPS \
--set trust-manager-provider:BCFIPS \
--offline \
--no-prompt

  3. Update the replication provider to use the new key providers:

    $ ./opendj/bin/dsconfig \
set-synchronization-provider-prop \
--provider-name "Multimaster Synchronization" \
--set key-manager-provider:BCFIPS \
--set trust-manager-provider:BCFIPS \
--offline \
--no-prompt

Disable the default key providers

The default key providers don’t support FIPS compliance and aren’t used any longer. Disable them:

  1. Disable the default key manager provider:

    $ ./opendj/bin/dsconfig \
set-key-manager-provider-prop \
--provider-name PKCS12 \
--set enabled:false \
--offline \
--no-prompt

  2. Disable the default trust manager provider:

    $ ./opendj/bin/dsconfig \
set-trust-manager-provider-prop \
--provider-name PKCS12 \
--set enabled:false \
--offline \
--no-prompt

Share keys across Crypto Managers

In many deployments, the master key, derived from the deployment ID, does both key wrapping and backup signing.

FIPS compliance requires separate keys for these operations.

The DS Crypto Manager configuration points to the keys for these operations. Each server’s Crypto Manager must use the same keys for key wrapping and signing across the entire deployment. This ensures any server can unwrap keys and verify signed backup files.

To use separate keys for key wrapping and for signing backups, follow these steps once for the entire deployment to prepare a shared keystore:

  1. In the shared keystore, generate separate key pairs for key wrapping and for signing backups.

    When using a file-based shared keystore, use the Bouncy Castle FIPS format (BCFKS type).

    Record the key pair aliases for use in the Crypto Manager configuration.

For each server in the deployment:

  1. Share the keystore with the server.

    When using a file-based shared keystore, copy it to the DS config folder.

  2. Create a key manager provider to access the shared keystore.

  3. Update the DS Crypto Manager configuration to set the provider, key wrapping mode, and key aliases:

    $ ./opendj/bin/dsconfig \
set-crypto-manager-prop \
--set key-manager-provider:<crypto-manager-key-manager-provider> \
--set key-wrapping-mode:wrap \
--set master-key-alias:<key-wrapping-key-alias> \
--set signing-key-alias:<signing-key-alias> \
--offline \
--no-prompt

When rotating keys in the shared keystore:

  • Add new keys but don’t delete the existing keys.

    Keep the existing keys in the keystore so DS can use them to unwrap keys and verify signed backup files.

  • Overwrite the old copies of the shared keystore on all servers.

  • Update the Crypto Manager master-key-alias and signing-key-alias properties as necessary to target the new keys.

Enable the Bouncy Castle FIPS provider

Before you start DS, update the DS Java settings to use Bouncy Castle FIPS support:

  1. Copy $JAVA_HOME/conf/security/java.security to the opendj/config/ folder.

  2. Update the opendj/config/java.security file to use the Bouncy Castle FIPS provider:

    1. Replace the list of security providers with the following:

      security.provider.1=org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider
# If entropy in the system is too limited to use the default
# deterministic random bits generator, try with C:HYBRID;ENABLE{All};
#security.provider.1=org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider C:HYBRID;ENABLE{All};
security.provider.2=org.bouncycastle.jsse.provider.BouncyCastleJsseProvider fips:BCFIPS
security.provider.3=SUN

    2. Update the default key manager factory algorithm:

      ssl.KeyManagerFactory.algorithm=PKIX

  3. Update the DS opendj/config/java.properties file to use the Bouncy Castle FIPS provider.

    Add the following flags to all server tools settings. Put all the flags on the same line each time. The following example shows one flag per line for readability:

    -Dorg.bouncycastle.fips.approved_only=true
-Djava.security.properties==/path/to/opendj/config/java.security

    Here, /path/to/opendj is the path to the folder where you installed DS.

    The following example shows an updated /path/to/opendj/config/java.properties file:

    default.java-home=$JAVA_HOME
# Default for client tools (make it the default because we are more likely to add client tools than server tools)
default.java-args=-server -Xms256m -Xmx256m
# Server tools need a bigger heap: opt-out of client tools heap sizing
addrate.java-args=-server
authrate.java-args=-server
backendstat.java-args=-server -Dorg.bouncycastle.fips.approved_only=true -Djava.security.properties==/path/to/opendj/config/security/java.security
changelogstat.java-args=-server -Dorg.bouncycastle.fips.approved_only=true -Djava.security.properties==/path/to/opendj/config/security/java.security
dsbackup.online.java-args=-server -Dorg.bouncycastle.fips.approved_only=true -Djava.security.properties==/path/to/opendj/config/security/java.security
dsbackup.offline.java-args=-server -Dorg.bouncycastle.fips.approved_only=true -Djava.security.properties==/path/to/opendj/config/security/java.security
dsrepl-offline.java-args=-server
dsrepl.java-args=-server -Dorg.bouncycastle.fips.approved_only=true -Djava.security.properties==/path/to/opendj/config/security/java.security
encode-password.java-args=-server -Dorg.bouncycastle.fips.approved_only=true -Djava.security.properties==/path/to/opendj/config/security/java.security
export-ldif.offline.java-args=-server -Dorg.bouncycastle.fips.approved_only=true -Djava.security.properties==/path/to/opendj/config/security/java.security
import-ldif.offline.java-args=-server -Dorg.bouncycastle.fips.approved_only=true -Djava.security.properties==/path/to/opendj/config/security/java.security
ldifdiff.java-args=-server
makeldif.java-args=-server
modrate.java-args=-server
rebuild-index.offline.java-args=-server -Dorg.bouncycastle.fips.approved_only=true -Djava.security.properties==/path/to/opendj/config/security/java.security
searchrate.java-args=-server
setup-profile.java-args=-server
start-ds.java-args=-server -Dorg.bouncycastle.fips.approved_only=true -Djava.security.properties==/path/to/opendj/config/security/java.security
upgrade.java-args=-server -Dorg.bouncycastle.fips.approved_only=true -Djava.security.properties==/path/to/opendj/config/security/java.security
verify-index.java-args=-server -Dorg.bouncycastle.fips.approved_only=true -Djava.security.properties==/path/to/opendj/config/security/java.security

Start DS

  1. Start DS:

    $ ./opendj/bin/start-ds

    When DS finishes starting up, it displays a message containing:

    The Directory Server has started successfully

  2. Verify you can run administrative tools, such as the status command:

    $ ./opendj/bin/status \
--bindDn uid=admin \
--bindPassword StrongPassword \
--hostname localhost \
--port 4444

    As you haven’t specified a truststore, the command prompts you to trust the server certificate.

    On success, the status command displays output about the DS server.

When running DS with Bouncy Castle FIPS, use the Java keytool command or other external command to manage keys.

The dskeymgr command doesn’t support Bouncy Castle FIPS format keystores or providers, so you can’t use it to create or renew TLS key pairs or to create and replace deployment IDs.

For most FIPS-compliant deployments, use your own cryptographic keys.

Command support for Bouncy Castle FIPS

When running online server commands, use these arguments:

--trustStorePath /path/to/opendj/config/security/keystore.bcfks \
--trustStoreType BCFKS \
--trustStorePassword:file /path/to/opendj/config/keystore.pin \
--trustStoreProviderClass org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider

When running server commands with the --offline option, the java.properties settings suffice.