IBM Support

Enabling the TLSv1.1 and TLSv1.0 Protocols with IBM Java 8, 7.1, and 7.0 on the IBM i OS

Troubleshooting


Problem

After updating to the latest IBM i Java Group PTF level, a "javax.net.ssl.SSLHandshakeException: No appropriate protocol (protocol is disabled or cipher suites are inappropriate)" error message occurs when using the TLSv1.0 and/or TLSv1.1 protocols.  This is because the TLSv1.0 and TLSv1.1 protocols have been disabled for use with IBM JDK 8.0, 7.1, and 7.0 on the IBM i OS.

Cause

The TLSv1.0 and TLSv1.1 protocols have been disabled for use with IBM JDK 8.0, 7.1, and 7.0 on the IBM i OS after installing 8.0 SR6 FP30, 7.1 SR4 FP85, and 7.0 SR10 FP85 when applying the following IBM i Java Group PTF level for your IBM i OS VRM.

Release 7.4 -- SF99665 level 11
Release 7.3 -- SF99725 level 22
Release 7.2 -- SF99716 level 32
Release 7.1 -- SF99572 level 46

Environment

IBM i OS
IBM JDK 8.0 SR6 FP30, 7.1 SR4 FP85, and 7.0 SR10 FP85 

Resolving The Problem

IBM recommends customers use the more secure TLSV1.2 or TLSv1.3 protocol instead.  Refer to the following document for more information on how to enable your Java application to use TLSv1.2:
If you are unable to update your Java application to use the TLSv1.2 or TLSv1.3 protocol and require the re-enablement of the TLSv1.1 or the TLSv1.0 protocol for your IBM JDK environment on the IBM i OS, you have a couple of options to do this:
IBM strongly recommends that you always run your IBM i server with the TLSv1.1 and TLSv1.0 network protocols and cipher suites DISABLED. NOTE: Configuring your IBM i server to allow the use of weak protocols and weak cipher suites will result in your IBM i server potentially being at risk of a network security breach. IBM DISCLAIMS AND YOU ASSUME ALL RESPONSIBILITY AND LIABILITY FOR ANY DAMAGE OR LOSS, INCLUDING LOSS OF DATA, ARISING OUT OF OR RELATED TO YOUR USE OF THE SPECIFIED NETWORK PROTOCOL AND/OR CIPHER SUITES.
Option 1: Customize your Java environment/application to use its own custom java.security file with the "TLSv1" and "TLSv1.1" values removed from the jdk.tls.disabledAlgorithms property.

How to Customize Java Security Configuration Properties for JDKs on the IBM i OS

a.  Copy the /QOpenSys/QIBM/ProdData/JavaVM/jdk80/64bit/jre/lib/security/java.security file to /home/java.security.
STRQSH
cp /QOpenSys/QIBM/ProdData/JavaVM/jdk80/64bit/jre/lib/security/java.security /home/java.security
F12
b. Edit the /home/java.security file and remove the "TLSv1" and "TLSv1.1" values from the jdk.tls.disabledAlgorithms property.
EDTF STMF('/home/java.security')
For example, the original string copied from the JAVA_HOME/lib/security/java.security file might look like the following:
---
jdk.tls.disabledAlgorithms=SSLv3, TLSv1, TLSv1.1, RC4, DES, MD5withRSA, DH keySize < 1024, DESede, \ EC keySize < 224, 3DES_EDE_CBC, anon, NULL, DES_CBC
---

