Configure TLS Versions and Ciphers with Client SSL Applications

IBM’s Digital Certificate Manager provides the capability to create SSL Applications which can be used in a variety of ways. SSL Applications can be defined for either client or server use. Server SSL Applications are typically created and used when offering web services over HTTPS to specify the certificates used for the service. Client SSL Applications are commonly used when calling a web service that require SSL client certificate authentication.

In normal use, RPG API Express will inherit and utilize the currently configured system values for SSL/TLS versions and ciphers (via system values QSSLCSL, QSSLPCL, and QSSLCSLCTL) when performing calls to endpoints that require SSL/TLS. A Client SSL Application can instead allow you to finely control your SSL/TLS versions and ciphers. You can then have RXS reference the Client SSL Application when performing web service calls with RXS_getUri() or RXS_Transmit(). This is helpful when calling web services which may respond poorly to specific SSL/TLS versions or ciphers.

Note that this is intended to be used in very specific circumstances and not as a general approach to creating and managing programs using RPG API Express that call HTTPS web services. For more information and guidance on whether this is a good solution for a problem you’re experiencing, please contact our support team at isupport@katointegrations.com.

Below explains how to create a Client SSL Application named EXAMPLE_APP which is only allowed to utilize TLS 1.2.

This guide shows the process using the new DCM interface. For instructions using heritage DCM, click here.

Accessing DCM

To begin, verify that the *ADMIN HTTP server job is running with the following command:

WRKSBSJOB SBS(QHTTPSVR)

If you don’t see *ADMIN in the list, please run the following command to start it:

STRTCPSVR SERVER(*HTTP) HTTPSVR(*ADMIN)

After you’ve ensured that the *ADMIN server is running, open a web browser, and go to http://YourIBMIPAddress:2006/dcm/ - you should see a login page as seen below:

You will want to log in to DCM using a profile with elevated permissions.

Open the *SYSTEM certificate store by first clicking on the “Open Certificate Store” link under the Actions header, then select *SYSTEM:

Enter your *SYSTEM store password when prompted and click “open”.

Managing SSL Applications

Click on the link to “Manage Application Definitions” to access the currently configured SSL applications:

You’ll see a large list of applications, most of them IBM applications:

Scroll until you find your application and click the “View” link:

First, ensure that there is an SSL certificate assigned to the application:

If there is not an assigned certificate, click the “Assign Certificates” link and choose from the installed server certificates to assign the certificate for this application. If you need to create a new server certification, view our guide on generating a Certificate Signing Request here.

To configure the TLS options for the application, click the “Update” link:

Under the “Protocols” option, if it is currently set to “*PGM”, change it to “Specify”:

This should bring up a list of TLS/SSL protocols. Select the protocol(s) you want to have enabled for this application. For example, if you want this application to only accept TLS 1.2 and explicitly not accept TLS 1.3, select options like this:

You can also choose specific cipher suites that will be accepted by the endpoint, under the “Cipher Specifications” option. This is an example setup for our TLS 1.2 application with restricted cipher suites. You may want to have different cipher suites enabled, depending on your needs, and TLS 1.3 uses some different cipher suites.

All other configuration settings on this page can be left as-is:

Click the “Update” link at the bottom of the page to save the changes:

Code Examples

Using SSL Application with RXS 3.x and RXS_Transmit

If your program is written using the RXS 3.x APIs including RXS_Transmit(), you can specify the SSL Application to be used at runtime via the RXS_TransmitDS_t data structure’s SSLApplication subfield prior to calling RXS_Transmit() using code similar the code below:

 /COPY QRPGLECPY,RXSCB

D TransmitDS      DS                  LikeDS(RXS_TransmitDS_t)
D gRequest        S                   Like(RXS_Var64Kv_t)
D gResponse       S                   Like(RXS_Var64Kv_t)

 /FREE

  RXS_ResetDS( TransmitDS : RXS_DS_TYPE_TRANSMIT );
  
  // Other configs for TransmitDS excluded for example purposes...

  TransmitDS.SSLApplication = 'EXAMPLE_APP';

  gResponse = RXS_Transmit( gRequest : TransmitDS );

 /END-FREE

Using SSL Application with RXS 2.x and RXS_getURI

If you have a program that was written using the older RXS 2.x APIs including RXS_getUri(), you can specify the SSL Application to be used at runtime via the RXS_GetUriIn data structure’s SSLApp subfield prior to calling RXS_getUri() using code similar the code below:

 /COPY QRPGLECPY,RXSCP
 
D gInCfg          DS                  LikeDS(RXS_GetUriIn) Inz
D gRspData        S                   Like(RXS_XmlData)
D gRspHttpHdr     S                   Like(RXS_XmlData)
D gReqData        S                   Like(RXS_XmlData)

 /FREE
  
  // Other configs for gInCfg excluded for example purposes...

  gInCfg.SSLApp = 'EXAMPLE_APP';

  RXS_getUri( gInCfg : gReqData : gRspData : gRspHttpHdr );

 /END-FREE