Apache Module mod_ibm_ssl

KeyFile Directive

This directive configures the SSL key file to be used for the enclosing virtual host. A corresponding stashfile (*.sth) is automatically used with the same base name as the specified KeyFile.

On z/OS, the name of a SAF keyring can be specified following a first argument of /saf. For more details on the syntax and usafe of SAF keyrings, see the definition of GSK_KEYRING_FILE in the z/OS Cryptographic Services System SSL Programming topic in your release of z/OS.

If the second argument is /prompt, IBM HTTP Server will interactively prompt for the corresponding password instead of using the stash file referenced above.

SSLAllowLegacyCerts Directive

When this directive is turned off, only the standard policy for certificates will be applied. That is, only certificates meeting the requirements in RFC5280 (part of the X.509 standard) will be accepted as valid.

The IBM Global Security Kit has deprecated the use of legacy certificates. However, if you still must use a pre-X.509 certificate, this directive may be toggled on and the certificate will be used as long as it is valid.

SSLAllowNonCriticalInhibitAnyPolicy Directive

SSLAttributeSet Directive

Sets underlying IBM Tivoli Global Security Kit (GSKit) configuration. Advanced usage only at the recommendation of IHS support.

These settings are applied after directives such as SSLCipherSpec and generally override what was previously set.

On z/OS, the file /usr/include/gskssl.h contains the symbolic names for the keys and values that are useable with this directive

SSLCheckCertificateExpiration Directive

If this directive is specified with a days parameter greater than zero, IHS will check the validity range of each certificate (personal, issuer, and immediate) in each configured KeyFile during SSL initialization.
For each certificate expiring within the specified number of days, the server will write a ALERT level message to the servers ErrorLog with the message ID "SSL0191E".

If this directive is enabled, certificates which have already expired are printed at NOTICE level with message ID "SSL0192E", unless the second parameter is the string "no_expired". To report only expired certificates, specify -1 for the first parameter.

Example:

Results in: "SSL0191E: Certificate label 'expiresoon' in key store /opt/IHS/conf/key.kdb will expire in 22 days"

SSLCipherSpec Directive

This directive allows the configuration of the specific SSL ciphers, as well as their order. Each protocol starts with a set of reasonable default ciphers, and this directive can add, remove, or re-order those ciphers.

The first argument specifies the name of a specific SSL protocol whose ciphers will be adjusted, or "ALL" to adjust all protocols for which the following ciphers are applicable. If "ALL" is specified, and a cipher cannot be removed or added due to not being applicable to that protocol, no error is reported. This allows a cipher to be added or removed from any protocol where it might be supported, without having to know in advance exactly where it applies.

The second argument specifies the cipher to add or remove. Ciphers prefixed with a minus symbol are removed from the current set of ciphers, and ciphers with a plus symbol (or no symbol at all) are added.

The second argument can be repeated, but "NONE" is only accepted in the initial position.

The first time a protocol is changed by this directive, if the cipher argument is not prefixed by a plus or minus symbol, the defaults are discarded and the current cipher becomes the only cipher.

Examples:

# Remove 3DES anywhere it shows up

SSLCipherSpec ALL -SSL_RSA_WITH_3DES_EDE_CBC_SHA

# Replace (no +/-) TLSv12 cipher list 

SSLCipherSpec TLSv12 TLS_RSA_WITH_AES_128_GCM_SHA256

SSLCipherSpec TLSv12 TLS_RSA_WITH_AES_256_GCM_SHA384

# Remove RSA key exchange (non-PFS) ciphers (requires 9.0.5.7 or later)
SSLCipherSpec ALL -RSA

SSLCipherSpec ALL -TLS_RSA_WITH_AES_128_CBC_SHA -TLS_RSA_WITH_AES_256_CBC_SHA

SSLClientAuth Directive

This directive configures if and how IBM HTTP Server will request an SSL certificate from clients. This feature is sometimes referred to as "mutual authentication" because it adds authentication of the client to the typical SSL server authentication.

none

No client certificate will be requested

optional

A client certificate will be requested, but no action is taken if a certificate is not presented.

required

A client certificate will be requested, and a failure to present one will result in a HTTP 403 error.

required_reset

A client certificate will be requested, and a failure to present one will result in a TLS alert being sent to the browser

SSLCompression Directive

This directive can be used to re-enable TLS compression TLS compression in web browsers is vulnerable to man in the middle attacks when malicious content is introduced.

SSLDisable Directive

This directive configures the enclosing virtual host to NOT use the SSL protocol. This is only necessary in non-SSL virtual hosts in the unusual case when the base server configuration has been configured for SSL with SSLEnable, which is automatically inherited by all virtual hosts.

SSLEnable Directive

This directive configures the enclosing virtual host to use the SSL protocol. The SNI option is only valid on the default (first listed) virtualhost for a set of name-based virtual hosts

SSLFatalErrorLimit Directive

