Learn the necessary steps to configure an application to be compliant with the US Federal Information Processing Standard (FIPS). The application in this article uses IBM DB2® and IBM WebSphere® in a Windows® system. Technical tips on how to connect in the database and configure the application in WebSphere when FIPS mode is enabled are also included.

Share:

Fabiana G. Rocha, Staff Software Engineer, IBM

Photograph of Fabiana RochaFabiana Rocha works as a software engineer in the Registry Services for Jazz for Service Management in the IBM Brazil Software Lab. She has over 11 years of experience with software development. For the past eight years, Fabiana has focused on Java EE, Oracle and DB2 databases, and WebSphere based systems.



11 December 2012

Introduction

The US Federal Information Processing Standard (FIPS) defines security standards for cryptographic modules that are used in IT software. Software must be compliant with FIPS certification and requirements to be qualified as an IT product for selection by a US government agency.

Configuring an application to be compliant with the US FIPS requires that all components of this application have FIPS mode enabled on it. This article explains how to configure FIPS mode for an application that has DB2 as the database and WebSphere as the application server. It contains all the necessary steps to configure the Java™ Runtime Environment (JRE), the database, and the application server to run on FIPS mode.

The FIPS configuration that is presented here is specific for an environment that uses DB2, WebSphere Application Server, and IBM Software Development Kit (SDK) on a Windows system. See Resources for links to more information that includes the complete list of steps for each configuration.


Create certificates for DB2 and WebSphere

Before you enable FIPS mode on the database and application server, it is necessary to generate trusted certificates. These certificates are used for the Secure Sockets Layer (SSL) connection in the database and in the application server.

It is possible to create one certificate for the database and one certificate for the application server. However, by following the steps here you create one single certificate to use for both DB2 database and WebSphere Application Server.

To create the certificate, use the tool gsk8capicmd from IBM Global Security Kit (GSKit). Alternatively, you can use another tool, for example the IBM iKeyman tool, to create the certificate.

Follow these steps to create a certificate authority (CA) and the certificate the CA signs:

  • Create a new folder to store the new certificates.

    For example, create c:\temp\certificates

    in a Windows system.
  • Create the certificate authority (CA)
    1. Create the certificate management system (CMS) key database
      "C:\Program Files\IBM\gsk8\bin\gsk8capicmd" -keydb -create -db 
      "C:\temp\certificates\myapp_ca.kdb" -pw changeit -stash -expire 1000 -fips
    2. Create the self-signed certificate
      "C:\Program Files\IBM\gsk8\bin\gsk8capicmd" -cert -create -db 
      "C:\temp\certificates\myapp_ca.kdb" -pw changeit -label "My App CA certificate" 
      -size 1024 -expire 1000 -dn "CN=My App CA certificate,O=IBM,
      OU=MyMachineNode01Cell,C=US"
    3. Extract the CA certificate
      "C:\Program Files\IBM\gsk8\bin\gsk8capicmd" -cert -extract -db 
      "C:\temp\certificates\myapp_ca.kdb" -pw changeit -label "My App CA certificate" 
      -target 
      "C:\temp\certificates\MYAPPCA.crt"
  • Create the certificate that is signed by a local, common, trusted CA:
    1. Create the client CMS key database.
      "C:\Program Files\IBM\gsk8\bin\gsk8capicmd" -keydb -create -db 
      "C:\temp\certificates\myapp_client.kdb" -pw changeit -stash -expire 1000 -fips
    2. Enter the following command to add the CA certificate as trusted in the CMS key database.
      "C:\Program Files\IBM\gsk8\bin\gsk8capicmd" -cert -add -db 
      "C:\temp\certificates\myapp_client.kdb" -pw changeit -label "My App CA 
      certificate client" -trust enable -file 
      "C:\temp\certificates\MYAPPCA.crt" -format ascii -fips
    3. Enter the following command to create the client certificate request that is based on 1024 bits.
      "C:\Program Files\IBM\gsk8\bin\gsk8capicmd" -certreq -create -db 
      "C:\temp\certificates\myapp_client.kdb" -pw changeit -label "My App 
      Client Certificate" -size 1024 -file "
      C:\temp\certificates\client.csr" -dn "CN=My App Client,
      O=IBM,OU=MyMachineNode01Cell,C=US" -fips
    4. Enter the following command so that the CA signs the client's certificate request and generates a new signed in file client.crt.
      "C:\Program Files\IBM\gsk8\bin\gsk8capicmd" -cert -sign -db 
      "C:\temp\certificates\myapp_ca.kdb" -pw changeit -label "My App certificate" 
      -target 
      "C:\temp\certificates\client.crt" -expire 365 -file 
      "C:\temp\certificates\client.csr" -
      fips
    5. Enter the following command to import the signed certificate client.crt in the CMS key database myapp_client.kdb.
      "C:\Program Files\IBM\gsk8\bin\gsk8capicmd" -cert -receive -db 
      "C:\temp\certificates\myapp_client.kdb" -pw changeit -file 
      "C:\temp\certKey\client.crt" -fips
  • Export the newly created certificate. The certificate key database converts to PKCS12 format.
    "C:\Program Files\IBM\gsk8\bin\gsk8capicmd" -cert -export -db 
    "C:\temp\certificates\myapp_client.kdb" -target 
    "C:\temp\certificates\myapp_client.p12" -fips -target_type pkcs12 -type cms
    
    Source database password: changeit
    Target database password: changeit

