[AIX Solaris HP-UX Linux Windows][z/OS]

Secure Sockets Layer (SSL) directives

Secure Sockets Layer (SSL) directives are the configuration parameters that control SSL features in IBM® HTTP Server.

You can specify many Secure Sockets Layer (SSL) directives in IBM HTTP Server either within a <VirtualHost> section, or globally, outside of any <VirtualHost> section.

When name-based SSL virtualhosts are used, configuration directives that influence the SSL handshake are taken only from the default (first listed) virtualhost for each unique IP:PORT combination.

Most directives that are valid in both contexts are copied or merged from the global configuration into the virtual host configuration, meaning they do not need to be repeated within multiple SSL enabled virtual hosts. Notable exceptions are OCSP related directives and SSLProtocolDisable. While SSLCipherSpec is merged, it is recommended to specify this directive either globally or within the <VirtualHost> section and not both at the same time. When specified globally and within a <VirtualHost> section, each is evaluated relative to the defaults then the union of the result is enabled. This can have unintuitive results.

For SSL directives specified in a directory scope (<Location>, <Directory>, or htaccess), configurations sections from a more general scope are merged into configuration sections with a more specific scope. Some example directives in this category are SSLCipherBan, SSLCipherRequire, SSLClientAuthRequire, and SSLVersion. These directives are less frequently used than the preceding ones.

Aside from a globally specified keyfile directive, avoid the merging of configurations whenever possible. Always test the result of any configuration that depends on the merging of multiple configuration scopes.

SSLOCSPResponderURL

The SSLOCSPResponderURL directive enables checking of client certificates through a statically configured online certificate status protocol (OCSP) responder.
Name Description
Syntax

[AIX Solaris HP-UX Linux Windows]SSLOCSPResponderURL<URL>

Scope Virtual host
Default Disabled
Module mod_ibm_ssl
Multiple instances in the configuration file One per virtual host
Values A fully qualified URL that points to an OCSP responder, for example, http://hostname:2560/.

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.

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.
Avoid trouble: In some cases IBM HTTP Server might not be able to determine the revocation status of a client certificate, because the backend server, which is the source of the revocation data, is not available. You should be aware that:
  • A static CRL repository (SSLCRLHost) must be configured to enable checking of other URI forms in the CRLDistributionPoint fields.
  • If your certificates use the LDAP or HTTP URI forms of the CertificateDistributionPoint or AIA extensions, be sure that the IBM HTTP Server system can establish outgoing connections of this type; you must adjust the settings for your firewall.
  • [AIX Solaris HP-UX Linux Windows]The SSLUnknownRevocationStatus directive is provided for cases in which recoverable errors occur in IBM HTTP Server when it is communicating with the backend server, and the IBM HTTP Server cannot determine the revocation status of a certificate. The default behavior is to continue processing the handshake unless the backend server can successfully indicate that the certificate is revoked.
  • [z/OS]Only an explicitly configured LDAP server can be queried for CRL, and the SSL handshake fails if the backend server is not reachable.

SSLOCSPEnable

The SSLOCSPEnable directive enables checking of client certificates through OCSP responders defined in the Authority Information Access (AIA) extension of their certificate.
Name Description
Syntax

[AIX Solaris HP-UX Linux Windows]SSLOCSPEnable

Scope Virtual host
Default Disabled
Module mod_ibm_ssl
Multiple instances in the configuration file One instance permitted for each virtual host
Values None

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.

Keyfile directive

The keyfile directive sets the key file to use.
Name Description
Syntax

[Windows][z/OS][Linux][AIX][Solaris][HP-UX]Keyfile [/prompt] /path/to/key.kdb

[z/OS]KeyFile /saf [owner/]saf-keyring-name

Scope Global and virtual host
Default None
Module mod_ibm_ssl
Multiple instances in the configuration file One instance per virtual host and global server
Values Path to keyfile

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.

[z/OS]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

The SSLAcceleratorDisable directive disables the accelerator device.
Name Description
Syntax SSLAcceleratorDisable
Scope Virtual and global
Default Accelerator device is enabled
Module mod_ibm_ssl
Multiple instances in the configuration file One instance per virtual host.
Values None. Place this directive anywhere inside of the configuration file, including inside a virtual host. During initialization, if the system determines that an accelerator device is installed on the machine, the system uses that accelerator to increase number of secure transactions. This directive does not take arguments.
[AIX Solaris HP-UX Linux Windows]

