Secure Sockets Layer (SSL) directives are the configuration parameters that control SSL features in IBM® HTTP Server.
Most SSL directives in IBM HTTP Server have the same behavior. A directive specified for a given virtual host configuration overrides a directive specified in the base server configuration. Also, a directive specified for a child directory overrides a directive specified for its parent directory. However, there are exceptions.
Also, a directive specified for a child directory might be appended to the directive specified for its parent directory. In this case, the directive for the parent directory does not override the directive for the child directory, but instead is appended to it and both directives are applied to the child directory.
Syntax | 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/. The path portion of the URL is not used when submitting OCSP requests. |
If CRL checking is configured, CRL checking is performed before any OCSP checking. OCSP checking only occurs if the result of the CRL 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, IHS checks OCSP responders as described above for SSLOCSPEnable.
Syntax | 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 CRL checking is configured, CRL checking is performed before any OCSP checking. OCSP checking only occurs if the result of the CRL 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, IHS checks OCSP responders as described above for SSLOCSPEnable.
Syntax |
|
Scope | Global base and virtual host |
Default | None |
Module | mod_ibm_ssl |
Multiple instances in the configuration file | One instance per virtual host and global server |
Values | File name of the key file. Use the prompt option to enable the HTTP server to prompt you for the Key file password during start up. |
You can only
use the Certificate Management Services (CMS) for the key file type.
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. |
Syntax | SSLCacheDisable |
Scope | One per physical Apache server instance, allowed only outside of virtual host stanzas. |
Default | None |
Module | mod_ibm_ssl |
Multiple instances in the configuration file | Not permitted. |
Values | None. |
Syntax | SSLCacheEnable |
Scope | One per physical Apache server instance, allowed only outside of virtual host stanzas. |
Default | None |
Module | mod_ibm_ssl |
Multiple instances in the configuration file | Not permitted. |
Values | None. |
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. |
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. |
Syntax | SSLCachePath /usr/HTTPServer/logs/sidd |
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. |
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 name. |
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. |
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 top to bottom. |
Values | See SSL Version 2 cipher specifications and SSL Version 3 and TLS Version 1.0 cipher specifications. |
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 SSL Version 2 cipher specifications and SSL Version 3 and TLS Version 1.0 cipher specifications. |
Syntax | SSLCipherSpec short name or SSLCipherSpec long name |
Scope | Virtual host. |
Default | If nothing is specified, the server uses all of the cipher specifications available from the installed GSK library. |
Module | mod_ibm_ssl |
Multiple instances in the configuration file | Permitted. Order of preference is top to bottom, first to last. If the client does not support the cipher specifications, the connection closes. |
Values | See SSL Version 2 cipher specifications and SSL Version 3 and TLS Version 1.0 cipher specifications. |
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 |
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 will cause browsers to re-prompt for client certificate information on subsequent access. This option requires GSKit version 7.0.4.19 or later, or z/OS V1R8 or later. |
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 will allow access to the protected resource.
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) |
Description of valid logical expressions. 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) means 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 are linked 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.
Long name | Short name |
---|---|
CommonName | CN |
Country | C |
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.
SSLClientAuthGroup IBMpeople Org = IBM)or
SSLClientAuthGroup NotMNIBM (ST != MN) && (Org = IBM)
A group name cannot include spaces. See SSLClientAuthRequire directive for more information.
The SSLClientAuthRequire directive specifies attribute values, or groups of attribute values, that must be validated against a client certificate before the server will allow access to the protected resource.
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 may 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.
Long name | Short name |
---|---|
CommonName | CN |
Country | C |
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 need to 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)or
SSLClientAuthRequire (group!=IBMpeople) && (ST=MN)
SSLClientAuthRequire (group != IBMpeople) && ("ST= MN")See SSLClientAuthGroup directive for more information.
The SSLCRLHostname directive specifies the TCP/IP name or address of LDAP server where the Certificate Revocation List (CRL) database resides.
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 (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.
The SSLCRLPort directive specifies the port of the LDAP server where the Certificate Revocation List (CRL) database resides.
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 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.
The SSLCRLUserID directive specifies the user ID to send to the LDAP server, where the Certificate Revocation List (CRL) database resides.
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 needed 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 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.
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. |
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. |
The SSLFakeBasicAuth directive enables the fake basic authentication support.
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. |
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. |
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. |
The SSLPKCSDriver directive identifies the fully qualified name to the module, or driver used to access the PKCS11 device.
Syntax | Fully qualified name to module used to access PKCS11 device>. If the module exists in the user's 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 SSLProtocolDisable directive allows 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.
Syntax | SSLProtocolDisable <protocolname> |
Scope | Virtual host |
Default | Disabled |
Module | mod_ibm_ssl |
Multiple instances in the configuration file | Multiple instances permitted per virtual host. |
Values | The following possible values are available for this directive.
|
<VirtualHost *:443> SSLEnable SSLProtocolDisable SSLv2 SSLv3 (any other directives) </VirtualHost>
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 |
The SSLRenegotiation directive determines whether, SSL renegotiation, as defined by the pertinent public standards, is permitted on existing SSL connections.
When on is specified, SSL renegotiation is permitted on existing SSL connections. When off is specified, SSL renegotiation requests are aborted.
Syntax | SSLRenegotiation 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 |
Syntax | SSLServerCert [prompt] my_certificate_label; on PKCS11 device - SSLServerCert mytokenlabel:mykeylabel |
Scope | IP-based virtual hosts. |
Default | None. |
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 Crypto token password during start up. Use no delimiters around the certificate label. Ensure that the label is contained on one line; leading and trailing white space is ignored. |
The SSLStashfile directive indicates path to file with file name containing the encrypted password for opening the PKCS11 device.
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 and/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 password stash file. The password you specify using the sslstash command should equal the one you use to log in to your LDAP server.
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.
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. We do not recommend enabling this directive under normal working conditions.
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 |
The SSLUnknownRevocationStatus directive specifies how IBM HTTP Server will react when IBM HTTP Server cannot readily determine the revocation status, which is coming through CRL or OCSP.
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 |
|
%{SSL_UNKNOWNREVOCATION_SUBJECT}eYou 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}sptcfg
The SSLV2Timeout directive sets the timeout for SSL Version 2 session IDs. The timeout begins counting when the first successful handshake is completed. The timeout is not reset each time a subsequent handshake reuses the SSL session ID.
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. |
The SSLV3Timeout directive sets the timeout for SSL Version 3 and TLS session IDs. The timeout begins counting when the first successful handshake is completed. The timeout is not reset each time a subsequent handshake reuses the SSL session ID.
Syntax | SSLV3Timeout 1000 |
Scope | Global base and virtual host.
|
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. |
The SSLVersion directive enables object access rejection, if the client attempts to connect with an SSL protocol version other than the one specified.
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 | SSLV2|SSLV3|TLSV1|ALL |