test

Sun WebServer 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 an X.509 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 encryption keys-and an associated certificate.

Sun WebServer 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 a Sun WebServer instance, 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:

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.

Note -

The preceding steps need to be completed only for self-signed certificates. It is not needed if only third-party certificates are used.

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

Federated Naming Service (FNS)

FNS is the interface the SSL security tools use to access credentials. The Sun WebServer security packages create a name service context in which to store and retrieve credentials from files.

Remove any existing FNS packages and install the SUNWfns package bundled with Sun WebServer.

This step is done before you install Sun WebServer. If you did not remove SUNWfns and install the bundled package, do so now on hosts where you will use SSL, including the Root CA host.

Note -

The SUNWfns package that is part of Solaris 2.6 will not work with SSL. Removing the package will not cause you to lose any data, and your existing FNS contexts will be preserved once the new SUNWfns package is installed. Both packages are version 11.6.0, but the full VERSION from pkginfo -l SUNWfns is 11.6.0,REV=1998.02.08.15.10 for the supported package.

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, 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:

  1. "Root CA Configuration"

  2. "Creating Credentials"

  3. "Enabling SSL on a Web Site "

  4. (optional) "Requesting Signed Certificates "

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

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

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

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

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

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

  2. Log in to the Root CA machine as the Root CA user.

  3. Run create_rootca

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

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

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

  6. Enter a password for the Root CA key package. 


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

  7. You have the option of making the key packages available in the naming service. To store the key package in the naming service, you will need the machine's root password.

    Key packages are always stored in files. Making the key package available in the naming service allows other security tools to locate the keys without the full path name.

    The Root CA is now configured. The next step is for the Root CA to generate a key package and certificate for a web site.

    Continue with the next configuration procedure, "Creating Credentials".

  8. If you don't choose this option, save the credentials in FNS, and then store the credentials manually: 


    # skistore -d dirname

    where dirname is as specified in step 5.

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

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

  2. Login to the Root CA machine as the Root CA user.

  3. Create a directory where you can store the credentials you are about to create. 


    rootca % mkdir /var/SSL_CERTS/121.122.123.12/

  4. Run /usr/http/bin/setup_creds with the appropriate options.

    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, setup_creds will ask for the user name of the Root CA user on this system. 


    # /usr/http/bin/setup_creds -r rootca \
-d /var/SSL_CERTS/121.122.123.12/ -i 121.122.123.12

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

  6. Enter the domain name for of the web site. 


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

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

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

    Each key package has a password, which should 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:

  9. 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 if you reinstall this certificate over another one.

  10. 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 Administration Console 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 three procedures: ensuring that the SSL packages are installed, installing the credentials on the machine where Sun WebServer is running, and configuring SSL on a port that the web site can use.

Creating Site Credentials

To Install Site Credentials on a Sun WebServer Machine

  1. The directories where the site's credentials are stored need to be copied 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 setup_creds 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.

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

    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/install_certs -p /floppy/cert_floppy -i \
121.122.123.12 0

  3. 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 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 Administration Console. 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:

  1. Connect to the Sun WebServer Administration Console and log in.

    For information on connecting, see Chapter 2, Configuring the Administration Server.

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

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

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

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

    The Network Connection Dialog opens.

  6. 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 on Help in the dialog. For adequate performance, set the Timeout to 300 seconds and allow HTTP 1.0 Keepalive.

  7. Click the Enable SSL box.

  8. 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 on Help in the dialog.

  9. 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. Click the 40-bit box.

  10. Click on OK to save your changes, then choose Serve->Save IP/Ports.

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

  12. From the Server List, choose the Web Site page and select the web site in the list. Choose Server->Edit Web Site.

    In the Edit Web Site dialog, find the SSL enabled network connection in the Connections list and choose it. The connections are listed as IP_Address:Port combinations.

  13. Click on > 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.

  14. Click on Save to confirm the web site changes.

  15. Select Server->Save to save your changes.

    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.

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

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

  2. Log in to the Sun WebServer machine as super-user (root).

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

    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/send_request -o /var/SSL_CERTS/requests \
121.122.123.12

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

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

  6. 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/idcenter/new/. You will need to request a server certificate for server software from Sun Microsystems.

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

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

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

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:

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

  1. Log in to the Sun WebServer Administration Console and go to the IP/Ports list for the server where the SSL-enabled web site is hosted.

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

    The Edit Network Connections dialog opens.

  3. In the dialog box, click on the "Require Client Certificate" box, then click OK.

  4. Choose Selected->Save IP/Ports to save the configuration.

  5. Return to the command line and become superuser.

  6. The syntax for the command is:

    setup_client_auth -e | -d -i IP_Address Signer

    The -e flag enables, and the -d flag disables, access to clients with certificates signed by the Signer. The IP_Address is the IP address of the SSL enabled web site.

    Signer can be one of the VeriSign classes: Class1, Class2, or Class3.

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