Setting Up Secure Sessions (SSL)

Overview

With the unmodified, default configuration files shipped with Webulator/400, the server only supports HTTP Webulator sessions. That is, by default, the server does not do secured (i.e., SSL) transactions. Below are the steps that need to be accomplished before secured transactions can be performed. Please read through all the instructions presented here before proceeding. This page contains many hyperlinks to other Web sites that may change over time. Hopefully, the appropriate areas can always be found by starting at the site's home page or using the site's search engine.

  1. Install Webulator/400.
  2. Obtain a Server Certificate.
    1. Create a Public Key, Private Key, and a certificate request.
    2. Submit the certificate request to a Certification Authority.
    3. Install certificate received from the Certification Authority.
  3. Change Webulator/400 Configuration Values.
    1. Set the Keylist Database File.
    2. Set the Protocols configuration value to SSL.
    3. Set the Allowed Protocols session based configuration value to SSL for the root session.
  4. Start the server (or re-start a running server).

Obtaining a Server Certificate

This step is the most time consuming step since it requires interacting with a new entity: a Certification Authority (CA). Customer's of Webulator/400 are able to easily obtain server certificates from the Certification Authority VeriSign, Inc. VeriSign, Inc. supplies server certificates (or Digital IDs ™) for a variety of security enhanced products. You will become a customer of VeriSign once you purchase a server certificate from them. VeriSign will also assist you with any special needs you may have concerning your server certificate. Below are sources of additional information about VeriSign and server certificates:

A server certificate/digital ID is required for Webulator/400 to serve secure sessions. The certificate will provide proof to your site's visitors that they are indeed communicating with your company, and it will provide browsers with your company's public key. This public key allows secure communications to be initiated between your server and your visitor's browsers.

VeriSign provides an enrollment process that must be followed to receive a certificate. This allows VeriSign to validate your identity to ensure some other entity is not masquerading as your company. The entire process may take several days to complete and you cannot perform secure (SSL) transactions until everything is finished.

Creating a Public Key, Private Key, and Certificate Request

The first step in obtaining a server certificate is to generate a public/private key pair and a certificate request by running Webulator/400's CRTWBLKEY command. Please check with your certification authority for additional information on the CRTWBLKEY command parameters that are required.

The CRTWBLKEY command will create four new stream files:

  1. Keylist file
  2. Key file
  3. Certificate file
  4. Certificate request file
The keylist file is text file that identifies the key and certificate files.

The key file is an encrypted binary file that contains your public and private keys, which are used by the server to perform encryption and digital signing tasks. This file has the same name as the keylist file, but with an extension of KEY. The key file is encrypted using the password provided on the CRTWBLKEY command.

The certificate file is binary file that contains your certificate once it is added and any trusted roots, including a preloaded set of roots and any others that have been added using the ADDWBLROOT command. This file has the same name as the keylist file, but with an extension if CER. These certificates are used by the server to perform encryption and digital signing tasks.

The certificate request file is an ASCII text file whose contents will be given (e.g., cut-and-pasted) to the Certification Authority to produce your server certificate. Please note that VeriSign calls the certificate request file a certificate signing request (CSR).

Each certificate request will require a new set of keylist files and a certificate request file. The following are reasons additional certificates may be acquired:

For each new certificate, change the CRTWBLKEY (keylist and certificate request) file parameters to use a different directory and/or file name.

IMPORTANT: Make a backup copy of the keylist, key and certificate files after they are successfully created. A backup copy may be needed to replace a deleted or damaged/corrupted keylist file. Also, since the key and certificate files file are binary files, other tools/editors, which may corrupt the keylist file, should not be used to try to view or manipulate the files.

WARNING: The keys are randomly generated and cannot be re-created if the file is lost or if the password is forgotten. If you lose access to the files, you must obtain a new certificate from VeriSign (for an additional fee) by repeating all of these instructions.

Submitting the Certificate Request

VeriSign provides an on-line enrollment process used to request and receive server certificates. To obtain a server certificate/digital ID for Webulator/400 from VeriSign, go to the URL https://www.verisign.com/products/site/index.html. To do this, you will need a browser that is attached to the Internet and capable of performing SSL requests. Click on the link allowing you to purchase Secure Site Services. To obtain your site's certificate please follow VeriSign's directions.

Installing the Certificate

After you receive your certificate from VeriSign through e-mail, you are ready to install the certificate into Webulator/400. This is done by running the AS/400 command ADDWBLCERT.

Step 1
The e-mail message that contains your certificate needs to be saved in a stream file in the root file system of IFS or in QDLS (shared folders). If you have a drive connected to your AS/400 from your e-mail machine, save the message to a file directly on the AS/400. Otherwise, you can use FTP to transfer the file from your e-mail machine into QDLS on your AS/400.

