SSL directives

These configuration parameters control the SSL feature in IBM HTTP Server.

• Keyfile directive

• LogLevel directive

• SSLAcceleratorDisable 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

• SSLCRLHostname directive

• SSLCRLPort directive

• SSLCRLUserID directive

• SSLDisable directive

• SSLEnable directive

• SSLFakeBasicAuth directive

• SSLFIPSDisable directive

• SSLFIPSEnable directive

• SSLPKCSDriver directive

• SSLProxyEngine directive

• SSLServerCert directive

• SSLStashfile directive

• SSLTrace directive

• SSLV2Timeout directive

• SSLV3Timeout directive

• SSLVdirective

 

Keyfile directive

The keyfile directive sets the key file to use.

Syntax	Keyfile [/prompt] /fully qualified path to key file/keyfile.kdb 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 and access is controlled by SAF rules. 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.
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 we for the Key file password during start up. Prompting for key database passwords, using the /prompt parameter on the mod_ibm_ssl Keyfile directive, is not supported. If we are using.kdb files, stash files must be provided. File system protection can be used to limit access. Use the SAF (System Authorization Facility) keyrings for limiting access to SSL certificates.

The z/OS system SSL does not support key database files created on other platforms. Key database files that are used on z/OS must be created on z/OS.

 

LogLevel directive

The LogLevel directive adjusts the verbosity of the messages recorded in the error logs. When we specify a particular level, the server reports messages from all other levels of higher significance. For example, when we specify LogLevel info, the server reports messages with log levels of notice and warn. Specifying at least level crit is recommended.

Syntax	LogLevel error
Scope	Server configuration and virtual host
Default	LogLevel error
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 cipher specifications, the connection closes.
Values	The following available levels appear in order of decreasing significance: Level Description Example emerg Emergencies: system rendered unusable. "Child cannot open lock file. Exiting" alert Take immediate action. "getpwuid: could not determine user name from uid" crit Critical conditions. "socket: Failed to get a socket, exiting child" error Error conditions. "Premature end of script headers" warn Warning conditions. "child process 1234 did not exit, sending another SIGHUP" notice Normal, but significant condition. "httpd: caught SIGBUS, attempting to dump core in..." info Informational. "Server seems busy, (we may need to increase StartServers, or Min/MaxSpareServers)..." debug Debug-level messages. "Opening configuration file..."

 

SSLAcceleratorDisable directive

The SSLAcceleratorDisable directive disables 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.

 

SSLCacheDisable directive

The SSLCacheDisable directive disables 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

The SSLCacheEnable directive enables 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

The SSLCacheErrorLog directive sets the file name for session ID cache.

Syntax	SSLCacheErrorLog /usr/HTTPServer/log/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.

Syntax	SSLCachePath /usr/HTTPServer/log/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

The SSLCachePortFilename directive sets the file name for the UNIX domain socket that is used for communication between the server instances and the session ID cache daemon.

Syntax	SSLCachePath /usr/HTTPServer/log/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

The SSLCacheTraceLog directive specifies the file to which the session ID trace messages are written. Without this directive, tracing is disabled.

Syntax	SSLCacheTraceLog /usr/HTTPServer/log/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

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

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

 

SSLCipherRequire directive

The SSLCipherRequire directive restricts 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.

Syntax	SSLCipherRequire <cipher_specification>
Scope	Multiple instances per directory stanza.
Default	None.
Module	mod_ibm_ssl
Multiple instances in the configuration file	Permitted per directory stanza.
Values	See SSL V2 cipher specifications and SSL V3 and TLS V1 cipher specifications.

 

SSLCipherSpec directive

If you 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 V2 cipher specifications and SSL V3 and TLS V1 cipher specifications.

 

SSLClientAuth directive

The SSLClientAuth directive sets the mode of client authentication to use (none (0), optional (1), or required (2)).

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. CRL: Turns crl on and off inside an SSL virtual host. If we use certificate revocation list (CRL), we need to specify crl as a second argument for SSLClientAuth. For example: SSLClientAuth 2 crl. If we do not specify crl, we cannot perform CRL in an SSL virtual host. If we specify the value 0/None, we cannot use the CRL option.

 

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 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 IBM people Org = IBM

