Chapter 1

Installation


This chapter describes how to install version 1.3 of Stronghold, including

Once you've installed the server, you'll need to edit certain configuration files. "Configuration" describes these files and other topics, including how to use virtual hosts with this server.

Once you've configured the server, running it is simple. If you have a problem with the server that is not resolved in this documentation set, the Stronghold FAQ at http://www.us.apache-ssl.com/faq.phtml offers additional information and troubleshooting tips.


Expanding The Archive

You download Stronghold as a compressed archive, which you must expand and extract. To expand the compressed file, place the file in a temporary directory, then run gunzip:

# gunzip stronghold-version-allplatforms.tar.gz

After gunzip expands the file, use tar to extract the archive:

# tar -xf stronghold-version-allplatforms.tar

Tar extracts the stronghold-version directory, which contains the server components.


Installing a New Stronghold Server

You can install an entire Stronghold server package from scratch, or turn your plain Apache server into an SSL-secured Stronghold server. If you already have a version of Stronghold installed, see "Upgrading an Existing Stronghold Server" later in this guide.

Installing Stronghold from Scratch

Use the INSTALL.sh script to set up a new Stronghold server from scratch. This scripts asks you a few questions, then installs the server according to the parameters you specify.

If you already have an installed Apache server, you can use the APACHE.sh script to upgrade it instead. See "Upgrading an Apache Server" later in this section.

  1. Platform

    The program detects available operating systems that are compatible with Stronghold. Enter the name of the operating system the server will use.

  2. SSLeay directory

    By default, the program creates a /usr/local/ssl directory and stores SSL security utilities there. Enter a different pathname if you want to store Stronghold elsewhere.

  3. Apache directory (ServerRoot)

    The Apache directory is where Stronghold stores the Apache component and items related to its activities, including the CGI-bin, configuration files, and document tree. The default is /usr/local/apache; enter a different pathname if you want to store these files elsewhere.

  4. Log directory

    The program creates separate logs in this directory for SSL and non-SSL transmissions.

  5. Server hostname

    The hostname of the local machine is the default server hostname. Enter a different hostname if the server will use an alias. Stronghold also uses the server hostname as the filename for both your key and certificate files, such as www.random.net.key and www.random.net.cert, to distinguish between them and keys belonging to virtual hosts.

  6. Server administrator's email address

    By default, the server will send notices and alerts to webmaster@hostname.

  7. Normal server port number

    The default HTTP server port number is 80. This is the port on which the Apache component will send and receive non-SSL transmissions.

  8. SSL server port number

    SSL server activity takes place on a separate port to isolate secured access or attempted access. The default SSL server port is 443.

  9. Username for server

    The server runs as nobody by default, to eliminate security weaknesses through user access accounts.

  10. Server group

    The server runs as nogroup by default.

INSTALL.sh completes the installation and displays instructions for editing the PATH variable and other basic configuration files to include Stronghold. You can do this now or later; the program then continues the setup process by invoking genkey, which prompts you for information related to key pair generation.

See the next section, "Generating a Key Pair," for instructions on using genkey.

Upgrading an Apache Server

With the APACHE.sh script, you can upgrade an existing Apache server to implement Stronghold's SSL scheme. If you do this, you'll need to configure its new SSL component and restart the server. See the "Configuring an Upgraded Apache Server" section of Chapter 2, "Configuration."

Like INSTALL.sh, the APACHE.sh upgrade script asks you a series of questions, then invokes genkey to generate a new key pair and certificate request to get you started.

  1. Platform

    The program detects available operating systems that are compatible with Stronghold. Enter the name of the operating system the server will use.

  2. SSLeay directory

    By default, the program creates a /usr/local/ssl directory and stores SSL security utilities there. Enter a different pathname if you want to store Stronghold elsewhere.

  3. Apache HTTPD directory

    Enter the directory where your Apache httpd binary is stored.

  4. Server hostname

    The hostname of the local machine is the default server hostname. Enter a different hostname if the server will use an alias. Stronghold also uses the server hostname as the filename for both your key and certificate files, such as www.random.net.key and www.random.net.cert, to distinguish between them and keys belonging to virtual hosts.

  5. SSL server port number

    SSL server activity takes place on a separate port to isolate secured access or attempted access. The default SSL server port is 443.

APACHE.sh completes the installation and displays instructions for editing the PATH variable and other basic configuration files to include Stronghold. You can do this now or later; the program then continues the setup process by invoking genkey, which prompts you for information related to key pair generation.

The next section describes how to use genkey.


Generating a Key Pair

Before you can use Stronghold for secure HTTP transactions, you must generate the encryption key pair using genkey. When INSTALL.sh or APACHE.sh invoke it, genkey generates a public key and a private key. Clients use your public key for encryption. The server passes the public key to the client, which uses it to encrypt the "session key" generated for that session. The session key is sent back to the server and all transmissions are encrypted using the session key. Because the session key was encrypted with the server's public key, only the server and the client know the session key.

