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

Version 3 Ciphers:

TLS 1.0 Ciphers:

TLS 1.1 Ciphers:

TLS 1.2 Ciphers:

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

  HEX	Short Name	Key Size	Long Name	SSLv3	TLSv10	TLSv11	TLSv12
  0x01	31	0	TLS_RSA_WITH_NULL_MD5 (*)	X	X	X	X
  0x02	32	0	TLS_RSA_WITH_NULL_SHA (*)	X	X	X	X
  0x03	33	40	TLS_RSA_WITH_NULL_SHA (*)	X	X
  0x04	34	128	TLS_RSA_WITH_RC4_128_MD5 (*)	X	X	X	X
  0x05	35	128	TLS_RSA_WITH_RC4_128_SHA (*)	X	X	X	X
  0x06	36	40	TLS_RSA_EXPORT_WITH_RC2_CBC_40_MD5 (*)	X	X
  0x09	39	56	TLS_RSA_WITH_DES_CBC_SHA (*)	X	X	X	X
  0x0A	3A	168	TLS_RSA_WITH_3DES_EDE_CBC_SHA (*)		X	X	X
  0x2F	X2F	128	TLS_RSA_WITH_AES_128_CBC_SHA		X	X	X
  0x35	X35	256	TLS_RSA_WITH_AES_256_CBC_SHA		X	X	X
  0x3B	X3B	0	TLS_RSA_WITH_NULL_SHA256				X
  0x3C	X3C	128	TLS_RSA_WITH_AES_128_CBC_SHA256				X
  0x3D	X3D	256	TLS_RSA_WITH_AES_256_CBC_SHA256				X
  0x9C	X9C	128	TLS_RSA_WITH_AES_128_GCM_SHA256				X
  0x9D	X9D	256	TLS_RSA_WITH_AES_256_GCM_SHA384				X
  0xC006	N/A	0	TLS_ECDHE_ECDSA_WITH_NULL_SHA				X
  0xC007	N/A	128	TLS_ECDHE_ECDSA_WITH_RC4_128_SHA				X
  0xC008	N/A	168	TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA				X
  0xC010	N/A	0	TLS_ECDHE_RSA_WITH_NULL_SHA				X
  0xC011	N/A	128	TLS_ECDHE_RSA_WITH_RC4_128_SHA				X
  0xC012	N/A	168	TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA				X
  0xC023	N/A	128	TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256				X
  0xC024	N/A	256	TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384				X
  0xC027	N/A	128	TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256				X
  0xC028	N/A	256	TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384				X
  0xC02B	N/A	128	TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256				X
  0xC02C	N/A	256	TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384				X
  0xC02F	N/A	128	TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256				X
  0xC030	N/A	256	TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384				X

  Note: (*) indicates the long name can also be named by starting with "SSL_" in order to be compatible with older releases.

  Version 3 Ciphers:

  Table 7.

  Long Name	Short name
  SSL_RSA_WITH_3DES_EDE_CBC_SHA / TLS_RSA_WITH_3DES_EDE_CBC_SHA	3A
  SSL_RSA_WITH_RC4_128_SHA / TLS_RSA_WITH_RC4_128_SHA	35
  SSL_RSA_WITH_RC4_128_MD5 / TLS_RSA_WITH_RC4_128_MD5	34
  SSL_RSA_WITH_DES_CBC_SHA / TLS_RSA_WITH_DES_CBC_SHA	39
  SSL_RSA_EXPORT_WITH_RC4_40_MD5 / TLS_RSA_EXPORT_WITH_RC4_40_MD5	33
  SSL_RSA_EXPORT_WITH_RC2_CBC_40_MD5 / TLS_RSA_EXPORT_WITH_RC2_CBC_40_MD5	36
  SSL_RSA_WITH_NULL_SHA / TLS_RSA_WITH_NULL_SHA	32
  SSL_RSA_WITH_NULL_MD5 / TLS_RSA_WITH_NULL_MD5	31

  Note: SSLV3 is disabled by default on i 7.2

  TLS 1.0 Ciphers:

  Table 8.

  Long Name	Short name
  SSL_RSA_WITH_3DES_EDE_CBC_SHA / TLS_RSA_WITH_3DES_EDE_CBC_SHA	3A
  SSL_RSA_WITH_RC4_128_SHA / TLS_RSA_WITH_RC4_128_SHA	35
  SSL_RSA_WITH_RC4_128_MD5 / TLS_RSA_WITH_RC4_128_MD5	34
  SSL_RSA_WITH_DES_CBC_SHA / TLS_RSA_WITH_DES_CBC_SHA	39
  SSL_RSA_EXPORT_WITH_RC4_40_MD5 / TLS_RSA_EXPORT_WITH_RC4_40_MD5	33
  SSL_RSA_EXPORT_WITH_RC2_CBC_40_MD5 / TLS_RSA_EXPORT_WITH_RC2_CBC_40_MD5	36
  SSL_RSA_WITH_NULL_SHA / TLS_RSA_WITH_NULL_SHA	32
  SSL_RSA_WITH_NULL_MD5 / TLS_RSA_WITH_NULL_MD5	31
  TLS_RSA_WITH_AES_128_CBC_SHA	X2F
  TLS_RSA_WITH_AES_256_CBC_SHA	X35

  TLS 1.1 Ciphers:

  Table 9.

  Long Name	Short name
  SSL_RSA_WITH_3DES_EDE_CBC_SHA	3A
  SSL_RSA_WITH_RC4_128_SHA / TLS_RSA_WITH_RC4_128_SHA	35
  SSL_RSA_WITH_RC4_128_MD5 / TLS_RSA_WITH_RC4_128_MD5	34
  SSL_RSA_WITH_DES_CBC_SHA / TLS_RSA_WITH_DES_CBC_SHA	39
  SSL_RSA_WITH_NULL_SHA / TLS_RSA_WITH_NULL_SHA	32
  SSL_RSA_WITH_NULL_MD5 / TLS_RSA_WITH_NULL_MD5	31
  TLS_RSA_WITH_AES_128_CBC_SHA	X2F
  TLS_RSA_WITH_AES_256_CBC_SHA	X35

  TLS 1.2 Ciphers:

  Table 10.

  Long Name	Short name
  SSL_RSA_WITH_3DES_EDE_CBC_SHA	3A
  SSL_RSA_WITH_RC4_128_SHA / TLS_RSA_WITH_RC4_128_SHA	35
  SSL_RSA_WITH_RC4_128_MD5 / TLS_RSA_WITH_RC4_128_MD5	34
  SSL_RSA_WITH_NULL_SHA / TLS_RSA_WITH_NULL_SHA	32
  SSL_RSA_WITH_NULL_MD5 / TLS_RSA_WITH_NULL_MD5	31
  TLS_RSA_WITH_AES_128_CBC_SHA	X2F
  TLS_RSA_WITH_AES_256_CBC_SHA	X35
  TLS_RSA_WITH_NULL_SHA256	X3B
  TLS_RSA_WITH_AES_128_CBC_SHA256	X3C
  TLS_RSA_WITH_AES_256_CBC_SHA256	X3D
  TLS_RSA_WITH_AES_128_GCM_SHA256	X9C
  TLS_RSA_WITH_AES_256_GCM_SHA384	X9D
  TLS_ECDHE_ECDSA_WITH_NULL_SHA	N/A
  TLS_ECDHE_ECDSA_WITH_RC4_128_SHA	N/A
  TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA	N/A
  TLS_ECDHE_RSA_WITH_NULL_SHA	N/A
  TLS_ECDHE_RSA_WITH_RC4_128_SHA	N/A
  TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA	N/A
  TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256	N/A
  TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384	N/A
  TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256	N/A
  TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384	N/A
  TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256	N/A
  TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384	N/A
  TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256	N/A
  TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384	N/A

