Module mod_ibm_ssl

The SSLAppName directive is used for the following reasons:

• unique label to identify the server as an application that intends to use SSL
• to keep track of the registered name used by the server
• to identify the server when association of a server certificate with a secure application is done in the Digital Certificate Manager (DCM)
• to identify the server to the SSL API's so that the SSL API's can use the certificate that is associated with the server

This registration of the secure application and the creation of the SSLAppName is done automatically when the system administrator enables SSL for the server using the IBM^® Web Administration for i5/OS™ interface. The association of a server certificate with the application is accomplished by the system administrator using DCM. After a secure application is registered, and before attempting to start the server with SSL enabled, the user must use DCM to assign a server certificate to the corresponding secure application. Since this directive is valid at the virtual host level, the server may have more than one certificate assigned, with each virtual host having a different application name. The specified value on this directive is the name of the application that the server or virtual host is known as. If the server certificate association for the application name is not configured through DCM, then the SSL connection cannot be initialized and the server will not start.

Parameter: server_application_name

• The server_application_name parameter value specifies the name of the application that the server or virtual host.

The SSLAuthType directive is used to specify the type certificate validation/authentication required for access to a directory. This option is used to ensure that a certificate received from the client is associated with a user ID or an Internet User validation list. If this is not the case, the client may be prompted for the user ID.

Parameter: option

• The option parameter value can be one of the following:

  Cert

  This option indicates to the server that the certificate received from the client must be in an Internet User list or be associated with an iSeries user ID convention. Note : If SSLAuthType Cert is specified, then AuthType should be set to SSL.

  CertOrBasic

  This option indicates to the server that the certificate, if there is one, that is received from the client may be associated with a user ID or may be in an Internet User validation list. If it is not, then the client is authenticated based on the value of HTTP Server AuthType directive. In order to simulate HTTP Server (original) behavior of AuthType CertOrBasic , HTTP Server (powered by Apache) AuthType directive must be Basic. This will cause the client to be prompted for a user ID and password, and this provided user ID and password will then be used to access the directory/file. If SSLAuthType CertOrBasic is used, then AuthType should be set to Basic.

The certificate does not need to be valid. This directive only refers to the existence of a certificate. If the certificate must be valid, then the SSLClientCertEnable directive must also be specified.

There are no default values for this directive. If the directive is not used, then if a certificate is present, association with a user ID or Internet User validation list is not checked. This directive's scope is the directory level. This directive is only to be specified once for a directory. Any subsequent uses of this directive override any previously specified values.

This directive may be used in conjunction with the SSLClientCertEnable directive. This will cause very specific behavior to occur, depending on the value specified on the SSLAuthType directive. If the SSLClientCert directive is used in addition to SSLAuthType Cert, the certificate received from the client must be valid, as well as associated with a user ID or in an Internet User validation list. If the SSLClientCert directive is used in addition to SSLAuthType CertOrBasic, a certificate must be received from the client, but does not need to be associated with a user ID or in an Internet User validation list. If the association is not present, the client will be authenticated based on the protection setup (basic or ldap).

This directive also interacts with the PasswdFile directive. This directive is used to help determine the type of certificate authentication to be used. If the PasswdFile directive is set to %%SYSTEM%%, then the certificate received from the client must be associated with an iSeries user profile in order for it the client to be authenticated. If the PasswdFile directive is set to an internet user list, then the certificate received must be in the internet user list in order for the client to be authenticated. Again, this authentication is only required if the Cert option is selected on the SSLAuthType directive. Otherwise it is only optional.

The SSLCacheDisable directive will cause SSL session ID caching to be disabled. The effect of this directive will depend on the location of the directive. If the directive is located in the configuration file for the main server, SSL session ID caching will not be done for the server. If the directive is located in a <Virtual Host> container, then SSL session ID caching will not be done for the virtual host. The directive located at the server level can be overridden for a particular virtual host using the SSLCacheEnable directive. Directives SSLV2Timeout and SSLV3Timeout will be ignored when SSLCacheDisable is set.

The SSLCacheEnable directive will cause SSL session ID caching to be enabled. The effect of this directive will depend on the location of the directive. If the directive is located in the configuration file for the main server, SSL session ID caching will be done for the server. If the directive is located in a <Virtual Host> container, then SSL session ID caching will be done for the virtual host. The directive located at the server level can be overridden for a particular virtual host using the SSLCacheDisable directive. A abbreviated handshake will be done whenever a handshake is necessary. Directives SSLV2Timeout and SSLV3Timeout will be ignored.

