Sun WebServer 2.1 Installation Guide

Chapter 3 SSL Configuration

SSL Requirements Overview

This section explains each of the major components required at your site to use Secure Sockets Layer (SSL) with web sites. This is intended to give you an overview of what you must have in place and how the components interact. A list of the procedures to follow to configure SSL is in the "SSL Configuration Procedures".

Before a web site can use SSL, it must have public and private keys for encryption and a PKCS#7 certificate which it can present to clients. The certificate contains the web site's identity (distinguished name), the identity of the issuer, the web site's public key, and the digital signature of the issuer. Public web sites typically get certificates signed by a third-party certificate authority (CA) such as VeriSign; if a client also has the public key of the third-party CA, it can trust that the site's identity has been verified and is authentic.

Note -

"Credentials" in this document refers to a key package -- public and private -- and an associated certificate.

Sun^TM WebServer^TM includes software for running a CA. The CA can create SSL credentials for web sites. Other tools allow you to install the web site's credentials for use by Sun WebServer, to get credentials signed by a third-party, and to install third-party certificates.

The following must be completed at your site to run SSL:

Install Sun WebServer with SSL.
Create a root certificate authority (Root CA).
Use a unique IP address for web sites that use SSL.
Create the server credentials.
(Recommended) Request signed certificates from an independent CA.

Root Certificate Authority (Root CA)

You need to create a Root CA at your site to create credentials for web sites. A Root CA user will create credentials for itself, and then use the credentials to create key packages and sign certificates for web servers in your network. You may store the credentials in the Federated Naming Service (FNS) for easy accessibility from other machines, or you can store them only in files on the Root CA machine to limit access. By default, they are stored in /var/fn.

The Root CA host (where credentials are created) does not need to be the same machine as Sun WebServer, and for security reasons you may want to run the Root CA on a different machine or a machine with no network access at all.

Root CA User

You can use any user name except for root (UID 0) on the Root CA host to be the Root CA user. The Root CA user is the only user that can create credentials for web sites. The Root CA user will have its own, password-protected credentials, which are used to sign all of the certificates it creates.

The Root CA credentials are bound to a distinguished name (DN) entry. All credentials are bound to a DN. The Root CA distinguished name uses the following attributes:

Attribute Type	Abbreviation	Example
Common name	cn	cn=rootca
Email address	em	em=rootca@A.net
Serial number	serial	serial=no12345
Organizational unit name	ou	ou=web
Organization Name	o	o=A.net
Locality name	l	l=internet
State or province name	st	st=California
Country name	c	c=US

The order of the attributes matters in the DN. The DN must begin with the most specific attribute and continue to the least specific. The attributes are listed in the table from most specific (common name) to least specific (country).

All credentials are stored in a directory owned by the Root CA user, which should not be publicly readable. The Root CA user's credentials (as well as each web site's credentials) will be available through the Federated Naming Service (FNS).

Root CA Host

All computers that use SSL or key packages will need to have the security tools packages installed. There must be at least one machine, the Root CA host, where

The user name of the Root CA exists.
The credentials of the Root CA are stored.
FNS is properly installed.

The Root CA will create and store credentials for web sites on this host.

Running Sun WebServer on the Root CA host is not necessary. A Sun WebServer machine can get access to the credentials for web sites it hosts by copying the files from the Root CA hosts.

SSL-Enabled Sun WebServer

To support SSL for web sites, you need an instance of Sun WebServer that has all of the SSL packages and libraries available and has SSL enabled on a port for each IP address where SSL will be used.

Once credentials are created by the Root CA, the credentials must be installed on the Sun WebServer machine where the site is hosted.

Unique IP for Web Site

The Root CA user creates credentials for a web site, using the web site's host name and IP address. The credentials must be bound to a unique host name and IP address, so there must be a unique IP address with an SSL port for each SSL-enabled site.

Certificate Signing

When a client connects to an SSL enabled port on a web site, it requests the site's credentials. To verify the credentials, they must be signed by a CA for which the client has a public key and which the client trusts.

