Configuring IBM i DB2 QSYS2 HTTP Functions for TLS/HTTPS Secure Communications

How To

Summary

This document provides information on how to configure TLS/HTTPS secure communications with the IBM i DB2 QSYS2 HTTP Functions utilizing the IBM i Web Service Client and IBM i System TLS.

Environment

IBM i 7.3, 7.4, 7.5 OS

Steps

There are 2 options to configure the IBM i Db2 QSYS2 HTTP Functions to utilize HTTPS with the remote URL.

1) IBM Recommended Method - Obtain the remote HTTPS URL Certificate Authority (CA) public certificates and import them into your IBM Digital Certificate Manager (DCM) for i *SYSTEM Certificate store. This configuration method utilizes and recognizes TLS certificate validation when executing the HTTPS URL.

2) Less secure method (recommended for development and testing environments only) - Enable the sslTolerate=true HTTP Option on the IBM i Db2 QSYS2 HTTP Function to tolerate or ignore soft TLS validation errors (including certificate errors). This method does not require obtaining and importing the remote HTTPS URL's Certificate Authority (CA) certificates. WARNING: Since soft TLS validation errors are ignored, this is a less secure connection method due to the decreased security validation. However, the data exchanged between the IBM i and remote HTTPS URL is still encrypted via TLS but the remote HTTPS certificates are not validated.

==============================

Option 1: Import the Remote HTTPS URL's Certificate Authority Certificates

1)	Grant the IBM i User Profile executing the QSYS2 HTTP Function R (Read) authority to the /QIBM/UserData/ICSS/Cert/Server/DEFAULT.KDB file or the keystore specified on the sslCertificateStoreFile HTTP option. It is recommended you create and assign an IBM i authorization list to your certificate store file. Then, add the individual user profiles with R (Read) authority to grant access as needed.
2)	Obtain the CA certificate(s) from the remote HTTPS URL There are 3 primary ways to do this: a) Enter the HTTPS URL into your web browser's address bar and view the TLS certificate currently used on the connection. Then, follow the instructions on Extracting a CA Root Certificate from a Digital Certificate. b) Use the QMGTOOLS/GETSSL utility. c) Follow the steps on How to extract CA certificates for the remote port 443 instead of 990.
3)	If you do not have both the Root and Intermediate Certificate Authorities in-hand, you may need to extract one or both from the digital certificate obtained for the remote HTTPS URL. How To Extract Root and Intermediate Certificate Authority (CA) Certificates 1) Identify all certificates in the personal certificate chain. Double-click the personal certificate .cer of .crt file on your PC and open it with CryptoShellExtensions application. If your file is a .pem or .arm, you will need to rename the file to .cer or .crt for the file to open automatically with CryptoShellExtensions. After the certificate information is displayed, click the Certification Path tab. 2) Extract the Root CA certificate first (1st in the list) and then the Intermediate CA certificate (2nd in the list). 3) Double-click the first certificate or Root CA listed in the tree. 4) Click the Details tab. 5) Click the Copy to File... button. 6) Click Next on the Welcome to the Certificate Export Wizard screen. 7) Select the Base-64 encoded X.509 (.CER) option. 8) Browse and select a location and file name you want to export. i.e. C:\Users\<WindowsUser>\Downloads\CA1.cer 9) Click the Save button. 10) Click the Next button. 11) Click the Finish button. 12) You will see a pop-up box stating "The export was successful." 13) Click the OK button. 14) Repeat steps 3-13 for the 2nd or Intermediate CA (CA2.cer) certificate in the tree if applicable. Typically, personal certificates are signed by an Intermediate Certificate Authority, which is then signed by a Root Certificate Authority, which would have been the previous CA certificate extracted. 15) After you have extracted the Root CA (CA1.cer) and Intermediate CA (CA2.cer) certificates from the personal certificate, you will need to either upload the certificates using the new certificate upload feature in the new Digital Certificate Manager application (IBM i 7.3 & 7.4 only) or manually FTP/transfer the certificates using ASCII mode to the IBM i server so you can import them into your Digital Certificate Manager keystore.
4)	Upload the Root Certificate Authority first and then the Intermediate Certificate Authority to the IFS of your IBM i. Upload your CA certificates to Digital Certificate Manager 1) Open a web browser and go to the NEW Digital Certificate Manager application URL: http://server:2006/dcm https://server:2007/dcm 2) Sign in with your IBM i user profile credentials. SECADM, ALLOBJ, and IOSYSCFG special authorities are required to access the IBM i Digital Certificate Manager web application. 3) Click on Upload Certificate* on the left menu. 4) Click on the Choose File grey button and select the Root CA, Intermediate CA, and personal certificate one-at-a-time to upload them to the /QIBM/UserData/ICSS/Cert/Upload IFS directory on your IBM i server. 5) Select your .cer, .crt, .pem, etc. certificate file you want to upload and click the Open* button. 6) Then, click the Upload button to complete the upload of the certificate file. 7) Repeat steps 4-6 for your Root CA, Intermediate CA, and personal certificates in the certificate chain. 8) You will now see the certificates listed and available for import under the Certificates section under the Upload Certificate view.
5)	Import the Root Certificate Authority first and then the Intermediate Certificate Authority certificate into your Digital Certificate Manager SYSTEM certificate store. Digital Certificate Manager for i FAQ Importing a Certificate Authority certificate in DCM How To Import Root and Intermediate Certificate Authority (CA) Certificates into your DCM SYSTEM certificate store 1) Open a web browser and go to the NEW Digital Certificate Manager application URL: http://server:2006/dcm https://server:2007/dcm 2) Sign in with your IBM i user profile credentials. If you are already signed in, proceed to the next step. SECADM, ALLOBJ, and IOSYSCFG special authorities are required to access the IBM i Digital Certificate Manager web application. 3) Click on the Open Certificate Store* link under Actions. 4) Click on the SYSTEM store, enter your certificate store password, and click on Open. If you do not know the password, you can click on Reset Password* to change the password. NOTE: This may affect ADMIN, IAS, and IWS application server TLS configurations specifying DCM as its keystore. Please ensure you have your security administrator's approval before resetting your Digital Certificate Manager keystore passwords. 5) If you are able to successfully authenticate to the SYSTEM store, a green message will display in the top-right corner of the page and the list of Server/Client Certificates will be displayed. 6) Click the Import* link under Certificates. 7) Click the Certificate Authority (CA) certificate type. 8) Click the Browse Uploads link under the Path field. NOTE: If you manually uploaded the certificates to your IBM i server, you can also use the Browse link under the Path field. 9) A list of uploaded certificates that reside in /QIBM/UserData/ICSS/Cert/Upload will be displayed. If you previously uploaded the Root CA, Intermediate CA, and personal certificates using the new Upload Certificate feature, you should see these certificates listed. 10) Click the radio button next to the Root CA CA1.cer (or Inter CA2.cer) file and click the Select link. 11) Click the Continue link. 12) Specify a unique label name that doesn't already exist in the SYSTEM keystore. i.e. MyAppRootCA or MyAppInterCA 13) Click the Import* link to complete the import certificate process. A green pop-up message will be display if the certificate import succeeded. If the import was unsuccessful, please take note of the following import errors and what they mean. This error indicates the certificate has already been imported or another certificate is already using the same certificate label name. You would want to verify if the certificate already exists in the *SYSTEM certificate store and if any other certificates are using the same label name specified. If you find the certificate already exists, you can simply move onto importing the Intermediate CA certificate. If you find an existing certificate is using the same label, try the import again using a different label value. This error indicates one or more parent CA certificates need to be imported first before this CA certificate can be imported. If the parent CA has already been imported, it may need to be enabled. You must import the certificates in the certificate chain order beginning with importing the Root CA first, then the Intermediate CA, and then the personal or server/client certificate last. Refer to the section "Extract the Root and Intermediate CA certificates from the personal certificate" above to ensure you have extracted the Root and Intermediate CA certificates. You will need to import the Root CA certificate first and then the Intermediate CA certificate. The very last certificate imported will be the server or client certificate. 14) Repeat steps 6-13 to import your Intermediate CA (CA2.cer) certificate.

