IBM Support

How to Consume an IWS Web Service behind an SSL Connection - REST or SOAP

Troubleshooting


Problem

This document describes the steps necessary to consume an IWS web service with an SSL/HTTPS connection.

Resolving The Problem

This document describes the API calls necessary to consume a web service with an SSL/HTTPS connection.

Additional information about these API's can be found in the Web Services Client for ILE Programming Guide.

Additional SSL options may periodically be added via PTF.  Ensure you are up to date on IWS client PTFs:

As of 1/31/2024 these options are available:
pKeyRingFile
Pointer to null-terminated character string representing the certificate store file to be used for the secure session or SSL environment. This parameter is ignored if the application ID parameter is set to a value.

pKeyRingPS
(optional) Pointer to null-terminated character string representing the password for the certificate store file to be used for the secure session or SSL environment. If the parameter is not passed or is set to the null string, the internal stash file associated
with the user profile that is being used to run the application is used as long as the user has authority to the certificate store file and the password has been used one time one the system. To specify any of the subsequent optional parameters, you must pass a value for this parameter. This parameter is ignored if the application ID parameter is set to a value.

pKeyRingLbl
(optional) Pointer to null-terminated character string representing the certificate label associated with the certificate in the certificate store to be used for the secure session or SSL environment. If the parameter is not passed or is set to the null string, the default certificate label in the specified certificate store file is used for the SSL environment. To specify any of the subsequent optional parameters, you must pass a value for this parameter. This parameter is ignored if the application ID parameter is set to a value.

pV2Cipher
(optional ) Pointer to null-terminated character string representing the list of SSL Version 2 ciphers to be used for the secure session or the SSL environment. Specifying "NONE" for this parameter will disable SSL Version 2 ciphers. To specify any of the subsequent optional parameters, you must pass a value for this parameter.

pV3Cipher
(optional) Pointer to null-terminated character string representing the list of SSL Version 3/TLS Version 1 ciphers to be used for the secure session or the SSL environment. Specifying "NONE" for this parameter will disable SSL Version 3 ciphers. To specify any of the subsequent optional parameters, you must pass a value for this parameter.

pTLSCipher
(optional) Pointer to null-terminated character string indicating whether to enable or disable the TLS Version 1 ciphers. A value of "NONE" will disable the ciphers; any other value will enable the ciphers. By default, the TLS Version 1 ciphers are enabled.

pTLSv11Cipher
(optional) Pointer to null-terminated character string indicating whether to enable or disable the TLS Version 1.1 ciphers. A value of "NONE" will disable the ciphers; any other value will enable the ciphers. By default, the TLS Version 1.1 ciphers are enabled.

pTLSv12Cipher
(optional) Pointer to null-terminated character string indicating whether to enable or disable the TLS Version 1.2 ciphers. A value of "NONE" will disable the ciphers; any other value will enable the ciphers. By default, the TLS Version 1.2 ciphers are enabled.

pTolerate
(optional) Pointer to null-terminated character string indicating whether to tolerate soft validation errors (expired certificate or certificate not in certificate store). Specify a value of true to tolerate soft validation errors, or false to not tolerate soft validation errors. The default is false.

pAppid
(optional) Pointer to null-terminated character string indicating the application ID to use for the SSL environment.

pFQDN
(optional) Pointer to null-terminated character string indicating the fully qualified domain name that will be used as Server Name Indication (SNI) as defined by RFC 6066.
 
pTLSv13
(optional) Pointer to a null-terminated character string indicating whether to enable or disable the TLSv1.3 ciphers. A value of "NONE" disables the ciphers; any other value enables the ciphers. By default, the TLSv1.3 ciphers are enabled.

Usage notes:
1: The last parameter passed must be the NULL pointer, in RPGLE this will be *NULL.

2: IBM recommends downloading and importing the remote HTTPS URL's CA certificates as the most secure HTTPS configuration option. However, a less secure option to resolve a "6000 - Certificate is not signed by a trusted certificate authority" error is to set the pTolerate option. This will allow soft TLS validation errors to be tolerated and ignored, which includes certificate errors.

QMGTOOLS has a utility to import the certificates -> GETSSL
 
Important Note: This code example is provided as-is. IBM accepts no responsibility for its correctness.
The following are examples of calling the API's from RPGLE.  The code should be added prior to making a call to the Web service in the client application.

SSL calls with a certificate:
1. Get the security certificate from the Web services server.
2. Install the certificate in the Digital Certificate Manager (DCM).
3. Once the certificate is successfully installed, the API needs to be called in the client application.
 
Required parameters:
  DCL-S propBuf CHAR(100);
  DCL-S NULLSTR CHAR(1) inz(x'00');
  DCL-S NONE CHAR(6);
  DCL-S SETFALSE CHAR(6);
----------------------------
----------------------------
//Set values
  NONE = 'NONE' + x'00';
  SETFALSE = 'false' + x'00';
  propBuf = '/QIBM/USERDATA/ICSS/CERT/SERVER/DEFAULT.KDB' + x'00';                                              

If using the transport API's, this is the correct method:
  rc = axiscTransportSetProperty(tHandle: AXISC_PROPERTY_HTTP_SSL: 
    %addr(propBuf): %addr(NULLSTR): %addr(NULLSTR): %addr(NONE):
    %addr(NONE): %addr(NONE): %addr(NONE): %addr(NULLSTR):
    %addr(SETFALSE): %addr(NULLSTR) : %addr(NULLSTR) : %addr(NULLSTR) : *NULL);
               
If using stubs created by wsdl2ws.sh utility, this is the correct method: 
  axiscStubSetSecure(WsStub.handle:  
    %addr(propBuf): %addr(NULLSTR): %addr(NULLSTR): %addr(NONE):
    %addr(NONE): %addr(NONE): %addr(NONE): %addr(NULLSTR):
    %addr(SETFALSE): %addr(NULLSTR) : %addr(NULLSTR) : %addr(NULLSTR) : *NULL);

Notes:
1. If you installed the certificate in another store other than the default, update propBuf accordingly.
2. If you need to pass a certificate label, pass a null terminated string with the label rather than NULLSTR for pKeyLabel.

[{"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":"a8m3p000000hB4rAAE","label":"API"}],"ARM Case Number":"","Platform":[{"code":"PF012","label":"IBM i"}],"Version":"All Versions"}]

Historical Number

622160517

Document Information

Modified date:
31 January 2024

UID

nas8N1011196