37 Enabling FIPS Mode

Learn how to enable FIPS 140-2 mode in Oracle WebLogic Server.

FIPS Overview

The Federal Information Processing Standards (FIPS) 140-2 is a standard that describes U.S. Federal government requirements for sensitive but unclassified use. WebLogic Server supports the use of the RSA FIPS-compliant (FIPS 140-2) crypto module.

For supported versions of FIPS, see Supported FIPS Standards and Cipher Suites.

When used in combination with the RSA JSSE and RSA JCE providers, this crypto module provides a FIPS-compliant (FIPS 140-2) implementation.

Note:

In addition to using the RSA JSSE and RSA JCE providers in FIPS mode as described in this section, you can also use them in non-FIPS mode. For example, you might want to use a particular encryption algorithm that is unique to the RSA JSSE provider.

See the following topics:

See FIPS-140 Support in Oracle Fusion Middleware in Administering Oracle Fusion Middleware Oracle Fusion Middleware for detailed information about Oracle Fusion Middleware support for FIPS.

Enabling FIPS 140-2 Mode From Java Options

You can enable FIPS 140-2 mode using Java security files and specifying Java options on the command line.

To enable FIPS 140-2 mode from Java options, follow these steps:

  1. Using the following URL, download and install the Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files that correspond to the version of your JDK. These Java policy JAR files affect cipher key sizes greater than 128 bits. 
    http://www.oracle.com/technetwork/java/javase/downloads/index.html

    Open the .ZIP distribution and update local_policy.jar and US_export_policy.jar in JAVA_HOME/jre/lib/security . See the README.txt file in the .ZIP distribution for more information and installation instructions.

  2. Create your own java.security file. You can use the one that comes with the installed JDK as a guide.

    Add both the RSA JCE provider and the RSA JSSE provider as the first two Java security providers listed in your java.security properties file:

    #
security.provider.1=com.rsa.jsafe.provider.JsafeJCE
security.provider.2=com.rsa.jsse.JsseProvider
 
security.provider.3=sun.security.provider.Sun
:
  3. Set -Djava.security.properties on the WebLogic Server start command line to override the default configuration in the java.security file. Specify a full file path to your custom java.security file. 
    set JAVA_OPTIONS=-Djava.security.properties=C:\Users\user\java.security

    Note:

    Use a single equal sign (=) to specify a filename if you want the java.security properties to be appended to the installed JRE security properties. Use two equal signs (==) if you want to override all the Java security properties, for instance, -Djava.security.properties==C:\Users\user\java.security.
  4. Put the jcmFIPS.jar jar and sslj.jar JAR files (both are in WL_HOME/server/lib/) at the head of the classpath. You can use the PRE_CLASSPATH environment variable to do this.

    (The RSA JCE provider Crypto-J is located in cryptoj.jar and is in the classpath by default.)

    For example, you could set jcmFIPS.jar and sslj.jar in the PRE_CLASSPATH variable before you call the server start script, typically startWebLogic.cmd/sh:

    set PRE_CLASSPATH=%ORACLE_HOME%\wlserver\server\lib\jcmFIPS.jar;%ORACLE_HOME%\wlserver\server\lib\sslj.jar
cd %ORACLE_HOME%\user_projects\domains\base_domain
startWebLogic.cmd
  5. Start WebLogic Server.

Enabling FIPS 140-2 Mode From java.security

You can enable FIPS 140-2 mode from the installed JDK java.security file.

The configuration steps are as follows:

  1. Using the following URL, download and install the Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files that correspond to the version of your JDK. These Java policy JAR files affect cipher key sizes greater than 128 bits.

    See the README.txt file in the .ZIP distribution for installation instructions.

    http://www.oracle.com/technetwork/java/javase/downloads/index.html

    Open the .ZIP distribution and update local_policy.jar and US_export_policy.jar in JAVA_HOME/jre/lib/security. See the README.txt file in the .ZIP distribution for more information and installation instructions.

  2. Edit the java.security file. Add both the RSA JCE provider and the RSA JSSE provider as the first two Java security providers listed in the java.security properties file: 
    #
security.provider.1=com.rsa.jsafe.provider.JsafeJCE
security.provider.2=com.rsa.jsse.JsseProvider
 
security.provider.3=sun.security.provider.Sun
:
  3. Put the jcmFIPS.jar jar and sslj.jar JAR files (both are in WL_HOME/server/lib/) at the head of the classpath. You can use the PRE_CLASSPATH environment variable to do this.

    (The RSA JCE provider Crypto-J is located in cryptoj.jar and is in the classpath by default.)

    For example, you could set jcmFIPS.jar and sslj.jar in the PRE_CLASSPATH variable before you call the server start script, typically startWebLogic.cmd/sh:

    set PRE_CLASSPATH=%ORACLE_HOME%\wlserver\server\lib\jcmFIPS.jar;%ORACLE_HOME%\wlserver\server\lib\sslj.jar
