[Top] [Prev] [Next] [Last]
Download PDF:   US   UK
Download Postscript:   US   UK
Stronghold Web Server 2.4.1 Administration Guide
Chapter 2

Authentication and Encryption

Stronghold Web Server's mod_ssl module implements authentication and encryption using the Secure Socket Layer (SSL) and the Transport Security Layer (TLS). Both are protocols for transmitting encrypted data over TCP/IP networks. They serve two important purposes:

This chapter discusses authentication and encryption topics:



SSL and TLS

The Secure Socket Layer (SSL), created by Netscape Communications Corporation, has been the standard World Wide Web security protocol for several years. While it has proven effective in performing encryption, authentication, and data integrity operations, it has the disadvantage of being a proprietary protocol that is subject to several patents. While this does not affect its performance as a security solution, it is somewhat prohibitive to widespread development.



Transport Layer Security (TLS)

The Transport Layer Security (TLS) protocol was developed by the Internet Engineering Task Force (IETF) as the successor to SSL version 3, and is nearly identical to SSL except that it implements

You can find specifications and other detailed information about TLS at http://www.ietf.org/html.charters/tls-charter.html. Although few clients support it now, TLS is expected to be intergrated into many client products in the near future. In particular, the Mozilla Crypto Group is integrating SSLeay, including TLS support, into Netscape's newly released browser source code. For information about this project, see http://mozilla-crypto.ssleay.org/.



Enabling SSL or TLS

In order to enable SSL or TLS features for any host on the server, the following directive must be included in each <VirtualHost hostname:secure-port> section of the configuration file:

SSLFlag on

This directive enables encryption and site authentication functions. (Client authentication is optional and must be configured separately). The SSLProtocol directive is also required, to specify which security protocols are enabled. Stronghold Web Server supports SSL version 2, SSL version 3, and TLS version 1. SSLProtocol can enable one, two, or all three of them. For example:

The complete list of SSL/TLS directives appears in Chapter 7.



Encryption

Encryption is the encoding of data in order to hide its content from everyone except its intended recipient. The mathematical algorithms used to encrypt data are called ciphers. SSL and TLS are protocols for exchanging encrypted data over TCP/IP networks, including the World Wide Web. Stronghold Web Server supports both SSL and TLS.

Ciphers fall into two categories:

Figure 2-1: Encryption and Decryption with Public Key Cryptography

Under this scheme, a server host gives its public key to the client at the beginning of a secure session. The client uses it to encrypt its next transmission. The server uses its private key to decrypt that transmission. The private key should be carefully guarded. Stronghold encrypts its private keys by default.

Figure 2-2: Encryption and Decryption with Symmetric Cryptography

In order for two parties to share the same key, one must communicate it to the other privately. To do so, they use an asymmetric algorithm to encrypt the symmetric key so that it can only be decrypted by its intended recipient.

Symmetric algorithms are faster than public key algorithms, but public key algorithms are required to maintain privacy during the exchange of the faster symmetric keys. To preserve both efficiency and privacy, secure Web transactions begin with a public key exchange, followed by the exchange of a session key that implements a faster, symmetric cipher.

Figure 2-3: Session Key Exchange

A session may last for one or more transactions, and a session key encrypts the entire session. Because the session key is encrypted using public key cryptography, the security of the private key in any public key pair is crucial to the security of a site. To protect its private keys, Stronghold stores them in encrypted form and requires a pass phrase on startup.



Generating an Encryption Key Pair

Every key pair must be accompanied by a site certificate in order to work. Every host on the server-including all virtual hosts-must have its own key pair and certificate. Stronghold's genkey utility

  1. generates a key pair for any host,

  2. calls genreq to generate a certificate signing request (CSR), and then

  3. calls gencert to create a temporary certificate.

Genkey runs automatically during server installation to create keys and a CSR for the main server host. It must be run separately for each additional host on the server. "Site Certificates and Keys" on page 2-12 provides complete instructions for using this utility.



Controlling Stronghold's Ciphers

Although the client generates the session key, the server influences the process by sending its cipher preferences along with its certificate. The client generates a session key that follows the symmetric cipher most preferred by both the client and the server. The security of a cipher depends on

Some ciphers, such as DES-CBC3-MD5, have never been broken, at least not publicly. Cryptographers continuously test and scrutinize ciphers and occasionally succeed in breaking one that was formerly considered unbreakable. By seeking and publicizing weaknesses in ciphers, cryptographers can alert the public to security risks that were previously unknown. They can also find ways to improve ciphers or create stronger ones.

Stronghold interoperates with the ciphers listed below. Strong ciphers use 168-bit keys; 128- and 56-bit ciphers are considered moderately secure; and 40-bit ciphers have known security flaws and should not be used on the Internet.

Cipher-Type Security Description
DES-CBC3-MD5 Strong 3DES in CBC, MD5 hash, 168-bit key
DES-CBC3-SHA Strong 3DES in CBC, SHA hash, 168-bit key
EDH-RSA-DES-CBC3-SHA Strong Ephemeral Diffie-Helman with RSA authentication, 3DES in CBC, SHA hash, 168-bit key
EDH-DSS-DES-CBC3-SHA Strong Ephemeral Diffie-Helman with DSS authentication, 3DES in CBC, SHA hash, 168-bit key
RC4-MD5 Moderate RC4 cipher, MD5 hash, 128-bit key
RC4-SHA Moderate RC4 cipher, SHA hash, 128-bit key (SSLv3/TLSv1 only)
RC2-CBC-MD5 Moderate RC2-compatible cipher in CBC mode, MD5 hash, 128-bit key
DES-CBC-MD5 Moderate DES in CBC, MD5 hash, 56-bit key
DES-CBC-SHA Moderate DES in CBC, SHA hash, 56-bit key
EDH-RSA-DES-CBC-SHA Moderate Ephemeral Diffie-Helman with RSA authentication, DES in CBC, SHA hash, 56-bit key
EDH-DSS-DES-CBC-SHA Moderate Ephemeral Diffie-Helman with DSS authentication, DES in CBC, SHA hash, 56-bit key
EXP-DES-CBC-SHA Weak DES in CBC, SHA hash, 40-bit key (SSLv3/TLSv1 only)
EXP-RC4-MD5 Weak Weakened for export, RC4 cipher, MD5 hash, 40-bit key
EXP-RC2-CBC-MD5 Weak Weakened for export, RC2-compatible cipher in CBC mode, MD5 hash, 40-bit key
EXP-EDH-RSA-DES-CBC Weak Weakened for export, Ephemeral Diffie-Helman with RSA authentication, DES in CBC, 40-bit key
EXP-EDH-DSS-DES-CBC-SHA Weak Weakened for export, Ephemeral Diffie-Helman with DSS authentication, DES in CBC, 40-bit key

