PingDirectory

Setting up the server in FIPS-compliant mode

You can’t have both FIPS-compliant and non-FIPS-compliant servers in the same topology, and you can’t update an existing non-FIPS-compliant server to run in FIPS-compliant mode.

Because of this, if you want to run a server in FIPS-compliant mode, you must set up a new instance. This can be done in the following two ways:

  • Use setup with an appropriate set of arguments.

  • Use manage-profile setup with a profile that includes the necessary setup arguments, along with any other configuration changes, extensions, and other files that you might want included in the installation.

You can run servers with different levels of FIPS compliance in the same topology.

Ensure sufficient entropy

Strong cryptography requires a reliable source of high-quality random data.

On some systems, the OS-provided random number generator, such as /dev/random on Linux systems, might block if there’s not enough entropy available to keep up with the demand for strong random data, which can severely impede server performance. This is especially likely when running the server in a virtual machine or in a container because it’s less likely to have access to the entropy stream from the underlying host system.

When running in non-FIPS-compliant mode, the server can work around this problem by using an alternative random number generator, such as /dev/urandom on Linux, that uses cryptographic techniques to ensure that it can still provide a high-quality stream of random data that won’t block even when available entropy is exhausted on the underlying system. However, the Bouncy Castle FIPS-compliant random number generator doesn’t support this alternative, and it’s likely to block for long periods of time if the server is installed in a container or virtual machine.

This isn’t a problem that’s likely to go unnoticed because the server is likely to appear completely unresponsive for many minutes at a time if the random number generator blocks because of a lack of entropy. It’s likely to block for long periods of time, especially if the server is installed in a container or virtual machine.

Resolve entropy exhaustion

To help diagnose the problem, the installer attempts to monitor available system entropy when setting up the server in FIPS-compliant mode and displays a warning message if entropy drops too low. Similarly, if the server is running in FIPS-compliant mode, it continuously monitors available system entropy and logs a warning message and raises an alarm if entropy drops low enough that the server is likely to become unresponsive.

If entropy exhaustion is a problem, the best options to address it include:

  • If the server is running in a virtual machine or container, you might be able to configure it with access to the underlying host system’s entropy pool if that’s not already the case.

  • Install a hardware random number generator on the system and ensure that the server can access it even when running in a container or virtual machine.

  • Install an entropy-supplementing daemon, such as rngd, to keep the OS-provided random number generator topped off and able to generate high-quality random data without blocking.

Setting up certificate key and trust stores

About this task

Because FIPS-compliant mode requires secure communication, you must provide arguments that indicate how the server should obtain the certificate chain, private key, and trusted certificate information that it should use during TLS negotiation.

Steps

  • Configure the server with appropriate key and trust stores during setup. Choose from:

    Choose from:

    • If you have existing key and trust stores in the BCFKS format:

    • Use the --useBCFKSKeyStore and --useBCFKSTrustStore arguments to provide the paths to those stores.

    • Use either the --keyStorePassword or --keyStorePasswordFile argument to specify the PIN needed to access the contents of the key store.

    • Use either the --trustStorePassword or --trustStorePasswordFile argument to specify the PIN needed to access the contents of the trust store.

      Unlike the JKS format, a PIN is always required when using a BCFKS key store, even if you don’t need to access the private key.

    • If you have existing key and trust stores in a non-BCFKS format:

    • Convert the non-BCFKS files using manage-certificates copy-keystore with the --destination-key-store-type BCFKS argument.

    • Follow the steps for existing key and trust stores in the BCFKS format.

    • If you have PEM files containing the certificate chain and private key from a certificate authority, and you want to use them to generate new BCFKS key and trust stores:

    • Use the --certificateChainPEMFile and --certificatePrivateKeyPEMFile arguments to specify the paths to those files.

    • If you have PEM files containing trusted certificates that you want to include in a new BCFKS trust store, you can use the --trustedCertificatePEMFile argument to provide the paths to those files.

    • If the listener certificate chain and private key that you want to use reside in a PKCS #11 token:

    • Use the --usePKCS11KeyStore argument to enable that support for creating a BCFKS key store.

      PingDirectory only supports key store creation using PKCS #11 tokens. In order to create a trust store, you must use either the --useBCFKSTrustStore or --trustedCertificatePEMFile arguments in conjunction with --usePKCS11KeyStore.

    • If the Java virtual machine (JVM) has not been pre-configured with the necessary PKCS #11 provider, then use the --pkcs11ProviderConfigFile argument to specify the path to the necessary provider configuration file.

    • Use either the --keyStorePassword or --keyStorePasswordFile argument to specify the PIN needed to access the token.

    • If you want the server to generate a self-signed certificate and use it to create BCFKS key and trust stores, use the --generateSelfSignedCertificate argument.

      Self-signed certificates are convenient for testing or evaluation purposes, but they aren’t trusted by any clients (by default) and shouldn’t be used in production environments.

Setting up data encryption

About this task

Setting up the server in FIPS-compliant mode requires that you enable data encryption.

