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.

Accessing IBM Digital Certificate Manager

To begin, verify that the IBM *ADMIN HTTP server is running on your system with the following command:

WRKSBSJOB SBS(QHTTPSVR)

If you don’t see several ADMIN jobs 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:2001 - you should see a login page as seen below:

Enter your IBM i username and password, and click “Log in”. You should see a page split into two sections - a menu on the left, and a larger content area on the right that looks like the below image:

Click the “IBM i Tasks Page” link which should update the right section to look similar to the below image.

Depending on your IBM i operating system version and installed PTFs, you may not have “http” and “https” links and instead “Digital Certificate Manager” is a direct link. In this case, click “Digital Certificate Manager”. Otherwise, if you do see “http” and “https” links as circled above, you should click one of the two links. Note: Many customers do not have HTTPS properly set up for their *ADMIN server which can cause issues when selecting “https”, so we recommend selecting “http” unless you know your *ADMIN server is configured correctly for HTTPS.

In either case, you will be redirected to a URL that looks similar to this:

http://YOUR_IBM_IP_ADDRESS:2001/QIBM/ICSS/Cert/Admin/qycucm1.ndm/main0

and your web browser will prompt you to log in again. Enter your IBM i username and password and click Sign In. Note: It is recommended to log into the Digital Certificate Manager on a profile with elevated authority such as a *SECOFR profile.

Verify *SYSTEM Certificate Store Access

Selecting the “Select a Certificate Store” button at the top of the left sidebar will place you at the below screen.

Make sure *SYSTEM is selected, and then select the “Continue” button. You will be prompted to enter the certificate store password. Enter the Certificate store password you specified when setting up the *SYSTEM store.

Enter the password you specified in Step 4, and select the Continue button. Note: If you ever forget the password, you can simply select “Reset Password” - by design, you will be allowed to reset the password without knowing the previous password.

Once you have logged in successfully, you should see a screen that looks like the one below:

Creating a Client SSL Application

Expand “Manage Applications” in the left menu, and click “Add application”.

You should be taken to a screen which allows you to select the type of application you’d like to create. Select “Client - Add a client application”, and then select the “Continue” button.

You will then be presented with a long form where you can configure various aspects of your application. Note that this form may vary depending upon your IBM i operating system version and installed PTF levels. For this use case, we only care about a few sections of the form.

First, we need to specify a name for the application, and a description. The name should consist of uppercase letters, numbers, underscores, and periods, and the first character should be an uppercase letter. Due to how DCM displays the application in other parts of the interface, our team generally recommends setting the description to match the name. For example, to create an SSL Application named EXAMPLE_APP, you would enter the following:

Next, you can configure the SSL/TLS versions your application will allow. By default, the application is set to *PGM which will cause your program to still rely on what is configured in the IBM system values. However, as we want to force EXAMPLE_APP to only utilize TLS 1.2, we would do the following:

The other sections on the form allow you to force the usage of specific ciphers as well as configure other parts of the overall SSL/TLS communication exchange. We can ignore them for this example, and instead press the “Add” button at the bottom of the screen. If the application was successfully created, you should see a success message:

If you see this message, you can then use the SSL Application in your RPG API Express programs.

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

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