Secure Sockets Layer (SSL) in Caching Proxy

Secure Sockets Layer (SSL) is a system that automatically encrypts information before sending it over the Internet and decrypts it at the other end before it is used. This system protects sensitive information like credit card numbers while it is transmitted over the Internet.

Caching Proxy uses SSL to secure surrogate servers and to provide secure remote administration, as described in the following sections. SSL can also be used to protect connections to back end servers (for example, content or application servers) as well as to protect communications between the proxy server and its clients.

For forward proxy, Caching Proxy supports SSL tunneling, which bypasses SSL and forwards the already-encrypted data without altering it.

The SSL handshake

SSL protection is initiated when a secure connection request is sent from one machine to another. For example, when a browser sends a request to a surrogate proxy server. The request syntax https:// instead of http:// tells the browser to send the request on port 443, which is where the server listens for secure connection requests (instead of port 80 for routine requests). To establish a secure session between the browser and the server, the two machines perform an exchange that is called an SSL handshake to agree on a cipher specification and to select a key that is used to encrypt and decrypt information. Keys are automatically generated, and they expire when the session expires.

A typical scenario with SSL Version 3 is as follows:
  1. Client hello

    The client initiates an SSL session with Caching Proxy by sending a Client Hello message that describes the client's encryption capabilities.

  2. Server hello

    The server sends its certificate to the client and chooses the cipher suite to use for data encryption.

  3. Client finish

    The client sends cipher key information that is used to create symmetric encryption keys for the encrypted data. This key material is known as the premaster secret and it is encrypted with the server's public key (obtained from the server's certificate; see (Key and certificate management). Both the server and the client can derive the read and write symmetric encryption keys from the premaster secret.

  4. Server finish

    The server sends a final confirmation and a Message Authentication Code (MAC) for the entire handshake protocol.

  5. Client validation

    The client sends a message to validate the server finish message.

  6. Secure data flow

    If the client validates the server finish message, then encrypted data flow begins.

Using a Caching Proxy as an endpoint for secure connections can reduce the load on your content or application servers. When a Caching Proxy maintains a secure connection, it performs encryption, decryption, and key creation, which are all CPU-intensive operations. Caching Proxy also allows you to configure SSL session timeouts to maximize the use of each key.

Limitations of SSL