In some rare cases, an individual process will stop processing handshakes and return errors such as SSL0209E/SSL0212E/SSL0203E. If this directive is set to non-zero, the process will gracefully exit after seeing the specified number of SSL0209E/SSL0212E/SSL0203E failures.

This directive is NOT inherited from the base server config to virtual hosts.

SSLFIPSDisable Directive

This directive causes the server to use the default SSL implementation in the bundled GSKit library. This directive is normally not required unless SSLFIPSEnable appears in global server configuration.

SSLFIPSEnable Directive

This directive causes the server to use the FIPS 140-2 validated cryptographic modules and ciphers available in the bundled GSKit library. It augments, not replaces, the SSLEnable directive.

IBM HTTP Server 8.5 and later on z/OS supports this directive being enabled only in a global (base configuration, outside of any vhost) context only. On z/OS, a FIPS compatible KeyFile must be created with gskkyman for both IBM HTTP Server and the WAS Plugin. FIPS compatible keystores on z/OS only allow certs with strong cryptography to be stored inside of them.

Optional arguments perform further configuration:

SP800131A

This enables a macro setting within the security library that tracks to current NIST SP800-131A recommendations. The exact set of ciphers, protocols, and algorithms supported may change over time.

SSLSuiteB-128

This enables a macro setting within the security library that tracks to current NSA Suite B recommendations. The exact set of ciphers, protocols, and algorithms supported may change over time. This mode is a very restrictive set of protocols and ciphers. SSLSuiteB is accepted as an alias.

SSLSuiteB-192

Like SSLSuiteB-128, but even stronger algorithms

uncertified

IHS contains two cryptographic modules. One is a FIPS140-2 certified implementation, the other is the service stream for the certified implementation where bugfixes and enhancements can be delivered without jeopardizing certification. This setting configures IHS to use FIPS140-2 approved algorithms, but does not use the certified cryptograhic module.

The uncertified module is what is used in the absense of SSLEnable.

SSLGSKitTraceEnable Directive

This directive enables the equivalent of setting the GSK_TRACE_FILE GSK_TRACE_FILE_SIZE, and GSK_TRACE_FILE_NUMBER environment variables.

The final parameter, options, can be set to "1" to enable GSK_TRACE_NO_BUFFERING

SSLHandshakeTimeout Directive

This directive can be used to reduce the timeout for SSL handshake I/O operations and to impose an end-to-end timeout on SSL handshakes.

A value of 0 for either value will use the core Timeout value.

SSLMinimumRSAKeySize Directive

This directive is primarily used to enforce a minimum RSA key size for client certificates. The exact behavior depends on the capabilities provided by the platform security library.

• On z/OS, the key size is enforced on client certificates received by the server. The issuers of the client certificates are not checked. This uses GSK_PEER_RSA_MIN_KEY_SIZE in the System SSL programming guide.
• On Distributed platforms:
  • The key size is enforced on all certificates sent or received by mod_ibm_ssl, including their full certificate chains.
  • The environment variables SSL_CLIENT_KEY_ALG ("RSA", "EC_ecPublicKey") and SSL_CLIENT_KEY_SIZE are provided to use in logging and conditional expressions.

In the event the minimum is not met, the SSL handshake will fail.

SSLOCSPCacheSize Directive

This directive specifies the size of the internal OCSP response cache.

Defaults

On Linux, AIX and Windows the default is 0 (no caching). On z/OS, the system default is 256. Further details can be found in the System SSL programmers guide of your zOS release.

Lifetime

The "nextUpdate" time of the OCSP response, or HTTP cache headers, determines the lifetime of cache entries. Entries can be evicted when the cache is full based on LRU.

Merging

This directive is not merged/inherited from global to virtual host scope

Scope

There is one cache per SSL enabled virtual host, per IHS child process.

Statistics

If the /server-status interface is accessed over HTTPS, some basic info about the OCSP cache for the virtual host and process handling the request is displayed torwards the bottom of the page. Not available on zOS.

SSLOCSPConnectionTimeout Directive

This directive can specify a timeout for connecting to an OCSP server while validating a client certificate. Prior to PH01222, there was no explicit default, and especially on Windows the connection attempt could have for an extended time if it was not completed or actively refused.

This directive is inherited from the base server config to virtual hosts.

SSLOCSPEnable Directive

If SSLOCSPEnable is set, and any certificate in the 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 that 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.

https URIs are not supported for OCSP.

SSLOCSPResponderURL Directive

If SSLOCSPEnable is set, and any certificate in the 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 that 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.

https URIs are not supported for OCSP.

SSLProtocolDisable Directive

This directive can be used to disable individual SSL protocols. Multiple protocols can be specified, separated by spaces.

In scopes with SSLProxyEngine set to "ON", this directive also controls the protocols used for outbound TLS connections. To change one without changing another, specify "PROXY" or "SERVER" as the first argument.

