![Extracted pic [1]](chapter2.fm-image-1.gif)
Stronghold Web Server 3.0 '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:
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.
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 an open, standards-based solution, more non-proprietary ciphers, better error reporting, and uses HMAC digests instead of MD5.
You can find specifications and other detailed information about TLS at
http://www.ietf.org/html/charters/tls-charter.html. TLS is already supported by many client products (e.g. web browsers) today and its acceptance is likely to grow.
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:
SSLEngine on
This directive enables encryption and server 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:
SSLProtocol all
SSLProtocol all -TLSv1
SSLProtocol SSLv3 TLSv1
The complete list of SSL/TLS directives appears in Chapter 3.
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.
There are two types of ciphers, symmetric and asymmetric. The graphic below represents an asymmetric, public-key cipher.
Public key ciphers require two keys: a public key and a private key. The public key encrypts data, but it cannot decrypt the same data. Only the private key can decrypt data that is encrypted with the public key.
Under this scheme, a web server gives its public key to the client at the beginning of a secure session. The browser then uses the web servers public key to encrypt its next transmission. The server uses its private key to decrypt that transmission. As you can see, the servers private key should be carefully guarded, which is why Stronghold encrypts any private keys it generates by default.
![Extracted pic [2]](chapter2.fm-image-2.gif)
Symmetric ciphers use a single key for all operations. Under this scheme, the sender and the recipient share the same key and use it for both encryption and decryption.
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.
![Extracted pic [3]](chapter2.fm-image-3.gif)
An SSL session may last for one or more transactions, and a session key encrypts all data in the 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. This is why guarding private key files is critical, through careful checking of files permissions and good passwords.
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
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-13 provides complete instructions for using this utility.
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
Cryptographers continuously attack and scrutinize ciphers and occasionally succeed in finding new weaknesses in existing ciphers. By seeking and publicizing weaknesses in ciphers, cryptographers can alert the public to security risks, and can also find ways to improve ciphers or create stronger ones. Most importantly, we can use this extensive peer-review to judge the level of confidence we can place in such ciphers.
Modern ciphers generally require an attacker to do a brute-force search through all possible keys to break any encrypted traffic. For ciphers with sufficiently large key sizes (e.g. 128-bit) this is virtually inconceivable with todays technology. Any cipher weakness that allows an improvement in "attack time", even if the improvement remains highly impractical to attempt, generally renders that cipher as "broken"--all software updates should remove support for such ciphers.
Stronghold interoperates with the ciphers listed below. Strong ciphers use 168-bit and 128-bit keys, 56-bit ciphers are considered quiite weak; and 40-bit ciphers offer little or no security and should not be used on the Internet unless unavoidable.
Ciphers using DES/DES3 with 168-bit keys actually have an effective key-size of 112-bit. However, as with 128-bit ciphers, these are certainly large enough to resist any known attacks.
To see a list of the available ciphers, run the following command:
# bin/openssl ciphers -v
Any object on the site can be configured to require certain ciphers and forbid others. Three configuration directives control 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 3-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.somesite.org:443>
SSLFlag on
SSLCipherSuite 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.
| Use either SSLRequireCipher or SSLBanCipher. Never use both for the same object. |
|---|
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 a "man in the middle". If an eavesdropper can impersonate a site, they can substitute other data in place of the data the user expects to receive. Site authentication provides the browser user an assurance that they are communicating directly and securely with the party owning the site certificate presented, and not to an imposter, or through a "man in the middle".
Recently, popular browsers also began supporting client authentication. Stronghold Web Server supports both site authentication and client authentication. The use of client certificates gives the web server the same assurance about the identity of the party it is communicating securely with that site certificates give to the browser about the web servers identity.
SSL and TLS authentication makes use of X.509 certificates. Certificates are issued by certification authorities (CAs) in response to certificate signing requests (or CSRs) sent in by web server administrators, the CAs act as trusted third parties. Each certificate contains;
The CAs 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. This technique provides authentication at the server identity even though the two parties may never have had the chance to securely verify the authenticity of each others certificate.
The CA's certificate is present in both the browser and the server and it is implicitly trusted. That is why this trusted third party approach works. The CA's certificate can be trusted (if your server or browser has not been tampered with), and so you can also trust any certificates it has signed if a signature check (as described next) validates successfully.
To check a CAs signature of a certificate, the receiving party 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.
Stronghold Web Server supports three different kinds of certificates:
Independent Certification Authorities issue certificates that are accepted worldwide. Here are some major independent CAs:
Each of these companies 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 secure site 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-22.
For policy information and current rates, consult the Web site of the CA you intend to send a certificate signing request to for a certificate. If you have purchased a bundled certificate, consult the information you were sent when you purchased Stronghold.
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.
Each virtual host on the web supported by the server is a site. When requesting a secure connection with a web server, each browser compares the <hostname> or IP address it is requesting to the fields in the certificate it receives from the certificate. As such each secure virtual host must have its own certificate and key. Each certificate and private key is stored in a separate file.
Stronghold Web Server sends a site certificate file to any client that requests access to the SSL/TLS port of that site (secure sites usually operate on port 433).The client uses the site's public key in the certificate file to encrypt the session key, and Stronghold uses the private site's key in the key files to decrypt the session key. Therefore, the private keys site's and public keys for each site must match.
This section explains how to acquire, install and manage site certificates and key pairs.
During installation, Stronghold Web Server's genkey utility generates a key pair for your main host, then calls genreq to request a certificate signing request (CSR), and finally calls gencert to create a temporary certificate that you can use until your CA has returned a valid signed certificate to replace the temporary certificate. This temporary certificate is signed with your site's private key.
![Extracted pic [4]](chapter2.fm-image-4.gif)
"To generate a key pair and request a certificate on page 2-28" 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-33". gencert can also be run separately.
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 secure virtual hosts. See "Installing a Site Certificate on page 2-33" for full getca instructions.
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 (using the email address configured by the installation--this is in conf/httpd.conf). When this happens, use the genreq utility to request a new certificate from your CA. The CA sends a new certificate and bills you for another year. For full instructions, see "Requesting a Renewed Certificate" on page 2-31.
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-33. The original key pair works with the new certificate so do not generate a new one.
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 in the logs/ssl/error-log file:
Unable to configure server RSA private key (OpenSSL library error follows)
x509 certificate routines:X509_check_private_key:key values mismatch. 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-32 for complete instructions.
Stronghold Web Server supports client authentication with X509 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 main disadvantage of basic authentication is that usernames and passwords can be communicated through unencrypted networks, 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 on the same machine, but the password does not enter the network--all network communication is fully secured with publicity cryptography.
Users obtain client certificates from a trusted third party 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, and Equifax. To accept other CAs (including private CAs) as being trusted to sign client certificates, see "Installing New Client CA Certificates" on page 2-17
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 this way use the SSLVerifyClient,SSL_Require and SSL_Group directives (use of 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 the public keys from the CA certificates in the <ServerRoot>/ssl/CA/client-rootcerts.open file. If the signature is invalid or originates with a CA whose certificate is not in client-rootcerts.open, 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 refer to any one of a number of possible client certificate fields. For example, it can allow 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 "Frank Roberts". The complete rules of building SSL_Require expressions appear on page 7-30.
SSL_Group is a related directive that creates client authentication groups whose members all meet the same criteria. Its expression syntax is identical to that 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 man objects, SSL_Group provides a convenient shortcut.
By default, Stronghold Web Server accepts client certificates signed by Verisign, Thawte, and Equifax, however it can be configured to accept certificates signed by other CAs, such as a private CA. To do so, it must have the CA's client root certificate. This is the certificate that is used to sign client certificates, and Stronghold must be configured to trust it before client certificates signed by the CA will be accepted by Stronghold. If the certificate is part of a chain, all certificates in the chain must be installed.
There are two ways to install a CA certificate; either by appending the certificate to the SSLCACertificateFile file or by installing the certificate file in the SSLCACertificatePath directory.
To append a CA certificate to the root fileThe x509 utility returns a hash like;
5a35beIf a file with this hash name already exists, name this one 5a35be.1 instead. Alternatively, create a symbolic link with the hash name instead of renaming the file itself:
# ln -s newcert.pem 5a35be.0Once the new CA certificate or chain is installed, Stronghold Web Server can automatically verify signatures on all client certificates signed by that CA.
Proxy transactions have two sides: a client side and a server side, with the proxy server in the middle. On the client side, the proxy server accepts requests and submits responses like a regular server. It uses its site certificate to authenticate itself to the client, and may also require that the client authenticate itself. On the server side, the proxy server submits requests and accepts responses as if it were a client. It may also be required to authenticate itself or the client to the remote server. This is proxy authentication.
Proxy authentication can take place in two ways, depending on whether the server is configured as a normal proxy or a mirror proxy:
A proxy client certificate is identical in format to a normal client certificate, but authenticates a 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. Remote servers use a different set of CA certificates to verify client certificates than browsers use to verify site certificates. For this reason, a site certificate cannot usually be used for proxy client authentication.
Some independent CAs do not offer proxy client certificates. To work around this limitation, 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-22.
SSLProxyMachineCertPath or SSLProxyMachineCertFile must be set in order to enable a proxy client certificate. If the server has multiple proxy client certificates, they can be stored in separate files in the SSLProxyMachineCertPath, or appended to the SSLProxyMachineCertFile.
When performing SSL or TLS mirror proxy transactions, Stronghold Web Server 3.0 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 including;
To accept certificates signed by other CAs, (such as a private CA), 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, install all certificates in the chain.
There are two ways to install a CA certificate;
# cd <ServerRoot>/ssl/CA
# cat newcert.pem >> server-rootcerts.pem
# cp newcert.pem <ServerRoot>/ssl/CA/newcert.pem
If a file with this hash name already exists, name this one 5a35be.1 instead. Alternatively, create a symbolic link with the hash name instead of renaming the file itself:
A private Certification Authority (CA) can be created to certify internal web servers and users on an intranet. 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, any web servers running externally for public access must be certified by an independent CA in order to provide a sufficient level of trust for general users.
If an intruder gains access to a private CA, he can forge certificates and use them to gain access to secure transactions or to impersonate a server. It is your responsibility to follow an adequate security policy. Choose the CA platform carefully and maintain it under the strictest security. We strongly advise consulting a security specialist before deploying a private CA in production environments.
Stronghold Web Server 3.0 provides tools for setting up a basic certification authority. To set up a CA,
The <ServerRoot>/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
The program generates some random data with which to create a unique key pair. Then it prompts you for random keystrokes.
0 * -Enough, thank you.
N.B. the line breaks are for readability, the command should be entered on a single line.
# openssl x509 -inform PEM -outform DER
-in <ServerRoot>/ssl/CA/cacert.pem
-out <ServerRoot>/htdocs/myca.cacert
Give the certificate a MIME type of application/x-x509-ca-cert to denote a Certification Authority certificate, then instruct users to download the certificate file using their browsers. A series of browser dialog boxes will guide each user through the installation process.
The configuration is provided in the default httpd.conf file installed with the server:
SSLCACertificateFile CA/cacert.pem
Uncomment this line to begin using the new certificate.
For private CA functions, OpenSSL uses the configuration file at
<ServerRoot>/ssl/lib/openssl.conf. The default 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 the file.
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 openssl.conf file contains two policies: policy_match and policy_anything. To create a new policy, copy one of these and insert a different name between the brackets.
# 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:
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 the CA is limited to one department, the organizationalUnitName field can be set to "match."
Normally, the policy parameters are the only fields that may require editing. When editing other fields, be sure to read the file comments carefully.
Before signing certificates, define your organization's policy regarding the level of documentation required with CSRs. In order to verify the origin and content of each CSR, separate documentation should be required with each CSR.
CSRs come in an encrypted format. To see a plain text version of any CSR, pass it through the <ServerRoot>/bin/openssl req program:
# openssl req -text -noout < <CSRfilename>
The program prints the CSR in plaintext. Use it to view the contents of a CSR before signing it. See also Authentication and Encryption
Next, establish a procedure for collecting and processing CSRs. For example, set up a special email address exclusively for submitting CSRs, or 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 sign them one by one.
To sign a certificate# sign_csr /tmp/csr
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 openssl.conf.
1 out of 1 certificate requests certified, commit?
[y/n]
The previous sections mention several of Stronghold Web Server 3.0 's security utilities, located in the <ServerRoot>/bin/ directory. This section contains detailed instructions for using all of the security utilities. Stronghold comes with utilities for;
Since all of these utilities are located in the <ServerRoot>/bin/ directory, it may be convenient to add this directory to your PATH variable.
To add the utilities directory to the PATH variablePATH=<ServerRoot>/bin:$PATHIf you are using the C shell or tcsh, add this line to the root .cshrc file:
set path=(<ServerRoot>/bin $PATH)
The change_pass utility changes the pass phrase used to encrypt a host's private key:
# bin/change_pass <hostname>
Since Stronghold prompts for only one pass phrase on startup, all hosts must share the same pass phrase. If one or more use different pass phrases, the following error appears on startup:
<hostname>:port: Cannot initialise SSL: Key file error. Host disabled
When this happens, use change_pass with the given <<hostname>> to make its pass phrase the same as all others. The same problem can also be solved by removing the pass phrase (as described in the next section) but this requires extreme care be taken to protect the (unencrypted) private key file.
The decrypt_key utility decrypts a host's private key so that it no longer requires a pass phrase:
# bin/decrypt_key <hostname>
When private keys are unencrypted, the server can restart unattended. Be sure to store unencrypted keys securely to avoid a major security risk. An unencrypted private key, if obtained by an intruder, can be used to impersonate the host and decrypt the requests that clients send to it.
To generate a key pair and request a certificate# bin/genkey <hostname>
genkey prints the filenames and location of the key file and certificate file it is about to generate:
The key will be stored in
<ServerRoot>/ssl/private/<hostname>.key
<ServerRoot>/ssl/certs/<hostname>.cert
genkey generates some random data with which to create a unique key pair. Then it prompts you for random keystrokes.
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.
Please choose the CA you would like to use:
A) VeriSign
B) Thawte
C) Other
Choose: A
-----BEGIN NEW CERTIFICATE REQUEST-----
MIIBEzCBzgIBADB7MQswCQYDVQQGEwJVUzETMBEGA1UECBMKQ2FsaWZvcm5p
YTEQMA4GA1UEBxMHT2FrbGFuZDEbMBkGA1UEChMSQzJOZXQgU29mdHdhcmUg
SW5jMRAwDgYDVQQLEwdUZXN0aW5nMRYwFAYDVQQDEw1nYWJiZXIuYzIubmV0
MEwwDQYJKoZIhvcNAQEBBQADOwAwOAIxAJukoQhq4LanG2k+LnRTGJAcgv9L
JPsdfCsjqRs8ygoyaw4ucOEdx+WdnM0x36NcQIDAQABMA0GCSqGSIb3DQEBB
AUAAzEABRLR6IkG70oNG1MnvuMDeWou4kIvc98ysjssCNKsDKsHAXBSEbfsI
Qs5JRNagVBW
-----END NEWCERTIFICATE REQUEST-----
Stronghold Web Server 3.0 sends email to the ServerAdmin when a certificate is about to expire, reminding the server administrator to run genreq. Do this promptly; an expired certificate prevents users from connecting to secured sites on the server. Use genreq to send a certificate renewal request to a CA:
# bin/genreq <hostname>
This section contains complete instructions for requesting a renewed certificate from Verisign, Thawte, and other CAs.
To request a renewed certificate# bin/genreq <hostname>
Genreq asks you which CA you want to request for a certificate from:
Please choose the CA you would like to use:
A) VeriSign
B) Thawte
C) Other
Choose: A
The checkcert utility compares a host's certificate to its key pair to determine whether they match.
To compare a certificate to a key pair# checkcert <hostname>
If the certificate and the key pair match, checkcert prints this message and then exits:
Cert <hostname>.cert matches key <hostname>.keyIf the certificate and the key pair do not match, check cert responds like this:
The cert stored in <ServerRoot>/ssl/certs/<hostname>.cert
does not match the key stored in
<ServerRoot>/ssl/private/<hostname>.key
# genreq <hostname>
The genreq utility generates a certificate signing request based on a host's existing key pair:
# bin/genreq <hostname>
A <hostname> must be specified to denote the correct key pair file, since key files are named by <hostname>. If an incorrect <hostname> is specified, the new certificate will not work properly. To generate a new key pair for the new certificate, plus a test certificate, use genkey instead.
The gencert utility generates a temporary certificate for a host:
# bin/gencert <hostname>
The test certificate does not authenticate the host. It generates an error message when users encounter it, and it exposes the server to possible man-in-the-middle attacks. Use the certificate generated by gencert for testing purposes only. It expires in 30 days.
The getca utility installs a site certificate.
To install a site certificate
This saves the certificate to the file <ServerRoot>/ssl/certs/<hostname>.cert
The server must restart in order to implement the new certificate.
The makeca utility sets up a private CA on the server platform by generating a key pair and self-signed certificate:
# bin/makeca
After running makeca, see "Private Certification Authorities" on page 2-22 for detailed instructions on configuring and running the private CA.
If you already have a site certificate formatted for the Netscape Commerce Server, it can be converted to a format that Stronghold can use. The ns_convert utility does this:
# bin/ns_convert <directory> <hostname>
| ns_convert cannot convert Netscape Enterprise 2.x certificates. |
|---|
The openssl x509 utility is used to view and manipulate certificate files. It can be used to view the complete text of a certificate or one or more individual fields.
To view the complete text of a certificate
Run the x509 utility as an argument to the OpenSSL command with the -text tag and the certificate file as input:
<ServerRoot>/bin/openssl x509 -text -in <certfilename>
The utility prints the contents of the certificate in plain text, followed by the certificate itself:
Certificate:
Data:
Version: 1 (0x0)
Serial Number: 0 (0x0)
Signature Algorithm: md5WithRSAEncryption
Issuer: C=US, ST=California, L=Oakland, O=C2Net Software US, OU=Security Services
Division, CN=gabber.c2.net
Validity
Not Before: Nov 4 00:30:41 1997 GMT
Not After : Dec 4 00:30:41 1997 GMT
Subject: C=US, ST=California, L=Oakland, O=C2Net Software US, OU=SecurityServices Division, CN=gabber.c2.net
Subject Public Key Info:
Public Key Algorithm: rsaEncryption
RSA Public Key: (512 bit)
Modulus (512 bit):
00:bf:2e:73:fe:c1:79:10:ed:25:e4:02:dd:0f:8d:
0a:2a:1b:e7:8d:b7:39:fc:db:a9:00:20:7c:99:6a:
cc:41:a7:a9:41:15:a7:de:81:07:74:d9:69:2b:69:
8e:0c:7d:9b:5d:67:d0:3b:47:55:04:7e:85:c3:2f:
95:4b:19:bb:25
Exponent: 65537 (0x10001)
Signature Algorithm: md5WithRSAEncryption
24:ae:ac:b9:59:9a:88:0d:32:df:c0:05:8c:48:31:6a:a6:2f:
6a:ce:1b:7a:c5:8d:b2:03:bf:0d:63:61:e9:5f:4b:e6:4d:8f:
14:49:8f:36:a4:ca:36:d4:ab:6c:54:26:f7:12:b4:c6:ae:7a:
70:8d:62:10:14:8f:f7:ee:8b:3e
-----BEGIN CERTIFICATE-----
MIICBjCCAbACAQAwDQYJKoZIhvcNAQEEBQAwgY0xCzAJBgNVBAYTAlVTMRMwQYDV
QQIEwpDYWxpZm9ybmlhMRAwDgYDVQQHEwdPYWtsYW5kMRowGAYDVQQKExFDMk5ld
CBTb2Z0d2FyZSBVUzEjMCEGA1UECxMaU2VjdXJpdHkgU2VydmljZXMgRGl2aXNpb
24xFjAUBgNVBAMTDWdhYmJlci5jMi5uZXQwHhcNOTcxMTA0MDAzMDQxWhcNOTcxM
jA0MDAzMDQxWjCBjTELMAkGA1UEBhMCVVMxEzARBgNVBAgTCkNhbGlmb3JuaWExE
DAOBgNVBAcTB09ha2xhbmQxGjAYBgNVBAoTEUMyTmV0IFNvZnR3YXJlIFVTMSMwI
QYDVQQLExpTZWN1cml0eSBTZXJ2aWNlcyBEaXZpc2lvbjEWMBQGA1UEAxMNZ2FiY
mVyLmMyLm5ldDBcMA0GCSqGSIb3DQEBAQUAA0sAMEgCQQCP+wXkQ7SXkAt0PjQoq
G+eNtzn826kAIHyZasxBp6lBFafegQd02WkraY4MfZtdZ9A7R1UEfoXDL5VLGbsl
AgMBAAEwDQYJKoZIhvcNAQEEBQADQQAkrqy5WZqIDTLfwAWMSDFqpi9qzht6xY2y
A78NY2HpX0vmTY8USY82pMo21KtsVCb3ErTGrnpwjWIQFI/37os+
-----END CERTIFICATE-----
To view one or more fields of a certificate
# <ServerRoot>/bin/openssl x509 -startdate -in <certfilename>The x509 utility prints the specified field in plaintext, followed by the complete, encoded certificate:
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.
Basic authentication requires a file that contains the list of allowed usernames and their corresponding, crypt()-, MD5, or SHA 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 listed in "Basic Authentication" on page 7-99.
To create a password file# mkdir <ServerRoot>/basicauth
# htpasswd -c <ServerRoot>/basicauth/<filename> <username>
The program prompts you for a new password.
# htpasswd <ServerRoot>/basicauth/<filename> <username>
The program prompts you for the new user's password.
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<Directory <ServerRoot>/htdocs/secret>
...
</Directory>
<Directory <ServerRoot>/htdocs/secret>
AuthType basic
...
</Directory>
This enables basic authentication for this server object.
<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
<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.
# bin/reload-server
Optionally, 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 within a 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 "management" with three member usernames:
management: loretta samuel frank
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:
<ServerRoot> group moshpit snakepit deeppitIn 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 main the password file specified by AuthUserFile.