Configure FIPS mode on WebSphere V8.5

WebSphere Application Server provides a FIPS-approved provider called IBMJCEFIPS. Use this provider when enabling FIPS mode in WebSphere Application Server.

Follow these steps to configure FIPS mode on WebSphere Application Server:

  • Enable FIPS through the WebSphere Application Server administrative console.

    Go to Security -> SSL Certificate and Key Management -> Manage FIPS

    Select Enable FIPS 140-2 and click Apply, as shown in Figure 1.

    In the next view, click Save.

    Figure 1. Enable FIPS 140-2
    Screen shot of window where you enable FIPS 140-2.

    (View a larger version of Figure 1.)

  • Configure FIPS properties in ssl.client.props file

    Edit the file ssl.client.props in the [WAS_HOME]\ profiles\AppSrv01\properties folder. In this example, consider AppSrv01 as the WebSphere profile.

    1. Change the property com.ibm.security.useFIPS from false to true:
      com.ibm.security.useFIPS=true
    2. Ensure that the property com.ibm.ssl.protocol is set to TLS. If necessary, change the property com.ibm.ssl.protocol from SSL_TLS to TLS:
      com.ibm.ssl.protocol=TLS
  • Configure FIPS provider in java.security file

    Edit the file java.security in [WAS_HOME]\ java\jre\lib\security to include IBMJCEFIPS as the FIPS provider. Again, in this example, we are considering the use of IBM Software Development Kit (SDK).

    Include the FIPS provider in the list of providers and rearrange the rest of the providers.

    security.provider.1=com.ibm.crypto.fips.provider.IBMJCEFIPS

    After the change, the list of providers in the java.security file reads as:

    #
    # List of providers and their preference orders (see above):
    #
    security.provider.1=com.ibm.crypto.fips.provider.IBMJCEFIPS
    security.provider.2=com.ibm.crypto.pkcs11impl.provider.IBMPKCS11Impl
    security.provider.3=com.ibm.crypto.provider.IBMJCE
    security.provider.4=com.ibm.jsse2.IBMJSSEProvider2
    security.provider.5=com.ibm.security.jgss.IBMJGSSProvider
    security.provider.6=com.ibm.security.cert.IBMCertPath
    security.provider.7=com.ibm.security.cmskeystore.CMSProvider
    security.provider.8=com.ibm.security.jgss.mech.spnego.IBMSPNEGO
    security.provider.9=com.ibm.security.sasl.IBMSASL
    security.provider.10=com.ibm.xml.crypto.IBMXMLCryptoProvider
    security.provider.11=com.ibm.xml.enc.IBMXMLEncProvider
    security.provider.12=org.apache.harmony.security.provider.PolicyProvider
  • Restart WebSphere Application Server so that the configuration takes effect.

