Secure Sockets Layer (SSL) directives

SSLOCSPResponderURL

Even if CRL checking is configured, OCSP checking is performed before any CRL checking. CRL checking occurs only if the result of the CRL is unknown or inconclusive.

If SSLOCSPResponderURL is set, IBM HTTP Server uses the supplied URL to check for certificate revocation status when an SSL client certificate is provided.

SSLOCSPEnable

If SSLOCSPEnable is set, and an SSL client certificate chain contains an AIA extension, IBM HTTP Server contacts the OCSP responder indicated by the AIA extension to check revocation status of the client certificate.

If both OCSP and CRL checking is configured, OCSP checking is performed before any CRL checking. CRL checking occurs only if the result of the OCSP checking is unknown or inconclusive.

If both SSLOCSPEnable and SSLOCSPResponderURL are configured, the responder defined by SSLOCSPResponderURL is checked first. If the revocation status is unknown or inconclusive, IBM HTTP Server checks OCSP responders for SSLOCSPEnable.

SSLOCSPCacheSize

Enabling a nonzero SSLOCSPCacheSize allows for the use of an in-memory cache for OCSP responses. The lifespan of cache entries depends on the following three factors:

1. The nextUpdate field specified by the OCSP responder.
2. HTTP cache headers specified by the OCSP responder.
3. Eviction from a full cache to accommodate new entries.

The contents of the cache cannot be viewed, and can be cleared only when a web server restarts.

Keyfile directive

Use the prompt option to enable the HTTP server to prompt you for the Key file password at start time. The prompt option is only supported when the server is started interactively from the command line.

Important: The z/OS® system does not support key database files created on other platforms. Key database files used for z/OS systems must be created on the z/OS platform.

The ID that is used to start IBM HTTP Server must have access to the keyring named in this directive. If the ID does not have access, SSL initialization fails.

SSLAcceleratorDisable directive

SSLAllowNonCriticalBasicConstraints directive

SSLCacheDisable directive

SSLCacheEnable directive

SSLCacheErrorLog directive

SSLCachePath directive

The SSLCachePath directive specifies the path to the session ID caching daemon. Unless you have multiple instances of IHS with multiple ServerRoot directives or -d options that share one installation, you do not need to specify this directive.

When multiple instances of IHS are being used with an alternate server root as previously described , this directive should be used to point this instance of IHS at the path to the bin/sidd binary in the single installation root instead of the separate server roots which are used by default.

There is no practical reason to copy the bin/sidd binary around, or to use this directive to specify anything other than the bin/sidd installed under the server root when multiple instances are used. The value of this directive does not have to vary between instances of IHS sharing the same binaries.

SSLCachePortFilename directive

SSLCacheTraceLog directive

SSLCheckCertificateExpiration

SSLCipherBan directive

SSLCipherRequire directive

SSLCipherSpec directive

The SSLCipherSpec directive enables you to customize the SSL ciphers that are supported during the handshake. You can customize the set of SSL ciphers and the order of preference of the SSL ciphers.

On distributed platforms, each protocol has its own ordered list of ciphers. The supported protocols are SSL version 2, SSL version 3, TLS version 1.0, TLS version 1.1, and TLS version 1.2.

On z/OS, there are only two lists of enabled ciphers, one for SSL version 2 and one for the other protocols. The supported protocols are SSL version 2, SSL version 3, and TLS version 1.0, and TLS version 1.1. TLS version 1.2 is supported on z/OS V1R13 with OA39422, or later.

SSL Version 2 ciphers default to no ciphers, which means that the protocol is disabled. The other protocols default to a set of SSL ciphers that excludes null ciphers, export ciphers, and weak ciphers.

When you use the single-argument form of SSLCipherSpec, the cipher is enabled in all protocols for which it is valid. The first time such a change is made for each protocol, the default ciphers for the protocol are discarded.

When you use the multiple-argument form of SSLCipherSpec, specifying the name of an SSL protocol (or ALL) as the first argument, you can use an enhanced syntax with the following benefits:

If you provide a protocol name of ALL, then the adding or removing specified for each cipher name is applied to each protocol where that cipher is valid.

As a special case, to empty all the cipher lists with a single command, you can use SSLCipherSpec ALL NONE. Using this command is a good way to start a configuration anytime you do not want to use the default ciphers.

Example 1

If you want to select just a few ciphers, it is best to start by resetting all the cipher lists, then adding the required ciphers:

# Delete all ciphers from the cipher lists 
SSLCipherSpec ALL NONE 
# Add a few specific ciphers 
SSLCipherSpec ALL +SSL_RSA_WITH_3DES_EDE_CBC_SHA 
SSLCipherSpec ALL +TLS_RSA_WITH_AES_256_CBC_SHA 

Example 2