Since most clients will not have your local Root CA's public key certificate as a trusted party, you will want to get site credentials signed by a well-known CA, such as VeriSign.

SSL Configuration Procedures

This section lists the top-level procedures to follow to configure SSL. Each procedure has a link to more detailed steps.

If you are unfamiliar with the environment required for running SSL and a Certificate Authority, please refer to "SSL Requirements Overview " before performing the following procedures:

Root CA Configuration

The Root Certificate Authority (CA) is required to create key packages and certificates for web sites on your network. See "SSL Requirements Overview " if you are unfamiliar with the role of the Root CA user and Root CA machine.

You need to configure the Root CA machine, and then create the Root CA that can create credentials for web sites.

To Configure the Root CA Machine

Make sure that the correct packages for generating credentials are installed on the machine:

SUNWhttp

Contains tools and scripts for running the Root CA.

SUNWfns

Up-to-date Federated Naming Service files.

SUNWski

SKI library.

SUNWskica

Encryption software for generating key packages and certificates.

SUNWskicw

Licensing software for the Root CA.

SUNWskimc

SKI 1.0 Software (CA Manual Page Package)

SUNWskimu

SKI 1.0 Software (CA User Manual Page Package)

SUNWssl

SSL 1.0 Software (Global Version Library)

SUNWskild

SKI 1.0 Software Package (US and Canada Library)

SUNWssld

SSL 1.0 Software (US and Canada Library)

These packages are installed during Sun WebServer installation if you choose to install SSL.

Sun WebServer installation will start the processes required for generating security keys and certificates. Make sure that the following processes are running:
- /usr/lib/security/skiserv
- /usr/lib/security/cryptorand

Select or create a user to be the Root CA user.

Note -
This document will refer to this user as rootca, but you may choose any UNIX user name from /etc/passwd.

Create a directory owned by rootca where you can store credentials.

This directory should not be readable by others. For example:
# mkdir /var/SSL_CERTS# chmod 700 /var/SSL_CERTS# chown rootca /var/SSL_CERTS

To Create the Root CA

Determine the distinguished name (DN) entry for the root CA.

For details see "Root CA User ". An example DN is cn=rootca, o=A.net, st=California, c=US.

Run crca.

If crca is not available in /usr/bin, you have not installed the SUNWski package on this machine.

Note -
The SSL script create_rootca has been renamed to crca.

Enter the DN for the Root CA.

Enter Distinguished Name (e.g. "o=SUN, c=US")
or q[uit]: cn=rootca, o=A.net, st=California, c=US

Enter the directory name where credentials will be stored.
Enter directory pathname under which the key package and certificate will be stored, or q[uit]. Directory name ?/var/SSL_CERTS
The script will generate public and private encryption keys for the Root CA. All key packages are protected by a password to prevent unauthorized use.

Enter a password for the Root CA key package.

keypkg: Enter your NEW key package password: 
keypkg: Reenter your NEW key package password:

Creating Credentials

The Root CA creates and stores credentials for web sites on the Root CA machine. The certificate can then optionally be signed by another CA, such as VeriSign. When the credentials are ready, they are installed on the Sun WebServer machine for use by the web site.

Note -

"Credentials" in this document refers to a key package public and private encryption keys and an associated certificate.

To Create Credentials for a Web Site

Determine the distinguished name entry for the web site, using the Fully Qualified Domain Name (FQDN) as the common name (cn).

For details on the distinguished name in certificates, see "Root CA User ".

Create a directory where you can store the credentials you are about to create.
rootca % mkdir /var/SSL_CERTS/121.122.123.12/

Run /usr/http/bin/sslgencrd with the appropriate options.

Note -
The SSL script setup_creds has been renamed to sslgencrd.

Valid options are:

-d output_directory

Specifies the directory where credentials should be stored; for example, /var/SSL_CERTS/121.122.123.12/.

-f trusted_file