Steps

  • Configure the server with at least one encryption settings definition. Choose from:

    Choose from:

    • If you want the server to generate an encryption settings definition from a passphrase that you provide, use the --encryptDataWithPassphraseFromFile argument to specify the path to a file containing that passphrase.

      If you provide the same passphrase to each instance, they will generate the same encryption settings definition and will encrypt data in the same way. Also, in many cases, if you know the passphrase used to generate an encryption settings definition, you can use that passphrase to decrypt encrypted data even if the encryption settings definition isn’t available.

    • If you have one or more encryption settings definitions that have been exported from another instance:

      1. Use the --encryptDataWithSettingsImportedFromFile argument to specify the path to that export file.

      2. Provide the --encryptionSettingsExportPassphraseFile argument to specify the path to a file containing the passphrase used to protect the contents of that export.

    • If you want the server to generate an encryption settings definition with a randomly generated passphrase, use the --encryptDataWithRandomPassphrase argument.

      If you use this argument when setting up multiple instances, then each instance will have a different encryption settings definition, and data encrypted on one instance might not be accessible to other instances. However, you can use it when setting up the first instance in a topology and then export the generated definition and use the --encryptDataWithSettingsImportedFromFile argument to import it when setting up additional instances.

      Because the random passphrase the server generated when creating the definition will not be exposed, you can’t use it to decrypt data if that encryption settings definition is not available.

Installing the server in FIPS-compliant mode

Install the server in FIPS-compliant mode with TLS negotiation and data encryption.

About this task

Interactive setup doesn’t provide an option to enable FIPS-compliant mode, and there are currently no other supported providers that can be used to enable FIPS-compliant mode.

Steps

  • Install the server with one of the supported FIPS specifications.

    Choose from:

    • To set up the server for FIPS 140-2 compliance, add --fips-provider BCFIPS1 to the set of arguments used when running setup in non-interactive mode or to the server profile’s setup-arguments.txt file when using manage-profile setup.

      Example:

      The following example provides a sample command line that demonstrates the process for setting up the server in FIPS 140-2-compliant mode. The server only accepts TLS-encrypted LDAP on port 636 and TLS-encrypted HTTP on port 443, but doesn’t allow unencrypted connections from either LDAP or HTTP clients. BCFKS key and trust stores are generated from information provided in PEM files, and an encryption settings definition is generated from a specified passphrase.

      ./setup \
  --fips-provider BCFIPS1 \
  --no-prompt \
  --acceptLicense \
  --localHostName ds1.example.com \
  --ldapsPort 636 \
  --httpsPort 443 \
  --baseDN "dc=example,dc=com" \
  --rootUserDN "cn=Directory Manager" \
  --rootUserPasswordFile /path/to/root-pw.txt \
  --maxHeapSize 2g \
  --primeDB \
  --sampleData 10001 \
  --certificateChainPEMFile /path/to/server-cert.pem \
  --certificateChainPEMFile /path/to/ca-cert.pem \
  --certificatePrivateKeyPEMFile /path/to/server-key.pem \
  --trustedCertificatePEMFile /path/to/ca-cert.pem \
  --encryptDataWithPassphraseFromFile /path/to/encryption-passphrase.txt \
  --instanceName ds1 \
  --location example-location \
  --noPropertiesFile

    • To set up the server for FIPS 140-3 compliance, add --fips-provider BCFIPS2 to the set of arguments used when running setup in non-interactive mode or to the server profile’s setup-arguments.txt file when using manage-profile setup.

Checking the level of FIPS compliance

You can check a server’s level of FIPS compliance by reviewing the properties of its cn=Version,cn=monitor entry.

About this task

The following table details the properties to review within the monitor entry:

Property Values

fips-compliant-mode

  • true indicates that the server is installed in FIPS-compliant mode (using any supported specification).

  • false indicates that the server isn’t installed in FIPS-compliant mode.

fips-140-2-compliant-mode

  • true indicates that the server is configured with the FIPS 140-2 specification.

  • false indicates that the server isn’t configured with the FIPS 140-2 specification.

fips-140-3-compliant-mode

  • true indicates that the server is configured with the FIPS 140-3 specification.

  • false indicates that the server isn’t configured with the FIPS 140-3 specification.

A FIPS-compliant server returns a value of true for the fips-compliant-mode property and one of the FIPS specification properties. It returns false for all other FIPS specification properties.

Steps

  • Run ldapsearch to return the cn=Version,cn=monitor entry.

    Example:

    The following example includes an ldapsearch and the resulting entry, which indicates that the server is installed in FIPS 140-2-compliant mode:

    $ bin/ldapsearch \
  --hostname <hostname> --port <port> --useSSL --trustAll \
  --bindDN "cn=Directory Manager" --bindPasswordFile <password_file> \
  --baseDN cn=Version,cn=monitor "(&)" fips-compliant-mode fips-140-2-compliant-mode fips-140-3-compliant-mode


  dn: cn=Version,cn=monitor
  fips-compliant-mode: true
  fips-140-2-compliant-mode: true
  fips-140-3-compliant-mode: false

  # Result Code:  0 (success)
  # Number of Entries Returned:  1

Changing the level of FIPS compliance

You can change the level of FIPS compliance for an existing FIPS-compliant server.

About this task

You can update a server’s FIPS compliance level to any supported FIPS specification. For example, your organization might be required by regulation to update an existing topology of FIPS 140-2-compliant servers to FIPS 140-3 compliance. Alternatively, you might need to transition a FIPS 140-3-compliant server to the FIPS 140-2 specification for technical reasons.

Before you begin

To update the FIPS specification on a FIPS-compliant server, you need to know the following:

  • The server’s current FIPS specification

  • The encoded value of the target FIPS specfication:

    • BCFIPS1 for FIPS 140-2

    • BCFIPS2 for FIPS 140-3

Steps

  1. In config/java.properties, edit the value of -Dcom.unboundid.crypto.FIPS_PROVIDER to the encoded value of the target FIPS specification.

  2. Run bin/dsjavaproperties.

  3. Restart the server.

    Troubleshooting:

    If the server doesn’t operate as expected after the update, revert the server to the previous FIPS compliance level.