To see a list of the available ciphers, run the following command:

# ssleay ciphers -v

Any object on the site can be configured to require certain ciphers and forbid others. Three configuration directives controll the ciphers used in Web transactions:

The value for each of these directives is a colon-separated list of ciphers. Use the cipher abbreviations shown in the table above. SSLCipherList can also take a number of cipher aliases as values, shown in the table on page 7-110. For example, the following configuration allows three different ciphers for access to the virtual host (and its /about directory), but only two for access to its /employees directory:

<VirtualHost www.mpp.org:443>

 SSLFlag on
 SSLCipherList DES-CBC3-MD5:DES-CBC3-SHA:RC4-MD5

 <Directory /about>
 FancyIndexing on
 </Directory>

 <Directory /employees>
 SSLRequireCipher DES-CBC3-MD5
 SSLRequireCipher DES-CBC3-SHA
 </Directory>

 </VirtualHost>

The same effect could be achieved by using

SSLBanCipher RC4-MD5

instead of the two SSLRequireCipher directives.

NOTE: Use either SSLRequireCipher or SSLBanCipher. Never use both for the same object.



Authentication

Authentication is the positive identification of a network entity, such as a client or a server. Site authentication has been standard on secure servers for some time, because users require assurance that the data they receive from a site is actually being transmitted by that site, rather than by an eavesdropper or "man in the middle." If an eavesdropper can impersonate a site, he can substitute other data in place of the data the user expects to receive. Recently, popular browsers also began supporting client authentication. Stronghold Web Server supports both site authentication and client authentication.

SSL and TLS authentication takes the form of X.509 certificates. Certificates are issued by certification authorities (CAs), which act as trusted third parties. Each certificate contains

The signature is a hash of the body of the certificate, encrypted with the CA's private key. Reputable CAs keep their private keys absolutely secret, ensuring that no one can impersonate the CA and issue forged certificates. This prevents a man in the middle from intercepting a certificate, replacing its public key with his own, then faking a CA signature for the false certificate.

When one entity receives a certificate from another, it first creates a hash of the body of the certificate, then uses the CA's public key to decrypt the signature and reveal the original hash. If the two hash blocks are identical, authentication is successful. Successful authentication verifies that

Once an entity is authenticated, its public key can safely be used to encrypt subsequent network transactions, including the crucial session key exchange described on page 2-5.

Stronghold Web Server supports three different kinds of certificates:



Independent Certification Authorities

Independent Certification Authorities issue certificates that are accepted worldwide. There are two major, independent CAs:

Each of these offers site certificates and client certificates to the general public for a fee. If Stronghold Web Server is running over the World Wide Web, each host on the server must have a site certificate signed by one of these CAs in order to attain credibility when performing secure transactions. Likewise, it's a good idea to accept only client certificates signed by these CAs, unless you choose to run your own private CA as described in "Private Certification Authorities" on page 2-11.

For policy information and current rates, consult the Web site of the CA you intend to petition for a certificate. If you have purchased the Stronghold/Thawte bundle, see "Acquiring a New Certificate and Key Pair" on page 2-12 for information about obtaining your Thawte certificate.



Private Certification Authorities

Private Certification Authorities exist to provide site certificates and client certificates to an exclusive group, usually the employees or clients of a corporate entity. In some organizations, only a private CA can meet the organization's security policy. Private CAs can also be useful for issuing special client certificates used only to gain access to the CA's site, as in the case of some online subscription services. If your organization already has a private CA and Stronghold runs only on a local area network within that organization, you can choose to use a site certificate issued by the private CA.

"Private Certification Authorities" on page 2-20 explains how to create and run a private Certification Authority.



Site Certificates and Keys

Each virtual host supported by the server is a site. Because a browser compares the hostname or IP number on a certificate with the one it requested, every host requires its own certificate and key pair. The certificate and the private key are stored in separate files:

Stronghold Web Server sends a site certificate file to any client that requests access to the SSL/TLS port, usually port 443. The client uses the public key in the certificate file to encrypt the session key, and Stronghold uses the private key in the key file to decrypt the session key. Therefore, the private key in the key file must match the public key in the certificate file.

This section explains how to acquire, install, and manage site certificates and key pairs.



Acquiring a New Certificate and Key Pair

In order to conduct secure transactions, every host-including virtual hosts-must have a key pair and a site certificate. Stronghold Web Server's genkey utility generates a key pair for your main host, then calls genreq to generate a certificate signing request (CSR), and finally calls gencert to create a temporary certificate that you can use until your CA responds. The temporary certificate is signed with your site's private key.

Figure 2-4: Key Pair and Certificate Generation
NOTE: Since browsers do not recognize your site as a trusted CA, the temporary certificate provides no authentication. A client that encounters a temporary certificate passes a warning to the user. You must acquire a certificate from a trusted CA in order to conduct secure transactions over the Web.

Stronghold Web Server's installation program also runs genkey as part of the setup sequence. "Generating a New Key Pair and Requesting a New Certificate" on page 2-27 provides complete instructions for using genkey. Genreq can be run separately, as described in "Requesting a New Certificate for an Existing Key Pair" on page 2-38. Gencert can also be run separately, as described in "Generating a Test Certificate" on page 2-38.

When a CA returns a new site certificate, Stronghold's getca utility installs it as ServerRoot/ssl/certs/hostname.cert. This file-naming scheme keeps site certificates organized, since the server may support many virtual hosts, each with its own site certificate. See "Installing a Site Certificate" on page 2-39 for full getca instructions.



Renewing an Expired Certificate

Site certificates are generally issued and billed for one-year periods. Stronghold notifies the server administrator via email when a site certificate is about to expire. When this happens, use the genreq utility to request a new certificate. The CA sends a new certificate and bills you for another year. For full instructions, see "Requesting a Renewed Certificate" on page 2-34.