(Not required; used to add certificates for other trusted CAs at setup time.) Specifies the full pathname to the file containing the Root CA certificate, for example, /export/skirca2/certs/skirca2.CERT.

-i IP_Address

Specifies the IP Address of the web site for which credentials are being created.

-r rootca

(Optional) Specifies the name of the Root CA user (the user name you have used to run the script). If -r is omitted, sslgencrd will ask for the user name of the Root CA user on this system.
# /usr/http/bin/sslgencrd -r rootca \ -d /var/SSL_CERTS/121.122.123.12/ -i 121.122.123.12

Enter the host name only as the name of the web site. You will be asked to enter the domain name next.

For example, if the web site is www.V.com, enter www.
Enter host name on which you run httpd server: (Hit return to use localhost)www

Enter the domain name of the web site.

Enter domain name for your server (for example, eng.sun.com)V.com

Enter the DN attributes for the web site, without the common name (cn).
Enter Distinguished Name Suffix for your server (eg: o=SUN, c=US) :o="Company V", st=California, c=US
The distinguished name must have the fields ou, o, l, st, and c in the DN suffix. For example,
ou=SUNIR, o=SUN, l=Palo Alto, st=California, c=US
Note -
The state (st) must be fully spelled out; a two-letter abbreviation cannot be used. The country must be the two-letter country code. If you don't use the correct DN, then VeriSign rejects the request. If this occurs, you must regenerate the credentials.

Enter a new password for this web site's credentials.

Each key package has a password, which can be different from the password for the Root CA's credentials.

Please provide the password to encrypt your server's private key.
You will need it when you install the certificates.
Enter password:
Reenter password:
         Using configuration file '/tmp/try/host_config

skilogin: Enter your own key package password:

The key package and certificate for the site will be generated and stored in the output directory you named.

The location of the certificate is output_directory/certs/IP_Address.cert. In this example, it would be /var/SSL_CERTS/121.122.123.12/certs/121.122.123.12.cert.

You will need the certificate directory later if you reinstall this certificate.

Repeat steps 1 through 9 to generate credentials for additional web sites.

You now have a "self-signed" certificate. You can use this for SSL encryption if the connecting browser has your Root CA in its list of trusted CAs. This is useful within your organization where you can update browsers that need to use SSL (for example, if you protect the Sun WebServer GUI with SSL). Most clients on the Internet, however, will not know about your Root CA so you will want certificates signed by a third party for public SSL sites. Refer to "Requesting Signed Certificates " after you have installed the credentials on the Sun WebServer machine.

Continue with the procedure in "Enabling SSL on a Web Site ".

Enabling SSL on a Web Site

Enabling SSL on a web site requires installing the credentials on the machine where Sun WebServer is running, and configuring SSL on a port that the web site can use.

Installing Site Credentials

To Install Site Credentials on a Sun WebServer Machine

Copy the directories where the site's credentials are stored to the Sun WebServer machine.

If the Root CA machine and the Sun WebServer machine are the same, skip this step.

You can move the directory to a floppy disk or other portable medium, or you can share the directory with the Sun WebServer machine over NFS.

In either case, copy the directory you specified for the output of sslgencrd and all of its subdirectories. The directory should contain:
- certs/IP_Address.CERT
- keypkgs/IP_Address.KEYPKG
where IP_Address is the address used by the web site.

Note -
The SSL script setup_creds has been renamed to sslgencrd.

As root on the Sun WebServer machine, run /usr/http/bin/sslstore.

Note -
The SSL script install_certs has been renamed to sslstore.

You will need to specify the path to the credentials, the IP address of the web site, and the user ID (uid) of the Sun WebServer process. For example
# /usr/http/bin/sslstore -p /floppy/cert_floppy -i \ 121.122.123.12 0
Valid options are:

-c

Indicates reinstallation of local certificate. This option replaces a third party certificate with the original self-signed certificate. The self-signed certificate created with sslgencrd from the credentials directory should be preserved. The same credentials directory is specified again in the -p option.