Configure FIPS mode on DB2 V9.7

Configure Secure Sockets Layer (SSL) in DB2 database to enable FIPS mode. According to the IBM DB2 Database for Linux, UNIX, and Windows Information Center (see Resources), the SSL communication is always in FIPS mode.

Follow these steps to configure FIPS mode on DB2 Database Server:

  • Ensure that the connection concentrator is not activated.

    SSL support is not enabled in the DB2 instance if connection concentrator is running.

    Run then database manager configuration command in DB2 command line:

    db2 get dbm cfg

    Verify if max_connections is set to a value greater than the value of max_coordagents, in this case connection concentrator is activated.

    Result of the command:

     Max number of coordinating agents     (MAX_COORDAGENTS) = AUTOMATIC(200)
     Max number of client connections      (MAX_CONNECTIONS) = AUTOMATIC(MAX_COORDAGENTS)
  • Set up your DB2 server for SSL support.

    Use the key database certificate that you previously created following the steps that are listed in Create Certificates for DB2 and WebSphere.

    Use DB2 command line (db2cmd) to run the commands.

    1. To list configured parameters, run db2 GET DBM CFG
    2. Run the following commands to set the new certificate for SSL configuration parameters:

      Set the key database:

      db2 update dbm cfg using SSL_SVR_KEYDB "C:\temp\certificates\myapp_client.kdb"

      Set the stash file:

      db2 update dbm cfg using SSL_SVR_STASH "C:\temp\certificates \myapp_client.sth"

      Set the label of the certificate:

      db2 update dbm cfg using SSL_SVR_LABEL 'My App Client Certificate'

      Set the port that DB2 database uses to list SSL connections:

      db2 update dbm cfg using SSL_SVCENAME 30171
    3. Add the value SSL to the DB2COMM registry variable:
      db2set -i DB2 DB2COMM=SSL,TCPIP

      In that command, DB2 is the DB2 instance name.

    4. Restart the DB2 instance.
      db2stop
      
      db2start

Configure the Java Runtime Environment to use SSL

It is necessary to configure the Java Runtime Environment to use SSL before you can use SSL connections in your application.

The prerequisites for the configuration of the JRE are:

  • Ensure that the Java Runtime Environment includes a Java security provider.

    For this example, use IBM SDK for Java. The IBM JSSE provider is automatically installed with the IBM SDK.

  • Configure SSL support on the database server.

    If you completed the steps in previous section entitled Configure FIPS mode on DB2 V9.7, you configured it already.

