Enabling FIPS mode

Enabling FIPS mode in IBM® Security Verify Directory Integrator

1. Set the com.ibm.di.server.fipsmode.on property to true in global.properties or solution.properties.
2. Make sure the com.ibm.di.securityTransformation property value is in an algorithm which is FIPS compliant, for example, AES/ECB/NoPadding. This algorithm is used when you attempt to open an encrypted configuration.
3. Hardware cryptography can not be used along with SSL in FIPS mode. The underlying SSL module – IBMJSSE2 does not support hardware cryptography in FIPS mode as stated here: http://www-128.ibm.com/developerworks/java/jdk/security/60/secguides/jsse2Docs/JSSE2RefGuide.html#runfips. You cannot use hardware-based SSL keys for the Server API in FIPS mode; the com.ibm.di.server.pkcs11 property must be absent or set to false in global.properties and solution.properties.
4. Make sure Server encryption uses a transformation that is FIPS 140-2 compliant.

By default the Server uses public key encryption with the RSA algorithm. However, the RSA encryption option is not compliant with FIPS 140-2. That is why you must manually configure another cryptographic transformation that is FIPS allowed. Below are sample steps that setup IBM® Security Verify Directory Integrator to use the AES cipher for encryption:

• Generate an AES secret key and put it in a keystore. This can be done using the keytool utility located in the bin folder of an IBM® Security Verify Directory Integrator installation like this:

  keytool –genseckey –alias server –keyalg AES –keysize 128 –keystore server.jck –storepass mypass –storetype jceks
    –keypass mykeypass –providerClass com.ibm.crypto.fips.provider.IBMJCEFIPS
  

  This command creates a new keystore file server.jck of type JCEKS (JKS keystores cannot host secret keys) with an AES key of size 128 under alias server. The password for the created keystore is mypass. Pay special attention to the keygenproviderclass parameter – it is absolutely necessary to specify the FIPS certified provider if you strive for FIPS 140-2 compliance. Note that this is just an example, you can use whatever file names, passwords and aliases you want.

• Change the IBM® Security Verify Directory Integrator settings to use secret key encryption with the newly generated key. For example in global.properties or solution.properties file, set the following properties: `

  com.ibm.di.server.encryption.keystore=server.jck
  com.ibm.di.server.encryption.keystoretype=jceks
  com.ibm.di.server.encryption.key.alias=server
  com.ibm.di.server.encryption.transformation=AES/CBC/PKCS5Padding
  

• Migrate all existing files that have been encrypted with the old key: All encrypted files that existed prior to the introduction of the new key, need to be migrated. Migration involves decryption with the old key and (optionally) re-encryption with the new one (see Maintaining encryption artifacts - keys, certificates, keystores, encrypted files). For example you can migrate global.properties as follows:

  cryptoutils -input ../etc/global.properties -output ../etc/global.properties
  -mode decrypt_props -keystore ../testserver.jks -storepass server -alias server
  -transformation RSA -storetype jks -keypass server
  
  cryptoutils -input ../etc/global.properties -output ../etc/global.properties
  -mode encrypt_props -keystore ../server.jck -storepass mypass -alias server
  -transformation AES/CBC/PKCS5Padding -storetype jceks -keypass mykeypass
  

• Regenerate the IBM® Security Verify Directory Integrator Server Stash File to reflect the new passwords of the encryption keystore and the encryption key. This is done using the createstash utility found in the bin folder of an IBM® Security Verify Directory Integrator installation. For example:

  createstash mypass mykeypass com.ibm.crypto.fips.provider.IBMJCEFIPS
  

• Use only FIPS compatible IBM® Security Verify Directory Integrator components in your solutions, as listed in the table below: [TABLE]

Table 1. FIPS compatible components

Setting com.ibm.di.server.fipsmode.on

To enable FIPS mode in IBM® Security Verify Directory Integrator you must specify it in a property in global.properties or solution.properties. The property is named com.ibm.di.server.fipsmode.on and can be set to either true or false. When this property is set to true, the IBM® Security Verify Directory Integrator Server runs in FIPS mode. In this mode, the IBM FIPS security provider is set in the IBM® Security Verify Directory Integrator JVM before the IBM JCE security provider in the providers list. When the IBM® Security Verify Directory Integrator FIPS enabling property is true, it also enables FIPS mode in the IBM JSSE2 provider and sets the default JSSE SSL socket factories to be the ones from the IBM JSSE2 provider. By default FIPS mode is not enabled in IBM® Security Verify Directory Integrator, that is, the com.ibm.di.server.fipsmode.on property is set to false.

Using crypto algorithms in FIPS mode

Only FIPS-compliant crypto algorithms can be used. This means that you must use only FIPS-compliant algorithms in order to stay in FIPS-compliant mode. Using other algorithms violates FIPS compliancy.

Setting com.ibm.di.securityTransformation

When opening an encrypted configuration, IBM® Security Verify Directory Integrator uses the com.ibm.di.securityTransformation property to get the algorithm that decrypts the configuration. If this property is set to an algorithm which is not FIPS-compliant, and the IBM® Security Verify Directory Integrator Server FIPS mode is turned on, then an Exception is thrown. The Exception message which is shown would look something like this:

CTGDIC012E Could not load file<FILE_PATH>. No such algorithm: <ALGORITHM_NAME>.

In order to avoid this Exception, always set FIPS-compliant algorithms for this property when running in FIPS mode. By default the com.ibm.di.securityTransformation property is set to DES/ECB/Nopadding which is not a FIPS-compliant algorithm. This property also defines a cipher for the password-based encryption and decryption of IBM® Security Verify Directory Integrator configurations.

Setting properties automatically when running in FIPS mode

• IBM® Security Verify Directory Integrator sets a relevant System property which is not present in the global.properties file by default. This property is called com.ibm.di.cryptoProvider and is set to the IBMJCEFIPS security provider when run in FIPS mode. You should note that if this property is set in global.properties then that particular value is used; if this property is set to a non-FIPS compliant provider, then even if IBM® Security Verify Directory Integrator is run in FIPS mode, IBM® Security Verify Directory Integrator is not FIPS-compliant.
• When in FIPS mode, specific JSSE Socket Factories are used. These are the IBMJSSE2 Socket Factories. This is done automatically by the IBM® Security Verify Directory Integrator Server which sets the ssl.SocketFactory.provider and the ssl.ServerSocketFactory.provider properties to the JSSE implementation classes in IBMJSSE2 provider.

Using the create stash file command line tool in FIPS mode

To create a stash file that conforms to FIPS 140-2 standards you must provide the IBMJCEFIPS provider class as the third parameter when using the createstash file tool. For example:

TDI_install_dir\bin\createstash Password Password com.ibm.crypto.fips.provider.IBMJCEFIPS

Using alternatives to RSA encryption in FIPS mode

In FIPS mode, configure IBM® Security Verify Directory Integrator to use the Advanced Encryption Standard (AES) instead of the RSA encryption algorithm. A secret key cipher that is FIPS 140-2 compliant is required. As an acronym, RSA stands for Rivest, Shamir, and Adelman, the inventors of the algorithm. The RSA algorithm is a strong encryption algorithm used for sending data over the internet. The RSA cipher is allowed only to encrypt and decrypt keys for transport (SSL, TLS) to stay within the boundaries of the Approved Mode of FIPS 140-2 Level 1, as stated at: http://www.ibm.com/developerworks/java/jdk/security/60/FIPShowto.html.

• Running auxiliary tools in FIPS mode You can use the command line syntax for identifying the appropriate crypto provider, and when generating a secret key.