37 Enabling FIPS Mode

Learn how to enable FIPS 140-2 mode in 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.

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>