The new certificate is identical to the original, except for its expiration date. After moving the old certificate, install the new one as described in "Installing a Site Certificate" on page 2-39. The original key pair works with the new certificate; do not generate a new one.



Troubleshooting Mismatched Certificates and Keys

When a certificate file and key file have matching filenames, such as www.host.com.cert and www.host.com.key, Stronghold assumes that the key file contains the private key that matches the public key in the certificate file. If not, Stronghold cannot decrypt the session key and must terminate the session. When this occurs, Stronghold generates an error like this one:

RSA decrypt error - i=-1 enc_bits=5

If you receive this error, or you are otherwise unsure that a host's certificate file matches its key file, use Stronghold's checkcert utility to compare the two files. See "Comparing Certificates and Key Pairs" on page 2-37 for complete instructions.



Client Authentication

Stronghold Web Server supports client authentication with X.509 certificates. Client certificates are similar to server certificates, and they are currently the most reliable means of identifying users and restricting access. The current versions of Netscape Navigator and Microsoft Internet Explorer both support client certificates.

Until recently, most browsers only supported basic authentication, which relies on usernames and passwords to authenticate users. The primary disadvantage of basic authentication is that usernames and passwords can be communicated through unencrypted transactions, allowing eavesdroppers to obtain the authentication criteria and access restricted material.

Client certificates can also be password-protected, but only on the user's local host. The browser prompts the user for a password to prevent others from using the client certificate, but the password does not enter the network.

Users can obtain client certificates from an independent CA or a private CA. Client certificates issued by major CAs are designed to provide authentication that any secure server can accept. Stronghold recognizes client certificates signed by Verisign and Thawte. To accept other CAs, including private CAs, see "Installing New Client CA Certificates" on page 2-16.



Controlling Access with Client Certificates

Since client certificates provide a reliable means of authenticating users, they also provide a reliable means of restricting access to material available from the server. For example, a directory can be configured to require a client certificate from any client who requests a file within that directory, and to require that the certificate meet certain criteria. To control access in this way, use the SSLVerifyClient, SSL_Require, and SSL_Group directives. SSL_Group is optional.

SSLVerifyClient indicates whether a client certificate is required in order to access a host. It has three possible values:

Value Description
0 A client certificate is not required
1 A client certificate is optional
2 A client certificate is required

When SSLVerifyClient is set to 2, Stronghold Web Server requires a client certificate with all requests. The server checks each certificate's signature using a public key from one of the CA certificates in the ServerRoot/ssl/CA/client-rootcerts.pem file. If the signature is invalid or originates with a CA whose certificate is not in client-rootcerts.pem, the request fails.

Access control with client certificates is enabled when

SSL_Require sets the criteria used to accept or reject client certificates. A client certificate must meet these criteria in order to receive the requested material. This directive's value can be

An SSL_Require expression can specify any parameter that client certificates contain. For example, it can specify only certificates that belong to clients in Denmark, were issued by your private CA, contain public keys larger than 512 bits, have previously been logged by the server, or belong to Sameer Parekh. The complete rules for building SSL_Require expressions appear on page 7-97.

SSL_Group is a related directive that creates client authentication groups whose members all meet the same criteria. Its valid values are identical to those for SSL_Require, except that the certificate criteria is preceded by a group name. The group name can be used as the value for SSL_Require, specifying that the certificate must meet the criteria for that group. If the same client certificate criteria is used for many different objects, SSL_Group provides a convenient shortcut.



Installing New Client CA Certificates

By default, Stronghold Web Server accepts client certificates signed by Verisign and Thawte. You can choose to accept certificates signed by other CAs, such as your private CA or another trusted CA. To do so, you must install the CA's client root certificate. This is the certificate that contains the public key counterpart of the priate key used to sign client certificates. If the certificate is part of a chain, you must install all certificates in the chain.

There are two ways to install a CA certificate:


To append a CA certificate to the root file

  1. Make sure the new CA certificate is in PEM format.

  2. Switch to the ServerRoot/ssl/CA/ directory:

    # cd ServerRoot/ssl/CA
  3. Append the new CA certificate to the existing certificate file:

    # cat newcert.pem >> client-rootcerts.pem
  4. If you are installing a certificate chain, repeat these steps for each certificate in the chain.


To save a CA certificate in the CA directory

  1. Make sure the new CA certificate is in PEM format.

  2. Copy the certificate file to the ServerRoot/ssl/CA/ directory:

    # cp newcert.pem ServerRoot/ssl/CA/newcert.pem
  3. Switch to the ServerRoot/ssl/CA/ directory.

  4. Create a hash of the certificate file using the ssleay x509 utility:

    # ssleay x509 -hash -noout < newcert.pem
     5a35be
  5. Rename the certificate according to its hash:

    # mv newcert.pem 5a35be.0

    If a file with this hash name already exists, name this one 5a35be.1 instead. Alternatively, you can create a symbolic link with the hash name instead of renaming the file itself:

    # ln -s newcert.pem 5a35be.0
  6. If you are installing a certificate chain, repeat these steps for each certificate in the chain.

Once you have installed the new CA certificate or chain, Stronghold Web Server can automatically verify signatures on all client certificates signed by that CA.



Proxy Authentication

Proxy transactions have two sides: a client side and a server side. On the client side, the proxy server accepts requests and submits responses like a regular server. The proxy server uses its site certificate to authenticate itself on the client side, and may also require that the browser authenticate itself with a client certificate. On the server side, the proxy server submits requests and accepts responses as if it were a client. This is proxy authentication. Proxy authentication can take place in two ways, depending on whether you have configured normal proxy service or a mirror proxy:



Proxy Client Certificates

A proxy client certificate is identical in format to a normal client certificate, but authenticates your proxy server rather than a browser. CAs typically use one set of keys to sign client certificates and another set of keys to sign site certificates. Since each public key is embedded in a single certificate, remote servers use a different set of CA certificates to verify client certificates than browsers use to verify site certificates. For this reason, you cannot use your server's site certificate for proxy client authentication.

NOTE: Never use any client certificate other than one specifically intended for the proxy server. If you use a personal client certificate, other users can use the proxy server to access secure sites that accept your certificate.

Currently, independent CAs do not offer proxy client certificates. To work around this limitation, you can either