The SSLCipherSpec directive allows for specifying a cipher spec to be used for the SSL connection. Each occurrence of this directive will add the associated cipher spec to that context's existing cipher suite list. The cipher spec is used on the SSL handshake, which then uses the cipher suite list to negotiate the cipher used for communications between the server and the client.

There are two syntaxes can be used for this directive:

• SSLCipherSpec cipher.

  For the single-argument form, the given cipher is enabled in all protocols for which it is valid.

• SSLCipherSpec [protocol_name] [+|-]cipher [[+|-]cipher...].

  For the multiple-argument form, specifying the name of an SSL protocol (SSLv2, SSLv3, TLSv10, TLSv11, TLSv12, ALL) as the first argument, the directive can add or remove the specific cipher from the SSL protocol cipher suite list.

The following cipher specs are allowed for this directive. Either the short name or the long name may be specified.

Version 3 Ciphers:

TLS 1.0 Ciphers:

TLS 1.1 Ciphers:

TLS 1.2 Ciphers:

TLS_RSA_WITH_NULL_SHA

TLS_RSA_WITH_NULL_MD5

TLS_RSA_WITH_DES_CBC_SHA

TLS_RSA_EXPORT_WITH_RC2_CBC_40_MD5

TLS_RSA_EXPORT_WITH_RC4_40_MD5

