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. 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.
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.

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.

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.

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 provided to VeriSign or another certificate provider. The process will depend on on the certificate provider itself, but involves filling out forms on their site, and generally cutting and pasting the contents of the certificate request file into a field on their site.

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.

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.
Step 3: If you are installing a Verisign certificate, or a certificate from another provider, you must install a new intermediate root into your keylist file. We have provided a copy of Verisign's intermediate certificate here for your convenience (VerisignIntermediateCA.crt). You will need to copy the intermediate certificates to a stream file in the root file system of IFS or in QDLS. You will then need to run the ADDWWWROOT command to add this root to your 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, 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 obtain a free trial certificate from Verisign.

Important: The free trial certificates obtained from Verisign should only be used for test and demonstration purposes and cannot be used for commercial purposes. Verisign 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.

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.