Remote servers on the Internet may not accept proxy client certificates issued by a private CA, because they do not have the CA's certificate on file and have no means of verifying the signature. A proxy client certificate from a private CA works best on a private network where all servers are configured to recognize the private CA. For more information, see "Private Certification Authorities" on page 2-20.

Once you have obtained a proxy client certificate, you must use SSLProxyMachineCertPath or SSLProxyMachineCertFile to set its location. If you have multiple proxy client certificates, you can store them in separate files in the SSLProxyMachineCertPath, or append them to the SSLProxyMachineCertFile.



Remote Server Authentication

When performing SSL or TLS mirror proxy transactions, Stronghold Web Server receives a site certificate from every remote server it contacts. In order to verify each site certificate's signature, it uses a collection of server root certificates from common CAs:

By default, Stronghold Web Server accepts server certificates signed by Verisign and Thawte. You can choose to accept certificates signed by other CAs, such as your private CA or another trusted CA. To do so, you must install the CA's server root certificate. This is the certificate that contains the public key counterpart of the private key used to sign server certificates. If the certificate is part of a chain, you must install all certificates in the chain.

There are two ways to install a CA certificate:


To append a CA certificate to the root file

  1. Make sure the new CA certificate is in PEM format.

  2. Switch to the ServerRoot/ssl/CA/ directory:

    # cd ServerRoot/ssl/CA
  3. Append the new CA certificate to the existing certificate file:

    # cat newcert.pem >> server-rootcerts.pem
  4. If you are installing a certificate chain, repeat these steps for each certificate in the chain.


To save a CA certificate in the CA directory

  1. Make sure the new CA certificate is in PEM format.

  2. Copy the certificate file to the ServerRoot/ssl/CA/ directory:

    # cp newcert.pem ServerRoot/ssl/CA/newcert.pem
  3. Switch to the ServerRoot/ssl/CA/ directory.

  4. Create a hash of the certificate file using the ssleay x509 utility:

    # ssleay x509 -hash -noout < newcert.pem
     5a35be
  5. Rename the certificate file according to its hash:

    # mv newcert.pem 5a35be.0

    If a file with this hash name already exists, name this one 5a35be.1 instead. Alternatively, you can create a symbolic link with the hash name instead of renaming the file itself:

    # ln -s newcert.pem 5a35be.0
  6. If you are installing a certificate chain, repeat these steps for each certificate in the chain.

Once you have installed the new CA certificate or chain, Stronghold Web Server can automatically verify signatures on all server certificates signed by that CA.



Private Certification Authorities

You can create a private Certification Authority for your intranet to certify internal Web servers. Since these servers are typically accessed only by internal clients, a private CA can provide a sufficient level of trust within certain security policies. However, your external Web server must be certified by an independent CA in order to provide a sufficient level of security for Internet transactions.

If an intruder gains access to your private CA, he can forge certificates and use them to gain access to secure transactions or to impersonate your server. It is your responsibility to follow an adequate security policy. Choose your CA platform carefully and maintain it under the strongest security:

Stronghold Web Server provides tools for setting up a basic Certification Authority. To set up a CA, you must

You also have the option to use Xcert Sentry in tandem with Stronghold Web Server. Xcert Sentry is a sophisticated private-CA tool that includes a Stronghold module, Lightweight Directory Access Protocol (LDAP) support, and an easy-to-use graphical interface. If you want to certify clients as well as servers, you must use Sentry. For more information, see http://www.xcert.com/.



Setting Up a CA

The ServerRoot/ssl/bin/makeca script sets up the CA by generating a key pair and a self-signed certificate for the CA. You use the private key to sign server certificates. Clients use the self-signed certificate to verify the CA's signature on server certificates.


To create a private CA

  1. Run the makeca utility:

    # makeca

    The program prompts you for a key size.

  2. Enter the key size in bits.

    NOTE: Keys sizes must be either 512 or 1024 for compatibility with certain browsers. We recommend 1024 bits. Keys larger than 1024 bits are incompatible with some versions of Netscape Navigator and Microsoft Internet Explorer, and with other browsers that use RSA's BSAFE cryptography toolkit.

    The program generates some random data with which to create a unique key pair. Then it prompts you for random keystrokes.

  3. Tap out some random keystrokes.

    The program generates more random data based on the intervals between your keystrokes. It also displays a counter that moves closer to zero as you type. Stop when the counter reads 0 and the program beeps:

    0 * -Enough, thank you.
  4. Enter the two-letter code for your country.

    This is the same two-letter code used in hostnames in your country, such as DE for Germany or JP for Japan. For the complete list of valid country codes, see Appendix D.

  5. Enter the full name of your state or province.

  6. Enter the name of your city, town, or other locality.

  7. Enter the name of your organization.

  8. Enter the name of your unit within the organization.

  9. Enter the domain name of your site.

    This information appears in your CA certificate, which other sites use to verify the certificates you sign.

Once the Certification Authority has been built, you need to



Configuring SSLeay

The default SSLeay settings are recommended. However, in order to use the CA according to your organization's security policy, you may need to edit the policy section of ServerRoot/ssl/CA/ssleay.conf.

The policy field gives the name of the current CA policy:

policy = policy_match

The sections that follow the policy field give the parameters of one or more CA policies whose names appear in brackets. The policy field must be set to one of the bracketed values. The default ssleay.conf file contains two policies: policy_match and policy_anything. You can copy one of these and insert a different name between the brackets to create a new policy.

# For the CA policy
 [ policy_match ]
 countryName = match
 stateOrProvinceName = match
 organizationName = match
 organizationalUnitName = optional
 commonName = supplied
 emailAddress = optional

 # For the 'anything' policy
 [ policy_anything ]
 countryName = optional
 stateOrProvinceName = optional
 localityName = optional
 organizationName = optional
 organizationalUnitName = optional
 commonName = supplied
 emailAddress = optional

Each policy parameter field corresponds to a certificate request field, and must have one of these three values:

Value Description
match The contents of the field must match the same field in the CA certificate.
optional The field is not required in the certificate request.
supplied The field must be supplied in the certificate request.

For example, policy_match is useful for most private CAs because it requires that certificate requests come from the same country, state or province, and organization as the CA, and that each request specify the common name of the server requesting certification. If your CA is limited to your department, you can set the organizationalUnitName field to "match."