==============================

Option 2: Set the sslTolerate=true HTTP Option

This will allow soft TLS validation errors to be tolerated and ignored, which includes certificate errors. No TLS certificates are required to be imported into your Digital Certificate Manager (DCM) *SYSTEM certificate store. This is only recommended for development and test environments.

Example:

VALUES CAST(QSYS2.HTTP_GET('https://google.com','{"sslTolerate":"true"}') AS VARCHAR(2048) CCSID 37)

Additional TLS options can be found here: https://www.ibm.com/docs/en/i/7.5?topic=functions-http-get-http-get-blob#rbafzscahttpget__HTTP_options

Related Information

QSYS2 HTTP Function Overview

New HTTP functions based in QSYS2

Configuring Your IBM i System Secure Sockets Layer (SSL)/Transport Layer Securi…

Digital Certificate Manager for i FAQ

Document Location

Worldwide

[{"Type":"MASTER","Line of Business":{"code":"LOB68","label":"Power HW"},"Business Unit":{"code":"BU070","label":"IBM Infrastructure"},"Product":{"code":"SWG60","label":"IBM i"},"ARM Category":[{"code":"a8m3p000000F98WAAS","label":"IBM i Db2-\u003EQSYS2 HTTP Functions"}],"ARM Case Number":"","Platform":[{"code":"PF012","label":"IBM i"}],"Version":"7.3.0;7.4.0;7.5.0"}]

Was this topic helpful?

Document Information

More support for:
IBM i

Component:
IBM i Db2->QSYS2 HTTP Functions

Software version:
7.3.0, 7.4.0, 7.5.0

Operating system(s):
IBM i

Document number:
7104487

Modified date:
19 November 2024

UID

ibm17104487

IBM Support

Tips

Configuring IBM i DB2 QSYS2 HTTP Functions for TLS/HTTPS Secure Communications

How To

Summary

Environment

Steps

How To Extract Root and Intermediate Certificate Authority (CA) Certificates

Upload your CA certificates to Digital Certificate Manager

How To Import Root and Intermediate Certificate Authority (CA) Certificates into your DCM *SYSTEM certificate store

Related Information

Document Location

Was this topic helpful?

Document Information

UID

Share your feedback

Need support?