cd %ORACLE_HOME%\user_projects\domains\base_domain
startWebLogic.cmd

    Or, you could add jcmFIPS.jar and sslj.jar to the PRE_CLASSPATH variable in the server start script itself.

  4. Start WebLogic Server.

Verifying JCE When FIPS 140-2 Mode is Enabled

To ensure that JCE verification is enabled when configuring WLS for FIPS 140-2 mode, set the -Dweblogic.security.allowCryptoJDefaultJCEVerification=true JAVA_OPTIONS environment variable when you start WebLogic Server.

During normal WebLogic startup, for performance reasons the RSA Crypto-J JCE Self-Integrity test is disabled.

Note that setting this environment variable adds additional processing and time to the startup.

Creating FIPS 140-2 Compliant Keystores

In WebLogic Server 12.2.1.3 and earlier, the JKS and PKCS12 keystores created with keytool using the Sun JSSE provider (the default) are not fully FIPS compliant. To ensure that your keystores are FIPS 140-2 compliant, you can convert the keystores that you created with the Sun JSSE provider by using the keytool command and specifying the RSA JCE provider supplied with the WebLogic Server distribution.

Also, some environments, such as Java Cloud Service configured with the Oracle Identity Cloud Integrator provider, use the default JKS keystore with CA certificates, cacerts. In these environments, you must convert the JKS keystore to a FIPS compliant PKCS12 keystore using the RSA JCE provider.

The following sections provide procedures for completing these steps to ensure your keystores are FIPS compliant:

Converting a Non-FIPS Compliant Keystore Using the RSA JCE Provider

Using the WebLogic Server distribution classpath, you can convert a non-compliant keystore using the keytool –importkeystore command with the RSA JCE provider as follows:

keytool -importkeystore -srckeystore srckeystore 
         –srcstoretype srcstoretype
         -srcprovidername providername –destkeystore destkeystore 
         -deststoretype PKCS12 -destprovidername JsafeJCE 
         -providerclass com.rsa.jsafe.provider.JsafeJCE 
         -providerpath $CLASSPATH

In this command, provide values for the following parameters:

  • -srckeystore – Name of the source keystore
  • -srcstoretype – Type of source keystore, for example PKCS12
  • -srcprovidername – Name of the source keystore provider. Set to JsafeJCE if srcstoretype is PKCS12
  • -destkeystore - Name of the destination keystore
  • -deststoretype – Type of destination keystore. Set to PKCS12 for the RSA JCE provider
  • -destprovidername – Name of the destination keystore provider. Set to JsafeJCE for the RSA JCE provider
  • -providerclass – Name of the provider class. Set to com.rsa.jsafe.provider.JsafeJCE
  • -providerpath - Classpath for the provider

Converting the Default JKS Keystore for FIPS Compliance

The default JKS keystore with CA certificates, cacerts, included with the JDK is not FIPS compliant in WebLogic Server 12.2.1.3 and earlier. FIPS 140-2 requires a PKCS12 PBES2 keystore; JKS keystores and PKCS12 keystores created with keytool using the Sun JSSE provider (the default) are not supported. If you are using the default JDK cacerts keystore, such as in a Java Cloud Service environment using the Oracle Identity Cloud Integrator provider, you need to complete the following steps to ensure FIPS compliance:

  • Convert the JDK cacerts keystore from JKS to PKCS12 format

  • Convert the PKCS12 keystore using the RSA JCE provider to be FIPS compliant

  • Set Java system properties to update the default trust store used by the Java default SSL Context in your environment so that you can boot and operate WebLogic Server successfully

This example illustrates the steps required to convert the keystore and update the Java system properties. In this example, the JDK is installed in the directory /u01.
  1. Convert the JDK cacerts keystore file to PKCS12 using the keytool –importkeystore command. For example: 
    keytool -importkeystore -srckeystore /u01/jdk/jre/lib/security/cacerts 
      -destkeystore /u01/jdk/jre/lib/security/cacerts.p12 
      –deststoretype pkcs12
    When you execute this command, you are prompted for the default password for the cacerts keystore file. For details about the keytool command and managing the cacerts file, including the default password, see "keytool" at https://docs.oracle.com/javase/8/docs/technotes/tools/windows/keytool.html
  2. Add the WebLogic Server classes to the CLASSPATH environment variable by running the ORACLE_HOME\wlserver\server\bin\setWLSEnv script.
    Here, ORACLE_HOME represents the directory you specified as the Oracle Home when you installed WebLogic Server.

    Note:

    On UNIX operating systems, the setWLSEnv.sh command does not set the environment variables in all command shells. Oracle recommends that you execute this command using the Korn shell or bash shell.
  3. Convert the PKCS12 keystore created in step 1 to a FIPS compliant keystore using the keytool –importkeystore command with the RSA JSE provider, as described in Converting a Non-FIPS Compliant Keystore Using the RSA JCE Provider.
    For example: 
    keytool -importkeystore -srckeystore /u01/jdk/jre/lib/security/cacerts.p12   
