InfoCenter

Using IBM Certificate Management for Host On-Demand server

Server certificates
Creating a key database file
Requesting a server certificate from a well-known CA
Requesting a server certificate from an unknown CA
Creating the public/private keys and certificate request
Sending the certificate request
Receiving and storing the server certificate
Making server certificates available to clients
Creating a self-signed certificate
Stopping and re-starting the Host On-Demand Service Manager

Creating a key database file

Certificate Management allows you to enable Secure Sockets Layer (SSL) communications between hod server and clients.

Before you begin configuring SSL communications, you must create the HODServerKeyDb.kdb key database file. This file is not shipped with hod, so it must be created after the first install.

To create a new key database file:

  1. Start Certificate Management.
  2. Click Key Database File > New.
  3. Select CMS key database file for the key database type.
  4. Type HODServerKeyDb.kdb for the file name.
  5. Type the name of the hod bin directory for the Location. The default is C:\Program Files\IBM\HostOnDemand\bin for Windows 2000 and /usr/opt/hostondemand/bin for AIX.
  6. Click OK.
  7. Enter a new password.
  8. Enter the same password again to verify.
  9. To set expiration date for the password, click Set expire time and specify the number of days until the password expires. To help ensure adequate security, the password should have an expiration date.
  10. Click Stash the password to stash the password of the current database into the HODServerKeyDb.sth file. HOD requires that the password be stashed to access the key file.
  11. Click OK.

Once the HODServerKeyDb.kdb key database file has been created, it holds all security information needed by the HOD server. Any additions or changes are made to the existing HODServerKeyDb.kdb key database file.

To open an existing key database file:

  1. Click Key Database File > Open.
  2. Change to the Host On-Demand bin directory. The default is C:\Program Files\IBM\HostOnDemand\bin for Windows 2000 and /usr/opt/hostondemand/bin for AIX.
  3. Type HODServerKeyDb.kdb as the key database file name and click Open.
  4. Enter the current password and click OK.

After you have created or opened the HODServerKeyDb.kdb file, you can:

Note: Whenever you change the HODServerKeyDb.kdb file, you must stop and re-start the Host On-Demand Service Manager.

Well-known trusted CA

Complete the procedures in this section to set up SSL security using a certificate issued by a well-known CA. The following CA signer certificates are automatically stored in a newly created HODServerKeyDb.kdb key database file and marked as trusted certificates:

When you finish creating and submitting a certificate request that corresponds to one of these types of certificates, you can create a self-signed certificate to use while you are waiting to receive the certificate from the CA. Following is an overview of the steps used to set up SSL security using a well-known CA:


Creating the keys and a certificate request

To create the public/private keys and certificate request:

  1. On the Certificate Management window, choose Personal Certificate Requests from the drop-down list then click New.
  2. Enter the name (label) that is used to identify the key and certificate within the database.
  3. Enter the number corresponding to the key size you want to use. Choosing a larger key size results in stronger security, but requires more processing on the client and the server to establish a connection.
  4. Enter the TCP/IP host name of the Host On-Demand server as the common name, for example, wtr05306.raleigh.ibm.com.
  5. Enter an organization name.
  6. Optionally enter an organization unit.
  7. Optionally enter a city or locality.
  8. Optionally enter a state or province.
  9. Optionally enter a ZIP code.
  10. Choose a country code.
  11. Enter a certificate request file name, or use the default file name.

When you click OK, your information is processed and four files are produced or updated:

File Description
HODServerKeyDb.kdb Key database file
HODServerKeyDb.sth Key database password file
HODServerKeyDb.rdb Key database private key file
certificate_name Default name (certreq.arm) or the name you assigned to the certificate request file. This file is a PKCS 10-type file in armored 64 format.

Do not attempt to edit these files. They should all be backed up at the end of this step. If the HODServerKeyDb.rdb file is not present or is corrupted when you attempt to enter the certificate into the key database file, you will have to resubmit your certificate request to the CA.


Sending the certificate request

Start a Web browser and access the CA's Web page. Follow the instructions provided to submit the certificate request. The following list provides the URLs of some well-known CAs:

Depending on the CA you choose, you can either e-mail the certificate request generated by Certificate Management or incorporate the certificate request into the form or file provided by the CA.

While you are waiting for the CA to process your certificate request, you can enable SSL security for controlled testing purposes only by creating and storing a self-signed certificate using the procedure described in "Creating a Self-Signed Certificate".

Sending the certificate request

Follow the unknown CA's procedures to submit the certificate request.

Depending on the CA you choose, you can either e-mail the certificate request generated by Cerficate Management or incorporate the certificate request into the form or file provided by the CA.

