PingDirectory

Setting up the server in FIPS 140-2-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 140-2-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.

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 140-2-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 140-2-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 140-2-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 140-2-compliant mode

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

About this task

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

Steps

  • Add --fips-provider BCFIPS 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 BCFIPS \
  --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