TLS_RSA_WITH_NULL_SHA256

See also SSLVersion.

LoadModule ibm_ssl_module /QSYS.LIB/QHTTPSVR.LIB/QZSRVSSL.SRVPGM

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

Parameter: level

• The level 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.

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

SSLProxyProtocolDisable

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 or optional does not require the certificate received from the client to be valid. With noverify parameter, the HTTP server enables SSL handshake to succeed and establish a connection, even if the certificate provided by the client fails validation (for example, the certificate is expired or revoked). Use this directive with SSLClientAuthVerify to provide a user-friendly web page, instead of the default browser error message.

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.

A value of require_reset, will cause the server to request a certificate from the client. 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.

LoadModule ibm_ssl_module /QSYS.LIB/QHTTPSVR.LIB/QZSRVSSL.SRVPGM

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 16. 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
  Email	E
  IssuerEmail	IE

  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

See also SSLClientAuthRequire

LoadModule ibm_ssl_module /QSYS.LIB/QHTTPSVR.LIB/QZSRVSSL.SRVPGM

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.

See also SSLClientAuthGroup.

LoadModule ibm_ssl_module /QSYS.LIB/QHTTPSVR.LIB/QZSRVSSL.SRVPGM

The SSLClientAuthVerify directive is used together with “SSLClientAuth Optional Noverify” to provide a user friendly web page, instead of the default browser error message when client certificate 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.

Parameter statuscode: 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.

Parameter OFF: Ignore the client certificate failure and process the request normally.

By providing a custom error document for specific status code, 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.

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. See below as an example.

Example:

<VirtualHost *:443>
   SSLClientAuth Optional Noverify
   <Location />
      SSLClientAuthVerify 419
   </Location>
   ErrorDocument 419 /error419.html
    <Location /error419.html>
        SSLClientAuthVerify OFF
    </Location>
</VirtualHost>

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 SSLFallbackProtection directive enables/disables TLS_FALLBACK_SCSV. It allows the TLS_FALLBACK_SCSV pseudo cipher to be sent by HTTP Server for i. This helps browsers from being fooled into downgrading TLS versions.

ON (default)

Enable TLS_FALLBACK_SCSV

OFF

Disable TLS_FALLBACK_SCSV

The SSLHandshakeTimeout directive can be used to reduce the timeout for SSL handshake I/O operations. If set to 0 or not specified, the value of Core Timeout will be used.

<VirtualHost *:443>
   SSLEnable
   Timeout 60
   SSLHandshakeTimeout 20
</VirtualHost>

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 SSLProxyCipherSpec directive allows for specifying a cipher specification to be used for the SSL connection. Each occurrence of this directive will add the associated cipher specification to that context's existing cipher suite list. The cipher specification is used on the SSL handshake, which then uses the cipher suite list to negotiate the cipher used for communications between the proxy server and the content server.