Follow these steps to configure Java Runtime Environment to use Secure Sockets Layer (SSL):

  • Configure the Java security provider in java.security file.

    Edit the file java.security in [WAS_HOME]\ java\jre\lib\security to include IBMJSSEProvider2 as the security provider. The configuration in the specified file depends on the Java development kit you have. In this example, we are considering the use of IBM Software Development Kit (SDK).

    Include the security provider in the list of providers and rearrange the rest of the providers.

    security.provider.1=com.ibm.jsse2.IBMJSSEProvider2

    After the change, the list of providers in the java.security file is displayed as:

    #
    # List of providers and their preference orders (see above):
    #
    security.provider.1=com.ibm.jsse2.IBMJSSEProvider2
    security.provider.2=com.ibm.crypto.fips.provider.IBMJCEFIPS
    security.provider.3=com.ibm.crypto.pkcs11impl.provider.IBMPKCS11Impl
    security.provider.4=com.ibm.crypto.provider.IBMJCE
    security.provider.5=com.ibm.security.jgss.IBMJGSSProvider
    security.provider.6=com.ibm.security.cert.IBMCertPath
    security.provider.7=com.ibm.security.cmskeystore.CMSProvider
    security.provider.8=com.ibm.security.jgss.mech.spnego.IBMSPNEGO
    security.provider.9=com.ibm.security.sasl.IBMSASL
    security.provider.10=com.ibm.xml.crypto.IBMXMLCryptoProvider
    security.provider.11=com.ibm.xml.enc.IBMXMLEncProvider
    security.provider.12=org.apache.harmony.security.provider.PolicyProvider
  • Set the Java system property.

    If you plan to use the IBM Data Server Driver for JDBC and SQLJ in FIPS-compliant mode, you must set the com.ibm.jsse2.JSSEFIPS Java system property:

    -Dcom.ibm.jsse2.JSSEFIPS=true
  • Configure SSL socket factory providers in java.security file

    Edit the file java.security in [WAS_HOME]\ java\jre\lib\security to include the SSL socket factory providers. Uncomment the following socket factory providers:

    ssl.SocketFactory.provider=com.ibm.jsse2.SSLSocketFactoryImpl
    ssl.ServerSocketFactory.provider=com.ibm.jsse2.SSLServerSocketFactoryImpl

    After the change, the list of SSL socket factory providers in the java.security file is displayed as:

    #
    # Determines the default SSLSocketFactory and SSLServerSocketFactory
    # provider implementations for the javax.net.ssl package.  If due to
    # export and/or import regulations, the providers are not allowed to be
    # replaced, changing these values will produce non-functional
    # SocketFactory or ServerSocketFactory implementations.
    #
    # Default JSSE socket factories
    ssl.SocketFactory.provider=com.ibm.jsse2.SSLSocketFactoryImpl
    ssl.ServerSocketFactory.provider=com.ibm.jsse2.SSLServerSocketFactoryImpl
    # WebSphere socket factories (in cryptosf.jar)
    #ssl.SocketFactory.provider=com.ibm.websphere.ssl.protocol.SSLSocketFactory
    #ssl.ServerSocketFactory.provider=com.ibm.websphere.ssl.protocol
    .SSLServerSocketFactory
  • Set parameters in the JVM arguments.

    Use the following parameters when you run your application. This configuration must be done in the JVM arguments. The truststore parameters refer to the certificate created in the section Create certificates for DB2 and WebSphere.

    javax.net.ssl.trustStore=certificate path

    javax.net.ssl.trustStorePassword=certificate password

    javax.net.ssl.trustStoreType=certificate type

    com.ibm.jsse2.JSSEFIPS=true

    Example of the JVM arguments:

    -Djavax.net.ssl.trustStore="C:\temp\certificates\myapp_client.p12" -Djavax.net.ssl
    .trustStorePassword=changeit -Djavax.net.ssl.trustStoreType=PKCS12 -Dcom.ibm.jsse2
    .JSSEFIPS=true

Connect in a database with FIPS mode enabled

After you enable FIPS mode in the DB2 database, the JDBC connections are done through the Secure Sockets Layer (SSL). Define the parameters JDBC Port, JDBC URL connection, and JVM Arguments. in your application to connect in the DB2 database:

JDBC Port

Use port 30171 defined in Configure FIPS mode on DB2 V9.7 section. DB2 database uses this port to listen SSL connections.

Example:

Port=30171

JDBC URL connection

The JDBC URL connection has a new parameter for SSL connections. This parameter is sslConnection=true.

Example:

JDBC_URL_Connection=jdbc:db2://myMachine:30171/myDB:sslConnection=true;

JVM Arguments

