C H A P T E R 6 - Installing and Configuring Apache Web Server Software

C H A P T E R 6

Installing and Configuring Apache Web Server Software

This chapter describes how to install and configure Apache Web Servers to use the board and includes the following sections:

Configuring Apache Web Server 1.3x

Building and Configuring Apache Web Server 2.x

Configuring the Apache Web Server to Start Up Without User Interaction on Reboot

Configuring the Sun Crypto Accelerator 1000 for Use With Apache After the Sun Crypto Accelerator 4000 Software is Installed

The following are the software requirements to configure Apache Web Server to use the board:

Apache Web Server 1.3.26 or later--the 1.3.26 version is provided with the Sun Crypto Accelerator 4000 software

Patch 109234-09 for Solaris 8 available from http://sunsolve.sun.com

Patch 113146-02 for Solaris 9 available from http://sunsolve.sun.com

SUNWkcl2a package included with the Sun Crypto Accelerator 4000 software

Once the SUNWkcl2a package is added, the system is configured with Apache Web Server and mod_ssl 1.3.26.

Note - Apache Web Servers do not use the keystore or user account features described in Chapter 5 Concepts and Terminology.

Caution - Do not configure Apache Web Server for use with the Sun Crypto Accelerator 1000 board and the Sun Crypto Accelerator 4000 board at the same time. Apache will not work correctly.

Note - The bulk encryption feature for Apache software is enabled by default and cannot be disabled.

Configuring Apache Web Server 1.3x

This section describes how to use the apsslcfg script to configure the web server to use the board. This section also describes how to create and install a server certificate.

To Configure Apache Web Server

1. Create an httpd configuration file if you have not already created one.

For Solaris systems, the httpd.conf-example file is usually in the /etc/apache directory. You can use this file as a template and copy it as follows:

# cp /etc/apache/httpd.conf-example /etc/apache/httpd.conf

2. Replace ServerName with your server name in the httpd.conf file.

3. Start apsslcfg.

# /opt/SUNWconn/cryptov2/bin/apsslcfg

4. Select 1 to configure your Apache Web Server to use SSL.

Note - This procedure assumes that you choose option 1 at this prompt. If you want to choose option 2, refer to Using the apsslcfg Script.

Sun Crypto Accelerator Apache Installation

---------------------------------------------------------

This script will install the Sun Crypto Accelerator

cryptographic modules for Apache.

Please select what you wish to do:

---------------------------------------------------------

1. Configure Apache for SSL

2. Work with Apache keys

Your selection (0 to quit): 1

5. Type the path of the Apache binaries.

On Solaris systems, this path is typically /usr/apache.

Please enter the directory where the Apache

binaries and libraries exist [/usr/apache]: /usr/apache

6. Type the path for the Apache configuration files.

On Solaris systems, this path is typically /etc/apache.

Please enter the directory where the Apache configuration files exist [/etc/apache]: /etc/apache

7. Create a remote security access (RSA) keypair for your system.

If you choose not to create a keypair, you must later use apsslcfg to generate one.

Do you wish to create a new RSA keypair and certificate request? [Y/N]: Y

If you answer no to this question, skip to To Generate a Server Certificate.

8. Provide the directory for storing the keys.

If this directory does not exist, it is created.

Where would you like the keys stored? [/etc/apache/keys]: /etc/apache/keys

9. Choose a base name for the key material.

This name is appended with different suffixes to distinguish key files, certificate request files, and certificate files from each other.

Please choose a base name for the key and request file: base-name

10. Provide a key length between 512 and 2048 bits.

For most web server applications, 1024 bits is sufficiently strong, but you can choose stronger keys if preferred.

What size would you like the RSA key to be [1024]? 1024

Using configuration from /opt/SUNWconn/cryptov2/ssl/openssl.cnf

Generating a 1024 bit RSA private key

........++++++

...................................................++++++

writing new private key to /etc/apache/keys/base-name

11. Create your PEM pass phrase.

This pass phrase protects the key material. Be sure to select a strong pass phrase, but one that you can remember. If you forget the pass phrase, you will be unable to access your keys.

Enter PEM pass phrase:

Verifying password - Enter PEM pass phrase:

Caution - You must remember the pass phrase you enter. Without the pass phrase, you cannot access your keys. There is no way to retrieve a lost pass phrase.

To Generate a Server Certificate

1. Create a certificate request using the keys you created in Step 7 of To Configure Apache Web Server.

a. Type the password to access your keys. Then type the appropriate information for the requestor information fields.

TABLE 6-1 provides a description of the requestor information fields.

Enter PEM pass phrase:

You are about to be asked to enter information that will be incorporated into your certificate request.

What you are about to enter is what is called a Distinguished Name or a DN.

There are quite a few fields but you can leave some blank

For some fields there will be a default value,

If you enter '.', the field will be left blank.

-----

Country Name (2 letter code) [US]:US

State or Province Name (full name) [Some-State]:.

