Chapter 2

Configuration

Once you've installed Stronghold, you must configure the server to support your virtual hosts and provide SSL security that meets your organization's security policy. This document describes


Editing the PATH Variable

The PATH variable behaves differently depending on which type of UNIX shell you are using.

From the Bourne shell, Korn shell, or bash, edit the PATH variable in your .profile as follows, where SSLTOP is the pathname of your top-level SSL directory:

# SSLTOP=${SSLTOP}
# PATH=${SSLTOP}/bin:$PATH
# export PATH SSLTOP

If you are using the C-shell or tsh, edit the PATH variable in your .cshrc as follows:

# setenv SSLTOP ${SSLTOP}
# set path=(${SSLTOP}/bin $path)

PATH variable configuration works the same whether you choose the unified or dual server configuration, described in the next section.


Configuring a Unified or Dual Server

You can configure Stronghold to carry out both SSL and non-SSL transmissions as a single server, instead of separate SSL and non-SSL servers. The httpd.conf file supports separate VirtualHost configurations for separate ports. When you enter a set of VirtualHost directives, you can specify a port number, either the port for SSL or non-SSL transmissions. In this way, a single configuration file stores both SSL and non-SSL directives for a single server.

To configure a unified server

  1. Configure the ServerRoot/conf/httpd.conf file as described in the Apache Configuration Directives guide.

  2. Add Listen directives for both the SSL port and the non-SSL port, so that the server listens on both:
    Listen 80
    Listen 443
  3. For each virtual host, add directives for port 80, the default non-SSL port. For example:
    <VirtualHost 204.17.33.10:80>
    ServerAdmin webmaster@www.random.com
    DocumentRoot /www/random
    ServerName www.random.com
    UserDir disabled
    ErrorLog /www/log/random/error_log
    TransferLog /www/log/random/access_log
    </VirtualHost>
  4. For each virtual host, add directives for port 443, the default SSL port:
    <VirtualHost 204.17.33.11:443>
    ...
    </VirtualHost>

    Use the directives described in "SSL Configuration Directives" later in this guide.

  5. Add SSL directives for the main host as if it were a virtual host:
    <VirtualHost 204.17.33.10:443>
    ...
    </VirtualHost>

    Use the directives described in the next section, "SSL Configuration Directives."

You can also configure Stronghold as as dual server with separate SSL and non-SSL components. To do so, use two separate configuration files: httpd.conf for the normal server and httpsd.conf for the SSL server.

To configure a dual server

  1. Configure ServerRoot/conf/httpd.conf for normal transmissions, according to the Apache Configuration Directives manual.
  2. Configure ServerRoot/conf/httpsd.conf for SSL-secured transmissions, using the directives described in the next section.


SSL Configuration Directives

The fields described here configure the SSL portion of Stronghold. For information on configuring the Apache server component, including VirtualHost directives for port 80, see the Apache Configuration manual.

You need to use these directives differently depending on whether you've installed a unified SSL/non-SSL server or separate SSL and non-SSL servers:

General Directives

These directives set the basic parameters used by the SSL server, including certificates, logs, and keys.

SSLFlag

Syntax: SSLFlag on
"SSLFlag on" is required to activate the SSL server functionality.

SSLRoot

Syntax: SSLRoot path
SSLRoot is the root directory for SSL files. SSL file directives (except logging directives) can be relative to SSLRoot.
Note: All other paths and filenames relating to SSL must be either absolute or relative to SSLRoot.

SSLCACertificatePath

Syntax: SSLCACertificatePath path
This is the path for trusted CA root certificates. Store the CA root certificates for client certification here.

SSLLogFile

Syntax: SSLLogFile filename
Stronghold stores information about each SSL-enabled connection‹such as cipher and client-authentication data‹in the SSLLogFile.

SSLErrorFile

Syntax: SSLErrorFile filename
SSLErrorFile is where error messages and SSL diagnostics are stored. If this directive is unspecified, Stronghold stores this data in the SSLLogFile instead.