It is necessary to provide the certificate information for the truststore in the JVM arguments. Configure the following parameters in the JVM arguments:

  • javax.net.ssl.trustStore: The full path of the entity that validates the database certificate, which is imported when you configure JVM for FIPS mode
  • javax.net.ssl.trustStorePassword: Password of the trusted certificate
  • javax.net.ssl.trustStoreType: Type of the trusted certificate
  • com.ibm.jsse2.JSSEFIPS: Is true when FIPS mode is enabled

Example of parameters in the JVM arguments:

-Djavax.net.ssl.trustStore="C:\temp\certificates\myapp_client.p12" -Djavax.net.ssl
.trustStorePassword=changeit -Djavax.net.ssl.trustStoreType=PKCS12 -Dcom.ibm.jsse2
.JSSEFIPS=true

The following Java class shows an example on how to connect in the database by using an SSL connection.

package com.ibm.test.ssl;

import java.sql.Connection;
import java.sql.PreparedStatement;
import java.sql.ResultSet;
import java.sql.Statement;
import java.util.Properties;

/**
 * This class tests an SSL connection in a database with FIPS mode enabled. The
 * test creates a new table test_ssl, includes some records in the table, runs
 * a query, and then removed the created table.
 *
 * @author Fabiana G. Rocha
 *
 */
public class TestSSLConnection {

