How to use TLSv1.2 with System SSL on IBM i 7.1


Why use TLSv1.2?

It is the latest and greatest version of the Secure Sockets Layer (SSL) protocol. It is deemed more secure than all of the previous versions for various technical reasons. The US government recommends TLSv1.2 be the only SSL protocol used. A transition phase is needed by most applications where TLSv1.2 is supported in addition to the older protocols rather than in place of them. The new support that is documented here allows security administrators to restrict individual applications to use only TLSv1.2 when deemed operationally feasible.

System requirements

The core System SSL TLSv1.2 functionality is included in IBM i 7.1 Technology Refresh 6 (TR6). To enable and use the new protocols, program temporary fixes (PTFs) from multiple areas of the operating system are also required. Provided DCM (5770SS1 option 34) is installed on the system, requesting and applying SI48659 gets all of the enablement PTFs. More than two dozen PTFs are pulled in by SI48659 as a result of PTF requisites. Be sure to apply the distribution requirement PTFs valid for the products and options that are installed on the system.

System value changes

The new support is installed but dormant in System SSL after applying SI48659. The QSSLPCL system value must be modified by Change System Value (CHGSYSVAL) to activate the new protocols for System SSL. Change the default value of *OPSYS to:





If QSSLPCL is set to something other than *OPSYS, add *TLSV1.2 and *TLSV1.1 to the existing setting.

Figure 1. Change the system value
Change the system value
Change the system value

In addition to the Change System Value (CHGSYSVAL) CL command, Navigator for i can be used to work with the QSSLPCL value. Navigator for i is on a different release cycle and the enhancements for enabling TLSv1.2 through this interface will not be available until the summer of 2013. When the new protocols are enabled through CHGSYSVAL this configuration will not be visible from Navigator for i until that update is available.

After you have modified the QSSLPCL system value, the system is ready to use the new protocols. No applications automatically use the new support, support must be turned on by each application.

Application enablement


Many of the IBM i provided applications use application definitions to configure certificate information for the application. Using DCM today, administrators assign a certificate to the application's definition. Other fields in the application definition determine whether client authentication is used and what certificate authorities (CAs) are allowed. This existing DCM configuration interface was enhanced to included several new fields in the application definition.

One of the new fields controls which protocols are supported by the application. You must change this field to include TLSv1.2 to activate that protocol for the application. The default setting for this field is *PGM, which allows the application's code and existing configuration to determine which protocols are used. Initially there are no applications that would use TLSv1.2 with the *PGM setting but over the lifetime of the release, that might change.

There is a disadvantage to having this new application-level control of supported protocols and cipher suites. An administrator can now configure weaker security properties for an IBM application than was previously possible.

The IBM i information center contains more information about the application definition fields that can be changed.

Some applications do not allow one or more of the new fields to be modified. A 4022 error is displayed on the DCM panel when the application prevented the change. IBM HTTP Server is one such application and does not allow protocols and ciphers to be configured from the DCM panel. The HTTP support for enabling TLSv1.2 is available as part of the HTTP Server PTF Group Level 18.

Integrated Language Environment (ILE) application programming interface

The System SSL programming interfaces are updated to allow developers to use TLSv1.2. You need to install SI48539 (distribution requisite of SI48659) to have the new version of gskssl.h and qsossl.h loaded on the development system. The GSKit and SSL API descriptions have been updated in the IBM i information center.

A typical GSKit application modification is to add two calls to gsk_attribute_set_enum(), specifying the secure environment handle that is returned from the existing gsk_environment_open() call.

Listing 1. GSKit sample code
rc = gsk_attribute_set_enum(env_handle, GSK_PROTOCOL_TLSV12, GSK_TRUE);
if (rc != GSK_OK)
 printf("gsk_attribute_set_enum() failed with rc = %d.\n", rc);
 printf("rc of %d means %s\n", rc, gsk_strerror(rc));
rc = gsk_attribute_set_enum(env_handle, GSK_PROTOCOL_TLSV11, GSK_TRUE);
if (rc != GSK_OK)
 printf("gsk_attribute_set_enum() failed with rc = %d.\n", rc);
 printf("rc of %d means %s\n", rc, gsk_strerror(rc));

Refer to the API documentation to see more details on these attributes and other new or changed attributes now available to developers.

Java Secure Socket Extension (JSSE)

If you are a user of the IBM Pure JSSE provider IBMJSSE2, the latest SR release for JDK6 and JDK7 provides TLSv1.2 support. IBM i 7.1 TR6 is not required.

If you are a user of the native IBM i JSSE provider IBMi5OSJSSEProvider, then the requirements that were listed previously are required including changing QSSLPCL.

JDK7 uses SSL_TLSv2 as the default context protocol. This context protocol supports TLSv1.2, TLSv1.1, TLSv1.0 and SSLv3. To limit the system to one protocol, you can use TLSV1.2 or TLSv1.1 as the protocol on the SSLContext.getInstance method.

For JDK6, you must specify SSL_TLSv2 on the SSLContext.getInstance method because it is not the default protocol value. You can also use TLSV1.2 or TLSv1.1.


The SSL protocol was designed with forward compatibility in mind. An SSL server can support multiple protocol versions at the same time. It negotiates by using the highest version protocol that is supported by both sides of the connection. Unfortunately there are indications that a few SSL implementations exist that are not compatible. This condition would manifest itself as an error when your newly TLSv1.2 enabled SSL client application connects to an SSL server by using one of these implementations. If an interoperability issue happens, the peer server must update its SSL implementation or the client must discontinue the use of TLSv1.2 with that server.

If testing determines all application peers support TLSv1.2, then that application can be configured to support only TLSv1.2 to have the highest level of security. For some applications, this configuration might never be feasible.

It is important to remember that the peer client must also support and enable TLSv1.2 in order for it to be negotiated. There are many client applications that currently do not support TLSv1.2 because of the "chicken and egg" factor: Because the server did not understand TLSv1.2, the client had no incentive to incorporate that support. Now that the server has the TLSv1.2 capability, over time, more client applications will add TLSv1.2 support.

Additional features

The focus of this article is TLSv1.2 support; however, there are other new System SSL features delivered along with the TLSv1.2 support. The DCM help text and GSKit API documentation provide details on those new features. Online Certificate Status Protocol (OCSP) support is one of these additional features you might find interesting.


TLSv1.2 support is now available with the release of IBM i 7.1 TR6. By making a few configuration or code changes your applications can begin to use this more secure protocol.


Downloadable resources


Sign in or register to add and subscribe to comments.

Zone=IBM i
ArticleTitle=How to use TLSv1.2 with System SSL on IBM i 7.1