The order of the SSLProxyCipherSpec 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 SSLProxyVersion directive during the SSL handshake. The values specified for the SSLProxyCipherSpec directive must correspond with the value specified on the SSLProxyVersion directive. If this directive is not used, a default cipher suite list is used.

Parameter: cipher-spec

• The cipher-spec parameter specifies the cipher specification to be used. Either the short name or the long name in the following table may be specified.

Table 18.

HEX	Short Name	Key Size	Long Name	SSLv3	TLSv10	TLSv11	TLSv12
0x01	31	0	TLS_RSA_WITH_NULL_MD5 (*)	X	X	X	X
0x02	32	0	TLS_RSA_WITH_NULL_SHA (*)	X	X	X	X
0x03	33	40	TLS_RSA_WITH_NULL_SHA (*)	X	X
0x04	34	128	TLS_RSA_WITH_RC4_128_MD5 (*)	X	X	X	X
0x05	35	128	TLS_RSA_WITH_RC4_128_SHA (*)	X	X	X	X
0x06	36	40	TLS_RSA_EXPORT_WITH_RC2_CBC_40_MD5 (*)	X	X
0x09	39	56	TLS_RSA_WITH_DES_CBC_SHA (*)	X	X	X	X
0x0A	3A	168	TLS_RSA_WITH_3DES_EDE_CBC_SHA (*)		X	X	X
0x2F	X2F	128	TLS_RSA_WITH_AES_128_CBC_SHA		X	X	X
0x35	X35	256	TLS_RSA_WITH_AES_256_CBC_SHA		X	X	X
0x3B	X3B	0	TLS_RSA_WITH_NULL_SHA256				X
0x3C	X3C	128	TLS_RSA_WITH_AES_128_CBC_SHA256				X
0x3D	X3D	256	TLS_RSA_WITH_AES_256_CBC_SHA256				X
0x9C	X9C	128	TLS_RSA_WITH_AES_128_GCM_SHA256				X
0x9D	X9D	256	TLS_RSA_WITH_AES_256_GCM_SHA384				X
0xC006	N/A	0	TLS_ECDHE_ECDSA_WITH_NULL_SHA				X
0xC007	N/A	128	TLS_ECDHE_ECDSA_WITH_RC4_128_SHA				X
0xC008	N/A	168	TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA				X
0xC010	N/A	0	TLS_ECDHE_RSA_WITH_NULL_SHA				X
0xC011	N/A	128	TLS_ECDHE_RSA_WITH_RC4_128_SHA				X
0xC012	N/A	168	TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA				X
0xC023	N/A	128	TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256				X
0xC024	N/A	256	TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384				X
0xC027	N/A	128	TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256				X
0xC028	N/A	256	TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384				X
0xC02B	N/A	128	TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256				X
0xC02C	N/A	256	TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384				X
0xC02F	N/A	128	TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256				X
0xC030	N/A	256	TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384				X

Note: (*) indicates the long name can also be named by starting with "SSL_" in order to be compatible with older releases.

Version 3 Ciphers:

Table 19.

Long Name	Short name
SSL_RSA_WITH_3DES_EDE_CBC_SHA / TLS_RSA_WITH_3DES_EDE_CBC_SHA	3A
SSL_RSA_WITH_RC4_128_SHA / TLS_RSA_WITH_RC4_128_SHA	35
SSL_RSA_WITH_RC4_128_MD5 / TLS_RSA_WITH_RC4_128_MD5	34
SSL_RSA_WITH_DES_CBC_SHA / TLS_RSA_WITH_DES_CBC_SHA	39
SSL_RSA_EXPORT_WITH_RC4_40_MD5 / TLS_RSA_EXPORT_WITH_RC4_40_MD5	33
SSL_RSA_EXPORT_WITH_RC2_CBC_40_MD5 / TLS_RSA_EXPORT_WITH_RC2_CBC_40_MD5	36
SSL_RSA_WITH_NULL_SHA / TLS_RSA_WITH_NULL_SHA	32
SSL_RSA_WITH_NULL_MD5 / TLS_RSA_WITH_NULL_MD5	31