The SSLCipherBan directive allows for banning access to a directory based on the cipher that is negotiated during the SSL handshake. A set of ciphers can either be defaulted or specified using the SSLCipherSpec directive. The cipher list then can be shortened for a specific directory. This directive will enforce a greater level of security through the use of cipher specs.

The SSLCipherBan directive will directly interact with the SSLCipherRequire directive. If a negotiated cipher is listed on the ban list, then the request will be rejected, even if the cipher is also on the require list.

Parameter: string

• The string parameter value specifies the cipher to be used. Either the short name or the long name in the table below may be specified.

  Table 1. Version 2 ciphers

  Long name	Short name
  SSL_WITH_3DES_EDE_CBC_MD5	27
  SSL_WITH_RC4_128_MD5	21
  SSL_WITH_RC2_CBC_128_MD5	23
  SSL_WITH_DES_CBC_MD5	26
  SSL_EXPORT_WITH_RC4_40_MD5	22
  SSL_EXPORT_WITH_RC2_CBC_40_MD5	24

  Table 2. Version 3 and TLS ciphers

  Long name	Short name
  SSL_RSA_WITH_3DES_EDE_CBC_SHA	3A
  SSL_RSA_WITH_RC4_128_SHA	35
  SSL_RSA_WITH_RC4_128_MD5	34
  SSL_RSA_WITH_DES_CBC_SHA	39
  SSL_RSA_EXPORT_WITH_RC4_40_MD5	33
  SSL_RSA_EXPORT_WITH_RC2_CBC_40_MD5	36
  SSL_RSA_WITH_NULL_SHA	32
  SSL_RSA_WITH_NULL_MD5	31

The SSLCipherRequire directive allows for the user to require that certain ciphers to be negotiated with the client during the SSL handshake. Specifying that a subset of ciphers are required will force a greater level of security for a particular directory which may not be required for all directories. The ciphers listed here may or may not be listed using the SSLCipherSpec directive.

Parameter: string

• The string parameter value specifies the cipher to be used. Either the short name or the long name in the table below may be specified.

  Table 3. Version 2 ciphers

  Long name	Short name
  SSL_WITH_3DES_EDE_CBC_MD5	27
  SSL_WITH_RC4_128_MD5	21
  SSL_WITH_RC2_CBC_128_MD5	23
  SSL_WITH_DES_CBC_MD5	26
  SSL_EXPORT_WITH_RC4_40_MD5	22
  SSL_EXPORT_WITH_RC2_CBC_40_MD5	24

  Table 4. Version 3 and TLS ciphers

  Long name	Short name
  SSL_RSA_WITH_3DES_EDE_CBC_SHA	3A
  SSL_RSA_WITH_RC4_128_SHA	35
  SSL_RSA_WITH_RC4_128_MD5	34
  SSL_RSA_WITH_DES_CBC_SHA	39
  SSL_RSA_EXPORT_WITH_RC4_40_MD5	33
  SSL_RSA_EXPORT_WITH_RC2_CBC_40_MD5	36
  SSL_RSA_WITH_NULL_SHA	32
  SSL_RSA_WITH_NULL_MD5	31

Text

Parameter: string

• The string parameter value specifies the cipher to be used. Either the short name or the long name in the table below may be specified.

  Table 5. Version 2 ciphers

  Long name	Short name
  SSL_WITH_3DES_EDE_CBC_MD5	27
  SSL_WITH_RC4_128_MD5	21
  SSL_WITH_RC2_CBC_128_MD5	23
  SSL_WITH_DES_CBC_MD5	26
  SSL_EXPORT_WITH_RC4_40_MD5	22
  SSL_EXPORT_WITH_RC2_CBC_40_MD5	24

  Table 6. Version 3 and TLS ciphers

  Long name	Short name
  SSL_RSA_WITH_3DES_EDE_CBC_SHA	3A
  SSL_RSA_WITH_RC4_128_SHA	35
  SSL_RSA_WITH_RC4_128_MD5	34
  SSL_RSA_WITH_DES_CBC_SHA	39
  SSL_RSA_EXPORT_WITH_RC4_40_MD5	33
  SSL_RSA_EXPORT_WITH_RC2_CBC_40_MD5	36
  SSL_RSA_WITH_NULL_SHA	32
  SSL_RSA_WITH_NULL_MD5	31

