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) With a valid Server Certificate on the server : 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 (installed with Client Access) from a command line
  • The 'IBM i Access Certificate Downloader' GUI opens.
  • 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'). If successfull, the next step is to extract the X.509 formatted certificate from cwbssldf.kdb:
  • Click the PC Key Management button :

• • Here in IBM Key Management a new cwbssldf.kdb can be created with Ctrl-N (if the original is missing). Then, after creating a new key file use the previous 'IBM i Access Certificate Downloader' GUI to download the certificate before moving on.)
  • Select "Open" (Ctrl-F) : A dialog opens.
  • If IBM Key Management was started with the CwbCOSSL command then the right certificate file (cwbssldf.kdb) within the correct folder will already be suggested:

• • 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 the highlighted certificate as .arm into a text file on the PCs (this is X.509 formatted, too).

(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 or create one of type JKS with Keystore Explorer and import the previously saved X.509 server certificate files.
• Place the resulting keystore file into the SIT config folder
• Make it known in Help/Settings/Connection. File location and encrypted password will be stored in the SIT config subfolder.
  • Exchanging the license file requires the certificate stores password to be entered and saved again.
• Shredder the X.509 text files - the data inside is sensitive information.

License file, keystore file and sslProperties.xml can be distributed as a whole.

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.