Enabling FIPS mode

When using FIPS, many IBM Security Directory Integrator configuration options are changed, so you must keep in mind several rules in order to maintain FIPS compliancy.

Some of the rules are mentioned in this document and others can be found in https://w3.webahead.ibm.com/w3ki/download/attachments/370821/FIPS+140+Guidelines.pdf?version=1 and http://www.ibm.com/developerworks/java/jdk/security/60/FIPShowto.html

Enabling FIPS mode in IBM Security 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 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 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 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 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 Directory Integrator installation. For example: 
    createstash mypass mykeypass com.ibm.crypto.fips.provider.IBMJCEFIPS
  • Use only FIPS compatible IBM Security Directory Integrator components in your solutions, as listed in the table below:
    Table 1. FIPS compatible components
    Directory Integrator Component Allowed in FIPS mode? Remarks
    Connectors    
    Active Directory Change Detection Connector yes Uses default JSSE factories for SSL
    AssemblyLine Connector yes Operates as a Server API client
    Axis Easy Web Service Server Connector yes Uses default JSSE factories for SSL
    Command line Connector yes Provides no cryptography features
    Domino/Lotus Notes® Connectors no Domino/Notes 7 cryptographic capabilities are not FIPS conformant.

    (Some FIPS enablement may be included in Notes 8.0.1.)
    ITIM DSMLv2 Connector yes Uses default JSSE factories for SSL
    DSMLv2 SOAP Connector yes Uses default JSSE factories for SSL
    DSMLv2 SOAP Server Connector yes Uses default JSSE factories for SSL
    Exchange Changelog Connector yes Uses default JSSE factories for SSL
    File Connector yes Provides no cryptography features
    FTP Client Connector yes Provides no cryptography features
    GLA Connector yes Provides no cryptography features. This connector is deprecated and will be removed in a future version of IBM® Security Directory Integrator.
    HTTP Client Connector yes Uses default JSSE factories for SSL
    Old HTTP Client Connector yes Uses default JSSE factories for SSL
    HTTP Server Connector yes Uses default JSSE factories for SSL
    Old HTTP Server Connector yes Provides no cryptography features
    IBM Security Directory Integrator Changelog Connector yes Uses default JSSE factories for SSL
    ITIM Agent Connector yes Provides no cryptography features
    JDBC Connector depends If no cryptography features are used (SSL, encryption), the Connector is FIPS conformant.

    Otherwise FIPS conformance depends on the FIPS conformance of the cryptographic functionality of the JDBC driver that is used.

    See Connectors, Function Components, Parsers for a discussion on the FIPS conformance of JDBC drivers.
    JMS Connector depends If no cryptography features are used (SSL, encryption), the Connector is FIPS conformant.

    Otherwise FIPS conformance depends on the FIPS conformance of the cryptographic functionality of the JDBC driver that is used.

    See Connectors, Function Components, Parsers for a discussion on the FIPS conformance of JMS providers.
    JMX Connector yes Provides no cryptography features
    JNDI Connector yes Uses default JSSE factories for SSL
    LDAP Connector yes Uses default JSSE factories for SSL
    LDAP Server Connector yes Uses default JSSE factories for SSL
    Mailbox Connector yes Uses default JSSE factories for SSL
    Memory Queue Connector depends Depends on the FIPS compliance of the JDBC driver used for the System Store.

    (The Memory Queue uses the System Store for persistence.)

    See Connectors, Function Components, Parsers for a discussion on the FIPS conformance of JDBC drivers.
    Memory Stream Connector yes Provides no cryptography features
    IBM WebSphere MQ Everyplace Password Store Connector depends Only PKCS#7 is allowed in FIPS mode for message protection.

    The RSA encryption option must not be used. The IBM WebSphere MQ Everyplace Mini Certificates are not FIPS compliant, so they must not be used in FIPS mode.
    Sun Directory Change Detection Connector yes Uses default JSSE factories for SSL
    Properties Connector depends If encryption is turned off, the Connector is FIPS conformant.

    Otherwise FIPS conformance depends on the cipher used for encryption.

    An example of a FIPS 140-2 approved cipher is AES. Other approved ciphers can be found at: http://csrc.nist.gov/publications/fips/fips140-2/fips1402annexa.pdf

    The Server encryption option will always be FIPS conformant as long as IBM Security Directory Integrator is configured correctly for FIPS mode. (See Enabling FIPS mode.)
    Server Notifications Connector yes Operates as a Server API client
    System Queue Connector depends If no cryptography features are used by the System Queue (SSL, encryption), the Connector is FIPS conformant.

    Otherwise FIPS conformance depends on the FIPS conformance of the JMS provider that is used by the System Queue.

    See Connectors, Function Components, Parsers for a discussion on the FIPS conformance of JMS providers.
    Windows Users and Groups Connector yes Provides no cryptography features
    System Store Connector depends Depends on the FIPS compliance of the JDBC driver used by the System Store.
    RAC Connector yes Provides no cryptography features. This connector is deprecated and will be removed in a future version of IBM Security Directory Integrator.
    RDBMS Changelog Connector depends Same as the JDBC Connector
    SNMP Connector yes Provides no cryptography features
    SNMP Server Connector yes Provides no cryptography features
    TAM Connector yes IBM Security Directory Integrator Runtime Environment for Java™ is FIPS conformant
    TCP Connector yes Uses default JSSE factories for SSL
    TCP Server Connector yes Uses default JSSE factories for SSL
    Timer Connector yes Provides no cryptography features
    URL Connector yes Provides no cryptography features
    Web Service Receiver Server Connector yes Uses default JSSE factories for SSL
    z/OS® Changelog Connector yes Uses default JSSE factories for SSL
         
    Function Components    
    Castor Java to XML FC yes Provides no cryptography features
    Castor XML to Java FC yes Provides no cryptography features
    EMF XMLToSDO yes Provides no cryptography features
    EMF SDOToXML yes Provides no cryptography features
    AssemblyLine FC yes Operates as a Server API client
    Java Class Function Component depends Depends on the FIPS compliance of the Java class, whose method will be invoked by the Function Component.

    If the Java class does not use cryptography (SSL, encryption, signing, cryptographic hash functions, and so forth) it can be safely used in FIPS mode.
    Parser FC depends Depends on the FIPS compliance of the Parser that is configured for the Function Component
    CBE Generator Function Component yes Provides no cryptography features
    SendEMail Function Component yes Uses default JSSE factories for SSL
    Memory Queue FC depends Depends on the FIPS compliance of the JDBC driver used by the System Store.

    (The Memory Queue uses the System Store for persistence.)

    See Connectors, Function Components, Parsers for a discussion on the FIPS conformance of JDBC drivers.
    Axis Java To Soap FC yes Provides no cryptography features
    WrapSoap FC yes Provides no cryptography features
    Invoke Soap WS FC yes Uses default JSSE factories for SSL
    Axis Soap To Java FC yes Provides no cryptography features
    Axis EasyInvoke Soap WS FC yes Uses default JSSE factories for SSL
    Complex Types Generator Function Component yes Provides no cryptography features
    Remote Command Line Function Component depends The cryptographic capabilities of the RXA toolkit are not FIPS compliant.

    If no cryptography features are used, the component can be used in FIPS mode.
    z/OS TSO/E Command Line FC depends Depends on the FIPS compliance of the cryptography involved in the TSO command that is invoked by the Function Component
    SAP ABAP Application Server Component Suite no The SAP cryptographic module has not been FIPS 140-2 certified.

    If no cryptography features are used, the components can be used in FIPS mode.
         
    Parsers yes None of the IBM Security Directory Integrator Parser components use cryptography so all of them can be used in FIPS mode.

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

To enable FIPS mode in IBM Security 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 Directory Integrator Server runs in FIPS mode. In this mode, the IBM FIPS security provider is set in the IBM Security Directory Integrator JVM before the IBM JCE security provider in the providers list. When the IBM Security 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 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 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 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 Directory Integrator configurations.

Setting properties automatically when running in FIPS mode

  • IBM Security 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 Directory Integrator is run in FIPS mode, IBM Security 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 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 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.

Parent topic: The IBM Security Directory Integrator server and FIPS