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. |
| serverAlias | string optional | The attribute serverAlias defines alternate names for a specific host when matching requests to name-virtual hosts. |
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 connectivity | 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 required, basic connectivity | 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:!kRSA | The attribute SSLCipherSuite configures the allowed SSL cipher suites for a connector. The default cipher suite reflects Nevis’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. 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 can affect clients that do not support newer alternatives for key exchange (for example, 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. An SSL renegotiation with an outdated SSL cipher suite can take up seconds. It is therefore recommended using the default value for the SSLCipherSuite attribute. The default value reflects Nevis’s current recommendation for best client compatibility and highest possible security.recommended valueThe recommended value is: ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-CHACHA20-POLY1305:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES256-GCM-SHA384:DHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES128-GCM-SHA256:DHE-RSA-AES128-GCM-SHA256(warning) Note that some browsers may not support this value yet. |
| 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 +TLSv1.3 | The attribute SSLProtocol configures the TLS/SSL protocol for the respective connector. Supported are:TLSv1.3 (best option, only supported for OpenSSL 1.1.1, el7 package)TLSv1.2TLSv1.1TLSv1SSLv3 (not recommended)SSLv2 (not recommended)Note: +SSLv3 +TLSv1.2 is equivalent to all -SSLv2.(error) SSLv3 is deprecated and may no longer be supported in one of the next releases. |
| 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 Frontend connectors. 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. Client certificates do not work with HTTP/2. They are experimental when using TLSv1.3. |
| 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 | 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 (512 or 1024 bits). A 2048-bit file is generated automatically when starting the proxy server (conf/dhparams2048.pem).This attribute is not compatible with Apache httpd/2.4. For Apache httpd/2.4, check the chapter Default DH parameters with Apache httpd/2.4. |
| 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. |
| SSLSessionCacheTimeout | integer optional default: 300 | This attribute sets the timeout in seconds for the information stored in the global/inter-process SSL Session Cache, the OpenSSL internal memory cache and for sessions resumed by TLS session resumption (RFC 5077). You can set it as low as "15" sec for testing, but set it to higher values, like "300", in real life. If you use an own SSLCache or RemoteSSLCache, the system ignores the SSLSessionCacheTimeout parameter. |
The system writes the attribute values found in the Connector tag and in the SSL tag to the hostTemplate file (see the chapter Service 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.
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, security default: 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. |
User agent
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, and the value is 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 is used for session tracking. |
| identification | enum: SSL, cookie, cookie-IP, both, both-required, none optional, security supports variable replacement | Deprecated Container Session Handling is deprecated. 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 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 only works in a limited way if HTTP/2 is enabled. Take into account the following points (the list is not complete): For TLS identification to work, nevisProxy relies on features removed from HTTP/2 and TLSv1.3, especially TLS renegotiation. TLS renegotiation does not work with HTTP/2 or TLSv1.3. 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 lower security. * 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 is not resumed. Instead, a new session is created. Therefore, TLS identification does not work. In all cases, the customer has 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-down; unclean: Close the socket without TLS shut-down; clean: Send TLS shut-down and close the socket; accurate: 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'. |
| 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
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 in the client-identification tag. It is acting as a fallback if no UserAgent tag matches.
Currently, the client-identification tag contains the following attributes:
| Name | Type, Usage Constraints, Defaults | Description |
|---|---|---|
| type | enum: SSL, cookie, cookie-IP, both, both-required, none | 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. |
If you find the client identification (or session tracking) mechanism policy configured with the client-identification tag too general, you can use user-agent based policies instead (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.