IBM Support

FIPS certified cryptography in IBM Semeru Runtimes

General Page

This guide describes the IBM Semeru Runtimes support for FIPS certified cryptography, and how to enable it.

FIPS certified cryptography in IBM Semeru Runtimes

FIPS certified cryptography is a key requirement for many users, especially in government and in regulated industries. On Red Hat® Enterprise Linux® (RHEL) 8 on x86 platforms, IBM® Semeru Runtimes can run in FIPS mode, which guarantees that only FIPS certified cryptography is used when a Java™ application uses Java security libraries or APIs.

FIPS mode is available in both IBM Semeru Runtime™ Certified Edition and IBM Semeru Runtime Open Edition, from versions 11.0.16 and 17.0.4, on RHEL 8 on x86 platforms only.

FIPS mode relies on the operating system's underlying NSS FIPS 140-2 certification. For information about the status of FIPS 140-2 certification in specific minor releases of RHEL 8, see the Red Hat Government Standards article.

Note: FIPS mode is not the same as the FIPS support in IBM SDK, Java Technology Edition version 8. For example, the configuration and restrictions are different.

Enabling FIPS mode

Follow these instructions to run IBM Semeru Runtimes in FIPS mode:

  1. If you didn't install your RHEL operating system in FIPS mode, switch it to FIPS mode as described in Switching the system to FIPS mode in the RHEL 8 documentation.
  2. Start the Semeru JVM, specifying the -Dsemeru.fips=true system property on the command line. This property instructs the JVM to use only FIPS certified cryptography, and ensures that the TLS and SSL protocols use only FIPS certified algorithms. If you want to enable debug tracing, also specify the -Djava.security.debug=semerufips system property.

If you want to run IBM Semeru Runtimes in FIPS mode in a container, ensure that the Network Security Services (nss) package is installed in the container image (you can install it by running the command dnf install nss). Then switch the host operating system to FIPS mode and run the JVM as described previously.

Keys and certificates in FIPS mode

In FIPS mode, the IBM Semeru Runtimes use the network security services (NSS) database as a read-only PKCS#11 store for keys and certificates. When you specify the -Dsemeru.fips=true system property, the keystore.type security property is set to PKCS#11 and the javax.net.ssl.keyStore system property is set to NONE.

If you want your Java application to use TLS or SSL in FIPS mode while also using custom trust certificates (as in Example 2, later), you might also need to specify the following command-line options. For example, if your application doesn't explicitly specify the provider to use and instead relies on the system-configured trust stores for TLS and SSL, use the following system properties to set the appropriate values for the truststore:

  • javax.net.ssl.trustStoreType="PKCS11"
  • javax.net.ssl.trustStore="NONE"
  • javax.net.ssl.trustStoreProvider=SunPKCS11-NSS-FIPS

For more information about these properties, see the Oracle PKCS11 documentation.

File-based keystores, such as JKS and PKCS#12, are not yet supported in FIPS mode. If you want to use a file-based keystore, you must import it into the NSS database before you use it. Use the pk12util NSS tool to import keys and certificates from a PKCS#12 keystore file into the NSS database. For example:

pk12util -i keystore.p12 -W changeit -d /etc/pki/nssdb

where keystore.p12 is the name of the keystore, changeit is the password, and /etc/pki/nssdb is the location of the NSS database repository.

Use the certutil tool to confirm that the keystore was imported successfully into the NSS database. For example:

certutil -K -d /etc/pki/nssdb

Similarly, use the pk12util tool to import trust anchor certificates from a PKCS#12 truststore file. For example:

pk12util -i truststore.p12 -W changeit -d /etc/pki/nssdb

where truststore.p12 is the name of the truststore. After importing the trust certificates, use the certutil tool to mark each of them as a trusted certificate authority (CA) for issuing client and server certificates, by setting the -t or trustargs attribute to CT, CT, CT. You can set this attribute for each individual certificate, for example:

certutil -M -n myTrustCert -t "CT,CT,CT" -d /etc/pki/nssdb

where myTrustCert is the name of the trust anchor certificate. Or you can set this attribute for all imported trust certificates by using a single command such as the following:

certutil -L -d /etc/pki/nssdb | grep ",," | sed 's/ ,,.*//' | sed 's/ *$//' | while read line; do certutil -M -n "$line" -t "CT,CT,CT" -d /etc/pki/nssdb; done

For more information about the NSS libraries and tools, see the Mozilla NSS documentation.

Example 1: Encryption

