| Product: | DBConnectivity Products for IBM Db2 for i (Ritmo/i, HiT JDBC/400) |
| Version: | All |
| ID: | 1667 |
| Summary: | How to install and run SafeConduct on IBM i/AS400 for use with DBConnectivity products |
NOTE: SafeConduct will be deprecated in 2025, end of support dated to April 2025.
SafeConduct secures application data access using the Secure Sockets Layer/Transport layer Security (SSL/TLS) v3.0 standard, including digital certificate authentication and 256-bit data encryption.
To install SafeConduct on the IBM i, you first need to obtain the package via the download request form. You can then extract the files, configure the server and copy the relevant files to the IBM i. For additional detail on the setup process, please refer to the SafeConduct User’s Guide included in the downloaded files.
In a Microsoft Windows Environment:
- Unbundle the downloaded zip file using a tool such as WinZip, pkunzip or jar. We recommend that you create a separate directory to unzip the file in. For example:
c:\ jar xvf safeconduct-s-130.zip
OR
c:\ pkunzip -d safeconduct-s-130.zip
NOTE: If you are using a tool that doesn't preserve path names by default, be sure to specify the option that preserves path names. For example, specify -d for pkunzip.
- Extract the SafeConduct files using a tool such as WinZip, pkunzip or jar. This creates a SafeConduct Server directory containing the following:
|
server |
Contains the files needed to run the server as well as a sample properties file and sample fingerprint files. |
|
ssltoolbox |
Contains ssltoolbox.jar which contains the class files for HiT SSL Toolbox utilities. |
- Obtain the License Key
A license key is required to run SafeConduct Server application. You should receive a license key for SafeConduct via email. If not, send an email to HiT Software at info@hitsw.com or call (408) 345 4001. The license key is included in a jar file called hitlicense.jar and attached to the email. Place the hitlicense.jar file in the same directory as the scserver.jar because these two jar files should be in the classpath when the server application is running.
- Configure the connection settings for SafeConduct. This step requires connection information as used in your IBM i environment.
SafeConduct’s connection settings are stored as properties in a text file. The connection settings are stored like arrays of properties where a set of properties with the same index represents the settings for a connection to a server. For example:
listener[0]=23000, “telnetsrv”, 23, “SSL”
server_cert[0]=srvcert.der,srvkey.der
ca_cert[0]=cacert.der
cipher_suite[0]=3DES
listener[3]=1446, “sys2”, 446, “”
Two properties files are included with the SafeConduct Server:
- safeconduct.properties is the default properties file used when running the server. It contains a mapping that includes fingerprints matching those provided in the default properties files for the SafeConduct clients: client.propertiesfor the Java client and WinClient.properties for the Windows client.
- samples.properties contains information on how to use the properties file as well as sample connections for both encrypted data and plain data. You can edit this file then specify it as a parameter when you run the SafeConductserver.
- (Optional) Create a shell script to run SafeConduct from QShell in the IBM i environment. For example, a start_scsrv.sh file can contain the following information to start the server. Make sure the Java CLASSPATH variable includes scserver.jar, hitlicense.jar, and hitsecurity_unix.jar (or hitsecurity_win.jar depending on your operating system). For example:
SET CLASSPATH=.;/apps/j2sdk1.4.1_01;/apps/SafeConductServer/server/ scserver.jar; /apps/SafeConductServer/server/hitlicense.jar; /apps/SafeConductServer/server/hitsecurity_win.jar com.hitsw.safeconduct.Server mysrv.properties
In the IBM I Environment:
SafeConduct is a Java tool and must be run from a Java command. JRE or JDK 1.5 or higher is recommended to run the application. IBM i (AS/400) provides two options for running Java programs:
- A unix-like shell named QSHELL http://publib.boulder.ibm.com/infocenter/iseries/v5r4/index.jsp?topic=%2Frzahz%2Fcommands.htm
This option is appropriate for testing. - The JAVA CL command. This option is appropriate for production environments.
Using QSHELL
- From an IBM i command prompt, type STRQSH to start QSHELL.
- Check to see that Java is installed by typing: java –version
- To install SafeConduct, create a new folder on the IBM i using the mkdir command:
mkdir hitsc - To load the SafeConduct files from the PC to the IBM i, use ftp from a Windows command prompt on your PC.
On the PC, first change directory to the directory where you have set up the .jar files, the .properties file and the .sh file. - Connect to the IBM i system:
ftp ibm-ip-address - Enter the user name and password.
- Set the file type to binary:
quote type I - Type:
quote site namefmt 1 - Change directory to the directory you created for the SafeConduct files:
cd /hitsc - Transfer the files from the PC using the put (single file) or mput (multiple files) command. Be sure to load all the files in the SafeConduct Server directory, including the properties file and the shell script.
- Close the ftp session.
- On the IBM i system, run SafeConduct Server either using the shell script you created above or directly from the QShell command line:
java com.hitsw.safeconduct.Server [-options] [property-file]
property-file is a pathname and/or filename and can be used to tell the SafeConduct Server to use the specified file as the configuration file. By default, the SafeConduct Server uses the file safeconduct.properties.
For example:
java com.hitsw.safeconduct.Server mysrv.properties
java com.hitsw.safeconduct.Server /apps/SafeConductServer/myfiles/mysrv.properties
Options are:
-help java com.hitsw.safeconduct.Server -help
Prints out the options listed here.
-stat java com.hitsw.safeconduct.Server -more –stat
Includes statistics in output.
-admin:port=<port-number> Specifies the admin port number (see SafeConduct User’s Guide for more information)
-version Prints out the build version.
-more java com.hitsw.safeconduct.Server -more –stat
Outputs more information (useful in case there are connection issues.)
-timeout:[seconds] Sets the connection timeout value specified. The default connection timeout value is 45 seconds.
-inactive:[minutes] Sets an inactive limit after which the connection is closed. The default value is 480 minutes.
Useful QSHELL commands:
- ls –la (directory listing)
- cd (change directory)
- rm (remove file/directory)
- cat (display file content)
Using CL
In production, it is recommended to start the server using CL, so the server becomes a job. Here is a sample CL script.
Columns . . . : 1 71 Editing CONSUMITAP/QCLSRC
SEU==> QSTRUPSSL
FMT ** ...+... 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7
013.00 PGM
014.00
015.00 /* STARTING REMOTE SECURITY */
016.00 CHGJOB PURGE(*NO)
017.00 MONMSG MSGID(CPF0000)
018.00 OVRPRTF FILE(QPRINT) PAGESIZE(*N 300) MAXRCDS(*NOMAX)
019.00 MONMSG MSGID(CPF0000)
020.00 ADDENVVAR ENVVAR(CLASSPATH) +
021.00 VALUE('.:/hitsc/scserver.jar:+
022.00 /hitsc/hitsecurity_unix.jar:/h+
023.00 itsc/hitlicense.jar')
024.00 MONMSG MSGID(CPF0000)
025.00 CD DIR('/hitsc)
026.00 MONMSG MSGID(CPF0000)
027.00 JAVA CLASS('com.hitsw.safeconduct.Server') +
028.00 PARM('-admin:port=9000' '-inactive:1' 'safeconduct.properties')
029.00 MONMSG MSGID(CPF0000) Note: Make sure the Java CLASSPATH includes these three jar files: scserver.jar hitsecurity_unix.jar hitlicense.jar
To add the option -stat, modify the CL using the example below.
027.00 JAVA CLASS('com.hitsw.safeconduct.Server') +
028.00 PARM('-admin:port=9000' '-stat' 'safeconduct.properties')
For more information on setting up and using SafeConduct, check the SafeConduct User’s Guide in the SafeConduct installation directory.