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
- SSLOCSPEnable
- SSLOCSPCacheSize
- Keyfile directive
- SSLAcceleratorDisable directive
- SSLAllowNonCriticalBasicConstraints directive
- SSLCacheDisable directive
- SSLCacheEnable directive
- SSLCacheErrorLog directive
- SSLCachePath directive
- SSLCachePortFilename directive
- SSLCacheTraceLog directive
- SSLCheckCertificateExpiration
- 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
- SSLMinimumRSAKeySize directive
- SSLPKCSDriver directive
- SSLProtocolDisable directive
- SSLProtocolEnable directive
- SSLProxyEngine directive
- SSLRenegotiation directive
- SSLServerCert directive
- SSLStashfile directive
- SSLSuiteBMode
- SSLSupportedCurves
- SSLTrace directive
- SSLUnknownRevocationStatus
- SSLV2Timeout directive
- SSLV3Timeout directive
- SSLVersion directive
SSLOCSPResponderURL
Name | Description |
---|---|
Syntax |
|
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 |
|
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.
SSLOCSPCacheSize
Name | Description |
---|---|
Syntax | SSLOCSPCacheSize number-of-elements |
Scope | Virtual host |
Default |
|
Module | mod_ibm_ssl |
Multiple instances in the configuration file | One instance permitted for each virtual host |
Values | The maximum number of elements for the cache |
Enabling a nonzero SSLOCSPCacheSize allows for the use of an in-memory cache for OCSP responses. The lifespan of cache entries depends on the following three factors:
- The
nextUpdate
field specified by the OCSP responder. - HTTP cache headers specified by the OCSP responder.
- Eviction from a full cache to accommodate new entries.
The contents of the cache cannot be viewed, and can be cleared only when a web server restarts.
Keyfile directive
Name | Description |
---|---|
Syntax |
|
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.
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
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 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. |
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. |
SSLCheckCertificateExpiration
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
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
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.
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 |
Version 9.0.5.2 and later supports all the listed protocol name values, including
|
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
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 IBM Global Security Kit (GSKit) version 7.0.4.19 or later, or z/OS V1R8 or later. |
CRL processing |
|
- 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) 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.
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.
=
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:
|
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. Attribute Prefix | Description |
---|---|
SANDNSNAME | DNS Name |
SANIPADDRESS | IP Address |
SANRFC822NAME | RFC822 Name (email) |
SANDIRECTORYNAME | Directory Name |
SANURI | Universal Resource Identifier (URI) |
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 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
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 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. |
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 |
SSLMinimumRSAKeySize directive
The SSLMinimumRSAKeySize directive is primarily used to enforce a minimum RSA key size for received client certificates. The behavior of the directive depends on the capabilities that the platform security library provides.
Name | Description |
---|---|
Syntax | SSLMinimumRSAKeySize size |
Scope | Global and virtual host |
Default | 0 (no minimum) |
Module | mod_ibm_ssl |
Multiple instances in the configuration file | One instance per virtual host and global server |
Values | Key size in bits, such as 2048 |
The key size is enforced on client certificates that the server receives. The issuers of the client certificates are not checked.
The key size is enforced on all certificates that are sent or received by
mod_ibm_ssl
, including their full certificate chains. Use the environment variables
SSL_CLIENT_KEY_ALG, such as RSA
and
EC_ecPublicKey
, and SSL_CLIENT_KEY_SIZE in logging and
conditional expressions.
The SSL handshake fails if the minimum RSA key size is not met.
SSLPKCSDriver directive
The SSLPKCSDriver directive identifies the fully qualified name to the module, or driver used to access the PKCS11 device.
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>
Supported protocol name values:
Version 9.0.5.2 and later supports all the
listed protocol name values, including |
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. |
<VirtualHost *:443>
SSLEnable
SSLProtocolDisable TLSv10
# Any other directives ...
</VirtualHost>
SSLProtocolEnable directive
The SSLProtocolEnable directive can be used to enable individual SSL protocols.
Name | Description |
---|---|
Syntax | SSLProtocolEnable <protocolname> Supported
protocol name values:
Version 9.0.5.2 and later supports all the
listed protocol name values, including |
Scope | Virtual host |
Default | Unset |
Module | mod_ibm_ssl |
Multiple instances in the configuration file | Multiple instances permitted per virtual host. |
SSLProxyEngine directive
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 |
SSLProxyCheckPeerCN directive
Name | Description |
---|---|
Syntax | SSLProxyCheckPeerCN on|off |
Scope | virtual hosts |
Default | ON |
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_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. |
- 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.
- 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.
- 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>
- -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 |
SSLSupportedCurves
The SSLSupportedCurves directive allows the curves that the server offers to be customized in the environment where handshakes use ECDHE key exchange. The client and server must negotiate a named curve that both sides support.
Name | Description |
---|---|
Syntax | SSLSupportedCurves TLSv12|TLSv13 curve-list |
Scope | Global and Virtual host |
Default |
|
Module | mod_ibm_ssl |
Multiple instances in the configuration file | One instance per protocol per virtual host and global server |
Values |
|
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 not 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
|
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:
Version 9.0.5.2 and later supports all the listed values, including |