While you are waiting for the CA to process your certificate request, you can enable SSL security for controlled testing purposes only by creating and storing a self-signed certificate using the procedure described in "Creating a Self-Signed Certificate".

Storing the server certificate

When you receive the certificate from the CA, use Certificate Management to put the certificate into the key file, HODServerKeyDb.kdb, located on the server. You should make a backup copy of the certificate issued to your server before starting this step.

  1. Choose Personal Certificates from the drop-down list then click Receive. to receive the key pair and certificate request. The Receive Certificate from a File window appears.
  2. The data type must be BASE64 encoded ASCII data (armored 64 format).
  3. Enter the certificate file name.
  4. Enter the location (path name) of the certificate.
  5. Click OK. The certificate you just stored is displayed as the first item.
  6. Highlight the certificate you just stored and click View/Edit. The Key information window appears.
  7. If not already checked, click Set the certificate as the default to set the selected key as the default.
  8. The certificate name should appear under the Personal Certificate drop-down list and the certificate request should disappear from under the Personal Certificate Requests drop-down list.
  9. Stop and re-start the Host On-Demand Service Manager.

Unknown CA

Complete the procedures in this section to set up SSL security using a certificate issued by a CA that is not already defined in the database. When you finish creating and submitting a certificate request to a CA, you can create a self-signed certificate to use for controlled testing purposes only while you are waiting to receive the certificate from the CA. Following is an overview of the steps used to set up SSL security using a certificate from a CA that is not predefined:


Storing the certificate

When you receive the certificate from the CA, contact the CA to obtain the CA's root certificate. You must store the CA root certificate in the key database file before you store the applied-for certificate. The CA root certificate is used to validate the applied-for certificate. You should make a backup copy of both the CA's root certificate as well as the certificate issued to your server before starting this step.

To store the CA's root certificate:

  1. Choose Signer Certificates from the drop-down list then click Add to receive the CA root certificate.
  2. The data type must be BASE64 encoded ASCII data (armored 64 format).
  3. Enter the certificate file name.
  4. Enter the location, or path, of the certificate.
  5. Click OK. The file is marked as "trusted" and is stored.

To store the applied-for certificate:

  1. Choose Personal Certificates from the drop-down list then click Receive to receive the applied-for certificate.
  2. The data type must be BASE64 encoded ASCII data (armored 64 format).
  3. Enter the certificate file name.
  4. Enter the location, or path, of the certificate.
  5. Click OK. The certificate you just stored is displayed as the first item.
  6. Highlight the certificate you just stored and click View/Edit. The Key information window appears.
  7. If not already checked, click Set the certificate as the default to set the selected key as the default.
  8. The certificate name should appear under the Personal Certificate drop-down list and the certificate request should disappear from under the Personal Certificate Requests drop-down list.
  9. Stop and re-start the Host On-Demand Service Manager.


Creating a self-signed certificate

It can take about two to three weeks to get a certificate from a CA. While waiting for a public server certificate to be issued, you can use Cerficate Management to create a self-signed certificate for controlled testing purposes only to enable SSL sessions between clients and the server.

Use the following procedures to set up your site with a self-signed certificate:

  1. Choose Personal Certificates from the drop-down list.
  2. Click Create > New Self-signed Certificate to create a new self-signed certificate.
  3. Enter the name (label) that is used to identify the key and certificate within the database.
  4. Select X509 V3 as the certificate version.
  5. Enter the number corresponding to the key size you want to use. Choosing a larger key size results in stronger security, but requires more processing on the client and the server to establish a connection.
  6. Enter the TCP/IP host name of the Host On-Demand server as the common name, for example, wtr05306.raleigh.ibm.com.
  7. Enter an organization name.
  8. Optionally enter an organization unit.
  9. Optionally enter a city or locality.
  10. Optionally enter a state or province.
  11. Optionally enter a ZIP code.
  12. Choose a country code.
  13. Enter the number of days the self-signed certificate is to be valid.
  14. Highlight the certificate you just created and click View/Edit. The Key information window appears.
  15. If not already checked, click Set the certificate as the default to set the selected key as the default.
  16. Click OK.
  17. Stop and re-start the Host On-Demand Service Manager.

Making server certificates available to clients

There are three types of Host On-Demand clients: locally installed, downloaded, and cached.

The locally-installed client is installed to the user's local machine from the Host On-Demand product CD. All Host On-Demand code and information is kept on the user's local machine. To run the locally installed client, the user loads a Web page and additional code off the local hard disk and then creates a secure connection to a Host On-Demand redirector or other telnet server. This type of client is considered the most secure because all code and security information is loaded off the local hard disk and not from the Internet. Personal Communications clients act the same as Host On-Demand locally installed clients in this respect.