Note: When you generate a new key pair, back up any old key pairs by copying them to another directory.

Along with the key pair, genkey generates a certificate signing request (CSR) to send to a Certificate Authority (CA), typically VeriSign. The CSR procedure described below corresponds to Step 2 of VeriSign's "Overview of the Process."

Your server's public key is embedded in the certificate you receive from the CA, and the certificate is signed with the CA's private key. The CA acts as a trusted third party who authenticates. When your server sends its signed certificate to a client, the client validates the signature with the CA's public key. Validation assures the client that there is no interposer, or "man-in-the-middle", violating the privacy and integrity of the session.

Successful decryption verifies that the certificate is valid, and the decrypted certificate reveals information about your server and its public key. If your CA is VeriSign, the standard CA, see http://www.verisign.com/apachessl-us/index.shtml" before you proceed. You can also find more information about using CAs in "Certificates and Certificate Authorities."

Like INSTALL.sh, genkey asks you a series of questions and generates the key pair and certificate-related information based on your parameters:

  1. New key generation or existing key conversion

    You can create a new key, test certificate, and CSR, or convert an existing Netscape Commerce certificate and key pair for use with Stronghold. When you enter your choice, genkey displays the names of the key file and certificate file, along with the directory in which they are stored.

  2. Key size

    This is a crucial point, since the size (and complexity) of the key determines its security level. Smaller keys are easier to crack, while cracking a larger key requires a dedicated supercomputer.

    Note: Decryption times are geometrically proportional to key size. Doubling the key size, for example, multiplies the decryption time by eight for every SSL transmission. Since 512-bit keys are considered innocuous enough for export, choose a larger key size‹ideally 1024-bit or as large as your server platform can handle.

    Once you have chosen a key size, genkey creates some of the random data used to generate the key pair. Depending on the key size, this may require some time.

  3. Random keystrokes

    The program then asks you to help complete the random data set by entering random keystrokes while it times the intervals between them.

  4. Random file data

    Finally, genkey asks for the names of files whose random bits can be used as the final components of the random data set. This step is optional. If you prefer, you can skip it and use only the random data already generated.

  5. Passphrase

    The passphrase is an identifying phrase that restricts key access to its owners. Choose your passphrase wisely and do not lose it. It's a good idea to write it down and store it in a safe deposit box or a safe.

  6. Certificate Signing Request

    Enter Y to send a CSR.

    Note: You must send a CSR and install a new certificate to use this key pair for SSL server transmissions. The test certificate generated by genkey is for testing purposes only, and does not authenticate your transmissions. Users will receive an error message when they encounter your test certificate.
  7. CA

    Select the CA you intend to petition for a certificate.

  8. Passphrase

    Enter your passphrase again, this time to verify that you are authorized to enter information related to the generation of your CSR.

  9. Country Name

    Enter the two-letter code for the country in which your Stronghold server resides.

  10. State Name

    Enter the full name of the state or province in which the server resides.

  11. Locality Name

    Enter the name of the city, town, or county in which the server resides.

  12. Organization Name

    Your organization name is required information.

  13. Organization Unit Name

    This information is optional. To skip this field, enter a period (.).

  14. Common Name

    This is typically the hostname of your server, such as www.random.com.

    The program prints your certificate signing request. Verify the information it contains before you proceed.

  15. Webmaster email address

  16. Webmaster phone number

  17. Certificate Authority

    Enter the email address of the CA to which you want to send the request if it differs from the default.

  18. Passphrase

    Genkey prompts you again for your passphrase for authentication, then generates and installs a self-signed certificate for test purposes. You can use this certificate until the CA responds to your request, but it does not authenticate your server.

When genkey has finished generating your key pair, be sure to create backups of your key files and store them in a secure directory. With the new server installed, you are ready to configure it as described in Chapter 2, "Configuration." When you receive the new certificate from your CA, see the "Installing a Certificate" section of Chapter 4, "Certificates and Certificate Authorities." For instructions on running the server, see Chapter 3, "Running the Server."


Upgrading an Existing Stronghold Server

If you already have a version of Stronghold, you can quickly upgrade it using the UPGRADE.sh script. The script asks you a few questions, then upgrades your server according to the parameters you specify:

  1. Old version number

    Select the version number of your existing Stronghold server.

  2. Apache directory (ServerRoot)

    Indicate the directory where your existing Apache server component is stored. The default is /usr/local/apache; enter a different pathname if Apache is installed elsewhere.

  3. SSLeay directory

    The default SSLeay directory is /usr/local/ssl. Enter a different pathname if you installed the SSL component elsewhere.

  4. Platform

    Enter the platform on which your Stronghold server runs.

The script upgrades the server, edits configuration and certificate files, and restarts the new server version. Your existing configuration files remain intact. For instructions on running the upgraded server, see Chapter 4, "Running the Server."


Contents