SSLSessionServer

Syntax: SSLSessionServer filename
In order for Stronghold to track client sessions and session keys, you must set the SSLSessionServer directive. If you do not specify a UNIX socket file, the default will be used.

SSLSessionTimeout

Syntax: SSLSessionTimeout seconds Specify the SSL session timeout in seconds. Any session that is inactive for the period you specify will be closed.

Client Authentication

Stronghold uses these parameters to authenticate clients using client certificates.

SSLVerifyClient

Syntax: SSLVerifyClient [0 |1 |2 ]
This sets the X.509 Client Authentication option:
0 = No
1 = X.509 certificate optional
2 = X.509 certificate required

SSLFakeBasicAuth

Syntax: SSLFakeBasicAuth
Include this directive to enable access-controls based on client authentication, then enter access-control directives for each directory that requires authentication. For example:
<Location path>
AuthUserFile UserFilePath
AuthType Basic
AuthName RealmName
require valid-user
</Location>

AuthUserFile denotes the file that contains the list of accepted certificate names and corresponding, encrypted passwords, such as /CN=Sameer Parekh/Email=sameer@c2.net:ieEc4N05EI.

The encrypted password is the client passphrase for the key pair associated with the client certificate.

AuthType should always be set to Basic, because browsers currently do not support other values. RealmName is an arbitrary label for this authentication realm; use it to distinguish between different authentication schemes for different virtual hosts or directories.

The require field can take the following values:

Verisign's Digital ID Center at http://digitalid.verisign.com/brw_pick.htm offers client certificate services.

Note: If this option is set, SSLVerifyClient must be set to 2 in order to avoid a security weakness. If SSLVerifyClient is set to 1, client authentication will only be implemented if the client offers a certificate.

SSLVerifyDepth

Syntax: SSLVerifyDepth n
Certificate Authorities are certified by other CAs, forming a chain of certificates that the server can follow for progressively decisive verification. SSLVerifyDepth sets the number of CAs the server will follow in this chain when verifying client certificates.

SSLCACertificateFile

Syntax: SSLCACertificateFile filename
This is the trusted CA root certificate file. Unlike SSLCACertificatePath, it specifies a certificate file rather than a certificate directory.

SSLCertificateKeyFile

Syntax: SSLCertificateKeyFile filename
This is the key pair file. Make sure it is stored securely.

Cipher-Types

Encryption directives set the acceptable encryption parameters for communication with your server. For these directives, use this list of cipher-types:

Cipher-Type

Description

NULL-MD5 No encryption, MD5 hash
RC4-MD5 Export-controlled RC4-compatible cipher, MD5 hash
EXP-RC4-MD5 Weakened for export, RC4-compatible cipher, MD5 hash
RC2-CBC-MD5 Export-controlled RC2-compatible cipher in CBC mode, MD5 hash
EXP-RC2-CBC-MD5 Weakened for export RC2-compatible cipher in CBC mode, MD5 hash
IDEA-CBC-MD5 IDEA cipher in CBC mode, MD5 hash
DES-CBC-MD5 DES in CBC, MD5 hash
DES-CBC-SHA DES in CBC, SHA hash
DES-CBC3-MD5 3DES in CBC, MD5 hash
DES-CBC3-SHA 3DES in CDC, SHA hash
DES-CFB-M1 DES in CFB, M1 hash

SSLRequiredCiphers

Syntax: SSLRequiredCiphers cipher1:cipher2:cipher3....
This is a list of permitted cipher-types for initial SSL transmissions, in order of preference. This list applies only when the accessed directory does not have its own SSLRequireCipher or SSLBanCipher directives. If the client does not support any of the specified cipher-types, the server returns an error message.

SSLRequireCipher

Syntax: <Directory path>
	SSLRequireCipher cipher
</Directory> SSLRequireCipher specifies a cipher-type that is required for access to the specified directory. Each SSLRequireCipher directive takes only one argument; enter multiple SSLRequireCipher directives on separate lines for multiple required cipher-types. If the client does not support any of the required cipher-types, the server returns an error message.

