Home

SSL directives

 

+

Search Tips   |   Advanced Search

 

SSL directives are the configuration parameters that control SSL features in IBM HTTP Server.

Most SSL directives in IHS 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 overrides a directive specified for its parent However, there are exceptions.

For example, when no directive is specified for a virtual host, the directive specified in the base server configuration might be copied to the virtual host configuration. In this case, the directive in the base server configuration overrides the virtual host configuration.

The SSLEnable directive should not be specified in the base server configuration if we do not want the directive automatically copied to a given virtual host configuration.

Also, a directive specified for a child might be appended to the directive specified for its parent In this case, the directive for the parent does not override the directive for the child directory, but instead is appended to it and both directives are applied to the child

The following list contains the SSL directives for IBM HTTP Server.

 

SSLOCSPResponderURL

Enable checking of client certificates through a statically configured online certificate status protocol (OCSP) responder.

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 SSLOCSPResponderURL is set, IHS uses the supplied URL to check for certificate revocation status when an SSL client certificate is provided.

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.

 

SSLOCSPEnable

Enable checking of client certificates through OCSP responders defined in the Authority Information Access (AIA) extension of their certificate.

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, IHS contacts the OCSP responder indicated by the AIA extension to check revocation status of the client certificate.

The path portion of the URL is ignored.

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.

 

Keyfile directive

The keyfile directive sets the key file to use.

This directive might be overridden by the base server configuration.

Syntax Keyfile [/prompt] /fully qualified path to key file/keyfile.kdbz/OS:

The /prompt function is only supported when running from a USS shell, not from a JCL started job. If we attempt to use the /prompt function from a JCL started job, then a configuration error occurs.

z/OS: 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:

  • Keyfile /fully qualified path to key file/keyfile.kdb
To use a keyring stored in SAF:

  • Keyfile /saf WASKeyring

    With SAF keyrings:

    • There is no stash file when using SAF, and access is controlled by SAF rules. Therefore, if we attempt to use the Keyfile/prompt/saf argument, the argument is not supported. An attempt to use this argument results in a configuration error.
    • The ID 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.
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.

z/OS: File system protection can be used to limit access. Use the SAF (System Authorization Facility) keyrings for limiting access to SSL certificates.

z/OS:

The z/OS system does not support key database files created on other platforms. Key database files used for z/OS systems must be created on the z/OS platform.

 

SSLAcceleratorDisable directive

Disable the accelerator device.

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

Allow compatibility with one aspect of the GPKI specification from the government of Japan that conflicts with RFC3280.

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 will not cause a validation failure. This allows compatibility with one aspect of the GPKI specification from the government of Japan that conflicts with RFC3280.

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

Disable the external SSL session ID cache.

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.

 

SSLCacheEnable directive

Enable the external SSL session ID cache.

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.

 

SSLCacheErrorLog directive

Set the file name for session ID cache.

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

Path to the session ID caching daemon.

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

Set the file name for the UNIX domain socket used for communication between the server instances and the session ID cache daemon. Set this directive if we run two instances of IHS from the same installation and both instances are configured for SSL. Otherwise, you do not need to set this directive.

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.

 

SSLCacheTraceLog directive

File to which the session ID trace messages are written. Without this directive, tracing is disabled.

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

Deny access to an object if the client has connected using one of the specified ciphers. The request will fail with a 403 status code.

This directive, when specified for a child directory, does not override the directive specified for the parent Instead, both directories are applied to the child directory.

Syntax SSLCipherBan <cipher_specification>
Scope Multiple instances per stanza.
Default None.
Module mod_ibm_ssl
Multiple instances in the configuration file Permitted per stanza. Order of preference is top to bottom.
Values See SSL Version 2 cipher specifications and SSL Version 3 and TLS Version 1 cipher specifications.

 

SSLCipherRequire directive

Restrict access to objects to clients that have connected using one of the specified ciphers. If access is denied, the request will fail with a '403' status code.

This directive, when specified for a child directory, does not override the directive specified for the parent Instead, both directories are applied to the child

Syntax SSLCipherRequire <cipher_specification>
Scope Multiple instances per stanza.
Default None.
Module mod_ibm_ssl
Multiple instances in the configuration file Permitted per stanza.
Values See SSL Version 2 cipher specifications and SSL Version 3 and TLS Version 1 cipher specifications.

 

SSLCipherSpec directive

If we specify V3 or TLS ciphers and no SSL V2 ciphers SSL V2 support is disabled. Also, if we specify SSL V2 ciphers and no SSL V3 or TLS ciphers SSL V3 and TLS support is disabled.

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 cipher specifications.

 

SSLClientAuth directive

Set the mode of client authentication to use...

Syntax SSLClientAuth <level required> [crl]
Scope Virtual host.
Default SSLClientAuth none
Module mod_ibm_ssl
Multiple instances in the configuration file One instance per virtual host.
Values

0/None No client certificate requested.
1/Optional Client certificate requested, but not required.
2/Required Valid client certificate required.
Required_reset The server requires a valid certificate from all clients, and if no certificate is available, the server sends an SSL alert to the client. This 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. No numeric option is provided so it will not look like the existing options.
CRL Turns crl on and off inside an SSL virtual host. If we use certificate revocation list (CRL), you need to specify crl as a second argument for SSLClientAuth.