Normally, the policy parameters are the only fields you may need to edit. If you want to edit other fields, be sure to read the file comments carefully.



Signing Certificates

Before you begin signing certificates, you must define your organization's policy regarding the level of documentation required with CSRs. In order to verify the origin and content of each CSR, you should require separate documentation with each CSR.

You can read the information contained in any CSR by passing it through the ServerRoot/ssl/bin/req program:

# ssleay req -text -noout < CSRfilename

The program prints the CSR in plaintext.

Next, you must establish a procedure for collecting and processing CSRs. For example, you can set up a special email address exclusively for submitting CSRs. You could also set up a Web page with instructions and an HTML form where users can paste and submit their CSRs. Depending on the number of CSRs you need to accommodate, you can construct an automatic mechanism for signing certificates, or you can sign them one by one.


To sign a certificate

  1. Save the CSR to a temporary file such as /tmp/csr.

  2. Run sign_csr:

    # sign_csr /tmp/csr
  3. Press Return.

  4. Enter the CA pass phrase that you set when you ran makeca.

    The program checks the signature on the request, then prints the request fields:

    Check that the request matches the signature
     Signature ok
     The Subjects Distinguished Name is as follows
     countryName :PRINTABLE:'US'
     stateOrProvinceName :PRINTABLE:'California'
     localityName :PRINTABLE:'Oakland'
     organizationName :PRINTABLE:'C2Net'
     organizationalUnitName:PRINTABLE:'Testing/QA'
     commonName :PRINTABLE:'test7.c2.net'
     Certificate is to be certified until Mar 31 22:19:53 1998 GMT (365 days)
     Sign the certificate? [y/n]:

    The expiration date is based on the default_days field in ssleay.conf.

  5. Enter "Y" to sign the certificate or N to abort.

    The program prompts you to commit the signature:

    1 out of 1 certificate requests certified, commit? [y/n]
  6. Enter "Y" to commit or "N" to abort.

    When you enter "Y," the program prints the contents of the new certificate and saves it in the ServerRoot/ssl/CA/ directory. The filename of each new certificate is a number in the series of all certificates signed by this CA. For example, the first certificate you sign is 01.pem, the next is 02.pem, and so on.

  7. Return the newly-signed certificate to the applicant-for example, as an email attachment.



Security Utilities

The previous sections discussed several of Stronghold Web Server's security utilities, located in the ServerRoot/bin/ directory. This section describes how to use the security utilities for

Since all of these utilities are located in the ServerRoot/bin/ directory, you can add this directory to your PATH variable for convenience.


To add the utilities directory to the PATH variable

  1. Edit the PATH variable according to the type of UNIX shell you are using:

    Be sure to replace ServerRoot with the actual path to your root server directory.

  2. Save the file.



Changing the Pass Phrase

The change_pass utility changes the pass phrase used to encrypt the private key for a host:

# bin/change_pass hostname

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



Decrypting a Private Key

The decrypt_key utility decrypts the private key for a host:

# bin/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, if obtained by an intruder, can be used to impersonate your server and decrypt all connections to it.



Generating a New Key Pair and Requesting a New Certificate

The genkey utility generates a public/private key pair, generates a certificate signing request, and generates a test certificate for use in the interim. This section provide complete instructions for using genkey to generate a key pair and request a signed certificate from Verisign, Thawte, and other CAs.


To generate a key pair and request a Verisign certificate

  1. Run genkey, specifying the name of the host or virtual host:

    # bin/genkey hostname

    Genkey shows you the filenames and location of the key file and certificate file it is about the generate:

    The key will be stored in
    ServerRoot/ssl/private/hostname.key
     The certificate stored in
    ServerRoot/ssl/certs/hostname.cert
  2. Press Return.

    Genkey reminds you to be sure you are not overwriting an existing key pair and certificate.

  3. Press Return.

    Genkey prompts you to specify the size of the key you want to generate.

  4. Enter a key size in bits.

    NOTE: Keys sizes must be either 512 or 1024 for compatibility with certain browsers. We recommend 1024 bits. Keys larger than 1024 bits are incompatible with some versions of Netscape Navigator and Microsoft Internet Explorer, and with other browsers that use RSA's BSAFE cryptography toolkit.

    Genkey generates some random data with which to create a unique key pair. Then it prompts you for random keystrokes.

  5. Tap out some random keystrokes.

    Genkey generates more random data based on the intervals between your keystrokes. It also displays a counter that moves closer to zero as you type. Stop when the counter reads 0 and genkey beeps:

    0 * -Enough, thank you.

    Genkey generates the key pair and saves it at ServerRoot/ssl/private/hostname.key. Then it asks whether you want to call genreq to send a CSR.

  6. Enter "Y" to send a CSR.

    Genreq takes over for genkey, and asks you which CA you want to petition for a certificate:

    Please choose the CA you would like to use:
     A) VeriSign
     B) Thawte
     C) Other
     Choose: A
  7. Enter "A."

  8. Enter the two-letter code for your country.

    This is the same two-letter code used in hostnames in your country, such as DE for Germany or JP for Japan. For the complete list of valid country codes, see Appendix D.

  9. Enter the full name of your state or province.

  10. Enter the name of your city, town, or other locality.

  11. Enter the name of your organization.

  12. Enter the name of your unit within the organization.

  13. Enter the fully-qualified domain name of your site.

    The program prints the certificate signing request (CSR), which looks something like this:

    -----BEGIN NEW CERTIFICATE REQUEST-----
     MIIBEzCBzgIBADB7MQswCQYDVQQGEwJVUzETMBEGA1UECBMKQ2FsaWZvcm5pYTEQ
     MA4GA1UEBxMHT2FrbGFuZDEbMBkGA1UEChMSQzJOZXQgU29mdHdhcmUgSW5jMRAw
     DgYDVQQLEwdUZXN0aW5nMRYwFAYDVQQDEw1nYWJiZXIuYzIubmV0MEwwDQYJKoZI
     hvcNAQEBBQADOwAwOAIxAJukoQhq4LanG2k+/LnRTGJAcgv9LJPsdfCsjqRs8ygo
     yaw4ucOEdx+WdnM0x36NcQIDAQABMA0GCSqGSIb3DQEBBAUAAzEABRLR6IkG70oN
     G1MnvuMDeWou4kIvc98ysjssCNKsDKsHAXBSEbfsIQs5JRNagVBW
     -----END NEWCERTIFICATE REQUEST-----
  14. Copy the CSR.

  15. Using your Web browser, access https://digitalid.verisign.com/ss_getCSR.html.

    This is Verisign's Digital ID Enrollment page.

  16. Paste the CSR into the text box on the Digital ID Enrollment page.

  17. Click Continue.

  18. Follow Verisign's online instructions until you complete the enrollment procedure.

  19. Return to the shell window.

  20. Enter the two-letter code of your country.

    This is the same two-letter code used in hostnames in your country, such as DE for Germany or JP for Japan. For the complete list of valid country codes, see Appendix D.

  21. Enter the full name of your state or province.

  22. Enter the name of your organization.

  23. Enter the name of your unit within the organization.

  24. Enter the "common name," or fully-qualified domain name, of your server.

  25. Enter the pass phrase you want to use for this host.

    NOTE: Even if you have many hosts, Stronghold Web Server only asks for one pass phrase on startup. For this reason, you should use the same pass phrase for all certificate/key pairs for all hosts.

  26. Enter the pass phrase again for verification.


