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 a 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.
 
If using the transport APIs for REST or SOAP based services, the following API will be used:
axiscTransportSetProperty(tHandle: AXISC_PROPERTY_HTTP_SSL 

If using the wsdl2ws.sh or wsdl2rpg.sh tool to generate stubs to call the web service, the following API will be used:
axiscStubSetSecure()

NOTE:  New parameters are added for SSL processing via PTF.  Since the API can be changed without knowledge of the application, the last parameter passed on the call to set the SSL information must be the value *NULL.  See examples below.

Additional information about these API's can be found in the Web Services Client for ILE Programming Guide at the following URL:
https://public.dhe.ibm.com/systems/support/i/iws/systems_i_software_iws_pdf_WebServicesClient_new.pdf
 
Important Note: This code example is provided as-is. IBM accepts no responsibility for its correctness.

First ensure you are current on IWS PTFs:
Link to latest IWS PTFs

There are 2 options to consume a web service behind an SSL connection:
A. WITHOUT a certificate
or
B. WITH a certificate
 
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.

Example
A. WITHOUT a certificate:

1. In the example we are setting the path to the default store in DCM. The default store needs to exist for this to work.
2. The pTolerate parameter is set to true to tolerate validation errors.
.                                                                    
Required parameters:
  DCL-S propBuf CHAR(100);
  DCL-S NULLSTR CHAR(1) inz(x'00');
  DCL-S NONE CHAR(6);
  DCL-S SETTRUE CHAR(6);
----------------------------
----------------------------
//Set values
  NONE = 'NONE' + x'00';
  SETTRUE = 'true' + x'00';
  propBuf = '/QIBM/USERDATA/ICSS/CERT/SERVER/DEFAULT.KDB' + x'00';                                              

If using the transport API's:
  rc = axiscTransportSetProperty(tHandle: AXISC_PROPERTY_HTTP_SSL: 
    %addr(propBuf): %addr(NULLSTR): %addr(NULLSTR): %addr(NONE):
    %addr(NONE): %addr(NONE): %addr(NULLSTR): %addr(NULLSTR):
    %addr(SETTRUE): *NULL);
               
If using stubs created by wsdl2ws.sh:                                                                               
  axiscStubSetSecure(WsStub.handle:  
    %addr(propBuf): %addr(NULLSTR): %addr(NULLSTR): %addr(NONE):
    %addr(NONE): %addr(NONE): %addr(NULLSTR): %addr(NULLSTR):
    %addr(SETTRUE): *NULL);
Details on pTolerate parameter:
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 .

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

B. 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:
  rc = axiscTransportSetProperty(tHandle: AXISC_PROPERTY_HTTP_SSL: 
    %addr(propBuf): %addr(NULLSTR): %addr(NULLSTR): %addr(NONE):
    %addr(NONE): %addr(NONE): %addr(NULLSTR): %addr(NULLSTR):
    %addr(SETFALSE): *NULL);
               
If using stubs created by wsdl2ws.sh:                                                                                  
  axiscStubSetSecure(WsStub.handle:  
    %addr(propBuf): %addr(NULLSTR): %addr(NULLSTR): %addr(NONE):
    %addr(NONE): %addr(NONE): %addr(NULLSTR): %addr(NULLSTR):
    %addr(SETFALSE): *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:
13 May 2022

UID

nas8N1011196