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) |
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. |
| 2) |
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) Certificates1) 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.
|
| 3) |
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 Manager1) Open a web browser and go to the NEW Digital Certificate Manager application URL:
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.
 |
| 4) |
Import the Root Certificate Authority first and then the Intermediate Certificate Authority certificate into your Digital Certificate Manager *SYSTEM certificate store.
How To Import Root and Intermediate Certificate Authority (CA) Certificates into your DCM *SYSTEM certificate store1) Open a web browser and go to the NEW Digital Certificate Manager application URL:
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
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":"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
Modified date:
02 January 2024
UID
ibm17104487