The downloaded client is not installed to the local machine, but loaded completely from the Host On-Demand server every time the Host On-Demand Web page is accessed. To start the downloaded client, the user loads a Web page and additional code from the Host On-Demand server, and then creates a secure connection to a Host On-Demand redirector or telnet server. This type of client is considered least secure because all code and security information must pass over the Internet and could be corrupted or forged in transit.

The cached client is a cross between the locally installed and the downloaded client. Like the downloaded client, the cached client is initially loaded completely from the Host On-Demand server over the Internet. But, like the locally installed client, some of the code files received in the initial download are stored on the local hard disk and only re-loaded if they are later changed on the server. This type of client is considered more secure than the downloaded client, because after the initial download less code and information is loaded off the Internet. However, it is still not as secure as the locally installed client because the initial download could be corrupted or forged, and some security files must still be loaded off the server each time the cached client is started.

All the certificates in HODServerKeyDb.kdb are available to the Host On-Demand server. However, in some configurations one of these certificates must also be made available to the clients that access the server. If your server uses a site certificate from an unknown CA, the unknown CA's root certificate must be made available to all its clients. If your server uses a self-signed certificate, a copy of the self-signed certificate must be made available to all its Host On-Demand and Personal Communications clients.

For Host On-Demand downloaded and cached clients, this is done by extracting the certificate to a temporary file, then creating or updating a file named CustomizedCAs.p12, and copying the file to the Host On-Demand publish directory. This file must be password protected and given the default password of "hod". Do not change this password.

For Personal Communications and Host On-Demand locally installed clients, the certificate must be extracted to a file, securely transferred to the client, and then added to the key database file of the client machine.

To create CustomizedCAs.p12 file for downloaded and cached clients

  1. Open the HODServerKeyDb.kdb file in the Host On-Demand bin directory of your server.
  2. If your server uses a self-signed certificate:
    1. Display the list of personal certificates.
    2. Highlight the certificate used by your server.
    3. Click Extract Certificate.

    If your server uses a site certificate issued by an unknown CA:

    1. Display the list of Signer Certificates.
    2. Highlight the root certificate of the CA that issued the site certificate for your server.
    3. Click Extract.
  3. On the Extract Certificate to a File window, choose the data type of BASE64 encoded ASCII data. The name can be any you choose.
  4. Click the New selection from the file menu.
  5. Choose a key database type of PKCS12. The file name must be CustomizedCAs.p12. The location should be the publish directory of your server. On Windows NT and Windows 2000, these values should be filled in automatically.
  6. Click OK. You will be prompted to enter a password. You must enter the default password "hod" for creating this file.
  7. If a file named CustomizedCAs.p12 already exists in your publish directory, Certificate Management will ask you if you want to replace the existing file. If your downloaded and cached clients only establish secure sessions with your Host On-Demand server, then you can replace the file. However, if your copy of CustomizedCAs.p12 contains certificates from other servers or certificate authorities, then open that database and add the certificate to it.
  8. To open an existing copy of CustomizedCAs.p12 file, from Certificate Management menu, click open and choose the Key database type PKCS12. For filename and location, enter CustomizedCAs.p12 and the location where this file exists. It will prompt for a password. Enter "hod" as the password and click OK.

To create a certificate file for IBM Personal Communications and Host On-Demand locally installed and other clients:

  1. Open the HODServerKeyDb.kdb file in the Host On-Demand bin directory of your server.
  2. If your server uses a self-signed certificate:
    1. Display the list of personal certificates.
    2. Highlight the certificate used by your server.
    3. Click Extract Certificate.

    If your server uses a site certificate issued by an unknown CA:

    1. Display the list of Signer Certificates.
    2. Highlight the root certificate of the CA that issued the site certificate for your server.
    3. Click Extract.
  3. On the Extract Certificate to a File window, choose either Base64 encoded ASCII data or Binary DER data. Base64 is usually used if the certificate will be securely transferred through e-mail. The certificate file name and location can be any you choose.
  4. Click OK and the certificate file will be created.
  5. Securely transfer the certificate file to the client, and have the client add the certificate to the its key database file.

Stopping and restarting the Host On-Demand Service Manager

On Windows NT:

  1. Open Control Panel, then Services.
  2. Highlight Host On-Demand Service Manager and click Stop.
  3. When the service stops, click Start.

On AIX:

  1. Find the name of the Service Manager process and kill it: At any command line enter: 
        ps -ef | grep NCServiceManager

    Host On-Demand
    The system responds with a line similar to: 

        root 20130 22944   0   Feb 16  pts/1  0:20 java /com/ibm/eNetwork/onDemand/services/admin/NCServiceManager/usr/local/ondemand

    The first number after root is the process id (20130 in the example above). Enter: 

        kill -9 20130
  2. When the Service Manager stops, restart it.