SSLBanCipher

Syntax: <Directory path>
SSLBanCipher cipher </Directory>
Some cipher-types may be not meet the security requirements for certain server directories. This directive specifies ciphers that are unacceptable to the directory specified by path. Each SSLBanCipher directive takes only one argument; enter multiple SSLBanCipher directives on separate lines for multiple cipher-types that are not acceptable.


Configuring an Upgraded Apache Server

If you've upgraded your existing Apache server to Stronghold using APACHE.sh, you'll need to set up a separate configuration file for the new SSL component. An ordinary Apache server that has been upgraded to Stronghold must run as a dual server; it cannot run as a unified server.

To configure an upgraded Apache server

  1. Copy the httpd.conf file to httpsd.conf.

  2. Edit the following directives in the httpsd.conf file:
    Port 443
    ScoreBoardFile logs/ssl/apache_runtime_status
    PidFile logs/httpsd.pid
    TransferLog logs/ssl/access_log
    ErrorLog logs/ssl/error_log
    SSLLogFile logs/ssl/cipher_log
    SSLErrorFile logs/ssl/ssl_error_log
  3. Add the following directives to the file:
    SSLFlag on
    SSLRoot path
    SSLCertificateKeyFile private/filename
    SSLCertificateFile certs/filename
    SSLVerifyDepth n
    SSLVerifyClient [0 |1 |2 ]
  4. Add the start script to the conf/ directory:
    #!/bin/sh
    SSLTOP=path
    export SSLTOP
    ServerRoot/httpsd -d ServerRoot -f conf/httpd.conf
    ServerRoot -d ServerRoot -f conf/httpsd.conf
  5. Add the stop script to the conf/ directory:
    #!/bin/sh
    kill Ścat ServerRoot/logs/httpd.pid ServerRoot/logs/httpsd.pid'
  6. Add the reload script to the conf/ directory:
    #!/bin/sh
    kill -HUP Ścat ServerRoot/logs/httpd.pid ServerRoot/logs/httpsd
  7. Run the stop script to stop the old Apache server.

  8. Run the start script to start the new, SSL-enabled Stronghold server.


SSL Utilities

Stronghold provides server maintenance utilities for its SSL component. The utilities listed here are stored in ${SSLTOP}/bin, and they control keys, certificates, and other SSL objects. Since you can use them with virtual hosts, use hostname as the command line argument for all utilities. The argument distinguishes the different hosts and their separate key pairs and certificate files.

change_pass

Sets the passphrase used to encrypt the private key for a host:

# change_pass hostname

Use this utility periodically to keep your passphrase dynamic and prevent intruders from guessing it.

decrypt_key

Decrypts the private key for a host:

# decrypt_key hostname

With decrypt_key, you can store your unencrypted private key on disk so that the server can access it when restarting unattended. If you use decrypt_key, be sure you store your unencrypted key securely to avoid a major security weakness. An unsecured and unencrypted private key exposes your server to attack.

gencert

Generates a test certificate for a host:

# gencert hostname

The test certificate does not authenticate your server. It generates an error message when users encounter it, and it exposes your server to possible man-in-the-middle attacks. Use the certificate generated by gencert for testing purposes only. It expires in 30 days.

genkey

Generates a key pair, then calls genreq and gencert to generate a certificate signing request and a temporary test certificate for a host:

# genkey hostname

Genkey creates a new, unique key pair for a new certificate. To generate a new certificate based on an existing key pair, use gencert alone.

genreq

Generates a certificate signing request based on the existing key pair for a host:

# genreq hostname

To generate a new key pair for the new certificate, plus a test certificate, use genkey instead.

When you use genreq, be sure you specify the correct key pair file, so that your current public key is embedded in the certificate you receive from a CA. If you specify an incorrect key pair file, the new certificate will not work properly.

checkcert

Checks a certificate against the current key pair for a host:

# checkcert hostname