Note: SSLV3 is disabled by default on i 7.2

TLS 1.0 Ciphers:

Table 20.

Long Name	Short name
SSL_RSA_WITH_3DES_EDE_CBC_SHA / TLS_RSA_WITH_3DES_EDE_CBC_SHA	3A
SSL_RSA_WITH_RC4_128_SHA / TLS_RSA_WITH_RC4_128_SHA	35
SSL_RSA_WITH_RC4_128_MD5 / TLS_RSA_WITH_RC4_128_MD5	34
SSL_RSA_WITH_DES_CBC_SHA / TLS_RSA_WITH_DES_CBC_SHA	39
SSL_RSA_EXPORT_WITH_RC4_40_MD5 / TLS_RSA_EXPORT_WITH_RC4_40_MD5	33
SSL_RSA_EXPORT_WITH_RC2_CBC_40_MD5 / TLS_RSA_EXPORT_WITH_RC2_CBC_40_MD5	36
SSL_RSA_WITH_NULL_SHA / TLS_RSA_WITH_NULL_SHA	32
SSL_RSA_WITH_NULL_MD5 / TLS_RSA_WITH_NULL_MD5	31
TLS_RSA_WITH_AES_128_CBC_SHA	X2F
TLS_RSA_WITH_AES_256_CBC_SHA	X35

TLS 1.1 Ciphers:

Table 21.

Long Name	Short name
SSL_RSA_WITH_3DES_EDE_CBC_SHA	3A
SSL_RSA_WITH_RC4_128_SHA / TLS_RSA_WITH_RC4_128_SHA	35
SSL_RSA_WITH_RC4_128_MD5 / TLS_RSA_WITH_RC4_128_MD5	34
SSL_RSA_WITH_DES_CBC_SHA / TLS_RSA_WITH_DES_CBC_SHA	39
SSL_RSA_WITH_NULL_SHA / TLS_RSA_WITH_NULL_SHA	32
SSL_RSA_WITH_NULL_MD5 / TLS_RSA_WITH_NULL_MD5	31
TLS_RSA_WITH_AES_128_CBC_SHA	X2F
TLS_RSA_WITH_AES_256_CBC_SHA	X35

TLS 1.2 Ciphers:

Table 22.

Long Name	Short name
SSL_RSA_WITH_3DES_EDE_CBC_SHA	3A
SSL_RSA_WITH_RC4_128_SHA / TLS_RSA_WITH_RC4_128_SHA	35
SSL_RSA_WITH_RC4_128_MD5 / TLS_RSA_WITH_RC4_128_MD5	34
SSL_RSA_WITH_NULL_SHA / TLS_RSA_WITH_NULL_SHA	32
SSL_RSA_WITH_NULL_MD5 / TLS_RSA_WITH_NULL_MD5	31
TLS_RSA_WITH_AES_128_CBC_SHA	X2F
TLS_RSA_WITH_AES_256_CBC_SHA	X35
TLS_RSA_WITH_NULL_SHA256	X3B
TLS_RSA_WITH_AES_128_CBC_SHA256	X3C
TLS_RSA_WITH_AES_256_CBC_SHA256	X3D
TLS_RSA_WITH_AES_128_GCM_SHA256	X9C
TLS_RSA_WITH_AES_256_GCM_SHA384	X9D
TLS_ECDHE_ECDSA_WITH_NULL_SHA	N/A
TLS_ECDHE_ECDSA_WITH_RC4_128_SHA	N/A
TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA	N/A
TLS_ECDHE_RSA_WITH_NULL_SHA	N/A
TLS_ECDHE_RSA_WITH_RC4_128_SHA	N/A
TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA	N/A
TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256	N/A
TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384	N/A
TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256	N/A
TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384	N/A
TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256	N/A
TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384	N/A
TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256	N/A
TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384	N/A

