Certificate Handling on IBM i

No special SSL setup is needed for Telnet and FTP functions with SIT. For all other SSL/TLS connections a keystore file with server certificate(s) is needed.

(1) For creating a server certificate on an IBM i system these steps are suggested;

• Start the HTTP Admin-server: STRTCPSVR SERVER(*HTTP) HTTPSVR(*ADMIN)
• Open a browser, connect and sign on: http://<server>:2001/QIBM/ICSS/Cert/Admin/qycucm1.ndm/main0
• If the connection fails see /QIBM/UserData/HTTPA/admin /logs/HTTPAdmin.log
• Choose the Certificate Location - for example *SYSTEM
• Choose the Status of Certification Authority - for example the LOCAL_CERTIFICATE_AUTHORITY_(<serial number>)
• Export certificate (to other systems)
• Create a "Server - or Client Certificate" (or work with an existing one)
• Add Applications/Protocolls like NETPRT or JDBC or all of them to a given Server or Client Certificate
• Set Certificate as standard (Manage Certificates)
• End the Admin HTTP server instance if not needed: ENDTCPSVR SERVER(*HTTP) HTTPSVR(*ADMIN)

or

• Follow the Digital Certificate Manager's steps to import an existing server certificate from a different system.

(2) Download the X.509 (i.e. plain text) formatted certificate to the PC

• Either access the HTTP admin server
  • There open the Digital Certificate Manager
  • Click on "Install Certificate of local certification instance on PC" and select "Copy certificate".
  • This will bring up the plain text X.509 type formatted server certificate.
  • Copy & paste the complete text into a text file file. The file name could be something like <server>.cer and is of type plain text.

• or start the System i Navigator
  • Right click the system, go into Properties/Secure Sockets and download the server certificate. A Sign On is required to the system. The default password for cwbssldf.kdb is 'ca400'.
  • If the certificate download fails, check that cwbssldf.kdb exists. If not, go to the next solution and create one. Then try again.

• or run the CwbCOSSL command (a certificate downloader installed with Client Access) from a command line
  • The 'IBM i Access Certificate Downloader' GUI opens.
  • Click the PC Key Management button 

• • The PC Key Management GUI opens.
  • If Key Management was started from CwbCOSSL the standard file location (C:\Users\Public\Documents\IBM\Client Access\cwbssldf.kdb) will already be suggested:

• • Verify that the cwbssldf file exists. If missing, use this IBM Key Management tool to create one (Ctrl-N).
  • Go back to the downloader.
  • Click the 'Start CA download from... with the IBM i in question. Obviously a user account on the server is required and the password to cwbssldf.kdb (default password 'ca400').
  • Then extract the certificate from cwbssldf.kdb 
    • Select "Open" (Ctrl-F) : A dialog opens.
    • Click OK, enter the password, press OK again.
    • With the drop down button select the option for "Signer Certificates". A list of certificates already stored in cwbssldf.kdb will show up.
    • Click the certificate previously downloaded. It will usually bear the servers name.
    • Export (or Extract) the highlighted certificate as .arm file to the PC (this will by default be created in the same Client Access folder).

(3) The X.509 type .crt or .arm plain text data files need to be inserted into a keystore file. Standard utilities are keytool.exe or -preferably - the Keystore Explorer freeware.

• Open an existing keystore file (i.e. the ssl.ts delivered with SIT inside the config folder)  or create a new one of type JKS with Keystore Explorer
• Import (Ctrl-T) the previously saved .arm files. Press the Save-Button.

(4)  Place the resulting keystore file into the SIT config folder if not already there)

• Make it known in Help/Settings/Connection. Enter file location and password. This will be stored as sslProperties.xml in the SIT config subfolder.
  • When exchanging the file or updating SIT to a new version the ssl.ts password has to be entered and saved again.
• Delete the previously created .arm file in  the Client Access folder - the data inside is sensitive information.

License file, keystore file and sslProperties.xml can be distributed as a whole to other work places.

Keystore Explorer Handling

Freeware tool "Keystore Explorer" needs the Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy to work.

• Download Keystore Explorer and install.
• If the Java Cryptography Extension has not been installed yet or if the Java version has changed since last use:
  • Start the Keystore Explorer in Admin mode.
  • D&D the downloaded the JCE file into Keystore Explorer; if neccessary also install the JCE into other Java environments.

Create a key store with Keystore Explorer:

1. Create a new key store file:
   • -File
   • --New (Type JKS)
2. Set a password:
   • -Tools
   • -- Set Password
3. Import your X.509 certificate(s) (or d&d)
   • -Tools
   • -- Import Trusted Certificat
   • --- Choose cer or arm file
4. Save & Exit

Keytool.exe - command line utility

Keytool.exe comes with every Java Runtime Environment(JRE)  and is also contained in the Client Access folder.

Open a Command Window.


C:\>dir c:\x509certs
 ...
02.05.2016  11:31               768 sysgroup1.crt


C:\>type c:\certs\sys1.cer

C:\>cd C:\Program Files\Java\jdk1.8.0_121\bin


C:...> keytool.exe -import -alias ASGROUP1 -file C:\x509certs\sys1.cer -keystore C:\keystores\ssl.ts

                    (and keystore was created)



The same keystore can contain more than one certificate:

C:...>keytool.exe -import -alias ASGROUP2 -file C:\x509certs\sys2.cer -keystore C:\keystores\ssl.ts

Any weird behaviour (like displaying the help function) usually means that there are invalid signs (for example blanks) in the pathnames of the file- or keystore parameter.