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
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.
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.
Listen 80
Listen 443
<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>
<VirtualHost 204.17.33.11:443>
...
</VirtualHost>
Use the directives described in "SSL Configuration Directives" later in this guide.
<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.
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:
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.
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:
- valid-user, to require authentication for any user who connects to this authentication realm
- user username, to require authentication only for specific users
- group groupname, to require authentication only for specific user groups
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.
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.
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.
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
SSLFlag on
SSLRoot path
SSLCertificateKeyFile private/filename
SSLCertificateFile certs/filename
SSLVerifyDepth n
SSLVerifyClient [0 |1 |2 ]
#!/bin/sh
SSLTOP=path
export SSLTOP
ServerRoot/httpsd -d ServerRoot -f conf/httpd.conf
ServerRoot -d ServerRoot -f conf/httpsd.conf
#!/bin/sh
kill Ścat ServerRoot/logs/httpd.pid ServerRoot/logs/httpsd.pid'
#!/bin/sh
kill -HUP Ścat ServerRoot/logs/httpd.pid ServerRoot/logs/httpsd
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.
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.
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.
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.
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.
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.
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
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.
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."
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.
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.
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>
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."
Run getca for each certificate and each virtual host, as follows:
# 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.
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:
# cd /usr/local/apache/src
This is the directory created during server installation.
# ./Configure
# make
# ../stop
# mv ../httpsd ../httpsd-bak # cp httpsd ..
# ../start