If you want to use most of the defaults, you can remove the unwanted ciphers from any lists in which they reside:

# Delete some specific ciphers from the protocols where they are valid 
SSLCipherSpec ALL -SSL_RSA_WITH_RC4_128_MD5
SSLCipherSpec ALL -SSL_RSA_WITH_RC4_128_SHA 

SSLClientAuth directive

SSLClientAuthGroup directive

The SSLClientAuthGroup directive defines a named expression group that contains a set of specific client certificate attribute and value pairs. This named group can be used by the SSLClientAuthRequire directives. A certificate must be provided by the client, which passes this expression, before the server allows access to the protected resource.

SSLClientAuthGroup IBMUSpeople (Org
=  IBM) AND (Country = US)

The following section provides a description of examples with valid logical expressions. For example: SSLClientAuthGroup ((CommonName = "Fred Smith") OR (CommonName = "John Deere")) AND (Org = IBM) indicates that the object is not served, unless the client certificate contains a common name of either Fred Smith or John Deere and the organization is IBM. The only valid comparisons for the attribute checks, are equal and not equal (= and !=). You can link each attribute check with AND, OR, or NOT (also &&, ||, and !). Any comparisons that you link with AND, OR, or NOT must be contained within parentheses. If the value of the attribute contains a non-alphanumeric character, you must delimit the value with quotation marks.

The long name or the short name can be used in this directive.

SSLClientAuthGroup IBMpeople Org = IBM)

SSLClientAuthGroup
NotMNIBM (ST != MN) && (Org = IBM) 

A group name cannot include spaces. For more information, see SSLClientAuthRequire directive.

SSLClientAuthRequire directive

The SSLClientAuthRequire directive specifies attribute values, or groups of attribute values, that must be validated against a client certificate before the server allows access to the protected resource.

SSLClientAuthRequire (group != IBMpeople)
 && (ST = M)

If the certificate you received does not have a particular attribute, then there is no verification for an attribute match. Even if the specified matching value is " ", this might still not be the same as not having the attribute there at all. Any attribute specified on the SSLClientAuthRequire directive that is not available on the certificate causes the request to be rejected.

The long name or the short name can be used in this directive.

The user specifies a logical expression of specific client certificate attributes. You can logically use AND , OR, or NOT for multiple expressions if you must specify groupings of client certificate attribute values. Any comparisons that are linked with AND, OR, or NOT must be contained within parentheses. Valid operators include = and !=. The user can also specify a group name, that is configured using the SSLClientAuthGroup directive, to configure a group of attributes.

SSLClientAuthRequire ((CommonName="John Doe") || (StateOrProvince=MN)) && (Org!=IBM)  

SSLClientAuthRequire (group!=IBMpeople) && (ST=MN)

SSLClientAuthRequire (group!= IBMpeople) && ("ST= MN")

Table 3. Attributes relating to the Subject Alternative Name (SAN) TLS client certificate extension. Each attribute must be suffixed with a digit between 0 and 3 inclusive, such as SANDNSNAME0 or SANIPADDRESS3.

Attribute Prefix	Description
SANDNSNAME	DNS Name
SANIPADDRESS	IP Address
SANRFC822NAME	RFC822 Name (email)
SANDIRECTORYNAME	Directory Name
SANURI	Universal Resource Identifier (URI)

Note: Only the first four values of each extension type are available as attributes. See Client certificate environment variables expression parser support for more complex needs.

SSLClientAuthVerify directive

The SSLClientAuthVerify directive controls whether IBM HTTP Server fails requests when a client certificate is received, but it fails validation (for example, it is expired or revoked).

Use this directive with SSLClientAuth Optional Noverify to provide a user friendly web page, instead of the default browser error message.

If you configure a virtual host with SSLClientAuth Optional Noverify, an SSL connection can be established when a client certificate is received, but it fails validation (for example, it is expired or revoked).

Use this directive in a context such as Location or Directory to fail requests that are received on that connection with a specific error code, or handled normally by setting OFF.

By providing a custom error document for that status, the administrator can control the page that is presented to the user, for example, to tell the user their certificate is invalid and provide further instructions.

If the error document is an internal redirect to another URL in the same virtual host, you must ensure that URL has SSLClientAuthVerify OFF in its context so it does not immediately fail, as well. An example of this scenario follows.

The specified status code must be a response status that is valid in HTTP and known to IBM HTTP Server. The values are between 100 and 599, and are typically defined in an RFC or standards proposal. If you are unsure, try a status code in a test configuration and use apachectl -t to see if it is valid. Other unused codes that are valid and would be good choices include: 418, 419, 420, and 421.