To generate a key pair and request a Thawte certificate

  1. Run genkey, specifying the name of the host or virtual host:

    # bin/genkey hostname

    Genkey shows you the filenames and location of the key file and certificate file it is about the generate:

    The key will be called hostname.key.
     The certificate will be called hostname.cert.
     They will be stored in /usr/local/www/ssl
  2. Press Return.

    Genkey reminds you to be sure you are not overwriting an existing key pair and certificate.

  3. Press Return.

    Genkey prompts you to specify the size of the key you want to generate.

  4. Enter a key size in bits.

    NOTE: Keys sizes must be either 512 or 1024 for compatibility with certain browsers. We recommend 1024 bits. Keys larger than 1024 bits are incompatible with some versions of Netscape Navigator and Microsoft Internet Explorer, and with other browsers that use RSA's BSAFE cryptography toolkit.

    Genkey generates some random data with which to create a unique key pair. Then it prompts you for random keystrokes.

  5. Tap out some random keystrokes.

    Genkey generates more random data based on the intervals between your keystrokes. It also displays a counter that moves closer to zero as you type. Stop when the counter reads 0 and genkey beeps:

    0 * -Enough, thank you.

    Genkey generates the key pair and saves it at ServerRoot/ssl/private/hostname.key. Then it asks whether you want to call genreq to send a CSR.

  6. Enter "Y" to send a CSR.

    Genreq takes over for genkey, and asks you which CA you want to petition for a certificate:

    Please choose the CA you would like to use:
     A) VeriSign
     B) Thawte
     C) Other
     Choose: B
  7. Enter "B."

  8. Enter the two-letter code for your country.

    This is the same two-letter code used in hostnames in your country, such as DE for Germany or JP for Japan. For the complete list of valid country codes, see Appendix D.

  9. Enter the full name of your state or province.

  10. Enter the name of your city, town, or other locality.

  11. Enter the name of your organization.

  12. Enter the name of your unit within the organization.

  13. Enter the fully-qualified domain name of your site.

  14. Press Return.

    The program prints your CSR.

  15. Copy the CSR.

  16. Using your Web browser, access https://www.thawte.com/cgi-bin/server/step1.sioux.

    This is the Thawte Server Cert Request Step 1 page.

  17. Follow Thawte's online instructions until you complete their enrollment procedure.

  18. Return to the shell window.

  19. In your shell window, press Return.

  20. Enter "Y" to confirm that you have successfully completed the Thawte application process.

    Now you must enter the same information to generate a temporary certificate, which you can use until your CA sends a signed certificate.

  21. Enter the two-letter code of your country.

    This is the same two-letter code used in hostnames in your country, such as DE for Germany or JP for Japan. For the complete list of valid country codes, see Appendix D.

  22. Enter the full name of your state or province.

  23. Enter the name of your organization.

  24. Enter the name of your unit within the organization.

  25. Enter the "common name," or fully-qualified domain name, of your server.

  26. Enter the pass phrase you want to use for this host.

    NOTE: Even if you have many hosts, Stronghold only asks for one pass phrase on startup. For this reason, you should use the same pass phrase for all certificate/key pairs for all hosts.

  27. Enter the pass phrase again for verification.


To generate a key pair and request a nonstandard certificate

  1. Run genkey, specifying the name of the host or virtual host:

    # bin/genkey hostname

    Genkey shows you the filenames and location of the key file and certificate file it is about the generate:

    The key will be called hostname.key.
     The certificate will be called hostname.cert.
     They will be stored in /usr/local/www/ssl
  2. Press Return.

    Genkey reminds you to be sure you are not overwriting an existing key pair and certificate.

  3. Press Return.

    Genkey prompts you to specify the size of the key you want to generate.

  4. Enter a key size in bits.

    NOTE: Keys sizes must be either 512 or 1024 for compatibility with certain browsers. We recommend 1024 bits. Keys larger than 1024 bits are incompatible with some versions of Netscape Navigator and Microsoft Internet Explorer, and with other browsers that use RSA's BSAFE cryptography toolkit.

    Genkey generates some random data with which to create a unique key pair. Then it prompts you for random keystrokes.

  5. Tap out some random keystrokes.

    Genkey generates more random data based on the intervals between your keystrokes. It also displays a counter that moves closer to zero as you type. Stop when the counter reads 0 and genkey beeps:

    0 * -Enough, thank you.

    Genkey generates the key pair and saves it at ServerRoot/ssl/private/hostname.key. Then it asks whether you want to call genreq to send a CSR.

  6. Enter "Y" to send a CSR.

    Genreq takes over for genkey, and asks you which CA you want to petition for a certificate:

    Please choose the CA you would like to use:
     A) VeriSign
     B) Thawte
     C) Other
  7. Enter "C."

  8. Enter the email address for certificate requests from your CA.

  9. Enter the two-letter code of your country.

    This is the same two-letter code used in hostnames in your country, such as DE for Germany or JP for Japan. For the complete list of valid country codes, see Appendix D.

  10. Enter the full name of your state or province.

  11. Enter the name of your organization.

  12. Enter the name of your unit within the organization.

  13. Enter the "common name," or fully-qualified domain name, of your server.

  14. Enter the email address of this server's administrator.

  15. Enter the phone number of this server's administrator.

  16. If the information you entered is correct, press Return to generate the CSR.

    If you made a mistake while entering the information, press ^C to exit.

  17. Accept the default email submission address for the CA you selected, or use a different one.

    • To accept the default email address, press Return.

    • To use a different address, enter it at the prompt and press Return.

    Now you must enter the same information to generate a temporary certificate, which you can use until your CA sends a signed certificate.

  18. Enter the two-letter code of your country.

    This is the same two-letter code used in hostnames in your country, such as DE for Germany or JP for Japan. For the complete list of valid country codes, see Appendix D.

  19. Enter the full name of your state or province.

  20. Enter the name of your organization.

  21. Enter the name of your unit within the organization.

  22. Enter the "common name," or fully-qualified domain name, of your server.

  23. Enter the pass phrase you want to use for this host.

    NOTE: Even if you have many hosts, Stronghold Web Server only asks for one pass phrase on startup. For this reason, you should use the same pass phrase for all certificate/key pairs for all hosts.

  24. Enter the pass phrase again for verification.



