|
+ +
|
+
|
+ +
|
+
|
+ +
|
+
+  +
+
+
+
+The idea in mod_ssl is mainly the following: because mod_ssl provides mostly a +superset of the functionality of all other solutions we can easily provide +backward compatibility for most of the cases. Actually there are three +compatibility areas we currently address: configuration directives, +environment variables and custom log functions. + Configuration Directives+For backward compatibility to the configuration directives of other SSL +solutions we do an on-the-fly mapping: directives which have a direct +counterpart in mod_ssl are mapped silently while other directives lead to a +warning message in the logfiles. The currently implemented directive mapping +is listed in Table 1. Currently full backward +compatibilty is provided only for Apache-SSL 1.x and mod_ssl 2.0.x. +Compatibility to Sioux 1.x and Stronghold 2.x is only partial because of +special functionality in these interfaces which mod_ssl (still) doesn't +provide. ++
+
+
+
+ Environment Variables+When you use ``SSLOptions +CompatEnvVars'' additional environment
+variables are generated. They all correspond to existing official mod_ssl
+variables. The currently implemented variable derivation is listed in Table 2.
++
+
+
+
+ Custom Log Functions+When mod_ssl is built into Apache or at least loaded (under DSO situation) +additional functions exist for the Custom Log Format of mod_log_config as documented in the Reference +Chapter. Beside the ``%{varname}x''
+eXtension format function which can be used to expand any variables provided
+by any module, an additional Cryptography
+``%{name}c'' cryptography format function
+exists for backward compatibility. The currently implemented function calls
+are listed in Table 3.
++
+
+
+
+
|
+|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
+ +
+
+
+ About the module+
+
+ About Installation+
+
+ About Configuration+
+
+ About Certificates+
+
+ About SSL Protocol+
+
+ About Support+
+
+
|
+
|
+ +
+
+
+
|
+
|
+ +
+
+
+
Cipher Suites and Enforced Strong Security+
+ Client Authentication and Access Control+
+
+
|
+||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
+ +
+
+
+
Cryptographic Techniques+Understanding SSL requires an understanding of cryptographic algorithms, +message digest functions (aka. one-way or hash functions), and digital +signatures. These techniques are the subject of entire books (see for instance +[AC96]) and provide the basis for privacy, integrity, and +authentication. +Cryptographic Algorithms+Suppose Alice wants to send a message to her bank to transfer some money. +Alice would like the message to be private, since it will include information +such as her account number and transfer amount. One solution is to use a +cryptographic algorithm, a technique that would transform her message into an +encrypted form, unreadable except by those it is intended for. Once in this +form, the message may only be interpreted through the use of a secret key. +Without the key the message is useless: good cryptographic algorithms make it +so difficult for intruders to decode the original text that it isn't worth +their effort. ++There are two categories of cryptographic algorithms: +conventional and public key. +
Message Digests+Although Alice may encrypt her message to make it private, there is still a +concern that someone might modify her original message or substitute +it with a different one, in order to transfer the money to themselves, for +instance. One way of guaranteeing the integrity of Alice's message is to +create a concise summary of her message and send this to the bank as well. +Upon receipt of the message, the bank creates its own summary and compares it +with the one Alice sent. If they agree then the message was received intact. ++A summary such as this is called a message digest, one-way +function or hash function. Message digests are used to create +short, fixed-length representations of longer, variable-length messages. +Digest algorithms are designed to produce unique digests for different +messages. Message digests are designed to make it too difficult to determine +the message from the digest, and also impossible to find two different +messages which create the same digest -- thus eliminating the possibility of +substituting one message for another while maintaining the same digest. + +Another challenge that Alice faces is finding a way to send the digest to the +bank securely; when this is achieved, the integrity of the associated message +is assured. One way to to this is to include the digest in a digital +signature. + Digital Signatures+When Alice sends a message to the bank, the bank needs to ensure that the +message is really from her, so an intruder does not request a transaction +involving her account. A digital signature, created by Alice and +included with the message, serves this purpose. ++Digital signatures are created by encrypting a digest of the message, +and other information (such as a sequence number) with the sender's +private key. Though anyone may decrypt the signature using the public +key, only the signer knows the private key. This means that only they may +have signed it. Including the digest in the signature means the signature is +only good for that message; it also ensures the integrity of the message since +no one can change the digest and still sign it. + +To guard against interception and reuse of the signature by an intruder at a +later date, the signature contains a unique sequence number. This protects +the bank from a fraudulent claim from Alice that she did not send the message +-- only she could have signed it (non-repudiation). + Certificates+Although Alice could have sent a private message to the bank, signed it, and +ensured the integrity of the message, she still needs to be sure that she is +really communicating with the bank. This means that she needs to be sure that +the public key she is using corresponds to the bank's private key. Similarly, +the bank also needs to verify that the message signature really corresponds to +Alice's signature. ++If each party has a certificate which validates the other's identity, confirms +the public key, and is signed by a trusted agency, then they both will be +assured that they are communicating with whom they think they are. Such a +trusted agency is called a Certificate Authority, and certificates are +used for authentication. + Certificate Contents+A certificate associates a public key with the real identity of an individual, +server, or other entity, known as the subject. As shown in Table 1, information about the subject includes identifying +information (the distinguished name), and the public key. It also includes +the identification and signature of the Certificate Authority that issued the +certificate, and the period of time during which the certificate is valid. It +may have additional information (or extensions) as well as administrative +information for the Certificate Authority's use, such as a serial number. ++
+
+
+
+A distinguished name is used to provide an identity in a specific context -- +for instance, an individual might have a personal certificate as well as one +for their identity as an employee. Distinguished names are defined by the +X.509 standard [X509], which defines the fields, field +names, and abbreviations used to refer to the fields +(see Table 2). + +
+
+
+
+A Certificate Authority may define a policy specifying which distinguished
+field names are optional, and which are required. It may also place
+requirements upon the field contents, as may users of certificates. As an
+example, a Netscape browser requires that the Common Name for a certificate
+representing a server has a name which matches a wildcard pattern for the
+domain name of that server, such as +The binary format of a certificate is defined using the ASN.1 notation [ X208] [PKCS]. This notation defines how to +specify the contents, and encoding rules define how this information is +translated into binary form. The binary encoding of the certificate is +defined using Distinguished Encoding Rules (DER), which are based on the more +general Basic Encoding Rules (BER). For those transmissions which cannot +handle binary, the binary form may be translated into an ASCII form by using +Base64 encoding [MIME]. This encoded version is called PEM +encoded (the name comes from "Privacy Enhanced Mail"), when placed between +begin and end delimiter lines as illustrated in Table 3. + +
+
+
+
Certificate Authorities+By first verifying the information in a certificate request before granting +the certificate, the Certificate Authority assures the identity of the private +key owner of a key-pair. For instance, if Alice requests a personal +certificate, the Certificate Authority must first make sure that Alice really +is the person the certificate request claims. +Certificate Chains+A Certificate Authority may also issue a certificate for another Certificate +Authority. When examining a certificate, Alice may need to examine the +certificate of the issuer, for each parent Certificate Authority, until +reaching one which she has confidence in. She may decide to trust only +certificates with a limited chain of issuers, to reduce her risk of a "bad" +certificate in the chain. +Creating a Root-Level CA+As noted earlier, each certificate requires an issuer to assert the validity +of the identity of the certificate subject, up to the top-level Certificate +Authority (CA). This presents a problem: Since this is who vouches for the +certificate of the top-level authority, which has no issuer? +In this unique case, the certificate is "self-signed", so the issuer of the +certificate is the same as the subject. As a result, one must exercise extra +care in trusting a self-signed certificate. The wide publication of a public +key by the root authority reduces the risk in trusting this key -- it would be +obvious if someone else publicized a key claiming to be the authority. +Browsers are preconfigured to trust well-known certificate authorities. ++A number of companies, such as Thawte and +VeriSign have established themselves as +Certificate Authorities. These companies provide the following services: +
+It is also possible to create your own Certificate Authority. Although risky +in the Internet environment, it may be useful within an Intranet where the +organization can easily verify the identities of individuals and servers. + Certificate Management+Establishing a Certificate Authority is a responsibility which requires a +solid administrative, technical, and management framework. +Certificate Authorities not only issue certificates, they also manage them -- +that is, they determine how long certificates are valid, they renew them, and +they keep lists of certificates that have already been issued but are no +longer valid (Certificate Revocation Lists, or CRLs). +Say Alice is entitled to a certificate as an employee of a company. Say too, +that the certificate needs to be revoked when Alice leaves the company. Since +certificates are objects that get passed around, it is impossible to tell from +the certificate alone that it has been revoked. +When examining certificates for validity, therefore, it is necessary to +contact the issuing Certificate Authority to check CRLs -- this is not usually +an automated part of the process. ++ Note:
+If you use a Certificate Authority that is not configured into browsers by
+default, it is necessary to load the Certificate Authority certificate into
+the browser, enabling the browser to validate server certificates signed by
+that Certificate Authority. Doing so may be dangerous, since once loaded, the
+browser will accept all certificates signed by that Certificate Authority.
+Secure Sockets Layer (SSL)+The Secure Sockets Layer protocol is a protocol layer which may be placed +between a reliable connection-oriented network layer protocol (e.g. TCP/IP) +and the application protocol layer (e.g. HTTP). SSL provides for secure +communication between client and server by allowing mutual authentication, the +use of digital signatures for integrity, and encryption for privacy. ++The protocol is designed to support a range of choices for specific algorithms +used for cryptography, digests, and signatures. This allows algorithm +selection for specific servers to be made based on legal, export or other +concerns, and also enables the protocol to take advantage of new algorithms. +Choices are negotiated between client and server at the start of establishing +a protocol session. + +
+
+
+
+There are a number of versions of the SSL protocol, as shown in Table 4. As noted there, one of the benefits in SSL 3.0 is +that it adds support of certificate chain loading. This feature allows a +server to pass a server certificate along with issuer certificates to the +browser. Chain loading also permits the browser to validate the server +certificate, even if Certificate Authority certificates are not installed for +the intermediate issuers, since they are included in the certificate chain. +SSL 3.0 is the basis for the Transport Layer Security [TLS] protocol standard, currently in development by the +Internet Engineering Task Force (IETF). + Session Establishment+The SSL session is established by following a handshake sequence +between client and server, as shown in Figure 1. This +sequence may vary, depending on whether the server is configured to provide a +server certificate or request a client certificate. Though cases exist where +additional handshake steps are required for management of cipher information, +this article summarizes one common scenario: see the SSL specification for the +full range of possibilities. ++ Note
+Once an SSL session has been established it may be reused, thus avoiding the
+performance penalty of repeating the many steps needed to start a session.
+For this the server assigns each SSL session a unique session identifier which
+is cached in the server and which the client can use on forthcoming
+connections to reduce the handshake (until the session identifer expires in
+the cache of the server).
++ ++The elements of the handshake sequence, as used by the client and server, are +listed below: +
+The first step, Cipher Suite Negotiation, allows the client and server to +choose a Cipher Suite supportable by both of them. The SSL3.0 protocol +specification defines 31 Cipher Suites. A Cipher Suite is defined by the +following components: +
Key Exchange Method+The key exchange method defines how the shared secret symmetric cryptography +key used for application data transfer will be agreed upon by client and +server. SSL 2.0 uses RSA key exchange only, while SSL 3.0 supports a choice of +key exchange algorithms including the RSA key exchange when certificates are +used, and Diffie-Hellman key exchange for exchanging keys without certificates +and without prior communication between client and server. ++One variable in the choice of key exchange methods is digital signatures -- +whether or not to use them, and if so, what kind of signatures to use. +Signing with a private key provides assurance against a +man-in-the-middle-attack during the information exchange used in generating +the shared key [AC96, p516]. + Cipher for Data Transfer+SSL uses the conventional cryptography algorithm (symmetric cryptography) +described earlier for encrypting messages in a session. There are nine +choices, including the choice to perform no encryption: +
Digest Function+The choice of digest function determines how a digest is created from a record +unit. SSL supports the following: +
Handshake Sequence Protocol+The handshake sequence uses three protocols: +
+ ++The encapsulation of SSL control protocols by the record protocol means that +if an active session is renegotiated the control protocols will be transmitted +securely. If there were no session before, then the Null cipher suite is +used, which means there is no encryption and messages have no integrity +digests until the session has been established. + Data Transfer+The SSL Record Protocol, shown in Figure 3, is used to +transfer application and SSL Control data between the client and server, +possibly fragmenting this data into smaller units, or combining multiple +higher level protocol data messages into single units. It may compress, attach +digest signatures, and encrypt these units before transmitting them using the +underlying reliable transport protocol (Note: currently all major SSL +implementations lack support for compression). ++ +Securing HTTP Communication+One common use of SSL is to secure Web HTTP communication between a browser +and a webserver. This case does not preclude the use of non-secured HTTP. The +secure version is mainly plain HTTP over SSL (named HTTPS), but with one major +difference: it uses the URL schemehttps rather than
+http and a different server port (by default 443). This mainly
+is what mod_ssl provides to you for the Apache webserver...
+References+
+
+
|
+
|
+ +
+
+
+
+The mod_ssl package was +created in April 1998 by Ralf S. +Engelschall and was originally derived from the Apache-SSL package developed by Ben Laurie. It stays under a BSD-style +license which is equivalent to the license used by The Apache Group for the Apache webserver +itself. This means, in short, that you are free to use it both for commercial +and non-commercial purposes as long as you retain the authors' copyright +notices and give the proper credit. + Legalese+Although the above conditions also apply to Apache and OpenSSL in general (both +are freely available and useable software packages), you should be aware that +especially the cryptographic algorithms used inside OpenSSL stay under +certain patents and perhaps import/export/use restrictions in some countries +of the world. So whether you can actually use the combination +Apache+mod_ssl+OpenSSL in your country depends mainly on your local state laws. +The authors of neither Apache nor mod_ssl nor OpenSSL are liable for any +violations you make here. ++If you're not sure what law details apply to your country you're strongly +advised to first determine them by consulting an attorney before using this +module. A lot of hints you can find in the International Law +Crypto Survey which is a really comprehensive resource on this topic. At +least two countries with heavy cryptography restrictions are well known: +In the United States (USA) it's not allowed to (re-)export mod_ssl +or OpenSSL And inside France it's not allowed to use any cryptography at all +when keys with more than 40 bits are used. + +
Module Architecture+The mod_ssl package consists of the SSL module (part 1 in Figure 1) and a set of source patches for Apache adding the +Extended API (EAPI) (part 2 in Figure 1) which is an +essential prerequisite in order to use mod_ssl. In other words: you can only +use the mod_ssl module when Apache's core code contains the Extended API. But +because when applying mod_ssl to the Apache source tree the Extended API is +also automatically added you usually don't have to think about this. It's +mainly important for package vendors who want to build separate packages for +Apache and mod_ssl. For more details on how to apply mod_ssl to the Apache +source tree please follow theINSTALL file in the mod_ssl
+distribution.
++ +Module Building+The SSL module (mod_ssl) resides under thesrc/modules/ssl/
+subdirectory inside the Apache source tree and is a regular Apache module. This
+means that you can configure, build and install it like any other Apache module.
+Usually this is done by using the APACI command
+++or by manually editing the+$ cd apache_1.3.x/ +$ SSL_BASE=/path/to/openssl ./configure ... --enable-module=ssl ++ SSL_BASE variable,
+uncommenting the corresponding AddModule directive inside the
+src/Configuration file and using the command
+++for configuring. Additionally you can enable the Dynamic Shared Object (DSO) +support for mod_ssl by either adding the+$ cd apache_1.3.x/src +$ ./Configure ++ --enable-shared=ssl
+option to the APACI configure command line or by replacing the
+++line in+AddModule ssl_module modules/ssl/libssl.a ++ src/Configuration with
+++Building mod_ssl as a DSO is especially interesting to achieve more run-time +flexibility, i.e. you can decide whether to use SSL or not at run-time instead +of build-time. But notice that building mod_ssl as a DSO requires that your +OS/compiler supports building DSOs in the first place, and additionally that +they support linking of a DSO against a static library (libssl.a, libcrypo.a). +Not all platform support this. ++SharedModule ssl_module modules/ssl/libssl.so ++
+
|
+
|
+ +
+
+
+
+And third Per-Directory Directives (i.e. those with context ``server
+config, virtual host, directory, .htaccess''), which can pretty much occur
+everywhere. Especially both inside the server config files and the
+per-directory +Additional directives and environment variables provided by mod_ssl (via +on-the-fly mapping) for backward compatiblity to other Apache SSL solutions +are documented in the Compatibility chapter. + Configuration Directives+The most visible and error-prone things of mod_ssl are its configuration +directives. So we document them in great detail here to assist you in setting +up the best possible configuration of your SSL-aware webserver. + +SSLPassPhraseDialog++
+When Apache starts up it has to read the various Certificate (see SSLCertificateFile) and Private Key (see SSLCertificateKeyFile) files of the +SSL-enabled virtual servers. Because for security reasons the Private Key +files are usually encrypted, mod_ssl needs to query the administrator for a +Pass Phrase in order to decrypt those files. This query can be done in two ways +which can be configured by type: +
+Example: + ++ ++SSLPassPhraseDialog exec:/usr/local/apache/sbin/pp-filter ++ SSLMutex++
+This configures the SSL engine's semaphore (aka. lock) which is used for mutual +exclusion of operations which have to be done in a synchronized way between the +pre-forked Apache server processes. This directive can only be used in the +global server context because it's only useful to have one global mutex. + +The following Mutex types are available: +
+Example: + ++ ++SSLMutex file:/usr/local/apache/logs/ssl_mutex ++ SSLRandomSeed++
+This configures one or more sources for seeding the Pseudo Random Number
+Generator (PRNG) in OpenSSL at startup time (context is
+ +The following source variants are available: +
+Example: + ++ ++SSLRandomSeed startup builtin +SSLRandomSeed startup file:/dev/random +SSLRandomSeed startup file:/dev/urandom 1024 +SSLRandomSeed startup exec:/usr/local/bin/truerand 16 +SSLRandomSeed connect builtin +SSLRandomSeed connect file:/dev/random +SSLRandomSeed connect file:/dev/urandom 1024 ++ SSLSessionCache+
+This configures the storage type of the global/inter-process SSL Session +Cache. This cache is an optional facility which speeds up parallel request +processing. For requests to the same server process (via HTTP keep-alive), +OpenSSL already caches the SSL session information locally. But because modern +clients request inlined images and other data via parallel requests (usually +up to four parallel requests are common) those requests are served by +different pre-forked server processes. Here an inter-process cache +helps to avoid unneccessary session handshakes. + +The following two storage types are currently supported: +
+Examples: + ++ ++SSLSessionCache dbm:/usr/local/apache/logs/ssl_gcache_data +SSLSessionCache shm:/usr/local/apache/logs/ssl_gcache_data(512000) ++ SSLSessionCacheTimeout+
+This directive sets the timeout in seconds for the information stored in the +global/inter-process SSL Session Cache and the OpenSSL internal memory cache. +It can be set as low as 15 for testing, but should be set to higher +values like 300 in real life. + +Example: + ++ ++SSLSessionCacheTimeout 600 ++ SSLEngine+
+This directive toggles the usage of the SSL/TLS Protocol Engine. This is +usually used inside a <VirtualHost> section to enable SSL/TLS for a +particular virtual host. By default the SSL/TLS Protocol Engine is disabled +for both the main server and all configured virtual hosts. + +Example: + ++ ++<VirtualHost _default_:443> +SSLEngine on +... +</VirtualHost> ++ SSLProtocol+
+This directive can be used to control the SSL protocol flavors mod_ssl should +use when establishing its server environment. Clients then can only connect +with one of the provided protocols. + +The available (case-insensitive) protocols are: +
+Example: + ++ ++# enable SSLv3 and TLSv1, but not SSLv2 +SSLProtocol all -SSLv2 ++ SSLCipherSuite+
+This complex directive uses a colon-separated cipher-spec string +consisting of OpenSSL cipher specifications to configure the Cipher Suite the +client is permitted to negotiate in the SSL handshake phase. Notice that this +directive can be used both in per-server and per-directory context. In +per-server context it applies to the standard SSL handshake when a connection +is established. In per-directory context it forces a SSL renegotation with the +reconfigured Cipher Suite after the HTTP request was read but before the HTTP +response is sent. + +An SSL cipher specification in cipher-spec is composed of 4 major +attributes plus a few extra minor ones: +
+
+
+
+
+Now where this becomes interesting is that these can be put together
+to specify the order and ciphers you wish to use. To speed this up
+there are also aliases (
openssl ciphers
+-v'' command which provides a nice way to successively create the
+correct cipher-spec string. The default cipher-spec string
+is ``ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP'' which
+means the following: first, remove from consideration any ciphers that do not
+authenticate, i.e. for SSL only the Anonymous Diffie-Hellman ciphers. Next,
+use ciphers using RC4 and RSA. Next include the high, medium and then the low
+security ciphers. Finally pull all SSLv2 and export ciphers to the
+end of the list.
+++The complete list of particular RSA & DH ciphers for SSL is given in Table 2. ++$ openssl ciphers -v 'ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP' +NULL-SHA SSLv3 Kx=RSA Au=RSA Enc=None Mac=SHA1 +NULL-MD5 SSLv3 Kx=RSA Au=RSA Enc=None Mac=MD5 +EDH-RSA-DES-CBC3-SHA SSLv3 Kx=DH Au=RSA Enc=3DES(168) Mac=SHA1 +... ... ... ... ... +EXP-RC4-MD5 SSLv3 Kx=RSA(512) Au=RSA Enc=RC4(40) Mac=MD5 export +EXP-RC2-CBC-MD5 SSLv2 Kx=RSA(512) Au=RSA Enc=RC2(40) Mac=MD5 export +EXP-RC4-MD5 SSLv2 Kx=RSA(512) Au=RSA Enc=RC4(40) Mac=MD5 export ++ +Example: + +++SSLCipherSuite RSA:!EXP:!NULL:+HIGH:+MEDIUM:-LOW ++ +
+
+
+
+
SSLCertificateFile+
+This directive points to the PEM-encoded Certificate file for the server and +optionally also to the corresponding RSA or DSA Private Key file for it +(contained in the same file). If the contained Private Key is encrypted the +Pass Phrase dialog is forced at startup time. This directive can be used up to +two times (referencing different filenames) when both a RSA and a DSA based +server certificate is used in parallel. + +Example: + ++ ++SSLCertificateFile /usr/local/apache/conf/ssl.crt/server.crt ++ SSLCertificateKeyFile+
+This directive points to the PEM-encoded Private Key file for the server. If
+the Private Key is not combined with the Certificate in the
+ +Example: + ++ ++SSLCertificateKeyFile /usr/local/apache/conf/ssl.key/server.key ++ SSLCertificateChainFile+
+This directive sets the optional all-in-one file where you can +assemble the certificates of Certification Authorities (CA) which form the +certificate chain of the server certificate. This starts with the issuing CA +certificate of of the server certificate and can range up to the root CA +certificate. Such a file is simply the concatenation of the various +PEM-encoded CA Certificate files, usually in certificate chain order. + +This should be used alternatively and/or additionally to SSLCACertificatePath for explicitly +constructing the server certificate chain which is sent to the browser in +addition to the server certificate. It is especially useful to avoid conflicts +with CA certificates when using client authentication. Because although +placing a CA certificate of the server certificate chain into SSLCACertificatePath has the same effect for +the certificate chain construction, it has the side-effect that client +certificates issued by this same CA certificate are also accepted on client +authentication. That's usually not one expect. + +But be careful: Providing the certificate chain works only if you are using a +single (either RSA or DSA) based server certificate. If you are +using a coupled RSA+DSA certificate pair, this will work only if actually both +certificates use the same certificate chain. Else the browsers will be +confused in this situation. + +Example: + ++ ++SSLCertificateChainFile /usr/local/apache/conf/ssl.crt/ca.crt ++ SSLCACertificatePath+
+This directive sets the directory where you keep the Certificates of +Certification Authorities (CAs) whose clients you deal with. These are used to +verify the client certificate on Client Authentication. +
+The files in this directory have to be PEM-encoded and are accessed through
+hash filenames. So usually you can't just place the Certificate files
+there: you also have to create symbolic links named
+hash-value.N. And you should always make sure this directory
+contains the appropriate symbolic links. Use the +Example: + ++ ++SSLCACertificatePath /usr/local/apache/conf/ssl.crt/ ++ SSLCACertificateFile+
+This directive sets the all-in-one file where you can assemble the +Certificates of Certification Authorities (CA) whose clients you deal +with. These are used for Client Authentication. Such a file is simply the +concatenation of the various PEM-encoded Certificate files, in order of +preference. This can be used alternatively and/or additionally to SSLCACertificatePath. + +Example: + ++ ++SSLCACertificateFile /usr/local/apache/conf/ssl.crt/ca-bundle-client.crt ++ SSLCARevocationPath+
+This directive sets the directory where you keep the Certificate Revocation +Lists (CRL) of Certification Authorities (CAs) whose clients you deal with. +These are used to revoke the client certificate on Client Authentication. +
+The files in this directory have to be PEM-encoded and are accessed through
+hash filenames. So usually you have not only to place the CRL files there.
+Additionally you have to create symbolic links named
+hash-value.rN. And you should always make sure this directory
+contains the appropriate symbolic links. Use the +Example: + ++ ++SSLCARevocationPath /usr/local/apache/conf/ssl.crl/ ++ SSLCARevocationFile+
+This directive sets the all-in-one file where you can assemble the +Certificate Revocation Lists (CRL) of Certification Authorities (CA) whose +clients you deal with. These are used for Client Authentication. +Such a file is simply the concatenation of the various PEM-encoded CRL +files, in order of preference. This can be used alternatively and/or +additionally to SSLCARevocationPath. + +Example: + ++ ++SSLCARevocationFile /usr/local/apache/conf/ssl.crl/ca-bundle-client.crl ++ SSLVerifyClient+
+This directive sets the Certificate verification level for the Client +Authentication. Notice that this directive can be used both in per-server and +per-directory context. In per-server context it applies to the client +authentication process used in the standard SSL handshake when a connection is +established. In per-directory context it forces a SSL renegotation with the +reconfigured client verification level after the HTTP request was read but +before the HTTP response is sent. + +The following levels are available for level: +
+Example: + ++ ++SSLVerifyClient require ++ SSLVerifyDepth+
+This directive sets how deeply mod_ssl should verify before deciding that the +clients don't have a valid certificate. Notice that this directive can be +used both in per-server and per-directory context. In per-server context it +applies to the client authentication process used in the standard SSL +handshake when a connection is established. In per-directory context it forces +a SSL renegotation with the reconfigured client verification depth after the +HTTP request was read but before the HTTP response is sent. +
+The depth actually is the maximum number of intermediate certificate issuers,
+i.e. the number of CA certificates which are max allowed to be followed while
+verifying the client certificate. A depth of 0 means that self-signed client
+certificates are accepted only, the default depth of 1 means the client
+certificate can be self-signed or has to be signed by a CA which is directly
+known to the server (i.e. the CA's certificate is under
+ +Example: + ++ ++SSLVerifyDepth 10 ++ SSLLog+
+This directive sets the name of the dedicated SSL protocol engine logfile.
+Error type messages are additionally duplicated to the general Apache error
+log file (directive +Example: + ++ ++SSLLog /usr/local/apache/logs/ssl_engine_log ++ SSLLogLevel+
+This directive sets the verbosity degree of the dedicated SSL protocol engine +logfile. The level is one of the following (in ascending order where +higher levels include lower levels): +
+Example: + ++ ++SSLLogLevel warn ++ SSLOptions+
+This directive can be used to control various run-time options on a
+per-directory basis. Normally, if multiple +The available options are: +
+Example: + ++ ++SSLOptions +FakeBasicAuth -StrictRequire +<Files ~ "\.(cgi|shtml)$"> + SSLOptions +StdEnvVars +CompatEnvVars -ExportCertData +<Files> ++ SSLRequireSSL+
+This directive forbids access unless HTTP over SSL (i.e. HTTPS) is enabled for +the current connection. This is very handy inside the SSL-enabled virtual +host or directories for defending against configuration errors that expose +stuff that should be protected. When this directive is present all requests +are denied which are not using SSL. + +Example: + ++ ++SSLRequireSSL ++ SSLRequire+
+This directive specifies a general access requirement which has to be +fulfilled in order to allow access. It's a very powerful directive because the +requirement specification is an arbitrarily complex boolean expression +containing any number of access checks. + +The expression must match the following syntax (given as a BNF +grammar notation): +
+
+while for varname any variable from Table 3
+can be used. Finally for funcname the following functions
+are available:
+
+Example: +
+
+
+
+
+
+ + + Additional Features+Environment Variables+This module provides a lot of SSL information as additional environment +variables to the SSI and CGI namespace. The generated variables are listed in +Table 4. For backward compatibility the information can +be made available under different names, too. Look in the Compatibility chapter for details on the +compatibility variables. ++
+
+
+
+ Custom Log Formats+When mod_ssl is built into Apache or at least loaded (under DSO situation) +additional functions exist for the Custom Log Format of mod_log_config. First there is an additional +``%{varname}x'' eXtension format function
+which can be used to expand any variables provided by any module, especially
+those provided by mod_ssl which can you find in Table 4.
+
+For backward compatibility there is additionally a special
+`` +Example: +
+
+
+
|
+|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
+ 
+ 
+ 
+ere we talk about backward compatibility to other SSL solutions. As you
+perhaps know, mod_ssl is not the only existing SSL solution for Apache.
+Actually there are four additional major products available on the market: Ben
+Laurie's freely available 
+ 
+ 
+his chapter is a collection of frequently asked questions (FAQ) and
+corresponding answers following the popular USENET tradition. Most of these
+questions occured on the Newsgroup 
+ 
+ 
+ 
+ 
+ow to solve particular security constraints for an SSL-aware webserver
+is not always obvious because of the coherences between SSL, HTTP and Apache's
+way of processing requests. This chapter gives instructions on how to solve
+such typical situations. Treat is as a first step to find out the final
+solution, but always try to understand the stuff before you use it. Nothing is
+worse than using a security solution without knowing it's restrictions and
+coherences.
+
+ 
+ 
+s an introduction this chapter is aimed at readers who are familiar
+with the Web, HTTP, and Apache, but are not security experts. It is not
+intended to be a definitive guide to the SSL protocol, nor does it discuss
+specific techniques for managing certificates in an organization, or the
+important legal issues of patents and import and export restrictions. Rather,
+it is intended to provide a common background to mod_ssl users by pulling
+together various concepts, definitions, and examples as a starting point for
+further exploration.
+
+
+
+
+ 
+ 
+his module provides strong cryptography for the 
+
+ 
+ 
+his chapter provides a reference to all configuration directives and
+additional user visible features mod_ssl provides. It's intended as the
+official resource when you want to know how a particilar mod_ssl functionality
+is actually configured or activated. Each directive is documented similar to
+the way standard Apache directives are documented in the official Apache
+documentation set, i.e. for each directive especially the syntax, default and
+context where applicable is given.
+