SSLAllowNonCriticalBasicConstraints directive

The SSLAllowNonCriticalBasicConstraints directive enables compatibility with one aspect of the GPKI specification from the government of Japan that conflicts with RFC3280.
Name Description
Syntax SSLAllowNonCriticalBasicConstraints on|off
Scope Global server or virtual host
Default Off
Module mod_ibm_ssl
Multiple instances in the configuration file One instance per virtual host and global server
Values None. This directive changes the behavior of the certificate validation algorithm such that a non-critical basic constraints extension on an issuer certificate authority (CA) certificate does not cause a validation failure. This enables compatibility with one aspect of the GPKI specification from the government of Japan that conflicts with RFC3280.
Attention: RFC3280 states that this extension must appear as a critical extension in all CA certificates that contain public keys used to validate digital signatures on certificates.
[z/OS][Linux][AIX][Solaris][HP-UX]

SSLCacheDisable directive

The SSLCacheDisable directive disables the external SSL session ID cache.
Name Description
Syntax SSLCacheDisable
Scope One per physical Apache server instance, enabled only outside of virtual host stanzas.
Default None
Module mod_ibm_ssl
Multiple instances in the configuration file Not permitted.
Values None.
[z/OS][Linux][AIX][Solaris][HP-UX]

SSLCacheEnable directive

The SSLCacheEnable directive enables the external SSL session ID cache.
Name Description
Syntax SSLCacheEnable
Scope One per physical Apache server instance, enabled only outside of virtual host stanzas.
Default None
Module mod_ibm_ssl
Multiple instances in the configuration file Not permitted.
Values None.
[z/OS][Linux][AIX][Solaris][HP-UX]

SSLCacheErrorLog directive

The SSLCacheErrorLog directive sets the file name for session ID cache.
Name Description
Syntax SSLCacheErrorLog /usr/HTTPServer/logs/sidd_logg
Scope Server configuration outside of virtual host.
Default None
Module mod_ibm_ssl
Multiple instances in the configuration file Not permitted.
Values Valid file name.
[z/OS][Linux][AIX][Solaris][HP-UX]

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.

Name Description
Syntax SSLCachePath /usr/HTTPServer/bin/sidd
Scope Server configuration outside of virtual host.
Default <server-root>/bin/sidd
Module mod_ibm_ssl
Multiple instances in the configuration file Not permitted.
Values Valid path name.
[z/OS][Linux][AIX][Solaris][HP-UX]

SSLCachePortFilename directive

The SSLCachePortFilename directive sets the file name for the UNIX domain socket that is used for communication between the server instances and the session ID cache daemon. You must set this directive if you run two instances of IBM HTTP Server from the same installation directory and both instances are configured for SSL. Otherwise, you do not need to set this directive.
Name Description
Syntax SSLCachePortFilename /usr/HTTPServer/logs/siddport
Scope Server configuration outside of virtual host.
Default If this directive is not specified and the cache is enabled, the server attempts to use the <server-root>/logs/siddport file.

Notes:

  • For AIX®, the default is /usr/HTTPServer/logs/siddport.
  • For Solaris, the default is /opt/IBMHTTPD/logs/siddport .
  • Not valid on Windows NT
Module mod_ibm_ssl
Multiple instances in the configuration file Not permitted.
Values Valid path name. The web server deletes this file during startup; do not use an existing filename.
[z/OS][Linux][AIX][Solaris][HP-UX]

SSLCacheTraceLog directive

The SSLCacheTraceLog directive specifies the file to which the session ID trace messages are written. Without this directive, tracing is disabled.
Name Description
Syntax SSLCacheTraceLog /usr/HTTPServer/logs/sidd-trace.log
Scope Server configuration outside of virtual host.
Default None.
Module mod_ibm_ssl
Multiple instances in the configuration file Not permitted.
Values Valid path name.
[AIX Solaris HP-UX Linux Windows]

SSLCheckCertificateExpiration

