Frontend connectors
The tag Connector specifies the port and the IP address on which the nevisProxy server is listening for incoming TCP connections. Several connectors with different ports may be configured here.
Apache IP-based virtual host
For every Connector tag found, the related Apache configuration for the respective IP-based virtual host is generated. From this point of view, each connector represents an IP-based Apache virtual host.
The Connector tag offers the following configuration attributes:
| Name | Type, usage constraints, defaults | Description |
|---|---|---|
| name | string required, basic connectivity, supports variable replacement default: DNS name of the machine | The attribute 'name' configures the DNS name of the machine. It must be the DNS name that the client resolves. If the attribute 'listen' is not configured nevisProxy is listening on the associated IP address. |
| port | integer required, basic connectivity, supports variable replacement | The attribute 'port' configures the port. It must be the port through which the client is connecting. If the attribute 'listen' is not connected, nevisProxy listens for incoming TCP connections using this port (the one connecting the client). |
| listen | string optional, advanced supports variable replacement | The attribute 'listen' configures the IP address and the port on which nevisProxy is listening. The format is: <ip-address>:<port>. It must only be configured if the IP address or the port of the client connection differs from the settings that are specified by 'name' and/or 'port' (i.e. in case a load balancer is using a different port than nevisProxy). |
| nameVirtualHost | String optional, advancedsupports variable replacement | The 'nameVirtual' attribute may be used instead of the 'listen' attribute if you are configuring name based virtual hosts, where multiple connectors are listening on the same IP address and port. In such a setup, only one of these connectors must use the 'listen' attribute, while all the other connectors use the 'nameVirtualHost' attribute instead. |
Refer to the section Configuring a setup with a load balancer for a detailed sample that clarifies the differences between these attributes.
How to set up a name-based host
The first connector of a name-based group, whereas the group identifier is <ip>:<port> and in this case 1.2.3.4:443 defines the listener.
<Connector
name="the.prime.com"
port="443"
listen="1.2.3.4:443">
...
</Connector>
The additional names no longer set up another listener, because it prevented navajo from starting since the latter can only listen once to a given <ip>:<port>. The recommended configuration is to use "nameVirtualHost" instead of "listen", which omits the listener directive for apache.
<Connector
name="the.second.com"
port="443"
nameVirtualHost="1.2.3.4:443">
...
</Connector>
<Connector
name="the.third.com"
port="443"
nameVirtualHost="1.2.3.4:443">
...
</Connector>
To have separated web.xml for the different names you have to add the following configuration into the "Engine" tag.
<Host name="the.prime.com">
<Context
docBase="/var/opt/nevisproxy/mytest/prime"
entryURI="/"
filePreload="false"
path=""
trailingSlashRedirect="true"
unsecureConnection="allow"
/>
</Host>
<Host name="the.second.com">
<Context
docBase="/var/opt/nevisproxy/mytest/second"
entryURI="/"
filePreload="false"
path=""
trailingSlashRedirect="true"
unsecureConnection="allow"
/>
</Host>
<Host name="the.third.com">
<Context
docBase="/var/opt/nevisproxy/mytest/third"
entryURI="/"
filePreload="false"
path=""
trailingSlashRedirect="true"
unsecureConnection="allow"
/>
</Host>
TLS Configuration
An SSL tag inside a Connector tag enables/enforces the related TLS configuration for the respective connector. The system uses the configuration attributes in the SSL tag to generate the mod_ssl attribute with the same name as the respective IP-based host. See http://httpd.apache.org/docs/2.2/mod/mod_ssl.html/` for a more detailed description of these attributes. The following table lists all configuration attributes of the SSL tag:
All attribute listed here support variable replacement.
| Name | Type, Usage Constraints, Defaults | Description |
|---|---|---|
| SSLCACertificateFile | string optional, basic connectivitydefault: <spool_dir>/keystore/public/peerverify.pem | The attribute ‘SSLCACertificateFile’ configures the accepted CA certificates used during the TLS handshake (if a client certificate is required). It is a bundle of CAs, including all of the signing superordinate CAs.Suggested value using nevisKeybox (slot ‘public’ and label ‘peer’):/var/spool/keybox/public/peer_truststore.pem |
| SSLCertificateChainFile | string optional, advanced default: not set | The attribute ‘SSLCertificateChainFile’ configures the file that is a concatenation of the certificate chain of the server certificate (excluding the server certificate itself). It is sent to the client and allows trust-verification even though the client has only the top trust-anchors to the certificate database. |
| SSLCertificateFile | string optional, basic connectivitydefault: <spool_dir>/keystore/public/nodeauth.pem | The attribute ‘SSLCertificateFile’ configures the certificate file used by nevisProxy for identification with HTTP clients during the TLS handshake. If SSLCertificateKeyFile is not set, this file also needs to contain the private key nevisProxy is using for server authentication. It is recommended that this file only contain the certificate without private key. Suggested value using nevisKeybox (slot ‘public’):/var/spool/keybox/public/node_keystore.pem |
| SSLCertificateKeyFile | string optional, advanced default: not set | The attribute ‘SSLCertificateKeyFile’ configures the private key file used by nevisProxy during the TLS handshake. Usually, the key is stored along with the certificate (see ‘SSLCertificateFile’). |
| SSLCipherSuite | string optional, advanced default: ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-SHA384:DHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES256-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-SHA256:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES128-SHA256:!aNULL:!eNULL:!LOW:!3DES:!MD5:!EXP:!PSK:!SRP:!DSS | The attribute SSLCipherSuite configures the allowed SSL cipher suites for a connector. The default cipher suite reflects AdNovum’s current recommendation for best client compatibility and highest possible security. If this attribute is configured, its value should be questioned periodically by the security officer.F If RSA is used for key exchange, there might be a vulnerability to the Bleichenbacher attack (http://robotattack.org/). Use the following tool to test your overall SSL configuration and the Bleichenbacher attack:<http://testssl.sh/>.To prevent attackers from exploiting this vulnerability in any way, disable the RSA key exchange from the affected client SSL profile. You do this by adding the expression "!RSA" to the SSL profile. However, note that disabling RSA from the SSL profile may affect clients that do not support newer alternatives for key exchange (e.g., DHE, ECDHE). Such legacy clients include, but are not limited to, Microsoft Internet Explorer 6 on any platform, Microsoft Internet Explorer 8 on Windows XP, and potentially non-browser user agents, such as embedded clients. |
| SSLOptions | string optional, advanced default: +OptRenegotiate | The attribute SSLOptions configures additional options during the TLS/SSL handshake. The option "+OptRenegotiate" must be set for proper TSL/SSL session management. See the mod_ssl documentation for other SSLOptions values. |
| SSLProtocol | string optional, advanced default: -all +TLSv1.2 | The attribute SSLProtocol configures the TLS/SSL protocol for the respective connector. Supported are:TLSv1.3 (only supported for OpenSSL 1.1.1, el7 package)TLSv1.2 (best option)TLSv1.1TLSv1SSLv3 (not recommended)SSLv2 (not recommended)Note: +SSLv3 +TLSv1.2 is equivalent to all -SSLv2.Note: SSLv3 is deprecated and may no longer be supported in one of the next releases.NoteSupport of TLSv1.3 is experimental. |
| SSLRequire | string optional, advanced default: not set | Deprecated This parameter has been deprecated by Apache. To block clients with a "wrong" certificate, use the LuaFilter instead. For more information, see the chapter Block clients with a wrong DN by using the LuaFilter.The attribute SSLRequire allows filter requests by certificate content. For syntax and details, refer to the mod_ssl documentation. |
| SSLVerifyClient | string optional, advanced default: not set | The mod_ssl default of "none" does not request a client certificate during the TLS handshake. For details, refer to the mod_ssl documentation.NoteClient certificates do not work with HTTP/2 or TLSv1.3.If you intent to set up an authentication by client certificate, use TLSv1.2. |
| SSLVerifyDepth | integer optional, advanced default: not set | The attribute SSLVerifyDepth configures the verify depth for client certificates. The mod_ssl default of "1" means, that the certificate of the signer of the client certificate must itself be trusted. For details, refer to the mod_ssl documentation. |
| SSLCACertificatePath | string optional, advanced default: not set | The attribute SSLCACertificatePath permits configuration of a directory where all certificate files are located. However, we do not recommend using this attribute. Use SSLCACertificateFile instead. |
| SSLRenegBufferSize | integer optional, advanced default: 131072 | If an TLS renegotiation is required in per-location context, then any HTTP request body must be buffered into memory until the new TLS handshake can be performed. This directive can be used to set the amount of memory that will be used for this buffer. The value defined is in bytes. |
| SSLInsecureRenegotiation | on, off optional, advanced default: off | As originally specified, all versions of the SSL and TLS protocols (up to and including TLS/1.2) were vulnerable to a Man-in-the-Middle attack (CVE-2009-3555) during a renegotiation. This vulnerability allowed an attacker to "prefix" a chosen plaintext to the HTTP request as seen by the web server. A protocol extension (RFC 5746) was developed which fixed this vulnerability if supported by both client and server. By default renegotiation is only supported with clients supporting the new protocol extension. If this directive is enabled, renegotiation will be allowed with old (unpatched) clients, albeit insecurely. |
| SSLHonorCipherOrder | on, off optional, advanced default: off | The attribute SSLHonorCipherOrder configures that clients prefer the server's cipher preference order. |
| SSLCompression | on, off optional, advanced default: off | This attribute allows enabling compression on TLS level.Important: Enabling compression causes security issues in most setups (the so-called CRIME attack). |
| SSLDHParametersFile | string optional, advanced | This attribute allows you to supply unique Diffie-Hellman parameters via a file. You can for example use the OpenSSL command "openssl dhparam 2048 > dhparam2048.pem" to generate parameters with 2048 bits. If this attribute is specified and parameters are found in the supplied file, the system will apply these parameters whenever DHE is in use to negotiate the pre-master secret. If this attribute is not set, everything works like it does now. That is, OpenSSL will ask mod_ssl for a set of parameters of the desired size . |
| SSLSessionTickets | on, off;optional default: off | This attribute allows to enable or disable the use of TLS session tickets (RFC 5077). The default is "off". Note that perfect forward secrecy (PFS) is compromised if you set this parameter to "on" without restarting the web server with an appropriate frequency (e.g. daily). |
| SSLCryptoDevice | string optional, advanced | This attribute enables the use of a cryptographic hardware accelerator board, to offload some of the TSL processing overhead. See also https://httpd.apache.org/docs/2.4/mod/mod_ssl.html#sslcryptodevice. In order for the system to find the device, the environment variable OPENSSL_ENGINES must be set in the file env.conf. The variable should point to the directory where the engine is located (the engine should be delivered by the HSM provider). For example OPENSSL_ENGINES=/usr/lib64/openssl/enginesNote that the value of the attributes SSLCertificateFile and SSLCertificateKeyFile depends on the vendor of the device.This attribute is only supported for Apache2.4 within nevisProxy. |
The system writes the attribute values found in the Connector tag and in the SSL tag to the hostTemplate file used to generate the respective IP-based host part of the Apache configuration file. Attribute values are not checked here. The check is done by the Apache web server and mod_ssl.
In the chapters that follow, HTTPSConnector will be used for TLS-enabled connectors and HTTPConnector for non-TLS-enabled connectors. The SSLRandomSeed child node may contain a list of the Apache SSLRandomSeed directives. Alternatively, you may configure the sources for seeding the random generator within the OpenSSL configuration file globally for all instances on your server.
[SSLRandomSeed]
SSLRandomSeed.0=file:/dev/random
SSLRandomSeed.1=file:/dev/urandom
TLS Cache Configuration
The TLS cache basically performs the following two tasks:
- It improves the performance of clients that support TLS session resumption.
- It enables client identification based on TLS sessions.
A local, in-memory TLS cache is configured with the SSLCache tag, and may only be used for the HTTPS Connector. The following attributes may be specified:
| Name | Type, Usage Constraints, Defaults | Description |
|---|---|---|
| maxEntries | integer optional, scaling default: 4000 | The attribute ‘maxEntries’ configures the maximum number of TLS sessions that can be stored at any given time. The sum of this value and the entry size of all other client association caches (i.e., the client cookie cache) should at least twice the size of the virtual hosts’ HTTP session caches (see chapters: Cookie Cache Configuration. |
| maxEntrySize | integer optional, scaling default: 150 | The attribute ‘maxEntrySize’ configures the maximum size of one TLS session in bytes. If client certificates are used, this value has to be increased (to e.g. 1500). |
| maxInactiveInterval | integer optional, advanced scaling default: 300 | The attribute ‘maxInactiveInterval’ configures the inactivity interval, in seconds, that when elapsed removes the TLS session. A client that has not authenticated within this period will need to do a full TLS negotiation after this inactivity timeout. The timeout is raised after authentication to the session timeout values required by the various components (see HttpSession maxInactiveInterval) |
| maxLifetime | integer optional, securitydefault: 3600 | The attribute ‘maxLifetime’ configures the maximum lifetime of an TLS session in seconds. After that time, the TLS session is removed.maxLifetime limits the amount of time during which an existing TLS session can be attacked. Therefore, this attribute is security relevant. If the remaining time-to-live is underlimiting the configured maxInactiveInterval, an TLS rehandshaking will be enforced. Note that possible client compatibility problems may arise (old or buggy SSL/TLS implementations used). |
| renegotiation | boolean: true, false optional, advanced securitydefault: false | The attribute ’renegotiation’ configures handling of TLS renegotiation. If set to true, the TLS cache allows the tracking of TLS sessions that have changed due to renegotiation. |
Cookie Cache Configuration
Fading out
Cookie caches are an element of the Container Session Handling. The Container Session Handling is replaced by the Dynamic Session Engine and therefore in the process of being faded out. Accordingly, cookie caches are also fading out. Do not use the Container Session Handling, including cookie caches, anymore. Instead, switch to the Dynamic Session Engine. For more information on the Dynamic Session Engine, see the chapter Dynamic Session Management Engine.
The cookie cache is used for client identification based on HTTP cookies. It may be configured for both the HTTPSConnector and the HTTPConnector. It is only required for cookie-based client identification (see the chapter Client Identification.
A local in-memory cookie cache is configured with the CookieCache tag, which has the following configuration, attributes:
| Name | Type, Usage Constraints, Defaults | Description |
|---|---|---|
| checkIP | boolean optional, security/troubleshooting default: true | The attribute ’checkIP’ configures the check of the IP address of the cookie sender. If set to true, the IP address of the cookie sender must match the IP address of the cookie receiver. |
| cookieName | string optional, advanced default: Navajo | The attribute ’cookieName’ is used to specify the name of the cookie. If nevisProxy instances are cascaded, the cookie name may need to be changed. If it is not changed, the cookie tracking mechanism might not work with all instances that require session tracking of individual sessions. The parameter may optionally define a path and domain using the following syntax:<cookieName>[:<path>[:<domain>]] |
| domain | string optional, advanced default: no domain specified | The attribute ’domain’ supports configuration of a domain to be included in the Set-Cookie header. ’domain’ may only be used if the CookieCache is defined within the Engine block (see the chapter Sharing HTTP sessions between connectors. * A super-domain of all the hosts that are defined. The super-domain must start with a ’.’ (dot), e.g. .adnovum.ch. For example, to share the session cookie between the domains 'intern.foo.com' and 'extern.foo.com', configure the CookieCache in the Engine block containing the two hosts and set domain to '.foo.com': |
<Engine defaultHost="extern.foo.com" > <CookieCache domain=".foo.com" ... /> <Host name="intern.foo.com"> ... </Host> <Host name="extern.foo.com"> ... </Host> </Engine>
| Name | Type, Usage Constraints, Defaults | Description |
|---|---|---|
| persistent | boolean optional, advanced default: false | If the attribute ’persistent’ is set to ’true’, the 'Expires' and 'Max-Age' directives will be set for the session cookie. In other words, the session cookie will live until ’maxLifetime’ (see below) even if the browser is shut down and restarted during that time. |
| maxEntries | integer optional, scaling default: 4000 | The attribute ‘maxEntries’ configures the maximum number of HTTP cookies that can be stored at any given time. The sum of this value and the entry size of all other client association caches (i.e. the TLS session cache) should at least twice the size of the virtual hosts’ HTTP session caches (see chapters: TLS Cache Configuration |
| maxLifetime | integer optional, securitydefault: 1800 | The attribute ‘maxLifetime’ configures the maximum lifetime of an HTTP cookie in seconds. After that time, the HTTP cookie is removed. The maxLifetime limits the amount of time during which an HTTP cookie can be attacked. Therefore, this attribute is security-relevant. To ensure that the cookie is really discarded after ’MaxLifetime’, both the ’max-age’ and the ’expires’ attribute of the cookie are set. The value of this parameter is sent to the client (in most cases) to signal when the cookie should be discarded. (Exception: Mozilla6-based browsers will store secure cookies in the cookie file.)If the remaining time-to-live underruns the current inactivity interval of the associated HTTP session, a new cookie is sent to the client. |
| maxInactiveInterval | integer optional, advanced default: 300 | The attribute ‘maxInactiveInterval’ configures the inactivity interval in seconds after which the cookie will be removed. A client that has not authenticated within this period, will receive a new cookie after this inactivity timeout and possible pending authentication procedures will start over. The timeout is raised after authentication to the session timeout values required by the various components (see HttpSession maxInactiveInterval) |
| randomSize | integer optional, advanced default: 56 | The attribute ‘cookieSize’ configures the number of pure random bytes that will be used as a HTTP cookie. For security reasons, this value should not be lower than 56. |
| signerCert | string optional, advanced default: not set | The attribute ’signerCert’ configures the certificate that will be used for checking the signature of the cookie sent by the client. The signature distinguishes timed-out from forged cookies and is used to detect brute-force attacks on the cookie. |
| signerKey | string optional, advanced default: not set | The attribute ’signerKey’ configures the private key that will be used for signing the cookie sent to the client |
| secretKeyFile | string optional default: not set | Defines a key store which enables encryption of the Navajo session cookie. |
UserAgent
The UserAgent section enables configuration of client-specific policies, e.g., client-specific policies for session tracking.
| Name | Type, Usage Constraints, Defaults | Description |
|---|---|---|
| header | string optional, advanced supports variable replacement default: User-Agent | The attribute header configures the name of the HTTP header, whose value will be matched against the configured 'pattern'. |
| pattern | string required, supports variable replacement | The attribute pattern configures a regular expression. If it matches the value of the respective HTTP header, the configured mechanism will be used for session tracking. |
| identification | enum: SSL, cookie, cookie-IP, both, both-required, combined (deprecated), noneoptional, security supports variable replacement | The attribute identification configures the mechanism used for session tracking. The recommended value for most installations is "cookie". Depending on the configured value, the following items have to match: SSL: TLS/SSL session; cookie: session cookie; cookie-IP: session cookie and client IP; both: TLS/SSL session or session cookie; both-required: SSLSession and session cookie; combined(deprecated): session cookie and either the TLS/SSL session or the client IP; none: no client identification See also the chapter Lock a session cookie to the user's IP address about advanced techniques to protect the session cookie. TLS identification will only work in a limited way if HTTP/2 is enabled. Take into account the following points (the list is not complete): 1: For TLS identification to work, nevisProxy relies on features that have been removed from HTTP/2 and TLSv1.3, especially TLS renegotiation. TLS renegotiation does not work with HTTP/2 or TLSv1.3. 2: Therefore, to make TLS identification work with HTTP/2 or with TLSv1.3, disable renegotiation on login and logout. You do this by disabling the parameters RenewIdentification and RenegotiateSSLOnLogout of the IdentityCreationFilter. This may slightly lower the security. 3: TLS resumption and hence TLS identification does not work when moving from an HTTP/1.1 to an HTTP/2 connection. If a connection changes between HTTP/1.1 and HTTP/2, it will not be resumed. Instead, a new session is created. Therefore, TLS identification will not work. In all cases, the customer will have to log in again. Generally, we recommend that you avoid using TLS identification with HTTP/2 or TLSv1.3. |
| identificationAction | enum: invalidate, reauth optional, security default: invalidate | Defines which action is taken when the client identification partially fails (this means that the session could be identified but some requirements were not matched). The following values can be configured:invalidate: the session is invalidated reauth: the session can be reauthenticated with a IdentityCreationFilter ). |
| sslshutdown | enum: none, unclean, clean, accurate optional, troubleshooting default: clean | Clients with a problematic TLS implementation may have troubles with the clean TLS shut-down (that is, an TLS shut-down message is sent by both peers before the TCP connection closes).none: let mod_ssl perform the handle the shut-downunclean: Close the socket without TLS shut-downclean: Send TLS shut-down and close the socketaccurate: clean, but wait for TLS shut-down message from client before closing the socket |
| keepAlive | boolean optional, scaling/troubleshooting default: true | To keep the server's KeepAlive="on" setting and disable HTTP keep-alive for specific client types "), set this attribute to 'false'. |
| cookieType | string: simple (deprecated), rfc2109 (deprecated), rfc6265, netscape (deprecated) optional, troubleshooting default: rfc6265 | Deprecated This parameter is deprecated. Instead, RFC 6265 will be used. This attribute is used to send specification-conformant cookies to clients, which otherwise have problems handling old style cookies. |
| cookieHttpOnly | string requiredsupports variable replacement default: true | The attribute cookieHttpOnly configures whether the attribute HttpOnly should be added to the cookies sent to the client. This attribute also configures whether the identification cookie set by the container-based session management engine (that is, the "Navajo cookie") will contain the HttpOnly flag. This attribute can take the following configuration values:"true": TheHttpOnlyattribute will be added to the cookies if it is missing, and it will be set for the "Navajo cookie"; "false": All the cookies will be left unchanged (that is, the HttpOnly attribute is neither added nor removed), and the "Navajo cookie" will not contain the HttpOnly attribute; List of cookie names: All the cookies will be left unchanged (that is, theHttpOnlyattribute is neither added nor removed) except for the cookies with the configured names. For those cookies theHttpOnlyattribute will be set. The cookie set by nevisProxy for the contained-based session management (the "Navajo cookie") will contain theHttpOnlyflag. The cookie names must match exactly (no regular expression involved). Choose an unlikely cookie name like "" or "neverusedcookiename321" tonot match any cookie. We suggest setting this attribute to "false" when using the dynamic session management engine. In this configuration, the attribute HttpOnly of the session cookie is set by the parameter Cookie.HttpOnly of the SessionManagementFilter. If required, you can overwrite the attribute HttpOnly of other cookies with a LuaFilter or a RewriteFilter. |
Session tracking can be configured per browser type in specific UserAgent sections ('type') or in the ClientIdentification section (fallback). The first matching user-agent tag is used for determining the session tracking mechanism.
Consider the following sample configuration:
<UserAgent
header="User-Agent"
pattern="^My.Agent.$"
identification="SSL"
/>
<ClientIdentification
type="cookie"
/>
The above configuration configures the following client identification behavior:
- If the client (UserAgent) matches the pattern "^My.Agent.$", then the TLS session will be used for session tracking.
- For all other clients, the cookie s has to match (default/fallback).
Client Identification
The client identification mechanism is configured via the following attributes in the client-identification tag. It is acting as a fallback if no UserAgent tag matches:
| Name | Type, Usage Constraints, Defaults | Description |
|---|---|---|
| type | enum: SSL, cookie, cookie-IP, both, both-required, none, consumedHeader (deprecated) | The attribute type defines the mechanism used for client identification. The recommended value for most installations is "cookie". For a description of the values "SSL", "cookie", "cookie-IP", "both", "both-required", and "none" see the attribute identification in the chapter/section UserAgent and the ConsumedIdentCache. |
| consumedHeader | String optional, advanced default: isiwebsessid | Deprecated This parameter is deprecated and will be removed in a future release. The attribute consumedHeader specifies the HTTP header to use, if nevisProxy comes behind another reverse proxy and needs to associate its session with the passed header. In this case, set the type parameter to "consumedHeader" (see above). |
If the client identification (or session tracking) mechanism policy configured with the ClientIdentification element is too general, use user-agent based policies (see the section UserAgent.
Sharing HTTP sessions between connectors
In most setups there is one TLS enabled Connector, with an SSLCache configured as described. In the case that there is more the one TLS-enabled connector, there are two possibilities:
- Every Connector has its own SSLCache configured.
- There is one SSLCache configured in the Engine.
The same applies for the CookieCache.