This example shows how to use the cipher algorithm AES/CBC/PKCS5Padding for encryption in FIPS mode.

  1. Create Java code:
    package com.test.fips;
    import java.security.SecureRandom;
    import javax.crypto.Cipher;
    import javax.crypto.SecretKey;
    import javax.crypto.spec.SecretKeySpec;
    
    public class AES {
    
        public static void main(String[] args) throws Exception {
    
            SecureRandom secureRandom = new SecureRandom(); 
            byte[] key = new byte[16]; 
            byte[] plainText = new byte[32]; 
            secureRandom.nextBytes(key); 
            secureRandom.nextBytes(plainText);
    
            SecretKey secretKey = new SecretKeySpec(key, "AES");
    
            Cipher cipher = Cipher.getInstance("AES/CBC/PKCS5Padding"); 
            cipher.init(Cipher.ENCRYPT_MODE, secretKey);
    
            byte[] cipherText = cipher.doFinal(plainText); 
            System.out.println("Encryption Done"); 
        }
    }
  2. Run the application, specifying both FIPS system properties on the command line to enable FIPS mode and provide tracing:
    java -Dsemeru.fips=true -Djava.security.debug=semerufips com.test.fips.AES
    The console shows the following output:
    semerufips: FIPS mode detected, loading properties
    semerufips: FIPS mode properties loaded
    Encryption Done

Example 2: Using a PKCS#12 keystore and truststore in FIPS mode

  1. Generate the keys and trust certificates by using OpenSSL commands:
    openssl req -x509 -newkey rsa:4096 -passin pass:changeit -passout pass:changeit -keyout key.pem -out cert.pem -sha256 -days 365  -subj '/C=CA/ST=ON/L=TORONTO/CN=www.ibm.com'
    openssl pkcs12 -export -keypbe AES-128-CBC -passin pass:changeit -passout pass:changeit -name myKeyCert -out keystore.p12 -inkey key.pem -in cert.pem
    openssl pkcs12 -export -nokeys -passout pass:changeit -caname myTrustCert -in cert.pem -out truststore.p12
    For more information about the OpenSSL utilities for generating certificates, see the OpenSSL documentation.
  2. Create Java code that reads the PKCS#12 keystore then prints its entries:
    char[] password = "changeit".toCharArray();
    byte[] byteArray = Files.readAllBytes(Paths.get("keystore.p12"));
    bais = new ByteArrayInputStream(byteArray);
    KeyStore ks = KeyStore.getInstance("pkcs12");
    ks.load(bais, password);
    
    Enumeration<String> enumeration = ks.aliases();
    while(enumeration.hasMoreElements()) {
        String alias = enumeration.nextElement();
        System.out.println("PKCS12 alias name: " + alias);
        System.out.println("PKCS12 certificate: \n" + ks.getCertificate(alias).toString());
    }
    Repeat the code, replacing keystore.p12 with truststore.p12, to read the PKCS#12 truststore and print its entries.
  3. Run the application without enabling FIPS mode to see the output for the PKCS#12 keystore and truststore.
  4. To run the application in FIPS mode, the keystore and truststore must reside in the PKCS#11 based NSS database. Import the PKCS#12 keystore and truststore into the NSS database then mark the truststore certificates as trusted CA:
    pk12util -i keystore.p12 -W changeit -d /etc/pki/nssdb
    pk12util -i truststore.p12 -W changeit -d /etc/pki/nssdb
    certutil -M -n myTrustCert -t "CT,CT,CT" -d /etc/pki/nssdb
  5. Modify the Java code to read the PKCS#11 keystore then print its entries:
    char[] password = "changeit".toCharArray();
    KeyStore ks = KeyStore.getInstance("pkcs11");
    ks.load(null, password);
    
    Enumeration<String> enumeration = ks.aliases();
    while(enumeration.hasMoreElements()) {
        String alias = enumeration.nextElement();
        System.out.println("PKCS11 alias name: " + alias);
        System.out.println("PKCS11 certificate: \n" + ks.getCertificate(alias).toString());
    }
    Do the same for the truststore.
  6. Run the application with FIPS mode enabled to see the output for the PKCS#11 keystore and truststore in the NSS database.

Example 3: Configuring Open Liberty to use FIPS mode

  1. Enable FIPS mode by following the earlier instructions.
  2. Import the keystore into the NSS database:
    pk12util -i keystore.p12 -W changeit -d /etc/pki/nssdb
  3. Create an Open Liberty configuration file, called pkcs11cfg.cfg for example, to point to the NSS library required for reading the PKCS#11 keystore. Create the file in a location that is accessible to the Open Liberty server, then add the following content to the file:
    name = NSS-FIPS
    library = /usr/lib64/libsoftokn3.so
    slot = 3
    showInfo=true
  4. Modify the Open Liberty server.xml configuration file to reference the file that you created in the previous step and specify that the NSS keystore is accessed using PKCS#11. For example:
    <keyStore id="daytrader7" location="pkcs11cfg.cfg" type="PKCS11-NSS-FIPS" fileBased="false" password="changeit" provider="SunPKCS11-NSS-FIPS"/>
    This change instructs Open Liberty to use the NSS PKCS#11 based keystore instead of the file based keystore. For more information about the keystore element, see the Open Liberty documentation.

[{"Type":"MASTER","Line of Business":{"code":"LOB45","label":"Automation"},"Business Unit":{"code":"BU059","label":"IBM Software w\/o TPS"},"Product":{"code":"SSA3RN","label":"IBM Semeru Runtimes"},"ARM Category":[],"Platform":[{"code":"PF025","label":"Platform Independent"}],"Version":"11.0.0;and future releases"}]

Document Information

Modified date:
27 September 2022

UID

ibm16612693