Apache Module mod_ssl

Environment Variables

This module can be configured to provide several items of SSL information as additional environment variables to the SSI and CGI namespace. Except for HTTPS and SSL_TLS_SNI which are always defined, this information is not provided by default for performance reasons. (See SSLOptions StdEnvVars, below) The generated variables are listed in the table below. For backward compatibility the information can be made available under different names, too. Look in the Compatibility chapter for details on the compatibility variables.

x509 specifies a component of an X.509 DN; one of C,ST,L,O,OU,CN,T,I,G,S,D,UID,Email. In httpd 2.2.0 and later, x509 may also include a numeric _n suffix. If the DN in question contains multiple attributes of the same name, this suffix is used as a zero-based index to select a particular attribute. For example, where the server certificate subject DN included two OU attributes, SSL_SERVER_S_DN_OU_0 and SSL_SERVER_S_DN_OU_1 could be used to reference each. A variable name without a _n suffix is equivalent to that name with a _0 suffix; the first (or only) attribute. When the environment table is populated using the StdEnvVars option of the SSLOptions directive, the first (or only) attribute of any DN is added only under a non-suffixed name; i.e. no _0 suffixed entries are added.

In httpd 2.4.32 and later, an optional _RAW suffix may be added to x509 in a DN component, to suppress conversion of the attribute value to UTF-8. This must be placed after the index suffix (if any). For example, SSL_SERVER_S_DN_OU_RAW or SSL_SERVER_S_DN_OU_0_RAW could be used.

The format of the *_DN variables has changed in Apache HTTPD 2.3.11. See the LegacyDNStringFormat option for SSLOptions for details.

SSL_CLIENT_V_REMAIN is only available in version 2.1 and later.

A number of additional environment variables can also be used in SSLRequire expressions, or in custom log formats:

HTTP_USER_AGENT        PATH_INFO             AUTH_TYPE
HTTP_REFERER           QUERY_STRING          SERVER_SOFTWARE
HTTP_COOKIE            REMOTE_HOST           API_VERSION
HTTP_FORWARDED         REMOTE_IDENT          TIME_YEAR
HTTP_HOST              IS_SUBREQ             TIME_MON
HTTP_PROXY_CONNECTION  DOCUMENT_ROOT         TIME_DAY
HTTP_ACCEPT            SERVER_ADMIN          TIME_HOUR
THE_REQUEST            SERVER_NAME           TIME_MIN
REQUEST_FILENAME       SERVER_PORT           TIME_SEC
REQUEST_METHOD         SERVER_PROTOCOL       TIME_WDAY
REQUEST_SCHEME         REMOTE_ADDR           TIME
REQUEST_URI            REMOTE_USER

In these contexts, two special formats can also be used:

ENV:variablename

This will expand to the standard environment variable variablename.

HTTP:headername

This will expand to the value of the request header with name headername.

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 the above table.

For backward compatibility there is additionally a special ``%{name}c'' cryptography format function provided. Information about this function is provided in the Compatibility chapter.

CustomLog "logs/ssl_request_log" "%t %h %{SSL_PROTOCOL}x %{SSL_CIPHER}x \"%r\" %b"

These formats even work without setting the StdEnvVars option of the SSLOptions directive.

Request Notes

mod_ssl sets "notes" for the request which can be used in logging with the %{name}n format string in mod_log_config.

The notes supported are as follows:

ssl-access-forbidden

This note is set to the value 1 if access was denied due to an SSLRequire or SSLRequireSSL directive.

ssl-secure-reneg

If mod_ssl is built against a version of OpenSSL which supports the secure renegotiation extension, this note is set to the value 1 if SSL is in used for the current connection, and the client also supports the secure renegotiation extension. If the client does not support the secure renegotiation extension, the note is set to the value 0. If mod_ssl is not built against a version of OpenSSL which supports secure renegotiation, or if SSL is not in use for the current connection, the note is not set.

Expression Parser Extension

When mod_ssl is built into Apache or at least loaded (under DSO situation) any variables provided by mod_ssl can be used in expressions for the ap_expr Expression Parser. The variables can be referenced using the syntax ``%{varname}''. Starting with version 2.4.18 one can also use the mod_rewrite style syntax ``%{SSL:varname}'' or the function style syntax ``ssl(varname)''.

Header set X-SSL-PROTOCOL "expr=%{SSL_PROTOCOL}"
Header set X-SSL-CIPHER "expr=%{SSL:SSL_CIPHER}"

This feature even works without setting the StdEnvVars option of the SSLOptions directive.

Authorization providers for use with Require

mod_ssl provides a few authentication providers for use with mod_authz_core's Require directive.

Require ssl

The ssl provider denies access if a connection is not encrypted with SSL. This is similar to the SSLRequireSSL directive.

Require ssl

Require ssl-verify-client

The ssl provider allows access if the user is authenticated with a valid client certificate. This is only useful if SSLVerifyClient optional is in effect.

The following example grants access if the user is authenticated either with a client certificate or by username and password.

Require ssl-verify-client
Require valid-user