Because the client certificate was invalid, the error document will not have any of the environment variables available that would contain information about the client certificate. The cause of the client certificate validation failure is available in the SSL_LAST_VALIDATION_ERROR environment variable . The variable could be GSKVAL_ERROR_REVOKED_CERT or GSKVAL_ERROR_CERT_EXPIRED. If the certificate has multiple validation problems, the reported cause is often GSKVAL_ERROR_CA_MISSING_CRITICAL_BASIC_CONSTRAINT.

Each time a client certificate validation fails, two messages are logged in the error log at loglevel Error. The second message includes the cause, for example:

[Tue Jun 08 08:54:25 2010] [error] [client 9.37.243.128] [9e44c28] [731] SSL0208E: SSL Handshake Failed, 
   Certificate validation error. [9.37.243.128:60347 -> 9.37.243.67:443] [08:54:25.000223331]
[Tue Jun 08 08:54:25 2010] [error] [client 9.37.243.128] [9e44c28] [731] Certificate validation error 
   during handshake, last PKIX/RFC3280 certificate validation error was 
   GSKVAL_ERROR_CA_MISSING_CRITICAL_BASIC_CONSTRAINT 
   [9.37.243.128:60347 -> 9.37.243.67:443] [08:54:25.000223331]

<VirtualHost *:443
SSLClientAuth Optional Noverify
<Location />
SSLClientAuthVerify 419
</Location>
ErrorDocument 419 /error419.html
<Location /error419.html>
SSLClientAuthVerify OFF
</Location>
</VirtualHost>

SSLCRLHostname directive (deprecated)

The SSLCRLHostname directive specifies the TCP/IP name or address of LDAP server where the Certificate Revocation List (CRL) database is located.

Use the SSLCRLHostname directive, along with SSLCRLPort, SSLCRLUserID, and SSLStashfile directives, for static configuration of an LDAP-based CRL repository. It is only necessary to use these directives to query the LDAP-based CRL repository if an explicit CRLDistributionPoint X.509v3 certificate extension is absent or the server specified in the extension is unresponsive (i.e. unavailable).

If a CRLDistributionPoint extension is present in the certificate and the server specified in the extension is responsive (i.e. available), then the LDAP server specified in the CRLDistributionPoint is queried anonymously, without using these directives.

SSLCRLPort directive (deprecated)

The SSLCRLPort directive specifies the port of the LDAP server where the Certificate Revocation List (CRL) database resides.

Use the SSLCRLPort directive, along with SSLCRLUserID, SSLCRLHostname, and SSLStashfile directives, for static configuration of an LDAP-based CRL repository. It is only necessary to use these directives to query the LDAP-based CRL repository if an explicit CRLDistributionPoint X.509v3 certificate extension is absent or the server that is specified in the extension is unresponsive (unavailable).

If a CRLDistributionPoint extension is present in the certificate and the server specified in the extension is responsive (available), then the LDAP server specified in the CRLDistributionPoint is queried anonymously, without using these directives.

SSLCRLUserID directive (deprecated)

The SSLCRLUserID directive specifies the user ID to send to the LDAP server, where the Certificate Revocation List (CRL) database is located.

Use the SSLCRLUserID directive, along with SSLCRLPort, SSLCRLHostname, and SSLStashfile directives, for static configuration of an LDAP-based CRL repository. It is only necessary to use these directives to query the LDAP-based CRL repository if an explicit CRLDistributionPoint X.509v3 certificate extension is absent or the server that is specified in the extension is unresponsive (i.e. unavailable).

If a CRLDistributionPoint extension is present in the certificate and the server specified in the extension is responsive (available), then the LDAP server specified in the CRLDistributionPoint is queried anonymously, without using these directives.

SSLDisable directive

SSLEnable directive

SSLFakeBasicAuth directive

The SSLFakeBasicAuth directive enables the fake basic authentication support.

SSLFIPSDisable directive

SSLFIPSEnable directive

The SSLFIPSEnable directive enables Federal Information Processing Standards (FIPS).

This directive is applicable to distributed platforms.

Avoid trouble: This directive is supported on the z/OS platform with the following limitations.

• The directive is valid in the global scope only.
• If you change the value of the directive, you must stop and then start the IBM HTTP Server for the new value to take effect. The new value does not take effect if you do a restart.

SSLInsecureRenegotiation directive

The SSLInsecureRenegotiation directive determines whether insecure (pre RFC5746) SSL renegotiation is permitted. SSL Renegotiation of any kind is not common, and this directive should not be changed from its default value of off.

Attention: Prior to V8.0.0.1, the server has RFC5746 support and accepts secure renegotiation requests. In V8.0.0.1 and later, secure renegotiation requests are not accepted without first enabling the SSLRenegotiation directive.

When on is specified, insecure SSL renegotiation is permitted. When off is specified (the default), insecure SSL renegotiation is not permitted.

SSLMinimumRSAKeySize directive

The SSLMinimumRSAKeySize directive is primarily used to enforce a minimum RSA key size for received client certificates. The behavior of the directive depends on the capabilities that the platform security library provides.