The SSLCheckCertificateExpiration directive checks for expired or expiring certificates at startup.
Name Description
Syntax SSLCheckCertificateExpiration <i>days</i>|-1 ["no_expired"]
Scope Global server or virtual host.
Default None.
Module mod_ibm_ssl
Multiple instances in the configuration file One instance per virtual host and global server.
Values

For the days parameter, specify the threshold for expiring certificates in days or enter -1 to disable the parameter.

For the optional no_expired parameter, specify no_expired to disable the reporting of certificates that already expired.

SSLCipherBan directive

The SSLCipherBan directive denies access to an object if the client has connected by using one of the specified ciphers. The request fails with a 403 status code.
Attention: This directive, when specified for a child directory, does not override the directive that is specified for the parent directory. Instead, both directories are applied to the child directory.
Name Description
Syntax SSLCipherBan <cipher_specification>
Scope Multiple instances per directory stanza.
Default None.
Module mod_ibm_ssl
Multiple instances in the configuration file Permitted per directory stanza. Order of preference is start to finish.
Values See the SSL cipher specification topic for values.

SSLCipherRequire directive

The SSLCipherRequire directive restricts access to objects to clients that connect by using one of the specified ciphers. If access is denied, the request fails with a '403' status code.
Attention: This directive, when specified for a child directory, does not override the directive that is specified for the parent directory. Instead, both directories are applied to the child directory.
Name Description
Syntax SSLCipherRequire <cipher_specification>
Scope Multiple instances per directory stanza.
Default None.
Module mod_ibm_ssl
Multiple instances in the configuration file Permitted per directory stanza.
Values See the SSL cipher specification topic for values

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:

  • Multiple ciphers can be listed with each occurrence of SSLCipherSpec.
  • Individual ciphers can be removed from the current set of enabled ciphers by prefixing the cipher name with -.
  • The first time a given protocol cipher list is being modified, the given cipher can be added to the end of the defaults, instead of replacing them, by prefixing the cipher name with +.

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.

Avoid trouble: The syntax of the SSLCipherSpec directive is different on z/OS before PI73819. Specifically, the SSLCipherSpec directive on z/OS before PI73819 only takes a short name or long name as an argument.
Note: Ciphers can be specified by either their long names or short names. The use of short names for ciphers, however, is not recommended as they are unreadable and might not match the short name designated for the cipher in the SSL specification. Additionally, short names for ciphers will no longer be documented any further.
Name Description
Syntax SSLCipherSpec [protocol-name] [+|-]cipher-name [[+|-]cipher-name ...]
Scope Server config, virtual host.
Default If nothing is specified, the server uses all non-NULL, non-export, non-weak cipher specifications available.
Module mod_ibm_ssl
Multiple instances in the configuration file Permitted. Order of preference is start to finish, first to last.
Values for protocol name on distributed platforms

SSLv2, SSLv3, TLSv10, TLSv1.1,TLSv1.2, ALL

[9.0.5.2 or later]TLSv1.3

Version 9.0.5.2 and later supports all the listed protocol name values, including TLSv1.3. Version 9.0.5.1 and earlier supports all the listed protocol name values except for TLSv1.3.

Values for protocol name on z/OS ALL
Values for cipher names See the SSL cipher specification topic for values

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

The SSLClientAuth directive sets the mode of client authentication to use (none (0), optional (1), or required (2)).
Name Description
Syntax SSLClientAuth <level required> [crl]
Scope Virtual host.
Default SSLClientAuth none
Module mod_ibm_ssl
Multiple instances in the configuration file One instance per virtual host.
Values
  • 0/None: No client certificate requested.
  • 1/Optional: Client certificate requested, but not required.
  • 2/Required: Valid client certificate required.
  • Required_reset: The server requires a valid certificate from all clients, and if no certificate is available, the server sends an SSL alert to the client. This alert enables the client to understand that the SSL failure is client-certificate related, and causes browsers to re-prompt for client certificate information about subsequent access. This option requires GSKit version 7.0.4.19 or later, or z/OS V1R8 or later.
    Important: No numeric option is provided so it will not look like the existing options.
  • CRL: Turns certificate revocation list (CRL) on and off inside an SSL virtual host. If you use CRL, you must specify crl as a second argument for SSLClientAuth. For example: SSLClientAuth 2 crl. If you do not specify crl, you cannot perform CRL in an SSL virtual host.
  • noverify: Enables SSL handshake to succeed and establish a connection, even if the certificate provided by the client fails validation (for example, the certificate is expired or revoked). Use this directive with SSLClientAuthVerify to provide a user-friendly web page, instead of the default browser error message. This option is only valid with Optional. Use SSLClientAuthVerify to fail requests received on the connection with the invalid client certificate.