The order of the SSLCipherSpec directives is important. The cipher suite list passed to SSL is created by putting the first cipher listed in the configuration file at the top of the cipher suite list. SSL uses this list as the preferred order of ciphers.

This directive works in conjunction with the SSLVersion directive during the SSL handshake. The values specified for the SSLCipherSpec directive must correspond with the value specified on the SSLVersion directive. If this directive is not used, a default cipher suite list is used.

The SSLClientAuth directive is used to indicate the type of client-side SSL certificate validation is required for the server.

Parameter: type

• The type parameter value specifies the client-side SSL certificate validation required for the server. Valid values include:

  0 or none

  No client certificate is required.

  1 or optional

  The client may present a valid certificate.

  2 or required

  The client must present a valid certificate.

The default value of this directive is 0, or none, indicating that no certificate is requested or required from the client. If an incorrect value is specified, an error message is issued and the server will not start. A value of 1, or optional, will cause the server to request a certificate from the client, and the SSL connection will be made even if a certificate is not received. A value of 1 does not require the certificate received from the client to be valid. A value of 2, or required, will cause the server to request a certificate from the client. If a valid certificate is not received, the client request will be rejected.

The SSLClientAuthGroup directive is used to define a group name to a set of specific client certificate attributes to be used on the SSLClientAuthRequire directive. To indicate the attributes, a validated certificate must be presented before the server will allow access to the directory.

Parameter One: groupname

• The groupname parameter value specifies the group name for the client certificate. A group name cannot include spaces.

Parameter Two: attribute-expression

• The attribute-expression parameter value specifies the attribute for a validated certificate to be used for client authentication. Either the long name or the short name may be used in this directive. Valid values include:

  Table 7. Attribute values

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

  Note: The short and long names can be quoted. For example, SSLClientAuthGroup IBMpeople "Org = IBM".

The user specifies a logic string of specific client certificate attributes and a group name is assigned to these attributes. Multiple subexpressions can be logically ANDed , ORed, or NOTed to configure the desired group of client certificate attributes. Valid equalities include '=' and '!='.

Example One

SSLClientAuthGroup IBMpeople Org=IBM

Example Two

SSLClientAuthGroup MNIBM ST=MN && Org=IMB

The SSLClientAuthRequire directive is used to provide a specific client certificate attributes, or groups of attributes, that must be validated before the server will allow access to the directory. If the certificate received does not have a particular attribute, then we do not check for an attribute match. Even if the matching value is " ", this may still not be the same as not having the attribute there at all. Any attribute specified on the SSLClientAuthRequire and not available on the certificate causes the request to be rejected.

The following is a list of the attribute values that may be specified on this directive:

Either the long name or the short name may be used in this directive.

The user specified a logic string of specific client certificate attributes. Multiple subexpressions can be logically ANDed , ORed, or Noted to configure the desired client certificate attributes. Valid logical symbols include '=' and '!='. The user may also specify a group name, configured on the SSLClientAuthGroup, that allows a group of attributes to be configured.

Multiple SSLClientAuthRequire directives may be specified for each directory, and each attribute specified is used to check the attributes in the client certificate. Multiple directives place a logical AND on the attributes specified with the directives.

The SSLClientCertDisable directive indicates to the server that a valid certificate is not required in order to access this directory.

This directive may be used in conjunction with the SSLAuthType directive. If specified in addition to the SSLAuthTypeCert directive, the certificate received only needs to be associated with a user ID or an Internet user.

This directive negates the SSLClientCertEnable directive.

The SSLClientCertEnable directive indicates to the server that a valid certificate is required in order to access this directory.

This directive may be used in conjunction with the SSLAuthType directive.

If specified in addition to the SSLAuthTypeCert directive, the certificate received needs to be valid, as well as associated with a user ID or an Internet user. This directive is negated by the SSLClientCertDisable directive.

The SSLDenySSL directive will deny access to the directory when SSL is used for the request. This directive interacts somewhat with the SSLRequireSSL directive. If a directory has both the SSLRequireSSL and the SSLDenySSL directives specified, then the last directive in the directory scope will take effect. Since this directive is scoped to a directory, a server or a virtual host may also have SSLRequireSSL for some directories, but SSLDenySSL for other directories. Also, more specific directory container directives will override previously specified directives for a less specific directory.

<Directory /ABC>
 SSLRequireSSL
</Directory>
<Directory /ABC/DEF>
 SSLDenySSL
</Directory>