SSLProtocolEnable Directive

This directive can be used to enable individual SSL protocols.

SSLProxyEngine Directive

This directive configures IHS to handle https URL's for reverse proxy directives such as ProxyPass and RewriteRule.

A KeyFile must be set and contain the trust chain for any origin servers.

This directive is not supported when IBM HTTP Server is used with WebSphere Application Server. Only the WebSphere WebServer Plug-in is supported.

SSLRenegotiation Directive

This directive controls the types of TLS renegotiation permitted by IBM HTTP Server. TLS renegotiation is how clents can initiate a new SSL handshake on an existing secure connection, which is rarely used by normal browser-based clients.

OFF (default)

No renegotiation is permitted.

ON

Secure renegotiation, as currently defined by RFC5746, is permitted.

LEGACY_AND_RFC5746

Both secure renegotiation and legacy insecure renegotiation are permitted.

SSLReverseCipherOrder Directive

In version 9 and later, the default order of ciphers prioritizes some stronger ciphers than previously used by default. Use this directive to reverse the cipher order, rather than picking and choosing the exact order with SSLCipherSpec.

SSLServerCert Directive

Each KeyFile may contain multiple personal certificates (certificates with private keys) as well as a single personal certificate marked as the default certificate. If you want IBM HTTP Server to use any certificates other than the default, specify SSLServerCert.

Two certificate labels may be specified as a space-delimited list where one certificate must contain an RSA key and the other must contain an ECDSA key. The server will choose a certificate based on the client's capabilities. If a client supports both key types, the certificate listed first in SSLServerCert is used regardless of how the ciphers are ordered using SSLCipherSpec.

Any labels containing spaces must be quoted. Spaces will need to be escaped if more than one label is specified.

If cryprographic hardware is in use, this directive is mandatory to communicate the cryptographic token name (the token name can be obtained using the crypto hardware vendor's tools such as pkcsconf:

On z/OS, the second label is only used when PH18102 is present and the operating system release is V2R3 or later.

SSLSkipCloseNofify Directive

9.0.5.2 added TLS13 support. Separate from TLS13, IHS began sending the TLS close_notify alert when the underlying Apache connection to the client was closed. This flag disables the new behavior

SSLSNIMap Directive

This directive maps server names transmitted via the TLS Server Name Extension to certificate labels, which allows the certificate presented to vary based on the hostname used by the client.

See the >SNI section for more details.

SSLSuiteBMode Directive

This directive configures the enclosing virtual host to use the "Suite B" profile for TLS. This profile drastically reduces the available signature algorithm and cipher specs that will be used by the server. 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.

• Setting this directive overrides most previous SSL directives. Only SSLAttributeSet is processed later (with a higher priority).
• All Suite B profiles require the servers certificate chain to use strong ECC signatures.
• At the time of this writing, RFC 6460 documents the restrictions of "Suite B".

SSLSupportedCurves Directive

During handshakes that use ECDHE key exchange, the client and server must negotiate a named curve that both sides support. This directive allows the curves that the server will offer to be customized.

Default and available settings:

SSLTrace Directive

This directive enables extra tracing in the ErrorLog for various SSL related operations. SSLTrace is only useful with LogLevel set to debug.

SSLUnknownRevocationStatus Directive

ignore

Specifies that a debug level message is issued when a handshake completes and the revocation status is not known. This message is not re-issued when the SSL session is resumed.

log

Specifies that a notice-level message is issued when a handshake completes and the revocation status is not known. This message is not re-issued when the SSL session is resumed.

log_always

Specifies that a notice-level message is issued when a handshake completes and the revocation status is not known. IBM HTTP Server issues the same message for subsequent handshakes.

deny

Specifies that a notice-level message is issued when a handshake completes, the revocation status is not known, the session is not resumable, and the HTTPS connection is immediately closed. IBM HTTP Server reports the same message for subsequent handshakes.

Whenever a message is logged for UnknownRevocationStatus, the SSL_UNKNOWNREVOCATION_SUBJECT variable, an internal SSL environment variable, is set. You can log this variable with the following LogFormat syntax:

You could also use the variable in mod_rewrite expressions when this directive directive has any value other than deny. Use the following variable name in your RewriteCond directive:

SSLVersion Directive

This directive returns an HTTP Forbidden response if the specified TLS version has not been negotiated. It does not cause the connection to be renegotiated, and cannot itself directly cause a customized HTTP response be sent to the client. This directive serves little practical purpose.

TLS13Options Directive

This directive allows the following options to be set for the TLSv1.3 protocol:

AllowLegacyCerts[=ON|OFF]

Allows legacy SHA1 certificates to be used. Default is OFF.

NumTickets=n

Sets the number of session tickets to the value n. Default is 6.

ServerKeyRefresh=n

z/OS only. Sets the frequency for rotating the key used for TLSv13 session tickets. Default is 608400 (7 days).