If you specify the value 0/None, you cannot use the CRL option.

Required_reset The server requires a valid certificate from all clients, and if no certificate is available, the server sends an SSL alert to the client. This enables the client to understand that the SSL failure is client-certificate related, and causes browsers to re-prompt for client certificate information about subsequent access. This option requires GSKit version 7.0.4.19 or later, or z/OS V1R8 or later.
Attention: In some cases IBM HTTP Server might not be able to determine the revocation status of a client certificate, because the backend server, which is the source of the revocation data, is not available. You should be aware that:
  • A static CRL repository (SSLCRLHost) must be configured to enable checking of other URI forms in the CRLDistributionPoint fields.
  • If your certificates use the LDAP or HTTP URI forms of the CertificateDistributionPoint or AIA extensions, be sure that the IBM HTTP Server system can establish outgoing connections of this type; you must adjust the settings for your firewall.
  • [AIX Solaris HP-UX Linux Windows]The SSLUnknownRevocationStatus directive is provided for cases in which recoverable errors occur in IBM HTTP Server when it is communicating with the backend server, and the IBM HTTP Server cannot determine the revocation status of a certificate. The default behavior is to continue processing the handshake unless the backend server can successfully indicate that the certificate is revoked.
  • [z/OS]Only an explicitly configured LDAP server can be queried for CRL, and the SSL handshake fails if the backend server is not reachable.

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.

Name Description
Syntax SSLClientAuthGroup group name attribute expression
Scope Server config, virtual host.
Default None.
Module mod_ibm_ssl
Multiple instances in the configuration file Permitted.
Override None.
Values Logical expression consisting of attribute checks linked with AND, OR, NOT, and parentheses. For example:
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.

This list contains attribute values that you can specify for this directive:
Table 1. Attribute values for the SSLClientAuthGroup directive. The table lists each attribute value as a long name and short name.
Long name Short name
CommonName CN
Country C
Email E
IssuerCommonName ICN
IssuerEmail IE
IssuerLocality IL
IssuerOrg IO
IssuerOrgUnit IOU
IssuerPostalCode IPC
IssuerStateOrProvince IST
Locality L
Org O
OrgUnit OU
PostalCode PC
StateOrProvince ST

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 !=. For example:
SSLClientAuthGroup IBMpeople Org = IBM)
or
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.

Name Description
Syntax SSLClientAuthRequire attribute expression
Scope server config, virtual host
Default None.
Module mod_ibm_ssl
Multiple instances in the configuration file Permitted. The function joins these directives by AND.
Override AuthConfig
Values Logical expression consisting of attribute checks linked with AND, OR, NOT, and parentheses. For example:
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 list contains attribute values that you can specify for this directive:
Table 2. Attribute values for the SSLClientAuthRequire directive. The table lists each attribute value as a long name and short name.
Long name Short name
CommonName CN
Country C
Email E
IssuerCommonName ICN
IssuerEmail IE
IssuerLocality IL
IssuerOrg IO
IssuerOrgUnit IOU
IssuerPostalCode IPC
IssuerStateOrProvince IST
Locality L
Org O
OrgUnit OU
PostalCode PC
StateOrProvince ST

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.

You can specify multiple SSLClientAuthRequire directives within the same scope. The logical expressions for each directive are used to evaluate access rights for each certificate, and the results of the individual evaluations are logically ANDed together. For example:
SSLClientAuthRequire ((CommonName="John Doe") || (StateOrProvince=MN)) && (Org!=IBM)  
or
SSLClientAuthRequire (group!=IBMpeople) && (ST=MN)
You can put quotes around the short and long names. For example:
SSLClientAuthRequire (group!= IBMpeople) && ("ST= MN")
See SSLClientAuthGroup directive for more information.
[AIX Solaris HP-UX Linux Windows]
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)
[AIX Solaris HP-UX Linux Windows]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).