Requesting a Renewed Certificate

Stronghold Web Server notifies you when a certificate is about to expire and automatically prompts you to run genreq. Do this promptly; an expired certificate prevents users from connecting to secured sites on your server. Use genreq to send a certificate renewal request to your CA:

# bin/genreq hostname

This section contains complete instuctions for requesting a renewed certificate from Verisign, Thawte, and other CAs.


To request a renewed Verisign certificate

  1. Run genreq:

    # bin/genreq hostname

    Genreq asks you which CA you want to petition for a certificate:

    Please choose the CA you would like to use:
     A) VeriSign
     B) Thawte
     C) Other
     Choose: A
  2. Enter "A."

  3. Enter the two-letter code for your country.

    This is the same two-letter code used in hostnames in your country, such as DE for Germany or JP for Japan. For the complete list of valid country codes, see Appendix D.

  4. Enter the full name of your state or province.

  5. Enter the name of your city, town, or other locality.

  6. Enter the name of your organization.

  7. Enter the name of your unit within the organization.

  8. Enter the fully-qualified domain name of your site.

    The program prints the certificate signing request (CSR), which looks something like this:

    -----BEGIN NEW CERTIFICATE REQUEST-----
     MIIBEzCBzgIBADB7MQswCQYDVQQGEwJVUzETMBEGA1UECBMKQ2FsaWZvcm5pYTEQ
     MA4GA1UEBxMHT2FrbGFuZDEbMBkGA1UEChMSQzJOZXQgU29mdHdhcmUgSW5jMRAw
     DgYDVQQLEwdUZXN0aW5nMRYwFAYDVQQDEw1nYWJiZXIuYzIubmV0MEwwDQYJKoZI
     hvcNAQEBBQADOwAwOAIxAJukoQhq4LanG2k+/LnRTGJAcgv9LJPsdfCsjqRs8ygo
     yaw4ucOEdx+WdnM0x36NcQIDAQABMA0GCSqGSIb3DQEBBAUAAzEABRLR6IkG70oN
     G1MnvuMDeWou4kIvc98ysjssCNKsDKsHAXBSEbfsIQs5JRNagVBW
     -----END NEWCERTIFICATE REQUEST-----
  9. Copy the CSR.

  10. Using your Web browser, access https://digitalid.verisign.com/ss_getCSR.html.

  11. Follow Verisign's online instructions for completing the certificate enrollment process.

  12. In your shell window, press Return.

  13. Enter "Y" to confirm that you have successfully completed the Verisign application process.


To request a renewed Thawte certificate

  1. Run genreq:

    # bin/genreq hostname

    Genreq asks you which CA you want to petition for a certificate:

    Please choose the CA you would like to use:
     A) VeriSign
     B) Thawte
     C) Other
     Choose: B
  2. Enter "B."

  3. Enter the two-letter code for your country.

    This is the same two-letter code used in hostnames in your country, such as DE for Germany or JP for Japan. For the complete list of valid country codes, see Appendix D.

  4. Enter the full name of your state or province.

  5. Enter the name of your city, town, or other locality.

  6. Enter the name of your organization.

  7. Enter the name of your unit within the organization.

  8. Enter the fully-qualified domain name of your site.

  9. Press Return.

    The program prints your certificate signing request (CSR).

  10. Copy the CSR.

  11. Using your Web browser, access https://www.thawte.com/cgi-bin/server/step1.sioux.

  12. Follow Thawte's online instructions for completing the certificate enrollment process.

  13. In your shell window, press Return.

  14. Enter "Y" to confirm that you have successfully completed the Thawte application process.


To request a renewed, nonstandard certificate

  1. Run genreq:

    # bin/genreq hostname

    Genreq asks you which CA you want to petition for a certificate:

    Please choose the CA you would like to use:
     A) VeriSign
     B) Thawte
     C) Other
  2. Enter "C."

  3. Enter the email address for certificate requests from your CA.

  4. Enter the two-letter code of your country.

    This is the same two-letter code used in hostnames in your country, such as DE for Germany or JP for Japan. For the complete list of valid country codes, see Appendix D.

  5. Enter the full name of your state or province.

  6. Enter the name of your organization.

  7. Enter the name of your unit within the organization.

  8. Enter the "common name," or fully-qualified domain name, of your server.

  9. Enter the email address of this server's administrator.

  10. Enter the phone number of this server's administrator.

  11. If the information you entered is correct, press Return to generate the CSR.

    If you made a mistake while entering the information, press ^C to exit.

  12. Accept the default email submission address for the CA you selected, or use a different one.

    • To accept the default email address, press Return.

    • To use a different address, enter it at the prompt and press Return.



Comparing Certificates and Key Pairs

The checkcert utility compares a certificate to the current key pair for a host.


To compare a certificate to a key pair

  1. Run checkcert, specifying the name of the host whose certificate and key will be checked:

    # checkcert hostname

    Checkcert asks for the pass phrase.

  2. Enter the pass phrase for this host.

  3. If the certificate does not match the key file, press Return.

    Checkcert prints a message explaining that this host cannot perform SSL- or TLS-secured transactions without a matching certificate and key pair.

  4. If there is another key file associated with this host, move it to the ServerRoot/ssl/private/ directory and run checkcert again to see whether that key pair matches the certificate.

  5. If there is another certificate file associated with this host, move it to the ServerRoot/ssl/certs/ directory and run checkcert again to see whether that certificate matches the key pair.

  6. If you cannot match a key file with a valid certificate file, use genreq to request a new certificate that matches an existing key file:

    # genreq hostname


