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:
-
Use the
--encryptDataWithSettingsImportedFromFile
argument to specify the path to that export file. -
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’ssetup-arguments.txt
file when usingmanage-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’ssetup-arguments.txt
file when usingmanage-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 |
---|---|
|
|
|
|
|
|
A FIPS-compliant server returns a value of |
Steps
-
Run
ldapsearch
to return thecn=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
-
In
config/java.properties
, edit the value of-Dcom.unboundid.crypto.FIPS_PROVIDER
to the encoded value of the target FIPS specification. -
Run
bin/dsjavaproperties
. -
Restart the server.
Troubleshooting:
If the server doesn’t operate as expected after the update, revert the server to the previous FIPS compliance level.