LoadModule ibm_ssl_module /QSYS.LIB/QHTTPSVR.LIB/QZSRVSSL.SRVPGM

The SSLProtocolDisable directive specifies one or more SSL protocols which cannot be used by the client for a specific virtual host. The specified protocol is disagreed to negotiate by the server.

The possible value for this directive is as following:

Example

<VirtualHost *:443>
   SSLEngine On 
   SSLProtocolDisable  SSLv2 SSLv3 
   (any other directives...) 
</VirtualHost>

LoadModule ibm_ssl_module /QSYS.LIB/QHTTPSVR.LIB/QZSRVSSL.SRVPGM

The SSLProxyProtocolDisable directive specifies one or more SSL protocols which cannot be used to negotiate between HTTP proxy server and the remote content server during the SSL handshake.

The possible value for this directive is as following:

Example

<VirtualHost *:443>
   SSLProxyEngine on 
   SSLProxyProtocolDisable  SSLv2 SSLv3 
   (any other directives...) 
</VirtualHost>

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:

The server will default to TLSV1.x indicating that the server will only accept TLS protocol that is negotiated due to the security vulnerability of SSLv2 and SSLv3.

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 SSLRenegotiation directive controls the types of TLS renegotiation permitted by HTTP Server for i. TLS renegotiation is how clients can initiate a new SSL handshake on an existing secure connection, which is rarely used by normal browser-based clients.

ON (default)

Secure renegotiation, as currently defined by RFC5746, is permitted.

OFF

No renegotiation is permitted.

The SSLServerCert directive sets the server certificate to use for the specific SSL enabled name based virtual host.

Server Name Indication(SNI) support has been added to HTTP Server for i. Specify this directive along with the ServerName directive to set the server certificate and fully qualified domain name(FQDN) for that specific virtual host if you have multiple SSL enabled name based virtual hosts are configured and want to have the SNI support.

If this directive is not specified, the default virtual host server certificate will be used for all SSL enabled name based virtual hosts.

Example:

<VirtualHost 10.1.2.3:443>
    SSLEngine On
    SSLAppName QIBM_HTTP_SERVER_APACHE1
    DocumentRoot /www/example1
    ServerName www.example1.com
    SSLServerCert QIBM_HTTP_SERVER_CERT1
</VirtualHost>

<VirtualHost 10.1.2.3:443>
    SSLEngine On
    SSLAppName QIBM_HTTP_SERVER_APACHE2
    DocumentRoot /www/example2
    ServerName www.example2.com
    SSLServerCert QIBM_HTTP_SERVER_CERT2
</VirtualHost>

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.

LoadModule ibm_ssl_module /QSYS.LIB/QHTTPSVR.LIB/QZSRVSSL.SRVPGM

The SSLUnknownRevocationStatus directive specifies how HTTP Server reacts when HTTP Server cannot readily determine the revocation status, which is coming through CRL or OCSP.

Parameter: ignore | log | log_always | deny

• The ignore parameter specifies that a debug level message is issued when a handshake completes and the revocation status is not known. This message is not re-issued when the SSL session is resumed.
• The log parameter specifies that a notice-level message is issued when a handshake completes and the revocation status is not known. This message is not re-issued when the SSL session is resumed.
• The log_always parameter specifies that a notice-level message is issued when a handshake completes and the revocation status is not known. HTTP Server issues the same message for subsequent handshakes.
• The deny parameter specifies that a notice-level message is issued when a handshake completes, the revocation status is not known, the session is not resumable, and the HTTPS connection is immediately closed. HTTP Server reports the same message for subsequent handshakes.

Whenever a message is logged for UnknownRevocationStatus, the SSL_UNKNOWNREVOCATION_SUBJECT variable, an internal SSL environment variable, is set. You can log this variable with the following syntax:

%{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}

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 TLSV1.x indicating that the server will only accept TLS protocol that is negotiated due to the security vulnerability of SSLv2 and SSLv3.

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.