Name Description
Syntax SSLClientAuthVerify statuscode|OFF
Scope Global server or virtual host.
Default 500
Module mod_ibm_ssl
Multiple instances in the configuration file One instance per directory stanza.
Values HTTP response status code, or OFF

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]
Example configuration:
<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.

Name Description
Syntax <SSLCRLHostName <TCP/IP name or address>
Scope Global server or virtual host.
Default Disabled by default.
Module mod_ibm_ssl
Multiple instances in the configuration file One instance per virtual host and global server.
Values TCP/IP name or address of the LDAP Server

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.

Name Description
Syntax SSLCRL<port>
Scope Global server or virtual host.
Default Disabled by default.
Module mod_ibm_ssl
Multiple instances in the configuration file One instance per virtual host and global server.
Values Port of LDAP server; default = 389.

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.

Name Description
Syntax SSLCRLUserID <[prompt] <userid>
Scope Global server or virtual host.
Default Defaults to anonymous if you do not specify a user ID.
Module mod_ibm_ssl
Multiple instances in the configuration file One instance per virtual host and global server.
Values User ID of LDAP server. Use the prompt option to enable the HTTP server to prompt you for the password to access the LDAP server during start up.

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

The SSLDisable directive disables SSL for the virtual host.
Name Description
Syntax SSLDisable
Scope Global server or virtual host.
Default Disabled by default.
Module mod_ibm_ssl
Multiple instances in the configuration file One instance per virtual host and global server.
Values None.

SSLEnable directive

The SSLEnable directive enables SSL for the virtual host.
Attention: This directive should not be specified in the base server configuration if you do not want the directive automatically copied to a given virtual host configuration.
Name Description
Syntax SSLEnable
Scope Global server or virtual host.
Default Disabled by default.
Module mod_ibm_ssl
Multiple instances in the configuration file One instance per virtual host and global server.
Values None.

SSLFakeBasicAuth directive

The SSLFakeBasicAuth directive enables the fake basic authentication support.

This support enables the client certificate distinguished name to become the user portion of the user and password basic authentication pair. Use password for the password.
Attention: This directive might be overridden by the base server configuration.
Name Description
Syntax SSLFakeBasicAuth
Scope Within a directory stanza, used along with AuthName, AuthType, and require directives.
Default None.
Module mod_ibm_ssl
Multiple instances in the configuration file One instance per directory stanza.
Values None.
[AIX Solaris HP-UX Linux Windows]

SSLFIPSDisable directive

The SSLFIPSDisable directive disables Federal Information Processing Standards (FIPS).
Name Description
Syntax SSLFIPSDisable
Scope Virtual and global.
Default Disabled by default.
Module mod_ibm_ssl
Multiple instances in the configuration file One instance per virtual host and global server.
Values None.

SSLFIPSEnable directive

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

This directive is applicable to distributed platforms.

[z/OS]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.
Name Description
Syntax SSLFIPSEnable
Scope Virtual and global.
Default Disabled by default.
Module mod_ibm_ssl
Multiple instances in the configuration file One instance per virtual host and global server.
Values None.
Attention: See the SSL cipher specification topic for values.

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.

[AIX Solaris HP-UX Linux Windows]
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.

Name Description
Syntax SSLInsecureRenogotiation directive on|off
Scope Virtual hosts
Default off
Module mod_ibm_ssl
Multiple instances in the configuration file One instance per virtual host and global server
Values on|off
[AIX Solaris HP-UX Linux Windows]

SSLPKCSDriver directive

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

Name Description
Syntax Fully qualified name to module used to access PKCS11 device>. If the module exists in the user path, then specify just the name of the module.
Scope Global server or virtual host.
Default None.
Module mod_ibm_ssl
Multiple instances in the configuration file One instance per virtual host and global server.
Values Path and name of PKCS11 module or driver.
The default locations of the modules for each PKCS11 device follow:
  • nCipher
    • AIX: /opt/nfast/toolkits/pkcs11/libcknfast.so
    • HP: /opt/nfast/toolkits/pkcs11/libcknfast.sl
    • Solaris: /opt/nfast/toolkits/pkcs11/libcknfast.so
    • Windows: c:\nfast\toolkits\pkcs11\cknfast.dll
  • IBM 4758
    • AIX: /usr/lib/pkcs11/PKCS11_API.so
    • Windows: $PKCS11_HOME\bin\nt\cryptoki.dll
  • IBM e-business Cryptographic Accelerator
    • AIX: /usr/lib/pkcs11/PKCS11_API.so

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.