After removing the TLSv1 and TLSv1.1 values from the jdk.tls.disabledAlgorithms property in the new /home/java.security file, the modified string should look like the following:
---
jdk.tls.disabledAlgorithms=SSLv3, RC4, DES, MD5withRSA, DH keySize < 1024, DESede, \ EC keySize < 224, 3DES_EDE_CBC, anon, NULL, DES_CBC
Then, press F3 twice to save and exit.
c.  Implement the java.security.properties JVM property to point to the modified /home/java.security properties file.
You can implement the java.security.properties in several different locations depending on how you are invoking your Java program.
RUNJVA/JAVA CL Command:
RUNJVA CLASS(MyClass) PROP((java.security.properties '/home/java.security'))
JAVA CLASS(MyClass) PROP((java.security.properties '/home/java.security'))
Java invocation in Qshell/PASE:
QSH CMD('java -Djava.security.properties==/home/java.security MyClass')
STRQSH
java -Djava.security.properties==/home/java.security MyClass
For a specific IBM i JVM job user:
STRQSH
touch -C 819 /home/<JVMuser>/SystemDefault.properties
echo "java.security.properties==/home/java.security" >> /home/<JVMuser>/SystemDefault.properties
Using the IBM_JAVA_OPTIONS environment variable:
NOTE:  Environment variable must be set before the JVM has been created.
ADDENVVAR ENVVAR(IBM_JAVA_OPTIONS) VALUE('-Djava.security.properties==/home/java.security') LEVEL(*JOB) REPLACE(*YES)
Option 2: Edit the IBM JDK global java.security file to remove the "TLSv1" and "TLSv1.1" values from the jdk.tls.disabledAlgorithms property.
READ FIRST!

Files that reside in the /QIBM/ProdData/* and /QOpenSys/QIBM/ProdData/* directory structures are "owned" by IBM. These system directories are used for Licensed Program Product (LPP) data. As a result, they will be updated/overlaid when Java PTFs are applied. This means it is very risky for clients/third parties to rely on changes/customizations made to any files in the /QIBM/ProdData/* or /QOpenSys/QIBM/ProdData/* directories because a PTF may overlay any changes/customizations.

The Java LPP on the IBM i provides default files for the security configuration. The default security configuration files include the java.security, java.policy and cacerts files which are located in the /QIBM/ProdData/Java400/jdkxx/lib/security/ and /QOpenSys/QIBM/ProdData/JavaVM/jdkxx/xxbit/jre/lib/security/ directories. It is recommended that you copy these files to another directory outside of the LPP system directories when making customizations. The following properties may be used so the JVM can find and use these customized configuration files. Using these custom properties will insulate your Java applications from changes made to the global Java system LPP security configuration files when applying PTFs.
a. Identify the EXACT IBM JDK version and bit level being used by your Java application.
This can be found in WRKJVMJOB Option 5 if the JVM is currently active or in the IBM i JVM job log in the second-level message text for the message "Java virtual machine is IBM Technology for Java."  Should look something like this:
Cause:   JAVA_HOME environment variable is
  /QOpenSys/QIBM/ProdData/JavaVM/jdk80/64bit         
In the above example, JAVA_HOME=/QOpenSys/QIBM/ProdData/JavaVM/jdk80/64bit
b. Edit the JAVA_HOME/jre/lib/security/java.security file and remove the "TLSv1" and "TLSv1.1" values from the jdk.tls.disabledAlgorithms property.
EDTF STMF('JAVA_HOME/jre/lib/security/java.security')
i.e. EDTF STMF('/QOpenSys/QIBM/ProdData/JavaVM/jdk80/64bit/jre/lib/security/java.security')
For example, the original string from the JAVA_HOME/lib/security/java.security file might look like the following:
---
jdk.tls.disabledAlgorithms=SSLv3, TLSv1, TLSv1.1, RC4, DES, MD5withRSA, DH keySize < 1024, DESede, \ EC keySize < 224, 3DES_EDE_CBC, anon, NULL, DES_CBC
---

After removing the TLSv1 and TLSv1.1 values from the jdk.tls.disabledAlgorithms property in the JAVA_HOME/lib/security/java.security file, the modified string should look like the following:
---
jdk.tls.disabledAlgorithms=SSLv3, RC4, DES, MD5withRSA, DH keySize < 1024, DESede, \ EC keySize < 224, 3DES_EDE_CBC, anon, NULL, DES_CBC
c. Then, press F3 twice to save and exit.

Document Location

Worldwide

[{"Type":"MASTER","Line of Business":{"code":"LOB57","label":"Power"},"Business Unit":{"code":"BU058","label":"IBM Infrastructure w\/TPS"},"Product":{"code":"SWG60","label":"IBM i"},"ARM Category":[{"code":"a8m0z0000001gHbAAI","label":"Java Development Kit->Java Secure Socket Extension"}],"ARM Case Number":"","Platform":[{"code":"PF012","label":"IBM i"}],"Version":"All Versions"}]

Document Information

Modified date:
19 August 2021

UID

ibm16479421

Page Feedback