-srcstoretype PKCS12 -srcprovidername JsafeJCE 
-destkeystore /u01/jdk/jre/lib/security/cacerts.rsa
-deststoretype PKCS12 -destprovidername JsafeJCE
-providerclass com.rsa.jsafe.provider.JsafeJCE 
-providerpath $CLASSPATH
  4. Set the Java system properties used by the default SSL context when booting WebLogic Server. You can do this by setting the following Java options in the WebLogic Server start script as described in Specifying Java Options for a WebLogic Server Instancein Administering Server Startup and Shutdown for Oracle WebLogic Server.
    For example: 
    Set JAVA_OPTIONS=”-Djavax.net.ssl.trustStore=/u01/jdk/jre/lib/security/cacerts.rsa -Djavax.net.ssl.trustStoreType=PKCS12”

Important Considerations When Using Web Services

When using web services in FIPS 140-2 mode, there are important considerations to keep in mind.

For example:

SHA-1 Secure Hash Algorithm Not Supported

SHA-1 Secure Hash Algorithm is not supported in FIPS 140-2 mode. Therefore the following WS-SP <sp:AlgorithmSuite> values are not supported in FIPS 140-2 mode:

  • Basic256

  • Basic192

  • Basic128

  • TripleDes

  • Basic256Rsa15

  • Basic192Rsa15

  • Basic128Rsa15

  • TripleDesRsa15

As described in Using the SHA-256 Secure Hash Algorithm in Securing WebLogic Web Services for Oracle WebLogic Server, the WebLogic Server web service security policies support both the SHA-1 and much stronger SHA-2 (SHA-256) secure hash algorithms for hashing digital signatures. Specifically, Using the SHA-256 Policies describes which policies use the SHA-1 secure hash algorithm and their SHA-2 equivalents.

FIPS 140-2 mode requires an Extended Algorithm Suite when digital signatures are used. See Using the Extended Algorithm Suite (EAS) in Securing WebLogic Web Services for Oracle WebLogic Server.

If you enable FIPS 140-2 mode, change the <sp:AlgorithmSuite> element in the Security policy to one of the following supported <sp:AlgorithmSuite> values as described in Using the SHA-256 Secure Hash Algorithm:

  • Basic256Sha256

  • Basic192Sha256

  • Basic128Sha256

  • Basic256Exn256

  • Basic192Exn256

  • Basic128Exn256

  • TripleDesSha256

  • TripleDesExn256

  • Basic256Sha256Rsa15

  • Basic192Sha256Rsa15

  • Basic128Sha256Rsa15

  • Basic256Exn256Rsa15

  • Basic192Exn256Rsa15

  • Basic128Exn256Rsa15

  • TripleDesSha256Rsa15

  • TripleDesExn256Rsa15

For example, to edit an existing Basic256 Algorithm Suite to an EAS Algorithm Suite, then change the policy from

<sp:AlgorithmSuite>
        <wsp:Policy>
             <sp:Basic256/>
        </wsp:Policy>
</sp:AlgorithmSuite>

to

<sp:AlgorithmSuite>
         <wsp:Policy>
             <orasp:Basic256Exn256 xmlns:orasp="http://schemas.oracle.com/ws/2006/01/securitypolicy"/>
         </wsp:Policy>
</sp:AlgorithmSuite>

X509PKIPathv1 token Not Supported

The X509PKIPathv1 token is not supported for FIPS 140-2 mode in this release of WebLogic Server. If you use the X509PKIPathv1 token in a custom policy, change the policy to use the PKCS7 token instead.

Specifically, the following two policy assertions are not supported in FIPS 140-2 mode in this release of WebLogic Server:

  • <sp:WssX509PkiPathV1Token10/>

  • <sp:WssX509PkiPathV1Token11/>

If you use these two policy assertions, change them to the following two assertions instead:

  • <sp:WssX509Pkcs7Token10/>

  • <sp:WssX509Pkcs7Token11/>

For example, if the policy has the following assertion in the custom policy:

<wsp:Policy>
   <sp:X509Token sp:IncludeToken=". . .">
         <wsp:Policy>
               <sp:WssX509PkiPathV1Token10/>
         </wsp:Policy>
   </sp:X509Token>
</wsp:Policy>

replace it with the following policy assertion:

<wsp:Policy>
   <sp:X509Token sp:IncludeToken=". . .">
         <wsp:Policy>
               <sp:WssX509Pkcs7Token10/>
         </wsp:Policy>
   </sp:X509Token>
</wsp:Policy>

Or, if the policy has the following assertion in the custom policy:

<wsp:Policy>
   <sp:X509Token sp:IncludeToken=". . .">
         <wsp:Policy>
              <sp:RequireThumbprintReference/>
              <sp:WssX509PkiPathV1Token11/>
         </wsp:Policy>
   </sp:X509Token>
</wsp:Policy>

replace it with the following assertion:

<wsp:Policy>
   <sp:X509Token sp:IncludeToken=". . .">
         <wsp:Policy>
               <sp:RequireThumbprintReference/>
               <sp:WssX509Pkcs7Token11/>
         </wsp:Policy>
   </sp:X509Token>
</wsp:Policy>