/======================\

| CwbCoSSL Version 5.2 |

| for |
>>>>>>>>>>>>>>>>>>>>>>>| Windows 95/98/NT/2K/ME |<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
| iSeries Access |
| V5R2 |
\======================/

NOTE: USE AT YOUR OWN RISK!

Table of Contents
=================

- Introduction
- Files included
- Setup
- Questions asked during CA download
- Button/Field Descriptions
- Common SSL problems
- Support for this tool

Introduction:
=============

This tool automates the downloading of an iSeries Certificate Authority (CA) to

the PC and Java key databases for iSeries Access Secure Sockets Layer
(SSL) support. It also automates the process up storing a CA from a binary file.
Please see the iSeries Access for Windows Setup Guide
and the iSeries iSeries Access for Windows Redbook (SG24-5191) for
more detailed SSL setup information.

The shipped default iSeries Access key databases contain CA's from
well-known signers (Verisign, Thawte, ...). If your iSeries Access host
servers have system certificates assigned the them from a well-known CA, there
is NO need to run this tool, the default key database already trusts
certificates issued by well-known CA's.

This tool is normally used when the iSeries Access host servers are
assigned system certificates signed/created by an iSeries Certificate Authority.

NOTE: In iSeries Access V5R1, the download of iSeries

Certificate Authorities can now be done via Operations Navigator system
properties - Secure Sockets tab.

Files included:
===============

cwbcossl.exe the executable

cwbcossl.txt this file

Setup:
======

To use CwbCoSSL:
 1. Install iSeries Access and at the latest iSeries Access
service pack (V4 or V5 iSeries Access supported)

2. Install the optional SSL component of iSeries Access

This is done using iSeries Access Selective Setup to an
iSeries with (V4) 5769CE1, 5769CE2 or 5769CE3 installed or (V5)
5722CE2 or 5722CE3

3. Optionally install the iSeries Java Toolbox component if developing Java

applications or using Operations Navigator Java plug-ins.
This is done using iSeries Access Selective Setup to an
iSeries with 5769JC1 installed

4. Have a valid user ID/password for the iSeries's you want to download from

5. Launch CwbCoSSL.exe, click the Start CA Download button, and answer the
simple questions asked

Questions asked during CA download

==================================

- Are you sure you want to trust all certificate issued by this iSeries CA?

This means that once the iSeries CA certificate is placed in the iSeries Access
key databases, ALL iSeries Access host servers on any iSeries
with system certificates signed/created by this iSeries's CA, will be trusted
and SSL connections to these trusted host servers will be possible.

At any point in the future, you can use the IBM Key Management utility to mark
this iSeries CA as NOT trusted or delete it from the database. Then any
connections to iSeries Access host servers with system certificates
signed/created by this iSeries's CA will NOT be possible.

- Enter your SSL key database password:

iSeries Access ships a default key database called CWBSSLDF.KDB in the

iSeries Access installation directory. The default password to this key
database in "ca400" (case-sensitive ). If you have not changed the default
Secure Socket properties, use click OK.

Using IBM Key Management, you can create your own key database and a unique
file name and password.

Use the iSeries Access properties Secure Sockets tab to change the key
database name and location. Both the key database (.KDB) and key database
stash (.STH) files must be located in the same directory.

NOTE: If you create your own key database, iSeries Access requires that
use must create a password stash file. This can be done by checking the
"Stash the password to a file?" option when creating the key database or
changing its password. This can also be done after the key database is created
by selecting the File->Stash Password menu option after opening your key
database.

Button/Field Descriptions:
==========================
NOTE: Many of the buttons have an advanced action if you hold down the Control
or Shift keys while pressing the button.

Start CA Download
-----------------

This button makes use of the non-SSL side of some iSeries Access host
servers (Signon, RmtCmd, ByteStream, and possibly Server Mapper). The other
iSeries host servers (HTTP, Telnet, ...) are not used during the download.
The system list is managed by Operations Navigator.

The Start CA Download button will perform the following steps:

- Make sure the optional SSL component of iSeries Access is installed

- Connect to the selected iSeries (this will require valid user ID/password)
- Make sure Digital Certificate Manager is installed on the iSeries
- Download the Certificate Authority in binary format
- Open the currently configured PC key database for iSeries Access
- Prompt for the PC key database password
- Store the CA in the PC key database
- Close the PC key database
- If iSeries Java ToolBox is installed, add the CA to the Java key database
( by default it's stored in the
classes\com\ibm\as400\access\KeyRing.Class file)