The SSLDisable directive causes SSL to be disabled for the server or virtual host. The effect of this directive will depend on the location of the directive. If the directive is located in the configuration file for the main server, SSL will not be allowed for the server. If the directive is located in a <Virtual Host> container, then SSL will not be allowed for the virtual host. The directive located at the server level can be overridden for a particular virtual host using the SSLEnable directive.

The SSLEnable directive will cause SSL to be enabled. The effect of this directive will depend on the location of the directive. If the directive is located in the configuration file for the main server, SSL will be required for the server. If the directive is located in a <Virtual Host> container, then SSL will be required for the virtual host. The directive, located at the server level, can be overridden for a particular virtual host using the SSLDisable directive. This directive requires that the directive SSLAppName be set.

The SSLEngine directive toggles the usage of SSL processing. If SSLEngine On is specified, SSL processing is enabled. If SSLEngine Off is specified, SSL processing is disabled. If SSLEngine Optional is specified, SSL processing is turned on to handle upgrading a non-SSL connection to an SSL connection. The effect of this directive depends on the location of the directive. If the directive is located in the configuration file for the main server, the type of SSL processing is set for the entire server. If the directive is located in a <VirtualHost> container, then the type of SSL processing is set for only that virtual host. If this directive is set at the server level, it can be overridden for a particular virtual host by specifying the other allowed option. SSLEngine On is equivalent to SSLEnable, SSLEngine Off is equivalent to SSLDisable, and SSLEngine Optional is equivalent to SSLUpgrade. These directives can be used interchangeably. The SSLEngine directive is being added in order to be compatible with Apache's mod_ssl.

If SSLEngine On or SSLEngine Optional is configured, the directive SSLAppName must also be configured.

See also SSLEnable, SSLDisable, SSLUpgrade, and SSLAppName.

Parameter: seconds

• The seconds parameter has a valid value range of 1 to 86400 seconds. If the value specified is greater than 86400, or less than 1, then the default value of 86400 seconds will be used as the timeout value. This value is used for negotiated SSLVersion 3, or TLS Version 1, sessions.

The SSLProxyAppName directive is used to:

• to uniquely label the proxy server as a client application that intends to use SSL to a remote content server.
• to keep track of the registered name used by the proxy server.
• to identify the server when association of a client certificate with a secure application is done in the Digital Certificate Manager (DCM).
• to identify the server to the SSL API's so that the SSL API's can use the certificate that is associated with the server.

The registration of the secure client application and the creation of the SSLProxyAppName is done automatically when the system administrator enables the SSL Proxy engine for the server using the HTTP Server configuration GUI. The association of a client certificate with the application is accomplished by the system administrator using DCM: after a secure client application is registered, and before attempting to start the server with the SSL proxy engine enabled and SSLProxyAppName configured, the user must use DCM to assign a client certificate to the corresponding secure application. Since this directive is valid at the virtual host level, the server may have more than one certificate assigned, with each virtual host having a different application name. The specified value on this directive is the name of the application that the server or virtual host is known as. If both the SSLProxyAppName directive and the SSLProxyMachineCertificateFile directive are configured for the server, then the SSLProxyAppName directive is used to identify the client certificate and the handshake processing.

The SSLProxyEngine directive toggles the usage of SSL connections to be used by the proxy to connect to the content server. This is usually used inside a <VirtualHost> section to enable SSL/TLS for proxy usage in a particular virtual host.

The SSLProxyVerify directive is used to indicate the type of server-side SSL certificate validation is required by the proxy server. The following values are valid for the SSLProxyVerify directive:

The default value of this directive is 2 or Required, indicating that the content server certificate must be valid and have a trusted root. If an incorrect value is specified, an error message is issued and the server will not start.

The proxy server requires a certificate to be received from the content server. However, this certificate may be expired, or not be trusted by the server CA, as configured on the SSLProxyAppName directive or the SSLProxyMachineCertificatePath directive. This will result in a handshake failure if 2 or Required is configured.

A value of 1 or Optional, will cause the proxy server to allow for an expired content server certificate, or allow for the consent server certificate to not be trusted by the server application ID configured. This will result in the handshake completing successfully.

The SSLProxyVersion directive specifies the SSL version that is negotiated with the remote content server during the SSL agreement that takes place when connecting the Apache proxy server to the content server via the SSL protocol. The version specified must be negotiated or access to content server is denied.

There are five possible values for this directive:

SSLV2

SSL Version 2.0 only

SSLV3

SSL Version 3.0 only

TLSV1

TLS Version 1.0 only

