How to connect to SSL-POP3 servers
 

This document describes what is to be done in order to enable an IBM i box to become client of SSL-POP3 servers.
(also check out this page describing all the steps taken by an IBM i user who succeded in connecting to a MS Exchange POP3 via SSL.)

 
1. Prerequisites
  1. To create the needed DCM (Digital Certificate Manager) environment on your IBM i:
    1. Product 5761DG1 option *BASE (IBM HTTP Server for i5/OS)
    2. Product 5761SS1 option 34 (Digital Certificate Manager, DCM)
  2. To test SSL-POP3 client connections (optional):
    1. Product 5761SS1 option 30 (Qshell)
    2. Product 5733SC1 option 1 (OpenSSH, OpenSSL, zlib)
 
2. Creating the needed DCM (Digital Certificate Manager) environment on your IBM i

The following describes how to create the *SYSTEM "Certificate Store" needed to connect to as a client any SSL-POP3 server.

  1. On your IBM i start the HTTP instance *ADMIN
  2. Connect your WEB browser to your IBM i IP address on port 2001 and login with a class *SECOFR user profile to enter "IBM WEB Administration for i"
  3. Select Digital Certificate Manager
  4. Press the link Create New Certificate Store
  5. Select the radio button *SYSTEM and press the Continue button
  6. Select the radio button NO - Do not create a certificate in the certificate store and press the Continue button
  7. Enter a certificate store password of your choice, confirm it and press the Continue button.
    The following screen appears:
  8. In the left frame press the button Select a Certificate Store
  9. Select the radio button *SYSTEM and press the Continue button
  10. Type your password and press the Continue button.
    The following screen appears:
  11. In the left frame expand the item Manage Certificates, then press the link Validate certificate.
  12. Select the radio button Certificate Authority (CA) and press the Continue button. The following screen appears:
  13. Press the Validate button. You will receive a confirmation screen and you are then done.
 
2. Some tips
  1. How to provide *PUBLIC access to the "*SYSTEM Certificate Store"
    DCM generated objects are not allowed to be accessed from *PUBLIC user profiles (the allowed user profiles are QSYS and *SECOFR class user profiles).
    That may generate some difficulties when trying to use SSL from a user profile (example: QTMHHTTP) not allowed to access those objects.
    In such cases, one may receive an error message with error code 107 and message text "Access to the key database is not allowed" .
    This is why, when you are finished with DCM, you have better to run the following commands:
    • CHGAUT OBJ('/QIBM') USER(*PUBLIC) DTAAUT(*RX)
    • CHGAUT OBJ('/QIBM/UserData') USER(*PUBLIC) DTAAUT(*RX)
    • CHGAUT OBJ('/QIBM/UserData/ICSS') USER(*PUBLIC) DTAAUT(*RX)
    • CHGAUT OBJ('/QIBM/UserData/ICSS/Cert') USER(*PUBLIC) DTAAUT(*RX)
    • CHGAUT OBJ('/QIBM/UserData/ICSS/Cert/Server') USER(*PUBLIC) DTAAUT(*RX)
    • CHGAUT OBJ('/QIBM/UserData/ICSS/Cert/Server/*') USER(*PUBLIC) DTAAUT(*RX)
  2. GSKit APIs
    Usually, IBM i programs activating some SSL connection do that by using the so called GSKit APIs, see this IBM i Infocenter page.
    The meaning of error codes from GSKit API's can also be found in a QSYSINC source file (run command STRSEU SRCFILE(QSYSINC/H) SRCMBR(GSKSSL)).
  3. Error message "The validity time period of the certificate has expired" (error code 107).
    If you are running a program that uses the GSKit APIs (example: program POP3READ/POP3RSSL) and you receive the above error message, in spite of any temptative re-definitions through DCM, you should be aware that the error may be generated from connecting by mistake to the wrong server.
 
3. Manually testing connections to SSL-POP3 servers
In order to test the ability of your IBM i to connect to a SSL-POP3 server (like GMail) you must:
  • have installed the required prerequisites (HPP Server, Digital Certificate Manager (DCM), QSHELL and OpenSSH/OpenSSL feature)
  • generated through DCM a "*SYSTEM certificate store", see page How to connect to SSL-POP3 servers.
You must then know the DNS name (or the IP address) of the SSL-POP3 server that you want to connect to. See the following example, illustrating the case where you would like to connect to the GMail SSL-POP3 servicing your GMail account (user name kibel@gmail.com, password 123sesami) that Goggle serves to you in Italian language.
  • If your IBM i is located in Italy, then the GMail SSL-POP3 server DNS name is pop.gmail.com.
    If your IBM i is located in another country, then the GMail SSL-POP3 server DNS name is pop.gmail.it (you must connect to the Italian language GMail SSL-POP3 server).
    We shall assume that its name is pop.gmail.com.
  • Logon on in Telnet on your IBM i and enter command QSH to start the QShell Command Entry.
  • Then you may have the following dialog: 
      $                                                                 
> openssl s_client -connect pop.gmail.com:995 -quiet                
  depth=2 /C=US/O=GeoTrust Inc./CN=GeoTrust Global CA               
  verify error:num=20:unable to get local issuer certificate        
  verify return:0                                                   
  +OK Gpop ready for requests from 80.16.163.20 z54pf31027476eeu.19 
> USER kibel@gmail.com                                          
  +OK send PASS                                                     
> PASS 123sesami                                                     
  +OK Welcome.                                                      
  read:errno=0                                                      
  $
    If your username and password are correct, but they are not accepted, that is because you are connecting to the wrong SSL-POP3 server.