Step 2
Run the ADDWBLCERT command specifying the file created in Step 1 as the Signed Certificate File. For example, if you used FTP to get the file into QDLS on the AS/400 you may use a filename like /qdls/myfolder/cert.txt. Provide the same password and keylist file that was supplied to the CRTWBLKEY command that generated the certificate request file for this certificate.

Step 3
If you are installing a Verisign certificate, please note that their Global Server ID Intermediate Root CA expired on on 1/7/2004. You must install a new intermediate root into your keylist file. To do this save the file found at this link VerisignIntermediateCA.crt, to a sream file in the root file system of IFS or in QDLS. You will then need to run the ADDWBLROOT command to add this root to your keylist file.

IMPORTANT: Make a backup copy of the keylist, key and certificate files after the server certificate is successfully added. If something should happen to the originals (e.g., deleted, damaged) the backups would then be used. Most certification authorities will charge additional money to re-create the server certificate for a new keylist file.

You should now have a valid and usable keylist file. Prior to this, trying to start Webulator/400 in a secure mode using this keylist file would fail. The keylist file needs both the public and private keys and the associated certificate to be valid.

Enabling Webulator/400 to do SSL

The following three configuration values need to be changed in order to enable secure sessions through Webulator/400. After making these changes, all sessions served by Webulator/400 can be accessed with either SSL (encrypted) or HTTP (not encrypted). You have the option of setting up Webulator/400 sessions to require the use of SSL and/or HTTP. You can also start two instances of Webulator/400; one that handles regular HTTP requests and one that handles SSL requests.

Set the Keylist Database File

Using the command CHGWBLSEC, the keylist file path can be set to the newly completed keylist file. By default this would be /Wbl/Key/KeyList.Cfg. The other values can be left to their default values. The keylist file path also needs to be changed when updating the server to use a new certificate (the server must be stopped and restarted after changing this value).

Set the Protocols Value

Using the command CHGWBLSVR, the Protocols configuration value can be changed from HTTP to SSL or it can be set to both HTTP and SSL.

Set the Allowed Protocols Value

Webulator Server/400 uses a Session Based Configuration value: Allowed Protocols. This tells Webulator/400 which protocol (SSL or HTTP) is allowed for a particular session.

Using the CHGWBLSSN command, set the Session Based Configuration file (ACCGBLFILE) to /wbl/cfg/access.cfg. If this value is already set to your own configuration file, you don't need to do this.

Using the WRKWBLSSN command, add the session "/" using option 1 (Add). If this session is already present, you don't need to add it. Select option 14 on the "/" session. Select the appropriate allowed protocols value:

Start the Server

The server should now be ready to start, using the STRWBL command. If the server is already running, you must end the server and re-start it to enable secure transactions. SSL cannot be enabled by reconfiguring the server since a password is now required. You must provide the keylist file password on the STRWBL command now that SSL transactions are being handled.

To access this server from your browser, you need to use the protocol identifier https instead of http. For instance, to open a new URL from your browser enter https://www.yourhost.com/.

Testing the Server

The following information can help test whether sessions are being served securely (encrypted and authenticated) by Webulator/400.

Accessing a page secured with SSL
From your browser, enter a URL for a SSL enabled session into the Open Document or Open URL entry box. For example, 

     https://www.your.host.com/SslSessionName

The protocol to use is https for SSL enabled sessions. Substitute your host name for the www.your.host.com portion of the URL and your SSL enabled session name for SslSessionName.

When accessing pages from a server running a certificate from an untrusted Certification Authority (such as test certificates), the browser will usually put up a dialog box indicating that the server's certificate could not be verified. Some browser's will let you continue after answering some questions. Netscape browsers, for instance, will normally display a series of dialog boxes explaining that the server's certificate could not be validated. These dialog boxes are not present if the server certificate is obtained from a Certification Authority that the browser trusts (such as VeriSign, Inc.).

How do I know my pages are secured?
All SSL-enabled browsers provide a visual clue that the current page is protected using SSL. The clue is usually a picture of a key or a lock near the bottom of the browser's window. Also, most browsers have a menu option that allows you to view information about the server's certificate. When frames are used, the visual clue that indicates the "page" is protected using SSL will only occur when all of the frames are retrieved using SSL.

Browser Support
Only browsers that are enabled with SSL 2.0 or 3.0 support can be used to do secured transactions with Webulator/400. Known, popular browsers that work with Webulator/400:

Test and Evaluation Server Certificates

If you are not running with secure Webulator sessions yet and want to try out SSL without purchasing a validated certificate from VeriSign, or if you would like to start evaluating the software while you wait for your official server certificate, you can obtain a test and evaluation server certificate from VeriSign.