	public static void main(String[] args) {

		// machine name of the database
		String machineName = "myMachineName";

		// db2 port that listens SSL connections
		int port = 30171;

		// database name
		String dbName = "mydb";

		// database user name
		String dbUser = "db2admin";

		// database password
		String dbPassword = "db2admin";

		String db2Driver = "com.ibm.db2.jcc.DB2Driver";

		// Properties used to connect in the database
		Properties conProps = new java.util.Properties();
		conProps.put("user", dbUser);
		conProps.put("password", dbPassword);
		conProps.put("sslConnection", "true");

		// URL to connect in the database
		String url = "jdbc:db2://" + machineName + ":" + port + "/" + dbName;

		Connection con = null;
		try {
			Class.forName(db2Driver).newInstance();
		} catch (Exception e) {
			System.out.println("*** Error: failed to load Db2 jcc driver.");
		}

		try {
			System.out.println("url: " + url);

			// connect in the database
			con = java.sql.DriverManager.getConnection(url, conProps);
			Statement stmt = con.createStatement();

			try {
				// create a new table
				String createCmd = "create table test_ssl (col int)";
				stmt.executeUpdate(createCmd);
			} catch (Exception e) {
				System.out
						.println("*** Error: create table test_ssl
 has failed.");
			}

			// insert data in the created table
			String insertCmd = "insert into test_ssl values ";
			stmt.executeUpdate(insertCmd + "(100)");
			stmt.executeUpdate(insertCmd + "(200)");
			stmt.executeUpdate(insertCmd + "(300)");

			// execute a query in the table
			PreparedStatement ps = con
					.prepareStatement("select * from test_ssl");
			ResultSet rs = ps.executeQuery();
			int i = 0;
			while (rs.next()) {
				i++;
				System.out.println("item " + i + " - " + rs.getString(1));
			}

			try {
				// drop the table
				String dropCmd = "drop table test_ssl";
				stmt.executeUpdate(dropCmd);
			} catch (Exception e) {
				System.out.println("Error: drop table test_ssl has 
failed.");
			}

			con.close();
		} catch (Exception e) {
			e.printStackTrace();
		}

	}
}

Compile and apply this class by using the JVM arguments that we previously specified.

Example of JVM arguments:

-Djavax.net.ssl.trustStore="C:\temp\certificates\myapp_client.p12" -Djavax.net.ssl
.trustStorePassword=changeit -Djavax.net.ssl.trustStoreType=PKCS12 -Dcom.ibm.jsse2
.JSSEFIPS=true

The output of the TestSSLConnection Java class is displayed as:

url: jdbc:db2://myMachineName:30171/mydb
item 1 - 100
item 2 - 200
item 3 - 300

Tips on configuring in WebSphere Application Server with FIPS mode enabled

This section presents some useful tips to configure your application in WebSphere Application Server after you enable FIPS mode.

  • Configure the sslConnection property

    After you enable FIPS mode in the WebSphere Application Server, if your application connects in the DB2 database though a data source, then this data source has the sslConnection=true property configured.

    However, the sslConnection property can be configured manually or programmatically, through code. To configure it manually, use the administrative console.

    Go to Resources-> JDBC -> Data sources

    Select your data source and click Custom properties. Search for sslConnection property and enter true as the Value, as shown in Figure 2.

    Figure 2. Set the sslConnection property manually
    Screen shot example of setting the sslConnection property manually

    (View a larger version of Figure 2.)

    Click Apply.

    Stop and start WebSphere Application Server.

  • Configure the com.ibm.jsse2.JSSEFIPS property.

    You configure the property com.ibm.jsse2.JSSEFIPS=true in the JVM arguments of WebSphere Application Server also. Use the administrative console to configure this property.

    Go to Servers -> Server types -> WebSphere Application Servers -> Select your server

    Go to Java and Process Management -> Process Definition -> Java Virtual Machine

    Enter the property com.ibm.jsse2.JSSEFIPS in the Generic JVM arguments, as shown in Figure 3.

    Figure 3. Configure the com.ibm.jsse2.JSSEFIPS property
    Image showing screen shot of the configuring the com.ibm.jsse2.JSSEFIPS window.

    (View a larger version of Figure 3.)

    Stop and start WebSphere Application Server.

  • Configure the trusted certificate for the truststore

    You configure truststore information so that the application server is able to connect to the databases that have FIPS enabled.

    You can configure the truststore information in the JVM arguments of WebSphere Application Server or you can import the trusted certificate, generated before, in your default truststore.

    To set truststore information in the JVM arguments, go to Servers -> Server types -> WebSphere Application Servers -> Select your server

    Go to Java and Process Management -> Process Definition -> Java virtual machine

    Add truststore properties by entering:

    javax.net.ssl.trustStore=certificate path

    javax.net.ssl.trustStorePassword=certificate password

    javax.net.ssl.trustStoreType=certificate type

    Example:

    -Djavax.net.ssl.trustStore="C:\temp\certificates\myapp_client.p12" -Djavax.net.ssl
    .trustStorePassword=changeit -Djavax.net.ssl.trustStoreType=PKCS12 -Dcom.ibm.jsse2
    .JSSEFIPS=true

    Alternatively you can import the trusted certificate into your truststore. It is not necessary to set these properties in the JVM arguments as mentioned before.

    To import the certificate in the truststore, go to SSL certificate and key management -> Key stores and certificates -> select your truststore (for example: NodeDefaultTrustStore)

    Click Personal certificates -> choose Import

    Select Key store file check box.

    Use the trusted certificate that you previously generated. Populate the following information:

    Key file name: c:/temp/certificates/myapp_client.p12
    Type: PKCS12
    Key file password: changeit

    Click Get Key File Aliases. The combo box Certificate Alias to Import populates with the certificate name created during database configuration.

    Populate Imported Certificate Alias field. For example: my app certificate, as shown in Figure 4.

    Click the Apply. Then, click the Save.

    Figure 4. SSL certificate and key management
    Screen shot showing

    (View a larger version of Figure 4.)

    The certificate imports into the truststore.

    Stop and start WebSphere Application Server.


Conclusion

The US Federal Information Processing Standard (FIPS) is an important mechanism to define security standards for cryptographic modules that are used in IT software. As part of FIPS configuration it is necessary to configure Secure Sockets Layer (SSL) for database connection, which helps to protect your data through the network.

You now have all the necessary steps to enable FIPS mode in an application that uses DB2 and WebSphere on a Windows system.

Resources

Learn

Get products and technologies

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into Information management on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Information Management, WebSphere
ArticleID=850547
ArticleTitle=Configure FIPS mode for DB2 and WebSphere
publish-date=12112012