Supported protocols for a virtual host are supported separately. If all supported protocols are disabled, clients cannot complete an SSL handshake.
Name Description
Syntax SSLProtocolDisable <protocolname>

Supported protocol name values: SSLv2|SSLv3|TLSv10|TLSv11|TLSv12

[9.0.5.2 or later]TLSv13

Version 9.0.5.2 and later supports all the listed protocol name values, including TLSv1.3. Version 9.0.5.1 and earlier supports all the listed protocol name values except for TLSv1.3.

Scope Virtual host
Default Disabled
Attention: The SSL Version 2 protocol is disabled by default with other methods.
Module mod_ibm_ssl
Multiple instances in the configuration file Multiple instances permitted per virtual host.
The following example shows how to disable support for multiple protocols on a virtual host.
<VirtualHost *:443> 
   SSLEnable 
   SSLProtocolDisable TLSv10
   # Any other directives ...
</VirtualHost>
Attention: SSL0230I is logged for each SSL connection attempt if the client and server do not share at least one protocol and cipher combination.

SSLProtocolEnable directive

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

Name Description
Syntax SSLProtocolEnable <protocolname>

Supported protocol name values: SSLv2|SSLv3|TLSv10|TLSv11|TLSv12

[9.0.5.2 or later]TLSv13

Version 9.0.5.2 and later supports all the listed protocol name values, including TLSv1.3. Version 9.0.5.1 and earlier supports all the listed protocol name values except for TLSv1.3.

Scope Virtual host
Default Unset
Module mod_ibm_ssl
Multiple instances in the configuration file Multiple instances permitted per virtual host.

SSLProxyEngine directive

The SSLProxyEngine toggles whether the server uses SSL for proxied connections. SSLProxyEngine on is required if your server is acting as a reverse proxy for an SSL resource.
Name Description
Syntax SSLProxyEngine on|off
Scope IP-based virtual hosts
Default Off
Module mod_ibm_ssl
Multiple instances in the configuration file One per virtual host and global server
Values on|off

SSLRenegotiation directive

The SSLRenegotiation directive controls IBM HTTP Server support of Transport Layer Security (TLS) renegotiation. The directive controls the types of TLS renegotiation permitted by IBM HTTP Server. TLS renegotiation is how clients can initiate a new SSL handshake on an existing secure connection, which is rarely used by normal browser-based clients.
Name Description
Syntax SSLRenegotiation on|off|LEGACY_AND_RFC5746
Default Off
Module mod_ibm_ssl
Context virtual host
Status extension
Values on|off|LEGACY_AND_RFC5746
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.
Compatibility
  • This directive supersedes the SSLInsecureRenegotiation directive in IBM HTTP Server 8.0 and later.
  • IBM HTTP Server 8.0.0.0 defaulted to ON (accepting RFC5746 renegotiations).
  • Prior to 7.0.0.21, the bundled GSKit security library was not aware of RFC5746, and ON referred to legacy insecure renegotiation.
  • Support for the LEGACY_AND_RFC5746 option depends on IBM HTTP Server 7.0.0.21 and later.

SSLServerCert directive

The SSLServerCert directive sets the server certificate to use for this virtual host.
Name Description
Syntax SSLServerCert [prompt|certificate_label] certificate_label
Scope IP-based virtual hosts.
Default None, but an SSL key store has its own notion of a default certificate.
Module mod_ibm_ssl
Multiple instances in the configuration file One instance per virtual host and global server.
Values Certificate label. Use the /prompt option to enable the HTTP server to prompt you for the cryptographic token password during startup. Use no delimiters around the certificate label. Ensure that the label is contained on one line; leading and trailing blank space is ignored.
Each SSL keystore keyfile might specify a default certificate. This directive configures the server to use a certificate other than the keystore default.
  • To choose a certificate label other than the default, specify a single parameter whose value is the label of the required non-default certificate.
  • To use a cryptographic token, specify a colon-separated cryptographic token name and certificate label (mytoken:mylabel). Optionally, specify /prompt as the first parameter to interactively prompt for the cryptographic token password instead of using SSLStashFile.
  • To configure both an ECDSA and an RSA based certificate, specify two certificate labels, separated by a space. If a client supports only RSA or only ECDSA based certificates, the appropriate certificate is selected. If a client supports both RSA and ECDSA, the certificate_label specified first in this directive determines the certificate to be used.