The following limitations apply to SSL in WebSphere® Application Server Caching Proxy:
  • The Caching Proxy itself cannot be used as a certificate authority (see Key and certificate management).
  • Some browsers might not support all of the encryption technology that is used in Caching Proxy.
  • SUSE Linux® supports SSL tunneling only (not SSL; see (SSL tunneling).

SSL performance tuning

During high HTTPS traffic volumes, the Caching Proxy server might cause high CPU usage. Tuning changes to an environment variable (GSK_V3_SIDCACHE_SIZE) and a proxy directive (SSLV3Timeout) can help the proxy server handle the load and reduce the CPU usage.

The SSL session ID identifies reusable SSL sessions, including encryption or decryption keys that are used by both browsers and servers, and is used to avoid unnecessary SSL handshakes on new connections, which consume much the server's CPU time. The GSKit library for the Caching Proxy server supports SSL session ID and includes an SSL session ID cache. By default, the SSL session ID cache contains 512 entries. When the entry limit is reached, the oldest session entry is removed and the new entry is added into the cache.

Use the GSK_V3_SIDCACHE_SIZE environment variable to change the default size of the SSL session ID cache. A valid value of the variable is 1 - 4096. Increasing the size increases the look-up time that is required to locate a cached SSL session. However, the increased lookup time is insignificant compared to the overhead required to establish an SSL connection. Increasing the cache size helps the proxy server handle more concurrent SSL sessions and reduce the CPU usage when the proxy server is under high HTTPS loads.

Caching Proxy also has a tunable directive SSLV3Timeout. (See SSLV3Timeout -- Specify the time to wait before a SSLV3 session expires.) The default value of the directive is 1000 seconds. This directive defines the lifetime of an SSL session in the session cache. If no incoming SSL connection uses an existing SSL session and the session lifetime exceeds the value, that session is removed from the session cache. It is recommended to set the SSLV3Timeout value to the length of a typical secured client session. If the timeout is set too short, it can slow the performance of the proxy because multiple SSL handshake sessions are needed to complete a single secured session. However, if the value is set too long, it can also hurt the security of a secured session.

Configuring SSL for a surrogate server

When Caching Proxy is used as a surrogate, requests between clients and the proxy, or requests between content servers and the proxy, or both, can be made secure by using Secure Sockets Layer. To enable SSL, you must first create a key database and create or obtain a certificate.

The Application Server distribution includes a GSKit utility to manage keys and certificates. For more information, see Key and certificate management.

After your key database and certificate are established, to configure SSL for your surrogate proxy server, in the Configuration and Administration forms, select Proxy Configuration –> SSL Settings. On the SSL Settings form, check the Enable SSL box and type the path names of your key ring database file and password file in the fields provided. Optionally, you can specify a timeout value for SSL sessions. (If your server spends too much time re-creating keys, you might want to increase the timeout value in the Timeout for SSL V3 Sessions field.)

You can also specify whether or not the server attempts to cache the content of secure requests. Although caching can improve performance, the caching of sensitive material can impose a security risk. You can use caching filters to control the type of files that are cached from secure requests by creating filters for URLs that use https:// (To specify caching filters, in the Configuration and Administration forms, select Cache Configuration –> Caching filters.) The SSL caching settings for your proxy server affect all connections terminated at that proxy server, whether they are made with client machines or with content server machines.

SSL support for multiple domains

Previously, it was not possible to have a single Caching Proxy server acting as a surrogate proxy for multiple domains that offered individual SSL certificates. This limitation no longer applies. Caching Proxy, acting as a surrogate proxy for multiple domains, can now determine the correct certificate to hand out based on the domain to which the request is sent. This new feature is configured by using the SSLCertificate directive in the ibmproxy.conf file. See SSLCertificate -- Specify key labels for certificates for details.

Use of IP ranges in protection masks

This new function uses the MASK subdirective of the Protection setup to enable the use of IP ranges in protection masks. Administrators can now more easily configure Caching Proxy to authenticate requests from specified IP addresses and not authenticate requests from others, avoiding the need to create very large protection rule files that might adversely impact proxy performance. For example, specify the following to authenticate all requests from 9.38.(100–192)/202/203.(0–255) and to pass all other requests. 
MASK  ALL@"9.38.[100-192,202,203].[0-255]", @"9.38.[0-99],193-201,204-255].
[0-255]",@"[0-8,20-255].[0-37,39-255].[0-255].[0-255]"
In this example, note that brackets ([]) enclose ranging; quotation marks (" ") enclose the ranging IP template, and spaces are not allowed in the ranging IP template. Note that the MASK subdirective must not contain line breaks. For further details, see Mask -- Specify the user names, groups, and addresses allowed to make HTTP requests in the directives reference chapter.
Note: Wildcard values cannot be used simultaneously with ranging; for example, 9.*.[32,33].154 is not allowed.

Disabling listener threads when SSL is enabled

This new function permits Caching Proxy administrators to disable listener threads for standard HTTP requests (typically on ports 80 or 8080) when SSL is enabled (typically on port 443). Running active HTTP listener threads can possibly create an insecure site on a server that performs secure transactions. The ability to disable these listener threads enhances server security. Use the SSLOnly directive to disable listener threads for standard HTTP requests when SSL is enabled.

After configuring SSL, you must stop the server completely and then start it again before the changes take effect, because SSL settings are not changed by a simple restart operation.

To configure SSL by directly editing the proxy configuration file, see the reference sections for these directives:

Client-side certificate authentication

This function permits Caching Proxy to retrieve a client-side public key infrastructure (PKI) certificate through an SSL session. This certificate is then used to authenticate the client. Requiring clients to present a PKI certificate increases server security by guaranteeing the authentication of the client. Use the SSLCertificate directive to specify whether the proxy server retrieves a client-side PKI certificate.

SSL tunneling

When Caching Proxy is configured as a forward proxy, it uses SSL tunneling to support secure connections between clients and content servers. In SSL tunneling, encrypted data is passed through the proxy server unaltered. Because the proxy server does not unencrypt the data, functions that require the proxy server to read requests or document headers are not supported in SSL tunneling. Also, tunneled requests are not cached.

This applies to forward proxy configurations only.

Figure 1 shows how a connection is established by using SSL tunneling.
Figure 1. SSL tunneling
SSL tunneling
The SSL tunneling process is as follows:
  1. The client makes a tunneling request: CONNECT server-host-name:port HTTP/1.1 (or HTTP/1.0). The port number is optional and is usually 443. The client's browser will automatically send the CONNECT request to the proxy server first for every HTTPS request if the forward proxy is configured in the browser.
  2. The proxy accepts the connection on its port 80, receives the request, and connects to the destination server on the port that is requested by the client.
  3. The proxy replies to the client that a connection is established.
  4. The proxy relays SSL handshake messages in both directions: From client to destination server, and from destination server to client.
  5. After the secure handshake is completed, the proxy sends and receives encrypted data to be decrypted at the client or at the destination server.
  6. If the client or the destination server requests a closure on either port, the proxy server closes both connections (ports 443 and 80) and resumes its normal activity.

Configuring SSL tunneling

In a forward proxy setting, only SSL tunneling is available. To enable SSL tunneling, in the Configuration and Administration forms, select Proxy Configuration –> Proxy Settings. Select the SSL Tunneling check box.

The CONNECT method (which by default is disabled) must also be enabled for SSL tunneling connections. To enable it in the configuration forms, select Server Configuration –> Request Processing and use the HTTP Methods form.

Three options (OutgoingPorts, OutgoingIPs, IncomingIPs) are provided for the Enable CONNECT directive for enhanced SSL tunneling security. It is required that you specify a value for at least OutgoingPorts, otherwise the CONNECT method will not be enabled.
  • OutgoingPorts (to limit access for SSL tunneling by remote server's ports). The format is, 
    Enable CONNECT OutgoingPorts [all | [port1|port1-port2|port1-*],...]
    To allow clients to connect only to the remote servers' port 443 for SSL tunneling, set the following directives. (Normally port 443 is for HTTPS requests on the remote server.) 
    Enable CONNECT OutgoingPorts 443 
SSLTunneling on
    To allow clients to connect to any port on the remote servers for SSL tunneling, set the following directives: 
    Enable CONNECT OutgoingPorts all 
SSLTunneling on
    To allow clients to connect to ports 80, 8080-8088, and 9000 and higher ports on the remote servers for SSL tunneling, set the following directives: 
    Enable CONNECT OutgoingPorts 80,8080-8088,9000-* 
SSLTunneling on

    Ports and port ranges are separated by a comma without any space in the list.

    IMPORTANT: For forward proxy configurations, at least specify 443 or all with OutgoingPorts option to enable normal SSL tunneling.

  • OutgoingIPs (to limit access for SSL tunneling by remote server's IP address). The format is, 
    Enable CONNECT OutgoingIPs [[!]IP_pattern,...]
    For example, to allow clients to connect to any port on the remote servers that matches the IP/host name *.ibm.com and must not match 192.168.*.* , set the following directives: 
    Enable CONNECT OutgoingPorts all OutgoingIPs *.ibm.com,!192.168.*.*
SSLTunneling on
    Note: IP_patterns are separated by a comma without any space in the list.
  • IncomingIPs (to limit access for SSL tunneling by client's IP address). The format is, 
    Enable CONNECT IncomingIPs [[!]IP_Pattern,...]
    For example, to allow clients coming from IP address 192.168.*.* to make a connection to any port on the remote servers for SSL tunneling, set the following directives: 
    Enable CONNECT OutgoingPorts all IncomingIPs 192.168.*.* 
SSLTunneling on
    Note:
    1. Assuming 192.168.*.* is the internal LAN IP mask. The preceding option allows only internal users to use the connect method and SSL tunneling function.
    2. IP_patterns are separated by a comma without any space in the list.

Configuring secure remote administration

Remote administration of your Caching Proxy can be achieved by using the security features provided by Secure Sockets Layer (SSL) and password authentication. This significantly reduces the probability of access to the proxy server by unauthorized persons.

To apply SSL during remote administration of your server, use an https:// request instead of an http:// request to open the Configuration and Administration forms. For example: 
https://
                  your.server.name
               /
                  yourFrontPage.html

Key and certificate management

Before you configure SSL you must set up a key database, and obtain or create a certificate. Certificates are used to authenticate server identities. Use the IBM Key Management utility (sometimes called iKeyman) to set up your certification files. This utility is part of the Java Development Kit (JDK). iKeyman also includes a Java based graphical interface for opening certificate files.

The following basic steps set up your SSL keys and certificates:
  1. Ensure that you have IBM JDK Version 1.6 or later.
  2. Use the key manager to create a key for secure network communications and receive a certificate from a certificate authority. You might decide to create a self-signed certificate while waiting to receive the certificate from the authority.
  3. Create a key database and specify a key database password.
Note: The key and keystash files are uninstalled whenever Caching Proxy is uninstalled. To avoid having to request a new certificate from a certificate authority, save backup copies of these two files in another directory before uninstalling the proxy software.

On all operating systems except for Linux, if the certificate has expired, Caching Proxy will not start properly, and an error message displays indicating the key database has expired. On Linux, the proxy appears to start but the process quickly disappears and no error message gets generated.

To prevent this problem on Red Hat Enterprise Linux 3.0 systems, ensure that the GCC packages are at the following levels or higher:
  • libstdc++-3.2.3-52
  • libgcc-3.2.3-52

Certificate authorities

Your public key must be associated with a digitally signed certificate from a certificate authority (CA) that is designated as a trusted root CA on your server. You can buy a signed certificate by submitting a certificate request to a certificate authority (CA) provider.

Caching Proxy supports the following external CAs:
  • VeriSign
  • Thawte
By default, the following are designated as trusted CAs:
  • Verisign Class 1 Individual Subscriber CA - Persona Not Validated
  • Verisign Class 2 Individual Subscriber CA - Persona Not Validated
  • Verisign Class 3 Individual Subscriber CA - Persona Not Validated
  • VeriSign Class 3 International Server CA
  • VeriSign Class 2 OnSite Individual CA
  • VeriSign Class 1 Public Primary CA
  • VeriSign Class 2 Public Primary CA
  • VeriSign Class 3 Public Primary CA
  • VeriSign Class 1 Public Primary CA - G2
  • VeriSign Class 2 Public Primary CA - G2
  • RSA Secure Server CA (from VeriSign)
  • Thawte Personal Basic CA
  • Thawte Personal Freemail CA
  • Thawte Personal Premium CA
  • Thawte Premium Server CA
  • Thawte Server CA

Using the IBM Key Manager utility

This section provides a quick reference for using the IBM Key Manager utility (iKeyman). Use the key manager to create your SSL key database file, public-private key pair, and certificate request. After you receive the CA-signed certificate, use the key manager to place the certificate in the key database where you created the original certificate request.

More detailed documentation on the IBM Key Manager and GSKit is packaged with the GSKit software.

Set up your system to run the key manager

Before starting the iKeyman GUI, do the following:
  1. Install IBM JDK version 1.6 or higher. You can use the Java package that is shipped with the Load Balancer product.
  2. Set JAVA_HOME to the Java directory location. For example:
    • For Windows platforms: 
      set JAVA_HOME=C:\Program Files\IBM\edge\lb\java
    • For AIX®, HP-UX, Linux, and Solaris platforms: 
       export JAVA_HOME=/opt/ibm/edge/lb/java/
  3. Register the IBM JCE, IBM CMS, and IBMJCEFIPS service providers.

    Update the JAVA_HOME/jre/lib/security/java.security file to add both the IBM CMS and IBM JCE providers at the positions that are shown in the following example:

    security.provider.1=com.ibm.jsse2.IBMJSSEProvider2
    security.provider.2=com.ibm.security.cmskeystore.CMSProvider
    security.provider.3=com.ibm.crypto.provider.IBMJCE
    security.provider.4=com.ibm.security.jgss.IBMJGSSProvider
    security.provider.5=com.ibm.security.cert.IBMCertPath

  4. To enable FIPS operation, update the JAVA_HOME/jre/lib/security/java.security file to also add IBMJCEFIPS. Make sure to register IBMJCEFIPS provider at a higher priority than IBMJCE. For example:
    security.provider.1=com.ibm.jsse2.IBMJSSEProvider2
    security.provider.2=com.ibm.security.cmskeystore.CMSProvider
    security.provider.3=com.ibm.crypto.fips.provider.IBMJCEFIPS
    security.provider.4=com.ibm.crypto.provider.IBMJCE
  5. Optional: If you are using crypto hardware, register IBMPKCS11Impl service provider. For example:
    security.provider.1=com.ibm.jsse2.IBMJSSEProvider2
    security.provider.2=com.ibm.security.cmskeystore.CMSProvider
    security.provider.3=com.ibm.crypto.fips.provider.IBMJCEFIPS
    security.provider.4=com.ibm.crypto.provider.IBMJCE
    security.provider.5=com.ibm.crypto.pkcs11Impl.provider.IBMPKCS11Impl
    security.provider.6=com.ibm.security.jgss.IBMJGSSProvider
    security.provider.7=com.ibm.security.cert.IBMCertPath

Starting the key manager

Start the key manager graphical user interface by running the iKeyman tool from JDK. For example, use the following command:

/opt/ibm/edge/lb/java/jre/bin/ikeyman

Creating a new key pair and certificate request

The key database stores key pairs and certificate requests. To create a public-private key pair and certificate request, follow these steps:
  1. If you have not created the key database, follow the instructions in Creating a new key database, password, and stash file.
  2. In the key management utility, from the main menu, click Key Database –> File –> Open.
  3. In the Open dialog box, type your key database name (or click key.kdb if you are using the default). Click OK.
  4. In the Password Prompt dialog box, type your password and click OK.
  5. From the main menu, click Create –> New Certificate Request.
  6. In the New Key and Certificate Request dialog box, specify the following:
    • Key Label: Type a name (label) that is used to identify the key and certificate in the database: for example, my self-signed certificate or www.companyA.com.
    • Keysize: Size of the key, for example, 1024. (In order to take advantage of 128-bit encryption, a Key size of 1024 is recommended.)
    • Organization Name: Name of the organization to associate with the key, for example, Company A.
    • Organization Unit (Optional)
    • Locality (Optional)
    • State/Province (Optional)
    • Zipcode (Optional)
    • Country: Your country code. You must specify at least 2 characters, for example, US.
    • Certificate request file name: A name for the request file. Optionally, a default name can be used.
  7. Click OK. A confirmation message is displayed: 
    A new certificate request has been successfully created 
in the file 
                        keyfile_database_name
                     .
  8. Click OK. Expect the label name that you entered to be displayed under the Personal Certificate Requests heading.
  9. In the Information dialog box, click OK. You are reminded to send the file to a certificate authority.
  10. Unless you created a self-signed certificate, send the certificate request to a CA:
    • Leave the key manager running.
    • Start a web browser and enter the URL of the CA from which you want to obtain the certificate.
    • Follow the instructions that are provided by the CA to send your certificate request.
    Certificate requests can take two to three weeks to be fulfilled. While you are waiting for the CA to process your certificate request, you can act as your own CA and use iKeyman to create a self-signed server certificate to enable SSL sessions between clients and your Caching Proxy server.

Creating a self-signed certificate

Use the key management utility to create a self-signed server certificate to enable SSL sessions between clients and your proxy server while waiting for a certificate to be issued. You also can use self-signed certificates for testing purposes.

Follow this procedure to create a self-signed certificate:
  1. If you have not created the key database, follow the instructions in Creating a new key database, password, and stash file.
  2. In the key management utility, from the main menu, click Key Database –> File –> Open.
  3. In the Open dialog box, type your key database name (or accept the default, key.kdb). Click OK.
  4. In the Password Prompt dialog box, type your password and click OK.
  5. In the Key Database content frame, select Personal Certificates and click Create New Self-Signed Certificate.
  6. In the Create New Self-Signed Certificate window, specify the following:
    • Key Label: A name (label) that is used to identify the key and certificate in the database: for example, my self-signed certificate
    • Key Size: Size of the key, for example, 512.
    • Common Name: The full host name of the server, for example, www.myserver.com
    • Organization Name: Name of the organization to associate with the key, for example Company A
    • Organization Unit (Optional)
    • Locality (Optional)
    • State/Province (Optional)
    • Zipcode (Optional)
    • Country: Your country code. You must specify at least two characters, for example, US.
    • Validity Period: The period of time that the certificate is valid.
  7. Click OK.
  8. Register the key database with the server by adding the key file and stash file to the configuration settings (see Creating a new key database, password, and stash file).

Exporting keys

Use this procedure to export keys to another key database:
  1. Start the key management utility.
  2. From the main menu, click Key Database File –> Open.
  3. In the Open dialog box, type your key database name (or accept the default, key.kdb). Click OK.
  4. In the Password Prompt dialog box, type your password and click OK.
  5. In the Key Database content frame, select Personal Certificates, then click the Export/Import button on the label.
  6. In the Export/Import Key window:
    • Select Export Key.
    • Select the target database type (for example, PKCS12).
    • Type the file name or click Browse to select it.
    • Type the correct location.
  7. Click OK.
  8. In the Password Prompt dialog box, type the correct password, type the password again to confirm, then click OK to export the selected key to another key database.

Importing keys

To import keys from another key database:
  1. Start the key management utility.
  2. From the main menu, select Key Database File –> Open.
  3. In the Open dialog box, type your key database name (or accept the default, key.kdb). Click OK.
  4. In the Password Prompt dialog box, type your correct password and click OK.
  5. In the Key Database content frame, select Personal Certificates, then click the Export/Import button on the label.
  6. In the Export/Import Key window:
    • Select Import Key.
    • Select the key database file type (for example, PKCS12).
    • Type the file name or click Browse to select it.
    • Select the correct location.
  7. Click OK.
  8. In the Password Prompt dialog box, type the correct password and click OK.
  9. In the Select from Key Label list, select the correct label name and click OK.

Listing certificate authorities

To display a list of trusted certificate authorities (CAs) in a key database:
  1. Start the key management utility.
  2. From the main menu, click Key Database File –> Open.
  3. In the Open dialog box, type your key database name (or accept the default, key.kdb). Click OK.
  4. In the Password Prompt dialog box, type your correct password and click OK.
  5. In the Key Database content frame, select Signer Certificates.
  6. Click Signer Certificates, Personal Certificates, or Certificate Requests to view the list of CAs in the Key Information window.

Use this procedure to receive a certificate that is electronically mailed to you from a certificate authority (CA) that is designated as a trusted CA by default (see the list in Certificate authorities). If the CA that issues your CA-signed certificate is not a trusted CA in the key database, you must first store the CA's certificate and designate the CA as a trusted CA. Then, you can receive your CA-signed certificate into the database. You cannot receive a CA-signed certificate from a CA that is not a trusted CA (see Storing a CA certificate).

To receive a CA-signed certificate into a key database:
  1. Start the key management utility.
  2. From the main menu, select Key Database File –> Open.
  3. In the Open dialog box, type your key database name (or accept the default, key.kdb). Click OK.
  4. In the Password Prompt dialog box, type your password and click OK.
  5. Ensure that the file name in the DB-Type listing is correct.
  6. In the Key Database window, select Personal Certificates, then click Receive.
  7. In the Receive Certificate from a File dialog box, type the name of a valid base 64-encoded file in the Certificate filename text field. Click OK.
  8. To close the key manager utility, from the main menu, click Key Database File –> Exit.

Displaying the default key in a key database

Display the default key entry as follows:
  1. Start the key management utility.
  2. From the main menu, click Key Database File –> Open.
  3. In the Open dialog box, type your key database name (or accept the default, key.kdb). Click OK.
  4. In the Password Prompt dialog box, type your password and click OK.
  5. In the Key Database content frame, select Personal Certificates and select the CA certificate label name.
  6. In the Key Information window, click View/Edit to display the certificate default key information.

Creating a new key database, password, and stash file

A key database is a file that the server uses to store one or more key pairs and certificates. You can use one key database for all your key pairs and certificates, or create multiple databases. The key management utility is used to create new key databases and specify their passwords and stash files.

To create a key database and stash file:
  1. Start the key management utility.
  2. From the main menu, select Key Database File –> New.
  3. In the New dialog box, make sure that the file type CMS Key Database is selected. Type your key database name and file location or accept the default, key.kdb. Click OK.
  4. In the Password Prompt dialog box, type and confirm the password for this database. Click OK.
  5. Select the check box to stash the password file. When prompted, type and confirm a password for verification. The following message is displayed: DB-Type: CMS key database file keyfile_database_name
    Note: If you do not stash the password file, the server starts but does not listen on port 443.

The password that you specify when you create a new key database protects the private key. The private key is the only key that can sign documents or decrypt messages encrypted with the public key.

Use the following guidelines when specifying the password:
  • The password must be composed from the US English character set.
  • The password must be at least 6 characters in length and contain at least two nonconsecutive numbers. Make sure that the password does not consist of publicly obtainable information about you, such as your name or your immediate family's names, initials, or birth dates.
  • Stash the password.

It is a good practice to change the key database password frequently. However, if you specify an expiration date for the password, keep a record of when to change it. If the password expires before you change it, a message is written to the error log and the server starts, but it cannot make secure network connections.

Follow these steps to change the key database password:
  1. From the main menu, click Key Database File –> Open.
  2. In the Open dialog box, type your key database name or accept the default, key.kdb. Click OK.
  3. In the Password Prompt dialog box, type your established password and click OK.
  4. From the main menu, click Key Database File –> Change Password.
  5. In the Change Password dialog box, type and confirm a new password. Click OK.

For an SSL connection between a proxy and an LDAP server, put the key database password in the pac_keyring.pwd file. (The pac_keyring.pwd file is not the stash file that is generated by iKeyman.)

Receiving a CA certificate

Use this procedure to receive a certificate that is electronically mailed to you from a certificate authority (CA) that is designated as a trusted CA by default in the list of certificate authorities. If the CA that issues your CA-signed certificate is not a trusted CA in the key database, you must first store the CA's certificate and designate the CA as a trusted CA. Then you can receive your CA-signed certificate into the database.

You cannot receive a CA-signed certificate from a CA that is not a trusted CA. See Storing a CA certificate.

To receive a CA-signed certificate into a key database:

  1. Start the key management utility.
  2. From the main menu, select Key Database File > Open.
  3. In the Open dialog box, type your key database name (or accept the default, key.kdb). Click OK.
  4. In the Password Prompt dialog box, type your password and click OK.
  5. Ensure that the file name in the DB-Type listing is correct.
  6. In the Key Database window, select Personal Certificates, then click Receive.
  7. In the Receive Certificate from a File dialog box, type the name of a valid base 64-encoded file in the Certificate filename text field. Click OK.
  8. To close the key manager utility, from the main menu, click Key Database File > Exit.

Storing a CA certificate

Only certificates that are signed by trusted CAs are accepted for establishing secure connections. To add a CA to the list of trusted authorities, you must obtain and store its certificate as trusted.

Follow this procedure to store a certificate from a new CA, before receiving it into the database:
  1. Start the key management utility.
  2. From the main menu, click Key Database File > Open.
  3. In the Open dialog box, type your key database name (or accept the default, key.kdb). Click OK.
  4. In the Password Prompt dialog box, type your password and click OK.
  5. In the Key Database content frame, select Signer Certificates, then click Add.
  6. In the Add CA's Certificate from a File dialog box, select the base 64-encoded ASCII data certificate file name, or use the Browse option. Click OK.
  7. In the Label dialog box, type a label name and click OK.
  8. Use the check box to designate the certificate as trusted (default).
    Note: View the check box after the certificate is created by using the "View/Edit" button. The check box is listed on the panel but it is not displayed during the adding of the certificate.

Supported cipher specifications

The encryption algorithms and hashes that are used for SSL versions 2 and 3 are listed in the following tables.

Key Pair Generation: RSA 512–1024 private key sizes

Table 1. SSL Version 2. US and export versions for SSL version 2.
US version Export version
RC4 US RC4 Export
RC2 US RC2 Export
DES 56-bit not applicable
Triple DES US not applicable
RC4 Export not applicable
RC2 Export not applicable
Table 2. SSL Version 3. US and export versions for SSL version 3.
US version Export version
Triple DES SHA US DES SHA Export
DES SHA Export RC2 MD5 Export
RC2 MD5 Export RC4 MD5 Export
RC4 SHA US NULL SHA
RC4 MD5 US NULL MD5
RC4 MD5 Export NULL NULL
RC4 SHA 56-bit not applicable
DES CBC SHA not applicable
NULL SHA not applicable
NULL MD5 not applicable
NULL NULL not applicable

These SSL specifications can also be configured by directly editing the proxy configuration file. For details, see the reference sections in Configuration file directives.

128-bit encryption for Caching Proxy

Only a 128-bit encryption version of Caching Proxy is being delivered. The 56-bit version is no longer available. If you are updating a previous version, you can install Caching Proxy directly to your currently installed 128-bit or 56-bit version. If you were previously using a 56-bit (export) browser, you must upgrade to a 128-bit browser to take advantage of the 128-bit encryption in the proxy.

After an upgrade from a 56-bit version of Caching Proxy to the 128-bit version, if the key size used to encrypt certificates is set to 1024, then no configuration change is necessary. However, if the key size is set to 512, in order to take advantage of the proxy's 128-bit encryption, you must create new certificates with a key size of 1024. Create new keys by using the IBM Key Manager utility (iKeyman).
  1. Start the key manager. For example, use the following command:
    /opt/ibm/edge/lb/java/jre/bin/ikeyman
  2. From the main menu, click Key Database File –> Open.
  3. In the Open dialog box, type your key database name (or click key.kdb if you are using the default) and click OK.
  4. If the Password Prompt dialog box opens, type your password and click OK.
  5. From the main menu, click Create –> New Certificate Request.
  6. In the New Key and Certificate Request window, specify the following:
    • Key Label: Type a name that is used to identify the key and certificate in the database.
    • Keysize: Select 1024.
    • Organization Name: type the name of the organization to be associated with the key.
    • Country: Type your country code. You must specify at least two characters, for example, US.
    • Certificate request file name: Type a name for the request file, or optionally, use a default name.
  7. Click OK.

This version of the product does not support encryption on SUSE Linux.