Locality Name (eg, city) []:.

Organization Name (eg, company) []: Company

Organizational Unit Name (eg, section) []: Department

SSL Server Name (eg, www.company.com) []:www.company.com

Email Address []:admin@company.com


Field	Description
Country Name	Two-letter ISO code for the country (for example, the United States is US)
State or Province Name	(Optional) Full name of the state, or you may enter a dot (.)
Locality	City, county, principality, or country
Organization Name	Company name
Organizational Unit Name	Department of the company
SSL Server Name	Web site domain that is typed in a visitor's browser
Email Address	Contact information for the requestor

2. Modify the /etc/apache/httpd.conf file as directed.

Information regarding your key and certificate files, and instructions for how to modify the /etc/apache/httpd.conf file appears.

The keyfile is stored in /etc/apache/keys/base-name-key.pem.

The certificate request is in /etc/apache/keys/base-name-certreq.pem.

You will need to edit /etc/apache/httpd.conf for the following items:

You must specify the ports that Apache will listen to for

SSL connections, as well as for non-SSL connections.  One

way to accomplish this is to add the following lines in

the Listen section:

Listen 80

Listen 443

In the LoadModule section, add the following:

LoadModule ssl_module /usr/apache/libexec/mod_ssl.so.version-number

In the AddModule section, add the following:

AddModule mod_ssl.c

Note - The correct version-number will be displayed for your configuration.

3. If you chose not to set up a VirtualHost, you must place the SSLEngine, SSLCertificateFile, and SSLCertificateKeyFile directives in the httpd.conf file just above the SSLPassPhraseDialog directive.

You may need a virtual host directive similar to

what is shown below:

<VirtualHost _default_:443>

        SSLEngine on

        SSLCertificateFile /etc/apache/keys/base-name-cert.pem

        SSLCertificateKeyFile /etc/apache/keys/base-name-key.pem

</VirtualHost>

You must add the following line after all of your VirtualHost definitions:

SSLPassPhraseDialog exec:/opt/SUNWconn/cryptov2/bin/apgetpass

Other SSL-related directives and their explanations

can be found in the Sun Crypto Accelerator documentation.

Other Apache-related directives may need to be configured

in order to start your Apache Web Server. Please refer

to your Apache documentation.

<Press ENTER to continue>

If you answered no to the question in Step 7 of Configuring Apache Web Server 2.x, you are given additional information on how to generate key material.

Since you did not create keys, you will need to

make sure that you have a key file and a certificate

file in place before enabling SSL for Apache.

You can create a new key file and certificate request

by selecting the "Generate a keypair and request a

certificate for Apache" option after choosing

"Work with Sun ONE and Apache keys" from the

apsslcfg main menu.

4. Type 0 to quit when you finish with apsslcfg.

To Install the Server Certificate

1. Copy your certificate request with the headers from the /etc/apache/keys/base-name-certreq.pem file (where base-name was set in Step 9 of To Configure Apache Web Server), and transfer the certificate request to your certificate authority.

2. Once the certificate is generated, create the certificate file /etc/apache/keys/base-name-cert.pem and paste your certificate into the file.

3. Start the Apache Web Server.

The following path assumes your Apache binary directory is /usr/apache/bin. If this is not your binary directory, type the correct path.

# /usr/apache/bin/apachectl sslstart

4. Enter your PEM pass phrase when prompted.

5. Verify the new SSL-enabled web server with a browser at the following URL: https://server-name:server-port/

Note that the default server-port is 443.

Note - Refer to the mod_SSL and OpenSSL documentation for information on how to self-sign a certificate for testing.

Building and Configuring Apache Web Server 2.x

The Sun Crypto Accelerator 4000 software does not include a mod_ssl library for Apache 2.x Web Servers. This section describes the options you need to include when building the web server, and describes how to configure Apache 2.x to use the board.

Building Apache 2.x Web Server

To start this process, your OpenSSL implementation must have all of the required patches. This section covers only the board specific options, and is not an exhaustive set of instructions to build the entire Apache 2.x suite. For complete instructions, refer to the documentation available at http://www.apache.org.

To Build Apache 2.x

1. Preset the SH_LIBS environment variable to comply with the configure script.

sh:

# SH_LIBS="-lssl -lcrypto"

# export SH_LIBS

csh/tcsh:

# setenv SH_LIBS "-lssl -lcrypto"

2. Change to the installation directory and execute the configure script.

This script has many command-line options, the following are required to configure the web server to use the board:

# ./configure --enable-ssl --enable-mods-shared=ssl

--with-ssl=/opt/SUNWconn/cryptov2

3. Once the script has finished, do one of the following:

a. If you are building and installing Apache 2.x for the first time, type the following.

# make

# make install

b. If you wish to build the mod_ssl shared library for an existing Apache 2.x Web Server, type the following:

# make shared-build

# cp modules/ssl/.libs/mod_ssl.so Apache-directory/modules