Avoid trouble: If you are using an SSL certificate label, you need to be aware of the following requirements.
  • If one certificate label is specified, a label with spaces must be quoted and the spaces must not be escaped, as in the following example:
    SSLServerCert "My Label"
  • If two certificate labels are specified, any label with spaces must be quoted and the spaces must be escaped with the backslash character, as in the following example:
    SSLServerCert "My\ First\ Label", "My\ Second\ Label"

SSLStashfile directive

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

Name Description
Syntax SSLStashFile /usr/HTTPServer/mystashfile.sth
Scope Virtual host and global server.
Default None.
Module mod_ibm_ssl
Multiple instances in the configuration file One instance per virtual host and global server.
Values File name of an LDAP or PKCS11 stash file that is created with the sslstash command.

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.

The stash file that the sslstash command creates is completely independent of the stash file that often accompanies a CMS KeyFile (*.kdb). Therefore, make sure that you:
  • Do not overwrite an existing *.sth file when you issue the sslstash command.
  • Never choose a file name for the output of the sslstash command that corresponds to the file name of a CMS KeyFile (*.kdb).

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

where:
  • -c: Creates a new stash file. If not specified, an existing file updates.
  • File: Represents the fully qualified name of the file to create, or update.
  • Function: Indicates the function for which to use the password. Valid values include crl, or crypto.
  • Password: Represents the password to stash.

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.

Name Description
Syntax SSLSuiteBMode
Scope Virtual host
Default Unset
Module mod_ibm_ssl
Multiple instances in the configuration file Once per virtual host

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.

Name Description
Syntax SSLTrace
Scope Global
Default mod_ibm_ssl debug logging in not enabled
Module mod_ibm_ssl
Multiple instances in the configuration file Ignored
Values None
Attention: See also LogLevel Directive.
[AIX Solaris HP-UX Linux Windows]

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.

Name Description
Syntax SSLUnknownRevocationStatus ignore | log | log_always | deny
Scope Virtual host
Default ignore
Module mod_ibm_ssl
Multiple instances in the configuration file One instance permitted for each virtual host
Values
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.
Supported configurations: 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 syntax:
%{SSL_UNKNOWNREVOCATION_SUBJECT}e
You could also use the variable in mod_rewrite expressions when the SSLUnknownRevocationStatus directive has any value other than deny. Use the following variable name:
%{ENV:SSL_UNKNOWNREVOCATION_SUBJECT}

SSLV2Timeout directive

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

Name Description
Syntax SSLV2Timeout 60
Scope Global base and virtual host.
Default 40
Module mod_ibm_ssl
Multiple instances in the configuration file One instance per virtual host and global server.
Values 0 to 100 seconds.

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.

Name Description
Syntax SSLV3Timeout 1000
Scope Global base and virtual host.

[Windows]The virtual host scope or global scope are applicable.

[Linux][AIX][Solaris][HP-UX]The virtual host scope is applicable if the SSLCacheDisable directive is also being used. Otherwise, only the global scope is allowed.

Default 120
Module mod_ibm_ssl
Multiple instances in the configuration file One instance per virtual host and global server.
Values 0 to 86400 seconds.

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.

Name Description
Syntax SSLVersion ALL
Scope One per directory stanza.
Default None.
Module mod_ibm_ssl
Multiple instances in the configuration file One instance per <Directory> or <Location> stanza.
Values

Supported values: SSLv2|SSLv3|TLSv10|TLSv11|TLSv12

[9.0.5.2 or later]TLSv13

Version 9.0.5.2 and later supports all the listed values, including TLSv1.3. Version 9.0.5.1 and earlier supports all the listed values except for TLSv1.3.