Description of valid logical expressions. The following section provides a description of examples with valid logical expressions. For example: SSLClientAuthGroup (CommonName = "Fred Smith" OR CommonName = "John Deere") AND Org = IBM means that the object is not served, unless the client certificate contains a common name of either Fred Smith or John Deere and the organization is IBM. The only valid comparisons for the attribute checks, are equal and not equal (= and !=). We can link each attribute check with AND, OR, or NOT (also &&, ||, and !). Use parentheses to group comparisons. If the value of the attribute contains a nonalphanumeric character, we must delimit the value with quotes.

The following is a list of the attribute values that we 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. We can logically use AND, OR, or NOT for multiple expressions to specify the desired grouping of client certificate attribute values. Valid operators include '=' and '!='. For example:

SSLClientAuthGroup IBM people 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 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 != IBM people && ST = M

If the certificate we received does not have a particular attribute, then there is no verification for an attribute match. Even if the specified matching value is " ", this may still not be the same as not having the attribute there at all. Any attribute specified on the SSLClientAuthRequire directive that is not available on the certificate, causes the request to be rejected.

The following is a list of the attribute values that we 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. We can logically use AND, OR, or NOT for multiple expressions to specify the desired grouping of client certificate attribute values. 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.

We 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!=IBM people && ST=MN

You can put quotes around the short and long names. For example:

SSLClientAuthRequire group != IBM people && "ST= MN"

See SSLClientAuthGroup directive for more information.

 

SSLCRLHostname directive

The SSLCRLHostname directive specifies the TCP/IP name or address of LDAP server where the Certificate Revocation List (CRL) database resides.

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

 

SSLCRLPort directive

The SSLCRLPort directive specifies the port of the LDAP server where the Certificate Revocation List (CRL) database resides.

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

 

SSLCRLUserID directive

The SSLCRLUserID directive specifies the user ID to send to the LDAP server, where the Certificate Revocation List (CRL) database resides.

Syntax	SSLCRLUserID <[prompt] <userid>
Scope	Global server or virtual host.
Default	Defaults to anonymous if 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 we for the password needed to access the LDAP server during start up.

 

SSLDisable directive

The SSLDisable directive disables 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

The SSLEnable directive enables SSL for the virtual host.

Syntax	SSLEnable
Scope	Global server or virtual host.
Default	Disabled by default.
Module	mod_ibm_ssl
Multiple instances in the configuration file	One instance per virtual host and global server.
Values	None.

 

SSLFakeBasicAuth directive

The SSLFakeBasicAuth directive enables the fake basic authentication support.

This support enables the client certificate distinguished name to become the user portion of the user and password basic authentication pair. Use password for the password.

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

The SSLFIPSDisable directive disables Federal Information Processing Standards (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 directive

The SSLFIPSEnable directive enables Federal Information Processing Standards (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 V3 and TLS V1 cipher specifications.

 

SSLPKCSDriver directive

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

Syntax	Fully qualified name to module used to access PKCS11 device>. If the module exists in the user's path, then specify just the name of the module.
Scope	Global server or virtual host.
Default	None.
Module	mod_ibm_ssl
Multiple instances in the configuration file	One instance per virtual host and global server.
Values	Path and name of PKCS11 module or driver.

The default locations of the modules for each PKCS11 device follow, platform:

• 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

 

SSLProxyEngine directive

The SSLProxyEngine toggles whether the server will use SSL for proxied connections. SSLProxyEngine on is required if our 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

The SSLServerCert directive sets 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 we 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.

 

SSLStashfile directive

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

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

The SSLStashFile does not point to a stash file for the KeyFile in use, as that is calculated automatically based on the name of the KeyFile, and is a different type of stashfile.

See also SSL certificate revocation list.

 

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

The SSLV2Timeout directive sets the timeout for SSL V2 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

The SSLV3Timeout directive sets the timeout for SSL V3 session IDs.

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.

 

SSLVdirective

The SSLVersion directive enables object access rejection, if the client attempts to connect with an SSL protocol version other than the one specified.

Syntax	SSLVALL
Scope	One per directory stanza.
Default	None.
Module	mod_ibm_ssl
Multiple instances in the configuration file	One instance per virtual host and global server.
Values	SSLV2|SSLV3|TLSV1|ALL

---

 

Related tasks

Choosing the level of client authentication
Choosing the type of client authentication protection
Securing with SSL communications