TLSV1_SSLV3

TLS Version 1.0 with SSL V3.0 compatibility

ALL (default)

TLS Version 1.0 with SSLV2.0 & SSL V3.0 compatibility

The server defaults to ALL indicating that the server accepts any version that is negotiated.

The SSLRequireSSL directive will deny access to the directory whenever SSL is not used for the request. This is used to ensure that the client uses the SSL protocol to access a directory, and helps protect the resources in the directory from being accessed, even though there may be errors in the server configuration.

This directive interacts with the SSLDenySSL directive. If a directory has both the SSLRequireSSL and the SSLDenySSL directives specified, the last directive in the directory scope will take effect. Since this directive is scoped to a directory, a server or a virtual host may also have SSLRequireSSL for some directories, but SSLDenySSL for other directories. Also, more specific directory container directives will override previously specified directives for a less specific directory.

<Directory /ABC>
 SSLRequireSSL
</Directory>
<Directory /ABC/DEF>
 SSLDenySSL
</Directory>

This example will require SSL for directory /ABC, but deny SSL for directory /ABC/DEF.

The SSLUpgrade directive enables a server to support a client request to upgrade a normal non-SSL connection to a Transport Layer Security (TLS) connection (for a single request). This directive's effectiveness will depend on the directive location. If the directive is located in the main server configuration file, any connection to the server will be eligible for a TLS upgrade. If the directive is located in a <Virtual Host> container, only the connection to that virtual host will be eligible for the upgrade. The directive, located at the server level, can be overridden for a particular virtual host using the SSLDisable or SSLEnable directives. SSLUpgrade requires that the directive SSLAppName is defined.

The SSLVersion directive is affected by SSLUpgrade. If SSLUpgrade is configured, the SSLVersion that is negotiated on the handshake will only be TLS. The SSLVersion specified in the configuration file will be ignored.

The SSLCipherSpec directive is also affected by SSLUpgrade. If SSLUpgrade is configured, only SSLV3/TLS ciphers are allowed. If SSLCipherSpec specifies SSL version 2 ciphers, these ciphers will be ignored, and only configured SSLV3/ TLS ciphers will be allowed. If there are no SSLV3/TLS ciphers configured, the defined default system cipher list will be used.

The SSLRequireSSL directive may be configured for a resource that is accessed through an upgraded connection. If the upgrade is requested as a part of the request through the use of the upgrade header, the SSLRequireSSL directive will be enforced before the connection is upgraded. This will allow the request to be processed, since the connection will be upgraded to SSL before the request has been handled, and the reply has been sent.

The SSLDenySSL directive will be enforced in the same manner as the SSLRequireSSL directive. If the request for the resource is received along with the upgrade header request, the request will be denied with a 403, Forbidden, response returned to the client, since the request will be processed after the connection has been upgraded.

he SSLVersion directive specifies the SSL version that will be negotiated with the client during the SSL handshake. The version specified must be negotiated or access to specified resource will be denied.

There are five possible values for this directive:

The server will default to ALL indicating that the server will accept any version that is negotiated.

The SSLV2Timeout directive specifies the timeout value for the session ID caching done by sockets that will be used on the SSL session. This directive indicates the number of seconds in which the internal SSL session identifier will expire. The session identifier is maintained by sockets. It allows caching of handshake information in order to allow for a shortened handshake to be done if the timeout value has not been reached. Lower values are safer but slower, because the complete handshake will be done after each timeout. If client certificates are being requested by the server, they will also be required to be represented at each timeout.

Parameter: seconds

• The seconds parameter has a valid value range of 1 to 100 seconds. If the value specified is greater than 100, or less than 1, then the default value of 100 seconds will be used as the timeout value. This value is used for negotiated SSL Version 2 sessions.

The SSLV3Timeout directive specifies the timeout value for the session ID caching done by sockets that will be used on the SSL session. This directive indicates the number of seconds in which the internal SSL session identifier will expire. The session identifier is maintained by sockets, and allows caching of handshake information in order to allow for a shortened handshake to be done if the timeout value has not been reached. Lower values are safer, but also slower, as the complete handshake will be done after each timeout. If client certificates are being requested by the server, they will also be required to be represented at each timeout.

Parameter: seconds

• The seconds parameter has a valid value range of 1 to 86400 seconds. If the value specified is greater than 86400, or less than 1, then the default value of 86400 seconds will be used as the timeout value. This value is used for negotiated SSLVersion 3, or TLS Version 1, sessions.