For example:

SSLClientAuth 2 crl

If we do not specify crl, you cannot perform CRL in an SSL virtual host.

If we 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.

 

SSLClientAuthGroup directive

Define 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)

The logical expression...

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, delimit the value with quotation marks.

Attribute values...

Long name Short name
CommonName CN
Country C
Email E
IssuerCommonName ICN
IssuerEmail IE
IssuerLocality IL
IssuerOrg IO
IssuerOrgUnit IOU
IssuerPostalCode IPC
IssuerStateOrProvince IST
Locality L
Org O
OrgUnit OU
PostalCode PC
StateOrProvince ST

The long name or the short name can be used in this directive.

The user specifies a logical expression of specific client certificate attributes. You can logically use AND , OR, or NOT for multiple expressions if we 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 '!='.

For example:

SSLClientAuthGroup IBMpeople Org = IBM)
or

SSLClientAuthGroup NotMNIBM (ST != MN) && (Org = IBM)

A group name cannot include spaces. See SSLClientAuthRequire for more information.

 

SSLClientAuthRequire directive

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 not available on the certificate, causes the request to be rejected.

The following is a list of the attribute values that you can specify for this directive:

Long name Short name
CommonName CN
Country C
Email E
IssuerCommonName ICN
IssuerEmail IE
IssuerLocality IL
IssuerOrg IO
IssuerOrgUnit IOU
IssuerPostalCode IPC
IssuerStateOrProvince IST
Locality L
Org O
OrgUnit OU
PostalCode PC
StateOrProvince ST

The long name or the short name can be used in this directive.

The user specifies a logical expression of specific client certificate attributes. You can logically use AND , OR, or NOT for multiple expressions if we 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, configured using the SSLClientAuthGroup, to configure a group of attributes.

You can specify multiple SSLClientAuthRequire directives within the same scope. The logical expressions for each directive are used to evaluate access rights for each certificate, and the results of the individual evaluations are logically ANDed together.

For example:

SSLClientAuthRequire ((CommonName="John Doe") || (StateOrProvince=MN)) && (Org !=IBM)
or

SSLClientAuthRequire (group!=IBMpeople) && (ST=MN)

You can put quotes around the short and long names.

For example:

SSLClientAuthRequire (group != IBMpeople) && ("ST= MN")

See SSLClientAuthGroup for more information.

 

SSLCRLHostname directive

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.

 

SSLCRLPort directive

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.

 

SSLCRLUserID directive

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 we 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.

 

SSLDisable directive

Disable SSL for the virtual host.

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

Enable SSL for the virtual host.

This directive should not be specified in the base server configuration if we do not want the directive automatically copied to a given virtual host configuration.

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

Enable fake basic authentication support which allows the client certificate distinguished name to become the user portion of the user and password basic authentication pair.

Use password for the password.

This directive might be overridden by the base server configuration.

Syntax SSLFakeBasicAuth
Scope Within a stanza, used along with AuthName, AuthType, and require directives.
Default None.
Module mod_ibm_ssl
Multiple instances in the configuration file One instance per stanza.
Values None.

 

SSLFIPSDisable

Disable FIPSs (FIPS).

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

Enable FIPSs (FIPS).

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.

See also SSL Version 3 and TLS Version 1 cipher specifications.

 

SSLPKCSDriver

Identify the fully qualified name to the module, or driver used to access the PKCS11 device.

Syntax /path/to/PKCS11_device/module

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 default locations of the modules for each PKCS11 device follow, platform:

 

SSLProtocolDisable directive

Specify one or more SSL protocols which cannot be used by the client for a specific virtual host. This directive must be located in a <VirtualHost> container. Supported protocols for a virtual host are supported separately. If all supported protocols are disabled, clients cannot complete an SSL handshake.

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.

  • SSLv2
  • SSLv3
  • TLSv1

The following example disables support for multiple protocols on a virtual host. 

<VirtualHost	*:443>
    SSLEnable
    SSLProtocolDisable	SSLv2 SSLv3
    Other directives...
</VirtualHost>

SSL0230I is logged for each SSL connection attempt if the client and server do not share at least one protocol and cipher combination.

 

SSLProxyEngine directive

Toggle whether the server will use SSL for proxied connections. SSLProxyEngine on is required if wer server is acting as a reverse proxy for an SSL resource.

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

 

SSLServerCert directive

Set the server certificate to use for this virtual host.

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. Verify the label is contained on one line; leading and trailing white space is ignored.

 

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 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> where:

See also SSL certificate revocation list.

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.

 

SSLTrace directive

Enable 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 IHS 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

See also LogLevel Directive.

 

SSLV2Timeout directive

Set the timeout for SSL Version 2 session IDs.

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

Set the timeout for SSL Version 3 and TLS session IDs.

Syntax SSLV3Timeout 1000
Scope Global base and virtual host.

Windows: 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

Enable 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 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

 

Related concepts


SSL certificate revocation list

 

Related tasks


Choosing the level of client authentication

Choosing the type of client authentication protection

Securing with SSL communications