Configure Federal Information Processing Standard Java Secure Socket Extension files
Use this topic to configure Federal Information Processing Standard Java Secure Socket Extension files.
In WebSphere Application Server, the Java Secure Socket Extension (JSSE) provider used is the IBMJSSE2 provider. This provider delegates encryption and signature functions to the Java Cryptography Extension (JCE) provider. Consequently, IBMJSSE2 does not need to be Federal Information Processing Standard (FIPS)-approved because it does not perform cryptography. However, the JCE provider requires FIPS-approval.
WebSphere Application Server provides a FIPS-approved IBMJCEFIPS provider that IBMJSSE2 can utilize. The IBMJCEFIPS provider that is shipped in WebSphere Application Server v8.5 supports the following SSL ciphers:
- SSL_RSA_WITH_AES_128_CBC_SHA
- SSL_RSA_WITH_3DES_EDE_CBC_SHA
- SSL_RSA_FIPS_WITH_3DES_EDE_CBC_SHA
- SSL_DHE_RSA_WITH_AES_128_CBC_SHA
- SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA
- SSL_DHE_DSS_WITH_AES_128_CBC_SHA
- SSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA
When enabling the Use the United States FIPS algorithms option on the server SSL certificate and key management panel, the runtime always uses IBMJSSE2, despite the contextProvider specified for SSL (IBMJSSE or IBMJSSE2S). Also, because FIPS requires the SSL protocol be TLS, the runtime always uses TLS when FIPS is enabled, regardless of the SSL protocol setting in the SSL repertoire. This simplifies the FIPS configuration in v8.5 because an administrator needs to enable only the Use the United States FIPS algorithms option on the server SSL certificate and key management panel to enable all transports using SSL.
- Click Security > SSL certificate and key management > Manage FIPS.
- Select the Enable FIPS 140-2 option and click Apply. This option makes IBMJSSE2 and IBMJCEFIPS the active providers.
- Accommodate Java clients that must access enterprise beans.
Change the com.ibm.security.useFIPS property value from false to true in the profile_root/properties/ssl.client.props file.
- Ensure that the com.ibm.ssl.protocol property within the profile_root/properties/ssl.client.props file is set to TLS.
- Ensure that the java.security file includes the provider.
Edit the java.security file to insert the IBMJCEFIPS provider (com.ibm.crypto.fips.provider.IBMJCEFIPS) before the IBMJCE provider, and also renumber the other providers in the provider list. The IBMJCEFIPS provider must be in the java.security file provider list.
(iseries) The java.security file is located in the profile_root/properties directory.
(dist)(zos) The java.security file is located in the WASHOME/java/jre/lib/security directory.
The IBM SDK java.security file looks like the following example after completing this step:
(dist)(zos)security.provider.1=com.ibm.crypto.fips.provider.IBMJCEFIPS security.provider.2=com.ibm.crypto.provider.IBMJCE security.provider.3=com.ibm.jsse.IBMJSSEProvider 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.crypto.pkcs11impl.provider.IBMPKCS11Impl security.provider.8=com.ibm.security.cmskeystore.CMSProvider security.provider.9=com.ibm.security.jgss.mech.spnego.IBMSPNEGO security.provider.10=com.ibm.security.sasl.IBMSASL security.provider.11=com.ibm.xml.crypto.IBMXMLCryptoProvider security.provider.12=com.ibm.xml.enc.IBMXMLEncProvider security.provider.13=org.apache.harmony.security.provider.PolicyProvider(iseries)
security.provider.1=com.ibm.crypto.fips.provider.IBMJCEFIPS security.provider.2=com.ibm.crypto.provider.IBMJCE security.provider.3=com.ibm.jsse.IBMJSSEProvider 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.i5os.jsse.JSSEProvider security.provider.8=com.ibm.crypto.pkcs11.provider.IBMPKCS11 security.provider.9=com.ibm.security.jgss.mech.spnego.IBMSPNEGO security.provider.10=com.ibm.security.cmskeystore.CMSProvider security.provider.11=com.ibm.security.sasl.IBMSASL security.provider.12=com.ibm.xml.crypto.IBMXMLCryptoProvider security.provider.13=com.ibm.xml.enc.IBMXMLEncProvider security.provider.14=org.apache.harmony.security.provider.PolicyProviderFor the Oracle Java SE Development Kit, the java.security file looks like the following example after completing this step:
security.provider.1=sun.security.provider.Sun security.provider.2=com.ibm.crypto.fips.provider.IBMJCEFIPS security.provider.3=com.ibm.crypto.provider.IBMJCE security.provider.4=com.ibm.jsse.IBMJSSEProvider security.provider.5=com.ibm.jsse2.IBMJSSEProvider2 security.provider.6=com.ibm.security.jgss.IBMJGSSProvider security.provider.7=com.ibm.security.cert.IBMCertPath #security.provider.12=com.ibm.crypto.pkcs11.provider.IBMPKCS11 security.provider.8=com.ibm.security.jgss.mech.spnego.IBMSPNEGO security.provider.9=com.ibm.security.cmskeystore.CMSProvider security.provider.10=com.ibm.security.sasl.IBMSASL security.provider.11=com.ibm.xml.crypto.IBMXMLCryptoProvider security.provider.12=com.ibm.xml.enc.IBMXMLEncProviderEdit the java.security file to uncomment the line with the IBMJCEFIPS provider and also renumber the rest of the provider list. The IBMJCEFIPS provider must be in the java.security file provider list. The java.security file is located in the WASHOME/java/jre/lib/security directory. To edit the file... (zos)
- Copy the java.security file to a directory that has write permissions.
- Edit the java.security file to comment out the line with the IBMJCE provider, uncomment the line with the IBMJCEFIPS provider, and save the file.
The IBM Software Development Kit (SDK) java.security file looks like the following example prior to completing this step:
#security.provider.1=com.ibm.crypto.fips.provider.IBMJCEFIPS security.provider.1=com.ibm.crypto.provider.IBMJCE security.provider.2=com.ibm.jsse.IBMJSSEProvider security.provider.3=com.ibm.jsse2.IBMJSSEProvider2 security.provider.4=com.ibm.security.jgss.IBMJGSSProvider security.provider.5=com.ibm.security.cert.IBMCertPath security.provider.6=com.ibm.crypto.pkcs11.provider.IBMPKCS11 security.provider.7=com.ibm.security.cmskeystore.CMSProvider security.provider.8=com.ibm.security.jgss.mech.spnego.IBMSPNEGO
- Configure the security.overridePropertiesFile and java.security.properties system properties for each Java Virtual Machine (JVM) in the cell. Add the following property and value pairs:
for the java.security file.
This table describes custom properties for specifying a new location for the java.security file.
Property name Value security.overridePropertiesFile true java.security.properties Specify the new location of the java.security file. Specify the previous set of system properties for the deployment manager, the node agent, and other application servers. For the deployment manager, specify this set of system properties for both the control and the servant. For the node agent, specify this set of system properties for the control. For all application servers, specify this set of system properties for the adjunct, control, and servant. For example...to specify these system properties for the control on an application server:
- In the console, click Servers > Application servers > server_name.
- Under Server infrastructure, click Java and Process Management > Process Definition > Control.
- Under Additional properties, click Java Virtual Machine > Custom properties.
- Enter the properties as two sets of name and value pairs.
- Click Save.
What to do next
After completing these steps, a FIPS-approved JSSE or JCE provider offers increased encryption capabilities. However, when you use FIPS-approved providers:
- By default, Internet Explorer might not have TLS enabled. To enable TLS, open the Internet Explorer browser and click Tools > Internet Options. On the Advanced tab, select the Use TLS 1.0 option.
Netscape Version 4.7.x and earlier versions might not support TLS.
- When you select the Use the Federal Information Processing Standard (FIPS) option on the SSL certificate and key management panel, the LTPA token format is not backwards-compatible with previous releases of WAS. However, we can import the LTPA keys from a previous version of the application server.
(dist) Attention: The following error might occur when you attempt to stop WebSphere Application Server after enabling the FIPS option:
ADMU3007E: Exception com.ibm.websphere.management.exception.ConnectorException
Uncomment the following entry in the java.security file if it was previously removed or commented out, then restart the server:
security.provider.2=com.ibm.crypto.provider.IBMJCE
When enabling FIPS, we cannot configure cryptographic token devices in the SSL repertoires. IBMJSSE2 must use IBMJCEFIPS when utilizing cryptographic services for FIPS.
The following FIPS 140-2 approved cryptographic providers that are the only devices that are supported with the FIPS option:
- IBMJCEFIPS (certificate 376)
- IBM Cryptography for C (ICC) (certificate 384)
The relevant certificates are listed on the NIST website (csrc.nist.gov) and FIPS 140-2 Pre-validation List
To unconfigure the FIPS provider, reverse the changes made in the previous steps. After you reverse the changes, verify that we have made the following changes to the sas.client.props, soap.client.props, and java.security files:
- In ssl.client.props, you must change the com.ibm.security.useFIPS value to false.
- (dist)(zos) In the java.security file, you must change the FIPS provider to a non-FIPS provider.
For the IBM SDK java.security file, you must change the first provider to a non-FIPS provider as shown in the following example:
#security.provider.1=com.ibm.crypto.fips.provider.IBMJCEFIPS security.provider.1=com.ibm.crypto.provider.IBMJCE security.provider.2=com.ibm.jsse.IBMJSSEProvider security.provider.3=com.ibm.jsse2.IBMJSSEProvider2 security.provider.4=com.ibm.security.jgss.IBMJGSSProvider security.provider.5=com.ibm.security.cert.IBMCertPath #security.provider.6=com.ibm.crypto.pkcs11.provider.IBMPKCS11For the Sun JDK java.security file, you must change the third provider to a non-FIPS provider as shown in the following example:
security.provider.1=sun.security.provider.Sun security.provider.2=com.ibm.security.jgss.IBMJGSSProvider security.provider.3=com.ibm.crypto.fips.provider.IBMJCEFIPS security.provider.4=com.ibm.crypto.provider.IBMJCE security.provider.5=com.ibm.jsse.IBMJSSEProvider security.provider.6=com.ibm.jsse2.IBMJSSEProvider2 security.provider.7=com.ibm.security.cert.IBMCertPath #security.provider.8=com.ibm.crypto.pkcs11.provider.IBMPKCS11
- (iseries) Edit the java.security file to remove the FIPS provider and renumber the providers as in the following example:
security.provider.1=sun.security.provider.Sun #security.provider.2=com.ibm.crypto.fips.provider.IBMJCEFIPS security.provider.2=com.ibm.crypto.provider.IBMJCE security.provider.3=com.ibm.jsse.IBMJSSEProvider 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.i5os.jsse.JSSEProvider #security.provider.8=com.ibm.crypto.pkcs11.provider.IBMPKCS11 security.provider.8=com.ibm.security.jgss.mech.spnego.IBMSPNEGO
(zos) When you use the FIPS provider, the IBM Software Development Kit (SDK) might issue an error message that refers to a bad certificate. Although this error message can result from a multitude of reasons, review your security configuration and consider one of the following actions:
- Reduce the cipher suite level to Medium, if the cipher suite level is currently Strong.
Avoid trouble: We can change the cipher suite level for different levels of the environment such as the node or server level. Limit the change to the level of your environment where the change is necessary.gotcha
To change the cipher suite, see the cipher suite groups information within the quality of protection settings documentation. If we change the cipher suite level to Medium, save and synchronize the changes. If the Dynamically update the run time when SSL configuration changes occur option is selected, we do not need to restart the server. However, if the option is not selected, you must restart the server for the changes to be effective. The Dynamically update the run time when SSL configuration changes occur option is available within the console on the SSL certificate and key management panel. To access the panel, click Security > SSL certificate and key management.
- Install security level 3 FMID JCPT3A1 for the z/OS operating system.
Security Level 3 FMID JCPT3A1 is the z/OS operating system implementation of the FIPS 140-2 approved cryptographic providers.
Related
Develop extensions to the WebSphere security infrastructureGlobal security settings The Beginner's Guide to Cryptography