Setting Up Commerce Server/400

NOTE:
The discussion contained here is only applicable to owners of Commerce Server/400. Web Server/400 owners cannot perform secured transactions.

Overview

With the unmodified, default configuration files shipped with Commerce Server/400, the server runs the same as Web Server/400. That is, by default, the server does not do secured 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.

Install Commerce Server/400.
Obtain a Server Certificate.
1. Enroll with the Certification Authority
2. Create a Public Key, Private Key, and a certificate request.
3. Submit the certificate request to a Certification Authority.
4. Install certificate received from the Certification Authority.
Change Commerce Server/400 Configuration Values.
1. Set the Keylist Database File.
2. Set the Protocols configuration value to SSL.
3. Set the Allowed Protocols directory based configuration value to SSL for the root directory.
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 Commerce Server/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:

Introduction to Cryptography
Frequently Asked Questions (Digital IDs)
Frequently Asked Questions (Server Digital IDs)
General Cryptography FAQ from RSA Data Security, Inc.
VeriSign's Price Schedule
Additional instructions for international (non-US/Canadian) customers or Japanese customers

Server certificates are required for Commerce Server/400 to serve secure documents. 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.

VeriSign Enrollment

VeriSign provides an on-line enrollment process. To obtain a server certificate for Commerce Server/400 from VeriSign, go to the URL http://www.verisign.com/inet. To do this, you will need a browser that is attached to the Internet and capable of performing SSL requests. The above page will provide introductory information about the enrollment process. After reading this information, select the Begin button.

The Enrollment Form will be displayed. Carefully read and follow the instructions provided on this page. You will be asked to supply information on your distinguished name, your company, payment information, and contacts. Submit this form using the Continue button. The server will return an error page if anything was missing or not entered correctly. If you receive errors, follow the instructions to fix them.

VeriSign Authorization Letter

Continuing with the VeriSign enrollment process, the VeriSign Secure Server Authorization Letter page should be displayed on your browser. You must fill in this form and acknowledge its contents before proceeding.

Creating a Public Key, Private Key, and Certificate Request

The next stage in the enrollment process is to generate a certificate request. Here are some specific instructions for generating a server certificate for Commerce Server/400, in addition to the instructions listed on the Generate a Request page.

The keylist database file and certificate request file are created by running the command CRTWWWKEY. Please follow the instructions for CRTWWWKEY when running this command. CRTWWWKEY will produce a keylist database file and a certificate request file. The certificate request file will be given to the Certification Authority to produce your server certificate. By default, this file is put in the document root of the Web server. This makes it easy to cut and paste the contents into an HTML form or an e-mail message (see below).

The keylist database file contains your public and private keys. These are used by the server to perform encryption and digital signing tasks. The keylist database file is encrypted using the password you provide.

IMPORTANT: Make a backup copy of the keylist file after it is successfully created. The backup will be needed if there is a problem adding the correct signed server certificate to the keylist file. 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 this file, you must obtain a new certificate from VeriSign (for an additional fee) by repeating all of these instructions.

IMPORTANT: The distinguished name entered into the CRTWWWKEY command must be exactly the same as the distinguished name entered in the VeriSign Enrollment Form. If possible, copy and paste this information from the VeriSign Authorization Letter into the command. You can use your browser's Back button to see the letter again. If this information is different in any way, the request will be rejected by VeriSign.

Submitting the Certificate Request

Once the CRTWWWKEY command has successfully completed, a certificate request stream file will exist. The contents of this stream need to be e-mailed to VeriSign. The instructions below go through one way of e-mailing this information to VeriSign. These instructions assume that you have Internet e-mail capabilities and Web browsing capabilities on the same machine.

Step 1

From your browser, load the certificate request file generated using the CRTWWWKEY command. If you are using the defaults, you can load the URL: http://www.yourhost.com/certrqs.txt into your browser. Copy the entire page into your clipboard. Note: Your Web server needs to be running to access this file.

Alternatively, you can load the certificate request file into a text editor and copy the contents into your clipboard from the text editor. If you have a drive assigned to the root file system of IFS and you are using the defaults for CRTWWWKEY and for the Web server, you can open the file /wwwserv/webdocs/certrqs.txt. If you only have shared folders access, have the CRTWWWKEY command write the certificate request file to a document in shared folders then load that document into a text editor.

Step 2

Create a new Internet e-mail message addressed to inet-request-id@verisign.com

Step 3

Paste the certificate request generated by CRTWWWKEY into the body of the e-mail message.

Step 4

Send the message.

Installing the Certificate

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

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 ADDWWWCERT 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 CRTWWWKEY command that generated the certificate request file for this certificate. Usually a PKCS10 formatted certificate is returned.

IMPORTANT: Make a backup copy of the keylist file after the server certificate is successfully added. If something should happen to the original (e.g., deleted, damaged) the backup 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 database file. Prior to this, trying to start Commerce Server/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 Commerce Server/400 to do SSL