The key size is enforced on client certificates that the server receives. The issuers of the client certificates are not checked.

The key size is enforced on all certificates that are sent or received by mod_ibm_ssl, including their full certificate chains. Use the environment variables SSL_CLIENT_KEY_ALG, such as RSA and EC_ecPublicKey, and SSL_CLIENT_KEY_SIZE in logging and conditional expressions.

The SSL handshake fails if the minimum RSA key size is not met.

SSLPKCSDriver directive

The SSLPKCSDriver directive identifies the fully qualified name to the module, or driver used to access the PKCS11 device.

SSLProtocolDisable directive

The SSLProtocolDisable directive enables you to specify one or more SSL protocols which cannot be used by the client for a specific virtual host. This directive must be located in a <VirtualHost> container.

<VirtualHost *:443> 
   SSLEnable 
   SSLProtocolDisable TLSv10
   # Any other directives ...
</VirtualHost>

SSLProtocolEnable directive

The SSLProtocolEnable directive can be used to enable individual SSL protocols.

SSLProxyEngine directive

SSLProxyCheckPeerCN directive

SSLRenegotiation directive

SSLServerCert directive

SSLStashfile directive

The SSLStashfile directive indicates path to file with file name containing the encrypted password for opening the PKCS11 device.

The SSLStashfile does not point to a stash file for the KeyFile in use, as that is calculated automatically based on the name of the KeyFile, and is a different type of stashfile.

Use the sslstash command, located in the bin directory of IBM HTTP Server, to create your CRL or cryptographic device stash file. The password you specify using the sslstash command should be the same as the password you use to log into your LDAP server or cryptographic hardware.

Usage: sslstash [-c] <directory_to_password_file_and_file_name> <function_name> <password>

Use the SSLStashFile directive, along with SSLCRLPort, SSLCRLHostname, and SSLCRLUserID directives, for static configuration of an LDAP-based CRL repository. It is only necessary to use these directives to query the LDAP-based CRL repository if an explicit CRLDistributionPoint X.509v3 certificate extension is absent or the server specified in the extension is unresponsive (unavailable).

If a CRLDistributionPoint extension is present in the certificate and the server specified in the extension is responsive (available), then the LDAP server specified in the CRLDistributionPoint is queried anonymously, without using these directives.

SSLSuiteBMode

The SSLSuiteBMode directive can be used to configures the enclosing virtual host to use the Suite B profile for TLS.

The Suite B profile drastically reduces the available signature algorithm and cipher specifications that the server uses. The set of acceptable algorithms and ciphers is subject to change over time as relevant standards change. The 128 and 192 arguments refer to the two levels of security discussed in RFC 6460.

Specifying this directive overrides most previously specified SSL directives. The SSLAttributeSet setting is not overridden by this directive because it has a higher priority. All Suite B profiles require the certificate chain for the server to use strong ECC signatures. The RFC 6460 documents the restrictions of the Suite B profile.

SSLSupportedCurves

The SSLSupportedCurves directive allows the curves that the server offers to be customized in the environment where handshakes use ECDHE key exchange. The client and server must negotiate a named curve that both sides support.

SSLTrace directive

The SSLTrace directive enables debug logging in mod_ibm_ssl. It is used in conjunction with the LogLevel directive. To enable debug logging in mod_ibm_ssl, set LogLevel to debug and add the SSLTrace directive to global scope in the IBM HTTP Server configuration file, after the LoadModule directive for mod_ibm_ssl. This directive is typically used at the request of IBM support while investigating a suspected problem with mod_ibm_ssl. It is not recommended to enable this directive under normal working conditions.

SSLUnknownRevocationStatus

The SSLUnknownRevocationStatus directive specifies how IBM HTTP Server reacts when IBM HTTP Server cannot readily determine the revocation status, which is coming through CRL or OCSP.

%{SSL_UNKNOWNREVOCATION_SUBJECT}e

%{ENV:SSL_UNKNOWNREVOCATION_SUBJECT}

SSLV2Timeout directive

The SSLV2Timeout directive sets the timeout for SSL Version 2 session IDs.

SSLV3Timeout directive

The SSLV3Timeout directive sets the timeout for SSL Version 3 and TLS session IDs. The validity period of the cached SSL session is not reset when an SSL session is reused.

SSLVersion directive

The SSLVersion directive causes object access rejection with a 403 response if the client has connected with an SSL protocol version other than the one specified.

In most cases, the SSLProtocolDisable directive is a better choice than the SSLVersion directive for ensuring use of particular SSL protocol versions. The SSLProtocolDisable directive enables the client browser to negotiate another protocol version if possible whereas the SSLVersion directive causes IBM HTTP Server to send a 403 response, which might confuse the user.