19.32 mod_ssl The mod_ssl enables encrypted, secure transactions between the server and client with SSL (Secure Sockets Layer) Versions 2 and 3, and TLS (Transport Layer Security) Version 1. Apache uses OpenSSL as its cryptography engine. Apache 2.0 and up. The directives in this module set the locations of certificate and key files, specify options for the behavior of the encryption engine, and set up authorization requirements for access to protected parts of the server. The module also creates a number of new SSL_* environment variables , which will be available to SSI, CGI, and custom logging formats.
SSLCACertificateFile filename [ server config , within <VirtualHost>] Specifies the location of a single file that contains all of the certificates for the Certificate Authorities that you need for client verification. The file is a concatenation of the separate certificates, in order of preference. You can also use separate certificate files located in a single directory specified by SSLCACertificatePath.
SSLCACertificatePath directory [ server config , within <VirtualHost>] Specifies the directory containing the PEM-encoded certificate files for the Certificate Authorities that you need for client verification. Certificate files are accessed with hash filenames via symbolic links of the form hashname .N, This directory can be set up properly using the Makefile provided with mod_ssl.
SSLCARevocationFile filename [ server config , within <VirtualHost>] Specifies a file containing multiple, encoded Certificate Revocation Lists (CRLs) of the Certificate Authorities used by your clients . CRLs are used to revoke client certificates during authentication.
SSLCARevocationPath directory [ server config , within <VirtualHost>] Specifies the directory containing Certificate Revocation Lists (CRLs) for Certificate Authorities used by clients. Encoded CRL files are accessed with hash filenames via symbolic links of the form hashname .rN, This directory can be set up properly using the Makefile provided with mod_ssl.
SSLCertificateChainFile filename [ server config , within <VirtualHost>] Specifies the single file containing all the server's certificates as a certificate chain establishing a path of trust. This will include the server's certificate and the certificate of the CA that issued it. It could possibly go to higher levels of CA certificates.
SSLCertificateFile filename [ server config , within <VirtualHost>] Specifies the file containing the server's certificate and optionally , its RSA or DSA private key.
SSLCertificateKeyFile filename [ server config , within <VirtualHost>] Specifies the file containing the server's Private key. This directive must be used in conjunction with SSLCertificateFile, which specifies the certificate file (when the Private key is not included there).
SSLCipherSuite cipher_spec [ server config , within <VirtualHost> or <Directory>, or .htaccess ] This directive combines a number of cipher specifications to configure the Cipher Suite. The Cipher Suite is the set of methods or algorithms used by the server and client to establish secure communications. The cipher suite is negotiated during the handshake phase, just after a client sends an SSL request. The cipher_spec provided by this directive lists a set of methods that the server will support for a request. The client and server negotiate the most common and preferred methods in this list to use for transactions. The cipher_spec is a rather complex string that requires at least one declaration for each of the following: a key exchange algorithm, an authentication algorithm, a cipher or encryption algorithm, and MAC digest algorithm. You can additionally declare an export cipher. There are many different tags for specific ciphers that can be combined for the cipher spec. Certain alias tags have been defined to group ciphers into specific sets that comprise certain protocols and levels of security. Table 19-2 lists the alias tags. Table 19-2. Cipher tag aliases
The cipher_spec string is composed of a list of cipher tags separated by colons. Each tag may also have a qualifier placed before it. No qualifier means that the cipher is added to the list. A + means that the cipher is added and is pulled to this location on the cipher order. A - means that the cipher is removed from the list, but can be added somewhere else. A ! means that the cipher cannot be used at all. The default value for this directive demonstrates these features: ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP The cipher_spec first includes all ciphers, then removes the ones it doesn't want (!ADH) and adjusts the order of preference for the remaining ciphers. See the Apache and OpenSSL documentation for a complete list of cipher tags and complete information on using SSL for secure server communications. |
SSLEngine |
SSLEngine offon
[ server config , within <VirtualHost>]
Enables or disables the SSL/TLS protocol engine for the server or a virtual host.
SSLMutex |
SSLMutex type
[ server config ]
Configures the SSL engines mutex (mutual exclusion) mechanism to synchronize multiple server processes' access to the SSL session cache. There are three types that can be used:
On Unix systems, you can specify a file that is used as the mutex lock. This option is not usable in the Win32 environment.
This options uses an IPC semaphore process flag for synchronization on Unix and a Windows Mutex flag on Win32.
The default specifies that no exclusion mechanism is used. This may result in mangled information in the SSL session cache.
SSLOptions |
SSLOptions [+-] option...
[ server config , within <VirtualHost> or <Directory>, or .htaccess ]
Controls a number of SSL runtime options. Per-directory or location merging of options is controlled by the + or - prepended to an option. A + option adds to the set of options that are in place from an higher-level specification. A - options removes an localized option that was in place from a higher-level specification. The available options are:
Creates the standard set of SSL- related environment variables. Since there are many of these and gathering this information can cause a performance hit, this configurable per directory, for example, is for CGI and SSL requests only.
Creates a set of environment variables that enable compatibility with previous Apache SSL programs.
Creates environment variables containing the encoded server and client certificate information for use with CGI.
Allows basic authorization to be mocked using the Subject Distinguished Name (DN) of a client certificate as a valid username. No password is requested from the user, but the user file must have the appropriately encoded string for "password" for this scheme to work.
Forces strict SSL authorization (with SSLRequire or SSLRequireSSL) to be satisfied regardless of whether other authorization requirements are met when the Satisfy any directive is used. Without this option, Satisfy any overrides a forbidden access from SSL if other authorization requirements are met.
Allows for optimized renegotiation handling of SSL connections when directory-specific directives are specified. Normally, full renegotiation will be performed.
SSLPassPhraseDialog |
SSLPassPhraseDialog type
[ server config ]
Sets the type of dialog used to get the administrator's pass phrase for accessing encrypted private keys. The administrator needs to provide this information during server startup. The valid types are:
This uses an interactive dialog at the terminal at startup. The administrator provides the pass phrase for each encrypted private key file. There is a reuse mechanism for multiple keys used on virtual hosts . Pass phrases will automatically be retried to see if it can be used for multiple key files, thus saving some input.
This option calls a program at startup to produce the pass phrase however it sees fit, and send it to stdout for use with the terminal dialog described by the builtin option. The script is called with two arguments. The first argument is servername :portnumber, The second is either RSA or DSA, which is determined by the encryption used by the key file. This method is very flexible, and the administrator can provide any number of security checks to the process.
SSLProtocol |
SSLProtocol [+-] protocol
[ server config , or within <VirtualHost>]
Specifies the SSL protocol(s) used by the server. The values can be: SSLv2, SSLv3, TLSv1, or All. The + or - flags are used to add or remove a protocol from a set.
SSLProxyCACertificateFile |
SSLProxyCACertificateFile
[ server config , within <VirtualHost>]
Specifies the location of a single file that contains all of the certificates for the Certificate Authorities that you need for remote server verification. The file is a concatenation of the separate certificates, in order of preference. You can also use separate certificate files located in a single directory specified by SSLProxyCA-CertificatePath.
SSLProxyCACertificatePath |
SSLProxyCACertificatePath
[ server config , within <VirtualHost>]
Specifies the directory containing the PEM-encoded certificate files for the Certificate Authorities that you need for remote server verification. Certificate files are accessed with hash filenames via symbolic links of the form hashname .N, This directory can be set up properly using the Makefile provided with mod_ssl.
SSLProxyCARevocationFile |
SSLProxyCARevocationFile
[ server config , within <VirtualHost>]
Specifies a file containing multiple, encoded Certificate Revocation Lists (CRLs) of the Certificate Authorities used by remote servers. CRLs are used to revoke remote server certificates during authentication.
SSLProxyCARevocationPath |
SSLProxyCARevocationPath
[ server config , within <VirtualHost>]
Specifies the directory containing Certificate Revocation Lists (CRLs) for Certificate Authorities used by remote servers. Encoded CRL files are accessed with hash filenames via symbolic links of the form hashname .rN. This directory can be set up properly using the Makefile provided with mod_ssl.
SSLProxyCipherSuite |
SSLProxyCipherSuite cipher_spec
[ server config , within <VirtualHost> or <Directory>, or .htaccess ]
Specifies the cipher suite used for a proxy connection. The options are the same as SSLCipherSuite.
SSLProxyEngine |
SSLProxyEngine onoff
[ server config , within <VirtualHost>]
Enables or disables the SSL engine for proxy connections. The default is off.
SSLProxyMachineCertificateFile |
SSLProxyMachineCertificateFile
[ server config ]
Specifies the location of a single file that contains all of the certificates for the Certificate Authorities that are needed to verify the proxy server to remote servers. The file is a concatenation of the separate certificates, in order of preference. You can also use separate certificate files located in a single directory specified by SSLProxyMachineCertificatePath.
SSLProxyMachineCertificatePath |
SSLProxyMachineCertificatePath
[ server config ]
Specifies the directory containing the PEM-encoded certificate files for the Certificate Authorities that you need to verify the proxy server to remote servers. Certificate files are accessed with hash filenames via symbolic links of the form hashname .N, This directory can be set up properly using the Makefile provided with mod_ssl.
SSLProxyProtocol |
SSLProxyProtocol
[ server config , within <VirtualHost>]
Specifies the SSL protocols available for the proxy server. The options are the same as SSLProtocol.
SSLProxyVerify |
SSLProxyVerify level
[ server config , within <VirtualHost> or <Directory>, or .htaccess ]
Specifies the verification level required for remote server verification. value can be one of the following:
No remote server certificate is required.
A valid certificate must be presented by the remote server.
A valid certificate may be required for the remote server. This option isn't very useful or supported.
The remote server is verified with or without a valid certificate. This is useful for test purposes only.
SSLProxyVerifyDepth |
SSLProxyVerifyDepth number
[ server config , within <VirtualHost> or <Directory>, or .htaccess ]
Specifies the maximum verification depth that is allowed for determination of a valid certificate by a proxy server. The number is the number of unknown intermediate certificates allowed between the client and a certificate authority trusted by the client. For example, a depth of two would allow a client certificate that is certified by a CA unknown to the server. If that CA is certified by another CA known to the server, the verification is allowed. The default is 1.
SSLRandomSeed |
SSLRandomSeed context source [ bytes ]
[ server config ]
Specifies the source of seeding for the pseudorandom number generator used by OpenSSL. context determines the seeding source either at startup or when a new SSL connection is made (connect).
The source specifies the utility that provides the random seed. builtin indicates that mod_ssl's internal seeding utility is used. It is a simple utility, but doesn't provide a strong seeding source. Other seeding sources are: file: /path/file , which uses the contents of a file to determine the seeding. This usually points to a device file for a random generator like /dev/random . exec: /path/prog points to an executable source for seeding. The source is the stream of bytes sent to stdout. For both file and executable sources, an optional argument specifying a number of bytes indicates that only the first bytes of the source (file or output) will be used. Without this argument, the complete source is used.
SSLRequire |
SSLRequire expression
[within <Directory> or .htaccess ]
Specifies the requirements that must be met before access is allowed to a resource. The access requirement is an arbitrarily complex boolean expression, whose syntax is very similar to common programming language syntax like C or Java. Logical and comparison operators can be used in any combination with the values of environment variables to determine access. Environment variables are available with the following syntax: %{ variable }.
SSLRequireSSL |
SSLRequireSSL
[within <Directory> or .htaccess ]
When this directive is used (it has no arguments), it forbids access to a directory unless HTTP over SSL is used.
SSLSessionCache |
SSLSessionCache type
[ server config ]
Specifies the type of resource used for the SSL session cache. The session cache contains the SSL verification information for an open session, and allows access to this information to the multiple processes involved in a client request session. Clients will commonly use HTTP KeepAlive to retrieve numerous files associated with a resource like inline images, style sheets, etc., simultaneously to reduce loading time.
This directive specifies the type of resource used for the session cache with the following options:
Disables the session cache. Functionality is not affected, but requests will take longer to complete.
Specifies the name of a DBM hash file to use as the session cache file.
Specifies a hash table stored in shared memory for the session cache file. An optional size argument sets the size of the hashtable. This option is not available on all platforms.
SSLSessionCacheTimeout |
SSLSessionCacheTimeout time
[ server config , within <VirtualHost> or <Directory>, or .htaccess ]
Specifies the timeout in seconds for the information in the session cache to be valid between requests. The default is 300.
SSLVerifyClient |
SSLVerifyClient level
[ server config , within <VirtualHost> or <Directory>, or .htaccess ]
Specifies the verification level required for client verification. value can be one of the following:
No client certificate is required.
A valid certificate must be presented by the client.
A valid certificate may be required for the client. This option isn't very useful or supported.
The client is verified with or without a valid certificate. This is useful for test purposes only.
SSLVerifyDepth |
SSLVerifyDepth number
[ server config , within <VirtualHost> or <Directory>, or .htaccess ]
Specifies the maximum verification depth is allowed for determination of a valid certificate by a client. The number is the number of unknown intermediate certificates are allowed between the client and a certificate authority trusted by the server. For example, a depth of 2 would allow a client certificate that is certified by a CA unknown to the server. If that CA is certified by another CA known to the server, the verification is allowed. The default is 1.
Team-Fly |
Top |