Requesting a New Certificate for an Existing Key Pair

The genreq utility generates a certificate signing request based on the existing key pair for a host:

# bin/genreq hostname

You must specify a hostname to denote the correct key pair file, since key files are named by hostname. If you specify an incorrect key pair file, the new certificate will not work properly.

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



Generating a Test Certificate

The gencert utility generates a test certificate for a host:

# bin/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 by default.



Installing a Site Certificate

The getca utility installs a site certificate.


To install a site certificate

  1. Save the new certificate file in a temporary location, such as /tmp/cert.tmp.

  2. Run getca, specifying the name of the host that owns this certificate and providing the temporary file as input:

    # getca hostname < /tmp/cert.tmp

    This saves the certificate to the file ServerRoot/ssl/certs/hostname.cert.

  3. Restart Stronghold:

    # reload-server

    The servermust restart in order to implement the new certificate.



Creating a Private Certification Authority

The makeca utility sets up a private certification authority on the server platform by generating a key pair and self-signed certificate for a host:

# bin/makeca

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

After you run makeca, see "Private Certification Authorities" on page 2-20 for detailed instructions on configuring and running your private certification authority.



Converting a Netscape Commerce Certificate and Key Pair

If you already have a site certificate formatted for the Netscape Commerce server, you can convert it to a format that Stronghold can use. The ns_convert utility does this for you:

# bin/ns_convert directory hostname
NOTE: Ns_convert cannot convert Netscape Enterprise 2.x certificates.



Viewing the Contents of a Certificate

The ssleay x509 utility allows you to view and manipulate certifi cate fi les. You can use it to view the complete text of a certifi cate or one or more individual fi elds.


To view the complete text of a certificate


To view one or more fields of a certificate



Administering Basic Authentication

Basic authentication uses simple usernames and password to authenticate users. Performed over HTTP, basic authentication exposes usernames and passwords to eavesdroppers by transmitting them in plaintext. This authentication scheme can still be useful for low-security applications or over HTTPS.

In order to use basic authentication, you must create a file that contains the list of allowed usernames and their corresponding, crypt()-encrypted passwords. Only clients that submit one of the listed usernames and its corresponding password are given access. You can create separate authentication realms, each with its own password file, or define different groups whose users share the same password file.

This section provides instructions for using the ServerRoot/bin/htpasswd utility to create a password file, add usernames and passwords, and configure basic authentication access control. The directives that implement basic authentication are described in "Basic Authentication" on page 7-90.


To create a password file

  1. Create a new directory for password files:

    # mkdir ServerRoot/basicauth
  2. Switch to the ServerRoot/bin/ directory.

  3. Use the htpasswd utility to create a new password file and add yourself, the administrator, as its first user:

    # htpasswd -c ServerRoot/basicauth/filename username

    The program prompts you for your new password.

  4. Enter a new password.

  5. Re-enter your password for confirmation.


To add a user to a password file

  1. Switch to the ServerRoot/bin/ directory.

  2. Run the htpasswd utility, specifying an existing password file and the new username:

    # htpasswd ServerRoot/basicauth/filename username

    The program prompts you for the new user's password.

  3. Have the new user enter the new password.

  4. Have the new user re-enter the password for confirmation.

The htpasswd utility uses crypt() to encrypt each new password. Passwords are saved only in crypt()-encrypted form. When a client submits a username and password, Stronghold crypt()-encrypts the submitted password and compares it with the one in the password file. This eliminates the security risk of a plaintext password file.


To configure basic authentication access control

  1. Open the httpd.conf file using a text editor.

  2. Create a container for the object you want to control access to, if one does not already exist. For example:

    <Directory ServerRoot/htdocs/secret>
     . . .
    </Directory>
  3. Inside the container, insert the AuthType directive and set it to "basic."

    <Directory ServerRoot/htdocs/secret>
     AuthType basic
     . . .
    </Directory>

    This enables basic authentication for this server object.

  4. Insert the Require directive after the AuthType directive and set it to "valid-user."

    <Directory ServerRoot/htdocs/secret>
     AuthType basic
     Require valid-user
     . . .
    </Directory>

    This instructs Stronghold to allow any valid user, that is, any user whose username and password match one of the entries in the password file. Alternatively, you can allow only some of the users in the password file by setting Require to "user" followed by the list of allowed users:

    Require user user1 user2 user3
  5. Insert the AuthUserFile directive after the Require directive and specify the path to the password file:

    <Directory ServerRoot/htdocs/secret>
     AuthType basic
     Require valid-user
     AuthUserFile filename
     . . .
    </Directory>

    This designates the password file that Stronghold uses to check usernames and passwords.

  6. Restart the server:

    # ServerRoot/bin/reload-server

Optionally, you can add the AuthName directive, which assigns a name to this authentication realm. The server passes the name of the realm to the client when it requests a username and password. This is useful for distinguishing between multiple basic authentication realms in your domain, particularly if users have different passwords for different realms.

Users can also be grouped for easier configuration by creating a file that contains a list of groups and the usernames of their constituents. Each line of the group file contains a group name followed by a colon and a space-separated list of usernames. For example, the following entry defines the group "moshpit" with three member usernames:

moshpit: deadkennedys minorthreat sexpistols

To use the group file, add the AuthGroupFile directive to the usual set of basic authentication directives, specifying the path to the group file. The basic authentication configuration must also contain one or more AuthUserFile directives specifying the password files that contain the password of members of allowed groups. To allow access by all groups, set the Require directive to "valid-user." To allow access by only certain groups, set it to "group" followed by the list of allowed groups. For example:

Require group moshpit snakepit deeppit

In this example, only members of moshpit, snakepit, and deeppit are allowed. The members of those groups must be defined in the group file specified by AuthGroupFile. Their crypt()-encrypted passwords must be in the password file specified by AuthUserFile.




[Top] [Prev] [Next] [Last]
© 1998 C2Net International
Feedback: stronghold-docs@c2.net 		C2Net Logo