Configuring Apache Web Server 2.x

This section describes how to configure the web server to use the board by generating and installing a server certificate and enabling the web server for SSL.

To Generate a Server Certificate

1. Generate a key and certificate request.

# /opt/SUNWconn/cryptov2/bin/openssl req \

-new -newkey rsa:keysize -keyout key-output-file \

-out cert-request-output-file \

-config /opt/SUNWconn/cryptov2/ssl/openssl.cnf

Generating a 1024 bit RSA private key

..........................................................................++++++

.......++++++

writing new private key to '/tmp/key1.pem'

2. Type the password to protect the key file.

Enter PEM pass phrase:

Verifying - Enter PEM pass phrase:

3. Type the "Distinguished Name" values (See TABLE 6-2).

You are about to be asked to enter information that will be incorporated into your certificate request.

What you are about to enter is what is called a Distinguished Name or a DN.

There are quite a few fields but you can leave some blank

For some fields there will be a default value,

If you enter '.', the field will be left blank.

-----

Country Name (2 letter code) [US]:US

State or Province Name (full name) [Some-State]:California

Locality Name (eg, city) []:San Diego

Organization Name (eg, company) []: Company

Organizational Unit Name (eg, section) []: Company Division

SSL Server Name (eg, www.company.com) []:www.company.com

Email Address []: admin@domain.com


Field	Description
Country Name	Two-letter ISO code for the country (for example, the United States is US)
State or Province Name	(Optional) Full name of the state, or you may enter a dot (.)
Locality Name	(Optional) City, county, principality, or country
Organization Name	Company name
Organizational Unit Name	(Optional) Department of the company
SSL Server Name	Web site domain that is typed in a visitor's browser
Email Address	Contact information for the requestor

To Install the Server Certificate

Copy your certificate request with the headers into the same directory where your key file was created in Step 1 of To Generate a Server Certificate.

To Enable SSL

1. Edit the ssl.conf file in the conf subdirectory of the Apache 2.x Web Server installation directory.

There are several directives in the ssl.conf file; the following directives must be configured for the web server to use the board.

Listen port-number

ServerName fully-qualified-domain-name

SSLEngine on

SSLCertificateFile path-to-certificate-file

SSLCertificateKeyFile path-to-key-file

2. Start the Apache Web Server.

This assumes your Apache binary directory is /usr/apache/bin. If this is not your binary directory, type the correct directory.

# /usr/apache/bin/apachectl sslstart

3. Enter your PEM pass phrase when prompted for it.

4. Verify the new SSL-enabled web server with a browser by going to the following URL:

https://server-name:server-port/

The default server-port is 443.

Note - Refer to the mod_SSL and OpenSSL documentation for information on how to self-sign a certificate for testing.

Configuring the Apache Web Server to Start Up Without User Interaction on Reboot

You can enable the Apache Web Server to perform an unattended startup at reboot with an encrypted key.

To Create an Encrypted Key for Automatic Startup of Apache Web Server on Reboot

1. Verify that the following entry exists in the httpd.conf file:

SSLPassPhraseDialog exec:/opt/SUNWconn/cryptov2/bin/apgetpass

This directive retrieves a password from a protected password file in the /etc/apache directory.

2. Create a password file that contains only the password in the /etc/apache directory with the following filename convention:

server-name:port.KEYTYPE.pass

server-name - The value that you placed in the ServerName directive in the httpd.conf file

port - The port on which this SSL server runs (for example, 443)

KEYTYPE - Either RSA or DSA

Example: For a server named webserv101 running SSL on port 443 with an RSA key, create the following file in /etc/apache:

webserv101:443.RSA.pass

Change the permissions and ownership of the password file as follows:

# chmod 400 server-name:port.KEYTYPE.pass

# chown root server-name:port.KEYTYPE.pass

Refer to the mod_SSL and OpenSSL documentation for more information.

Configuring the Sun Crypto Accelerator 1000 for Use With Apache After the Sun Crypto Accelerator 4000 Software is Installed

Once the SUNWkcl2a software package is installed, the system is configured with Apache Web Server mod_ssl 1.3.26.

If you want to configure the Sun Crypto Accelerator 1000 board with Apache, you must have the following patches.

To configure the Sun Crypto Accelerator 1000 for use with Apache 1.3.26 on a Solaris 8 system with the SUNWkcl2a package installed, you need the following patches:

For Apache 1.3.26 - Patch ID 109234-09 or later

For Sun Crypto Accelerator 1000 version 1.0 software - Patch ID 112869-02

For Sun Crypto Accelerator 1000 version 1.1 software - Patch ID 113355-01

To configure the Sun Crypto Accelerator 1000 for use with Apache 1.3.26 on a Solaris 9 system with the SUNWkcl2a package installed, you need the following patches:

For Apache 1.3.26 - Patch ID 113146-01 or later

For Sun Crypto Accelerator 1000 version 1.1 software - Patch ID 113355-01