The following three configuration values need to be changed in order to enable secure transactions through Commerce Server/400. After making these changes, all pages served by Commerce Server/400 will be encrypted. You may want to set up Commerce Server/400 to serve some content encrypted and some content unencrypted. You can also start two instances of Commerce Server/400; one that handles regular HTTP requests and one that handles SSL requests.

Set the Keylist Database File

Using the command CHGWWWSEC, the keylist database file can be set to the newly completed keylist file. By default this would be /WWWServ/Key/KeyList.Cfg. The other values can be left to their default values.

Set the Protocols Value

Using the command CHGWWWCFG, the Protocols configuration value can be changed from HTTP to SSL.

Set the Allowed Protocols Value

Commerce Server/400 has a new Directory Based Configuration value: Allowed Protocols. This tells Commerce Server/400 which protocol (SSL or HTTP) should be used to serve documents out of a directory and its subdirectories. This value should be set to SSL in the root directory so all documents served off of your AS/400 are served using SSL.

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

Using the WRKWWWDIR command, add the directory "/" using option 1 (Add). If this directory is already present, you don't need to add it. Select option 14 (Change Commerce Server/400) on the "/" directory. Select SSL as the Allowed Protocols and make sure HTTP is not selected.

Start the Server

The server should now be ready to start, using the STRWWW 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 Database File password on the STRWWW 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 documents are being served securely (encrypted and authenticated) by Commerce Server/400.

Accessing a page secured with SSL

From your browser, enter the following URL into the Open Document or Open URL entry box. This will bring down the Web site's home page securely.

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

The protocol to use is https for SSL pages. Substitute your host name for the www.your.host.com portion of the URL.

When accessing pages from a server running a certificate from an untrusted Certification Authority (such as Northern Telecom's Entrust Demo Web Certification Authority), 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 version 2.0, for instance, will 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.

Browser Support

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

Netscape Navigator version 1.1N, 2.x, or 3.0
Microsoft Internet Explorer 2.0 or 3.0
OS/2 Secure Web Explorer 1.0 or later.

Test and Evaluation Server Certificates

If you are not running a production Web site yet and want to try out Commerce Server/400 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 follow these instructions to obtain a test and evaluation server certificate.

Northern Telecom provides free test and evaulation certificates for anyone that agrees to their terms. These are available from Northern Telecom's Web site through their service entitled Entrust Demo Web Certification Authority.

Note: The Entrust Demo Web Certification Authority service is provided and supported by Northern Telecom. This service is currently available and works with Commerce Server/400. However, I/NET makes no claims that this service will always be available or appropriate for Commerce Server/400 customers. It is up to Northern Telecom to continue this service.

Important: The certificate obtained from Northern Telecom should only be used for test and demonstration purposes and cannot be used for commercial purposes. Northern Telecom does not verify the identity or credentials of the certificate requester before issuing the certificate. This service is only meant to provide a quick, easy, and inexpensive way of obtaining demo server certificates. Please read the acknowledgement page on Northern Telecom's site and remember to include their disclaimer page on your Web site.

Note: If any of the www.nortel.com hyperlinks in this document are no longer valid, they can be found off of the page http://www.nortel.com/entrust.

Creating a Public Key, Private Key, and Certificate Request

Follow the instructions given above for creating a public and private key and certificate request for VeriSign.

Submitting the Certificate Request

Once the CRTWWWKEY command has successfully completed, you can submit your request for a test server certificate to Northern Telecom's Entrust Demo Web Certification Authority Web site.

Step 1: From your browser, load the certificate request file generated using the CRTWWWKEY command. If you are using the defaults, you can load the URL: http://www.yourhost.com/certrqs.txt into your browser. Copy the entire page into your clipboard. Note: Your Web server needs to be running to access this file.
Step 2: Load Northern Telecom's Entrust Demo Web CA page into your browser: http://www.nortel.com/entprods/entrust/certificates/servcert.html. You need to have Internet access from your browser to do this.
Step 3: Select the "Proceed with a request" link. Read their acknowledgement page carefully. If you agree, select the "Acknowledged" link.
Step 4: Fill in the entry fields on the form. Be sure to supply an accurate Internet e-mail address since this is how you will receive your certificate.
Step 5: Paste your certificate request obtained in Step 1 into the Encoded Certificate Request entry field on the form.
Step 6: If everything looks right, select the "Submit Request" button.

Your certificate will be automatically sent to you by e-mail. This usually takes just a few minutes. If you submit the request on a weekend or holiday, the certificate may not arrive until the next business day.

Installing the Certificate

Follow the instructions given above for installing a certificate received from VeriSign.

When you receive your real server certificate, simply change the keylist database file you are using for your server (using the CHGWWWSEC command) to the new keylist database file and re-start the server.