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 <virtual Host> section, or globally, outside of any <virtualHost> section.
Most directives that are valid in both contexts are not copied or merged from the global configuration into the virtual host configuration, with these exceptions: SSLEnable, SSLDisable, KeyFile, SSLServerCert, SSLTrace, SSLv2Timeout, and SSLv3Timeout. For most other directives that are valid within the SSL enabled virtual host scope, you must explicitly specify them within the SSL enabled virtual host for the directives to take effect. Examples of other SSL directives that are not merged or copied are SSLCipherSpec and Uncompromisable.
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
- SSLOCSPEnable
- Keyfile directive
- SSLAcceleratorDisable directive
- SSLAllowNonCriticalBasicConstraints directive
- SSLCacheDisable directive
- SSLCacheEnable directive
- SSLCacheErrorLog directive
- SSLCachePath directive
- SSLCachePortFilename directive
- SSLCacheTraceLog directive
- SSLCipherBan directive
- SSLCipherRequire directive
- SSLCipherSpec directive
- SSLClientAuth directive
- SSLClientAuthGroup directive
- SSLClientAuthRequire directive
- SSLClientAuthVerify directive
- SSLCRLHostname directive (deprecated)
- SSLCRLPort directive (deprecated)
- SSLCRLUserID directive (deprecated)
- SSLDisable directive
- SSLEnable directive
- SSLFakeBasicAuth directive
- SSLFIPSDisable directive
- SSLFIPSEnable directive
- SSLInsecureRenegotiation directive
- SSLPKCSDriver directive
- SSLProtocolDisable directive
- SSLProtocolEnable directive
- SSLProxyEngine directive
- SSLRenegotiation directive
- SSLServerCert directive
- SSLSNIMap
- SSLStashfile directive
- SSLSuiteBMode
- SSLTrace directive
- SSLUnknownRevocationStatus
- SSLV2Timeout directive
- SSLV3Timeout directive
- SSLVersion directive
SSLOCSPResponderURL
Name | Description |
---|---|
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/. |
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
Name | Description |
---|---|
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 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
Name | Description |
---|---|
Syntax | Keyfile [/prompt] /fully qualified
path to key file/keyfile.kdb
Attention: The /prompt function is only supported when running from a USS
shell, not from a JCL started job. If you attempt to use the /prompt function from a JCL started
job, then a configuration error occurs.
You can use a keyring stored in the Hierarchical File System (HFS) or in the
System Authorization Facility (SAF). To use a keyring stored in HFS:
|
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 at start time. File system protection can be used to limit access. Use the SAF (System Authorization Facility) keyrings for limiting access to SSL certificates. |
- Certificate Management Services (CMS)
- CMS or Resource Access Control Facility (RACF®)
SSLAcceleratorDisable directive
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. |
SSLAllowNonCriticalBasicConstraints directive
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.
|
SSLCacheDisable directive
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. |
SSLCacheEnable directive
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. |
SSLCacheErrorLog directive
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. |
SSLCachePath directive
The SSLCachePath directive specifies the path to the session ID caching daemon. Unless multiple instances of IHS, with multiple ServerRootor -d parameters are sharing one installation, this directive is not required to be specified.
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. |
SSLCachePortFilename 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
|
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. |
SSLCacheTraceLog directive
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. |
SSLCipherBan directive
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 top to bottom. |
Values | See the SSL cipher specification topic for values. |
SSLCipherRequire directive
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 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.
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 given 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.
Name | Description |
---|---|
Syntax | SSLCipherSpec short name or SSLCipherSpec long name |
Syntax | SSLCipherSpec [protocol_name] [+|-]short name|long name [[+|-]short name|long 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 top to bottom, first to last. |
Values for protocol name on distributed platforms | SSLv2, SSLv3, TLSv10, TLSv11, TLSv12, ALL |
Values for protocol name on z/OS | SSLv2, SSLv3, TLSv10, 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 ones you want to use:
|
Example 2 | If you want to use most of the defaults, but there are one or two ciphers that you do not
want, you can remove those from any lists that they are currently in:
|
SSLClientAuth directive
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 |
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. |
- 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.
- 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.
- 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:
|
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 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.
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.
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:
|
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.
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 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)
or
SSLClientAuthRequire
(group!=IBMpeople) && (ST=MN)
SSLClientAuthRequire (group
!= IBMpeople) && ("ST= MN")
See SSLClientAuthGroup directive for more information. 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]
<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 resides.
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 (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.
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 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 resides.
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 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.
SSLDisable directive
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
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.
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. |
SSLFIPSDisable directive
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.
- 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 will 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. |
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.
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 |
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. |
- 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.
Name | Description |
---|---|
Syntax | SSLProtocolDisable <protocolname> |
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. |
Values | The following possible values are available for this directive.
|
A value of TLS disables all TLS versions.
A value of TLSv1 disables TLS Version 1.0.
A value of TLSv1.1 disables TLS version 1.1.
A value of TLSv1.2 disables TLS version 1.2.
<VirtualHost *:443> SSLEnable SSLProtocolDisable SSLv2
SSLv3 (any other directives) </VirtualHost>
SSLProtocolEnable directive
The SSLProtocolEnable directive can be used to enable individual SSL protocols.
On distributed platforms, this directive has limited usefulness because all useful protocols are automatically enabled by default.
On z/OS, this directive can be used after z/OS service adds support for TLSv1.1 and TLSv1.2. The TLSv1.1 and TLSv1.2 protocols are not enabled by default in an IBM HTTP Server running on z/OS.
Name | Description |
---|---|
Syntax | SSLSuiteBMode |
Scope | Virtual host |
Default | Unset |
Module | mod_ibm_ssl |
Multiple instances in the configuration file | Multiple instances permitted per virtual host. |
SSLProxyEngine directive
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
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.
- 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
Name | Description |
---|---|
Syntax | SSLServerCert [prompt] certificate_labelSSLServerCert [prompt|ecdsa_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 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. |
- To choose a certificate label other than the default, specify a single parameter whose value is the label of the desired 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, seperated by a space. The RSA certificate will be used by default, but clients supporting TLS1.2 or higher may request the ECDSA certificate during the handshake.
SSLServerCert example.com
SSLServerCert myRSA, myECDSA
SSLServerCert swtoken:cert1
SSLSNIMap
The SSLSNIMap directive maps TLS Server Name Indication (SNI) hostnames to certificate labels.
Name | Description |
---|---|
Syntax | SSLSNIMap hostname cert-label |
Scope | Virtual host |
Default | Disabled |
Module | mod_ibm_ssl |
Multiple instances in the configuration file | Multiple per virtual host |
Values | Hostnames used by the client and certificate labels present in the configured KeyFile |
The SSLSNIMap directive allows the server to respond with a different TLS certificate, based on the hostname the client requested. If name-based virtual hosts are used, SSLSNIMap should be present only in the first-listed virtual host for an ip:port combination (the default virtual host for a set of name-based virtual hosts).
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 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 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.
- Do not overwrite an existing *.sth file when you issue the sslstash command.
- Never choose a filename for the output of the sslstash command that corresponds to the filename of a CMS KeyFile (*.kdb).
Usage: sslstash [-c] <directory_to_password_file_and_file_name> <function_name> <password>
- -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 SSSLSuiteBMode 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 |
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 |
|
%{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 reset when an SSL session is reused.
Name | Description |
---|---|
Syntax | SSLV3Timeout 1000 |
Scope | Global base and virtual host. The virtual host scope or global scope are applicable. 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 | SSLV2|SSLV3|TLS|TLSV1|TLSV11|TLSV12|ALL | SSLV2|SSLV3|TLS|TLSV1|ALL |