Use the "Just place in a pc file" check box to just have the iSeries CA
stored as a PC file in the iSeries Access service trace files directory.
This file can then be directly used with the IBM Key Management
utility as well as browsers (double click on file from Windows Explorer to
start the Microsoft Certificate Manager Import Wizard which will place the CA
into MS Internet Explorer's key database).

Store CA from file...

---------------------

The Store CA from file button will allow you to put your own CA
file into the iSeries Access key databases. Type in the text label to
use before pressing the button. The CA file must be in binary format.

iSeries DCM
----------

This button will launch iSeries Digital Certificate Manager (DCM) in your
default browser. You will need a valid user ID/password for that AS400 system
to use this program. Check with the DCM help for the special authorities
required to perform certain DCM tasks.

The iSeries DCM program requires that the iSeries HTTP Administration server is
running. You can check to see if it's running by clicking on the Verify button
while pressing the Control key. If it's not running, hold down the Control and
click the iSeries DCM button again to that the STRTCPSVR *HTTP command issued to
the iSeries to try to start this server.

NOTE: Hold down the Control key to have the STRTCPSVR *HTTP command
issued to try to start the iSeries HTTP Admin server.
PC Key Mgt.
-----------

The PC Key Management button will launch the PC IBM Key Management program.
The default iSeries Access key database file is CWBSSLDf.KDB located in
the iSeries Access installation directory. The default password is
"ca400" (lowercase). Check with the iSeries Access properties button and
select the Secure Sockets tab to see if the default database name and location
has been changed. Use the IBM Key Management help for more usage information.
For V5, the default pc key database will be automatically opened for you.

Java Key Mgt.

-------------

The Java Key Mgt. button will load the current Java key database into the
IBM Key Management program. The default/only Java key database is KeyRing.Class.

NOTE: Hold down the Control key to have the contents dumped via the KeyringDB
tool.

NOTE: Hold down the Control and Shift keys to just have the Java key database
log file displayed.

NOTE: (V5) Hold down the Control key to have the Java key database loaded
into the IBM Key Mgt. program.

Operations Navigator
--------------------

The Operations Navigator button will launch the Operations Navigator program.

NOTE: Hold down the Control key to have the STRHOSTSVR *ALL command
issued to try to restart the iSeries Access host servers after making
changes in iSeries DCM.

iSeries Access Properties

--------------------------------

The Client Access Properties button will launch the Secure Sockets properties
page for iSeries Access.

Telnet Client Authentication

----------------------------

The Telnet client authentication button will issue the cmd need to
enable (CALL PGM(QSYS/QTVSRV) PARM(*SSLCERT)) or
disable (CALL PGM(QSYS/QTVSRV) PARM(*NOSSLCERT)) client authentication for the
iSeries telnet server. After the command is issued, you will be asked to restart
the telnet server to have this change take effect.

NOTE: Hold down the Control key to have just the Telnet SSL port verified.
Verify
------

The Verify buttons will perform SSL and non-SSL connection attempts to the
specified iSeries. This is the same as using the CWBPING command or the Verify
button in Operations Navigator.

NOTE: Hold down the Control key to have ALL the possible iSeries Access
host servers verified, not just the default verify set.

Trace
-----

The trace check-box will enable the CwbCoSSL, CwbCoTrc, and IBM Key Management
traces. The resulting trace files will be stored in the iSeries Access
service trace files directory. The file produced are as follows:

- cwbco.trc is a trace from the communications core of iSeries Access.

- cwbcossl.log is a record of activity for the CwbCoSSL tool.

NOTE: Trace will always be turned off when exiting the CwbCoSSL program.

About
-----

Clicking on the CwbCoSSL icon will display the CwbCoSSL About dialog. Clicking
on the CwbCoSSL About dialog CwbCoSSL icon will display the standard iSeries
Access about dialog.

Help
----

The help button will display this text file.

NOTE: Hold down the Control key to have the iSeries Access Online Users
Guide launched.

Common SSL Problems:

===================

Telnet - For the iSeries telnet server to pick up changes made in DCM, it must
be stopped and restarted. This will end all telnet sessions to that iSeries, so
be careful! This was fixed with a PTF, so to avoid this problem, instal the
latest PTF CUM package.

iSeries Access Host Servers - The host servers, if already started, will
automatically pick up changes made in DCM, no restart is necessary. If they are
not started, hold down the Control key and press the Operations Navigator
button to have them started, or use the iSeries command STRHOSTSVR *ALL.

iSeries DCM - If when you click the iSeries DCM button your browser is launched,
but no page appears, this probably means that the HTTP Admin host server is not
started on the iSeries. Hold down the Control key while pressing the DCM button
to try to have the HTTP Admin host server started.
Support:
=======

This tool is provided on an as-is basis. Extensive testing has NOT been
performed. If you believe there to be a bug in the tool, or have ideas for
improvement, you may send feedback via http://www.as400.ibm.com/clientaccess

NOTE: USE AT YOUR OWN RISK!