HTTPAPI -- HTTP client support for ILE RPG -- README

Main website https://www.scottklement.com/httpapi/
Discussion/Support forum: https://www.scottklement.com/forums/

ALTERNATIVE #1: (Recommended) Use Git/Makefile

This is the most modern approach and is the approach recommended if you wish to make changes to the source code that will be contributed back to the project. Using this approach, the source code will be kept in your IFS and managed with git.

If not already installed, you'll need YUM on your IBM i. Instructions can be found here:
- https://ibmi-oss-docs.readthedocs.io/en/latest/yum/README.html
You'll need git and GNU make. If not already installed, from a PASE command line, type:
- yum install git
- yum install make-gnu
Clone this repository from GitHub. From a PASE command line:
- (if your PATH isn't set up)export PATH=/QOpenSys/pkgs/bin:$PATH
- https://github.com/ScottKlement/httpapi.git
Build HTTPAPI from the PASE command line:
- (if your PATH isn't set up) export PATH=/QOpenSys/pkgs/bin:$PATH
- cd httpapi
- make LIBRARY=libhttp

NOTE: To keep the messages on the screen clean and easy to follow, compile errors are not printed to the screen. Instead, files are created in the tmp subdirectory containing the output of the various compile commands.

ALTERNATIVE #2: INSTALL/COMPILE FROM A SAVE FILE

Transfer the HTTPAPI.SAVF from my web server to your PC.
Create a SAVF on your IBM i: CRTSAVF MYLIB/HTTPAPI
Transfer the file called HTTPAPI.SAVF from your PC to the newly created SAVF on your IBM i. I use FTP to do this, using binary mode, I do put httpapi.savf MYLIB/HTTPAPI You can do it whichever way you like, however
Unpack the HTTPAPI library:
- RSTLIB SAVLIB(LIBHTTP) DEV(*SAVF) SAVF(MYLIB/HTTPAPI)
Build the INSTALL program:
- CHGCURLIB CURLIB(LIBHTTP)
- CRTBNDCL PGM(INSTALL) SRCFILE(LIBHTTP/QCLSRC)
Use the INSTALL program to build everything else:
- CALL INSTALL

ALTERNATIVE #3: ZIP FILE WITH WINDOWS BATCH UPLOADER

The ZIP download from scottklement.com contains a Windows batch file designed to automate the the process of uploading the data from your PC to the IBM i. This batch file only works on Windows, and only works if FTP is the file transfer protocol. If you can't use the batch file, there are manual instructions in the next section.

On Windows, unzip the HTTPAPI.ZIP file to a temporary folder, for example, extract all files to C:\httpapi
Open an MS-DOS prompt (or Command Prompt)
Switch to the folder where you extracted the files
- cd \httpapi
Run the batch file. Pass the host name, userid and password as parameters to the batch file.
- upload.bat ibmi.example.com bob mypassword
On the IBM i command-prompt, type:
- CHGCURLIB CURLIB(LIBHTTP)
- CRTCLPGM INSTALL SRCFILE(LIBHTTP/QCLSRC)
- CALL INSTALL

WHAT IS SSL/TLS

Secure Socket Layer (SSL) was introduced by Netscape Communications Corp to protect internet transactions. Netscape decided to open this protocol up to the wider Internet community, making it an open standard. After it became an open standard, it was renamed Transport Layer Security (TLS), so all newer version are named TLS (instead of SSL.) Despite this name change, many (most?) people still refer to it as "SSL" when referring to it as a concept. When referring to it in terms of the different versions available, you can think of TLS as "newer versions of SSL".

SSL/TLS provide two important measures of protection:

encryption: All data in an SSL/TLS sessions are encrypted. This is important because data is often confidential and encryption prevents it from being viewed by others on the network.

authentication/idenfication: Encryption is only useful if you know it can only be decrypted by a trusted party. For example, if you are sending a credit card number, you want to make sure it can only be decrypted by the store you are sending it to (in order to purchase something.) It doesn't do much good to encrypt it if it'll be decrypted by a credit card thief. In other words, you need to know who you are sending it to.

REQUIREMENTS FOR BUILDING WITH SSL/TLS SUPPORT

You need to have these programs installed (as of V5R2):
- Digital Certificate Manager which is opt 34 of IBM i. (57xx-SS1)
- TCP/IP Connectivity Utilities (57xx-TC1)
- IBM HTTP server for iSeries (57xx-DG1)
- IBM Crypto Access Provider (57xx-NAE)
- In order to access the Digital Certificate Manager from the web server, you'll also need the IBM Developer Kit for Java (57xx-JV1).
This software uses IBM's "Global Secure Toolkit" (GSKit) for TLS. It is included with the base operating system.
Once you have all of that installed, you'll need to set up the *SYSTEM certificate store in the Digital Certificate Manager. If you already have this configured, you're ready to use HTTPAPI's SSL/TLS support.
Start the IBM Navigator for i by typing:
- STRTCPSVR SERVER(*HTTP) HTTPSVR(*ADMIN)
Connect to the Navigator for i instance of the HTTP server by pointing your Web browser to:
- http://your-system-name:2001
Click "Digital Certificate Manager"
Click "Create New Certificate Store" (in the navigation frame on the left)
Follow the prompts to create a *SYSTEM certificate store
You do not need to create or assign any certificates unless required by the business partner that you will be communicating with. Usually this is only required when security is vital (such as when talking to a bank). Companies like UPS, for example, don't require you to send them any certificates.

ENABLING/DISABLING SSL/TLS PROTOCOLS

Starting with IBM i 6.1, there are system values that control which versions of SSL/TLS that are available for applications (incuding HTTPAPI) to use.

QSSLPCL: The default value of *OPSYS means to let the operating system select the versions of SSL/TLS available to applications. This differs with each OS version.

7.1: SSLv3 and TLSv1.0
7.2: TLSv1.0, TLSv1.1 and TLSv1.2
7.3+: TLSv1.1, TLSv1.2, and TLSv1.3

You can change these values, however, to disable/enable protocol versions. For example:

CHGSYSVAL SYSVAL(QSSLPCL) VALUE('*TLSV1 *TLSV1.1 *TLSV1.2')

NOTE: Because cryptography and security are always changing, it is highly recommended that you update to a supported version of IBM i if at all possible. (For example, at the time that I am writing this, the TLS support in v7r1 is not very secure, and many sites will reject it.)

The QSSLCSL and QSSLCSLCTL system values can be used to control which ciphers are available. We recommend keeping the system defaults for these unless you know what you're doing. For more details on ciphers, see the IBM Information Center.

ENABLING SSL STRICT MODE:

By default, HTTPAPI does not attept to verify the identity of the HTTP server you are communicating with. This is turned off because many organizations use SSL with "self-signed" certificates, and this makes things much simpler for them.

However, this essentially disables the identity checking that is meant to be done with SSL. Therefore, you may wish to perform stricter checking within HTTPAPI. You can do this by calling the https_strict() function prior to using SSL in your application:

https_strict(*ON);

GRANTING ORDINARY USERS PERMISSION TO RUN TLS (SSL) APPLICATIONS

When you get an error using SSL like the following: (GSKit) Access to the key database is not allowed This is because the end-user doesn't have authority to the files in the IFS needed by the Global Secure Toolkit (GSKit) in the operating system. This is the component in the OS used for SSL/TLS.

To solve that problem, grant authority as follows... In this example, I'm giving a user named SCOTTK access to the files. (Change SCOTTK to the proper userid when you do it)

 CHGAUT OBJ('/') +
        USER(SCOTTK) DTAAUT(*RX)
 CHGAUT OBJ('/QIBM') +
        USER(SCOTTK) DTAAUT(*RX)
 CHGAUT OBJ('/QIBM/UserData') +
        USER(SCOTTK) DTAAUT(*RX)
 CHGAUT OBJ('/QIBM/UserData/ICSS') +
        USER(SCOTTK) DTAAUT(*RX)
 CHGAUT OBJ('/QIBM/UserData/ICSS/CERT') +
        USER(SCOTTK) DTAAUT(*RX)
 CHGAUT OBJ('/QIBM/UserData/ICSS/CERT/SERVER')
        USER(SCOTTK) DTAAUT(*RX)
 CHGAUT OBJ('/QIBM/UserData/ICSS/CERT/SERVER/DEFAULT.KDB')
        USER(SCOTTK) DTAAUT(*R)
 CHGAUT OBJ('/QIBM/UserData/ICSS/CERT/SERVER/DEFAULT.RDB')
        USER(SCOTTK) DTAAUT(*R)

If you wish to give all users access to run SSL programs, then you should change USER(SCOTTK) to USER(*PUBLIC). You can also use an AUTL if you like by specifying AUTL(your-autl) instead of USER(your-user)

NOTE: It's okay to give extra access. For example, if your users currently have *RWX to the IFS root, there's no need to change it to *RX, *RWX will also work. The above authorities are the minimum levels needed.

NOTE: Adopted authority does not work in the IFS. Please grant permissions by the actual userid, not the adopted one.

REQUIREMENTS FOR BUILDING EXPAT FOR XML SUPPORT

NOTE: This describes the process of building the EXPAT service program tha

Httpapi

Install / Use

README