Note -
It is recommended that you save third party certificates received from a CA in a file because they cannot be recovered after they have been removed with the -c option.

-i IP_Address

Specifies the IP address of the web site for which credentials are being created.

uid

User ID under which the web server process runs. Default uid is 0.

-p path

Certificates directory.

Enter the key package password for this web site.

This is the password specified in step Step 8 in "Creating Credentials".
/usr/bin/skilogin: Enter host key package password
The credentials are now stored on the Sun WebServer machine. Follow the next procedure to configure the web site to use SSL.

Configuring a Web Site for SSL

You must create a port on the web site's IP address that uses SSL. The default port used for SSL connections is 443.

These instructions assume you are using the Sun WebServer GUI. You can also configure the port by editing the configuration file for the web site's server instance (for example, /etc/http/sws_server.httpd.conf). Please refer to the man page for httpd.conf(4) if you choose to edit the configuration file.

To Configure A Web Site for SSL:

Connect to the Sun WebServer GUI and log in.

For information on connecting, see Chapter 2, Configuring Sun WebServer.

Find the server instance that hosts the web site in the Server List. Click the + to expand the folder if the configuration pages are not listed.

If you do not know the IP address of the web site, choose the Web Sites page.

The IP address(es) used by the web site are shown in the list.

Note -
The IP Address must not be used by multiple web sites. The SSL certificate is bound to a unique IP address and host name.

Click the IP/Ports page to add a port to the web site's IP address.

The Network Connections list will display on the right, showing all of the IP addresses and ports used by this server instance.

Click Add to create a Network Connection using the web site's IP address and port 443.

The Network Connection Dialog opens.

Fill in the IP Address and Port fields with the web site's IP address and the port on which you want SSL active (usually 443). Set the Timeout and whether you want to allow HTTP 1.0 Keepalive.

If you are unsure about Timeout and Allow HTTP 1.0 Keepalive, click Help in the dialog. For best performance, set the Timeout to 300 seconds and allow HTTP 1.0 Keepalive.

Select the Enable SSL check box.

If you want to accept connections only from clients that have valid personal certificates, click the Require Client Certificate box.

For more information on this field, click Help.

Set the cipher suites you want to enable.

The server will negotiate with the client to use a common cipher suite. If the client and server have more than one suite in common, the strongest suite will be used.

If you have the US/Canada encryption software, you may choose 128-bit, 40-bit, or both. Select both, unless you explicitly want to require a certain set from clients.

If you have global encryption software, you can only use the 40-bit cipher suite. Select the 40-bit check box.

Note -
For domestic software, to ensure successful operation with various browsers, always include the strongest available cipher choice (SSL_RSA_WITH_RC4_128_MD5) in the ssl_ciphers attribute when you enable SSL on a port.

Click OK to confirm your changes, then choose Save from the Web Server menu.

If you are configuring SSL on the default site for the server instance, skip the remaining steps.

The default site on a server listens to all connection endpoints defined for that server, so there is no need to add the new SSL connection to the web site.

From the Server List, choose the Web Site page and select the web site in the list. Choose Edit Web Site from the Edit menu.

In the Edit Web Site dialog, find the SSL enabled network connection in the Available IP/Ports list of the IP/Ports section, and choose it. The connections are listed as IP_Address:Port combinations.

Click < to move the connection in the Site Connections list.

Note -
This option is disabled for default sites because default sites automatically listen in on all connection endpoints for the server. If you are configuring the default site for the server instance, skip steps 12 through 15.

Click Save to save the web site changes.

If you want the web site to be available only through server SSL connections, remove all other ports from its Site Connections list.

Continue with the next configuration procedure, "Requesting Signed Certificates ".

Requesting Signed Certificates

Having a web site's certificate signed by an independent CA is the equivalent of having an independent auditor vouch for the site's identity. Clients may not believe that a secure site is what it claims to be unless its credentials are "digitally signed" by a CA that the client trusts.