Since the certificate passes a public key to the client for use during encrypted sessions, the current certificate for any host or virtual host must match the current key pair. If they do not match, either

getca

Installs a certificate. When you receive your signed certificate from a CA, save it in a temporary file, such as tmp/cert. Run getca and specify both the name of the server that owns the certificate and the name of the temporary certificate file:

# getca hostname < tmp/cert

This saves the certificate to the file ${SSLTOP}/certs/servername.cert. After you run getca, be sure to remove the temporary certificate file as a security precaution.

makeca

Sets up a private certificate authority on the Stronghold server platform by generating a key pair and self-signed certificate for a host:

# makeca hostname

Use the key pair to sign certificates in response to CSRs.

Before you run makeca, make sure that ${SSLTOP} is set to the correct path for your SSL directory. After you run makeca, edit the ${SSLTOP}/lib/ssleay.conf file to configure the certificate authority according to your organization's parameters. For more detailed instructions, see the "Using a Private Certificate Authority" section of Chapter 4, "Certificates and Certificate Authorities."

renewal

Submits a certificate renewal request to your CA for a host:

# renewal hostname

Stronghold notifies you when a certificate is about to expire, and automatically prompts you to run renewal. Run renewal promptly; an expired certificate prevents users from connecting to secured sites on your server.


Virtual Hosts

Because Netscape Navigator version 2.0 and later check the URL against the hostname on the server certificate, each virtual host requires a separate certificate. To run Stronghold with virtual hosts and multiple certificates, you need to configure VirtualHost, run genkey, and install the certificates.

Configuring VirtualHost

The example below illustrates a VirtualHost configuration for port 443, the default SSL port:

<VirtualHost 140.174.185.37:443>
ServerAdmin admin@alpha.c2.org
DocumentRoot /ul/ghio/alpha_html
ServerName alpha.c2.org
UserDir disabled
ErrorLog /var/log/www/alpha/eror_log
TransferLog /var/log/www/alpha/access_log
SSLRoot /usr/local/ssl
SSLLogFile /var/log/www/alpha/ssl_log
SSLErrorFile /var/log/www/alpha/ssl_error_log
SSLCertificateKeyFile private/alpha.c2.org.key
SSLCertificateFile certs/alpha.c2.org.cert
SSLCACertificateFile CA/rootcerts.pemn
SSLCACertificatePath certs
SSLVerifyClient 0
SSLVerifyDepth 10
</VirtualHost>

Running Genkey

Run the genkey program just as you did for the original host, specifying a virtual host instead:

# genkey alpha.c2.org

Along with the key pair, genkey will generate a certificate signing request (CSR) to send to a Certificate Authority (CA), typically VeriSign. For more detailed information about genkey, see "Installation."

Installing the Certificates

Run getca for each certificate and each virtual host, as follows:

  1. Save the certificate on disk, in a temporary file such as /tmp/cert.
  2. Run getca:
    # getca hostname < /tmp/cert # rm /tmp/cert

The certificate includes your server's public key and other identifying information about the server. It is also signed with the CA's private key. Since the client can obtain the matching public key directly from the CA, successfully decrypting the certificate shows the client that the certificate is valid and authorized by a trusted third party--the CA. It can therefore trust that the information in your certificate is correct and the public key belongs to your server. In this way, certificates prevent malicious parties from intercepting data packets and substituting their own encryption keys, which would allow them to decrypt all of your transmissions.


Apache Server Extension

As you optimize your server platform, you may want to install modules or patches to improve or extend the server's capabilities. To do so, compile them as follows:

  1. Switch to the ServerRoot/src directory:
    # cd /usr/local/apache/src
    This is the directory created during server installation.
  2. Edit the configuration file to reflect your platform.

  3. Run configure:
    # ./Configure
  4. Build HTTPSD:
    # make
  5. Stop the server:
    # ../stop
  6. Install the new binaries:
    # mv ../httpsd ../httpsd-bak # cp httpsd ..
  7. Restart the server:
    # ../start


Contents