This means that if you run your web site with the self-signed certificates created above, then when users contact your web site, their browser may request the users' permission to accept the credentials.

Sun WebServer currently only supports VeriSign as a third party CA. You can use the tools that come with Sun WebServer to send a certificate and a certificate signing request (CSR) to VeriSign via their public web site.

To Request a Signed Web Site Certificate

Your local Root CA must generate credentials and store them on the Sun WebServer machine.

Refer to "Creating Credentials" and "Enabling SSL on a Web Site ".

Run the sslgenreq utility to generate a certificate that can be sent to a CA.

Note -
The SSL script send_request has been renamed to sslgenreq.

On the command line, you must specify the IP address of the site whose certificate you want signed. The portable certificate will be stored in a file in /tmp, unless you use -o to specify a different directory (the directory must already exist).
# mkdir /var/SSL_CERTS/requests # /usr/http/bin/sslgenreq -o /var/SSL_CERTS/requests \ 121.122.123.12

Enter the key package password for the web site.

This is not the Root CA's key package password. This is the password you created when you ran sslgencrd.

The certificate signing request will be stored in the directory you named, or /tmp, in a file named cert.request.

The contents of this file can be sent to VeriSign through their web site.

You will need to follow the CA's procedures for requesting a signed certificate. At some point, you will need to supply the generated certificate file to the CA.

To request a VeriSign certificate, visit http://www.verisign.com/server/. You will need to request a server certificate for server software from Sun Microsystems.

When the CA sends the signed certificate, save it in a file.

For example, save the reply in /tmp/121.122.123.12.cert.

Caution -
Do not save the certificate from the CA in the directory the Root CA uses to store credentials.

As root, run /usr/http/bin/sslstorex to make the signed certificate available for SSL.

Note -
The SSL script install_external has been renamed to sslstorex.

Valid options are:

-c file_path

Certificate reply file from the external CA. This option is required.

-o option

CAs to be added to the server's trusted key list. Type of certificate can be one of the following:

test

A trial certificate from VeriSign valid for two week. In order to test the clients against a server that has a test certificate from a third party, the test CA's certificate must be embedded into the browser. Browsers prompt users for this when an SSL connection with such a server is established.

prod

A production certificate valid for one year. This is the default setting.

update

Migrates from a test certificate to a production certificate. The test CA is removed as a trusted key, and the production CA's key is added to the server's trusted key list.

Note -
Test, prod, and update are tokens defined by Sun WebServer. They refer to the certificate lifetimes of the server certificates issued by VeriSign.

-i IP_Address

Specifies the IP Address of the web site for which credentials are being created.

uid

User ID under which the web server process runs. Default uid is 0.

Enabling Client Authentication

You can use SSL as a method for authenticating client connections if clients have digital IDs. Currently Sun WebServer supports personal digital IDs from VeriSign. VeriSign offers three levels of personal digital ID, based on the strength of the key and the insurance protection:

Class1
Class2
Class3

You can configure an SSL web site to require client authentication and define which level(s) of personal IDs to accept.

To require client authentication for SSL

Select the SSL-enabled connection used by this web site, and click Edit.

The Edit IP/Ports dialog appears.

In the dialog, click the Require Client Certificate check box, and click OK.

Choose Save from the Web Server menu to save the configuration.

Return to the command line and become superuser.

Run sslclauth multiple times to enable or disable multiple signers. The enabled CAs are added to the web site's trusted key list.

The syntax for the command is:

sslclauth -e | -d -i IP_Address Signer

-d

Disables access to clients with certificates signed by the Signer.

-e

Enables access to clients with certificates signed by the Signer.

-i IP_Address

Specifies the IP Address of the SSL-enabled host.

-i Signer

Specifies the signer who has signed the personal digital certificate of the client. Sun WebServer only supports VeriSign personal digital IDs. VeriSign has three classes: Class1, Class2, or Class3. These vary based upon the strength of the key and the insurance protection.

Note -
The SSL script setup_client_auth has been renamed to sslclauth.