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: String
Usage Constraints: 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

Type: Integer
Usage Constraints: 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

Type: String
Usage Constraints: optional, 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

Type: String
Usage Constraints: optional, advanced, supports variable replacement

The 'nameVirtualHost' 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

Type: String
Usage Constraints: optional

The attribute serverAlias defines alternate names for a specific host when matching requests to name-virtual hosts.

AllowEncodedSlashes

Type: Enum: On, Off, NoDecode
Usage Constraints: optional
Default: Off

The AllowEncodedSlashes directive allows URLs which contain encoded path separators (%2F).

With the default value, Off, such URLs are refused with a 404 (Not found) error.

With the value On, such URLs are accepted, and encoded slashes are decoded like all other encoded characters.

With the value NoDecode, such URLs are accepted, but encoded slashes are not decoded but left in their encoded state.

If set to NoDecode, the HttpConnectorServlet and the BackendConnectorServlet will not encode again the already encoded slashes.

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>

How to set up a name-based host with wildcard address

Instead of the <ip>:<port> identifiers, it is possible to use a wildcard *:<port>.

The previous example configuration using wildcards:

<Connector
 name="the.prime.com"
 port="443"
 listen="*:443">
 ...
</Connector>

The same rule applies here as well, only one listener can be defined. Instead of the listen directive, use nameVirtualHost:

<Connector
 name="the.second.com"
 port="443"
 nameVirtualHost="*:443">
 ...
</Connector>

<Connector
 name="the.third.com"
 port="443"
 nameVirtualHost="*:443">
 ...
</Connector>

TLS configuration

The optional 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. This section presents all configuration attributes of the SSL tag. See Apache Module mod_ssl for a more detailed description of these attributes.

All attributes listed here support variable replacement.

SSLCACertificateFile

Type: string
Usage Constraints: 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

Type: string
Usage Constraints: 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. The SSLCertificateChainFile is deprecated. Use the SSLCertificateFile Apache directive.

SSLCertificateFile

Type: string
Usage Constraints: 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

Type: string
Usage Constraints: optional, advanced
Default: not set

The attribute SSLCertificateKeyFile configures the private key file used by nevisProxy during the TLS handshake. The key maybe also be stored along with the certificate (see SSLCertificateFile).

SSLCipherSuite

Type: string
Usage Constraints: optional, advanced
Syntax: SSLCipherSuite [protocol] cipher-spec
Default: 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

The attribute SSLCipherSuite configures the allowed SSL cipher suites for a connector. See the apache documentation (https://httpd.apache.org/docs/2.4/mod/mod_ssl.html#sslciphersuite) for possible values for the protocol and the cipher-spec. 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 (https://robotattack.org). Use the following tool to test your overall SSL configuration and the Bleichenbacher attack: https://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.

SSLOptions

Type: string
Usage Constraints: 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

Type: string, list of enabled (+) or disabled (-) protocols
Syntax: [+|-]protocol
Supported protocols: TLSv1.3, TLSv1.2, TLSv1.1, TLSv1
Usage Constraints: optional, advanced
Default: -all +TLSv1.2 +TLSv1.3

The attribute SSLProtocol configures the TLS/SSL protocols for the respective connector.

SSLVerifyClient

Type: string
Usage Constraints: 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 are experimental with HTTP/2, and SSLVerifyClient must be configured at the Connector level, because HTTP/2 forbids TLS renegotiation once the server started reading the request, see RFC-9113. They are experimental when using TLSv1.3 due to lack of client/browser support.

SSLVerifyDepth

Type: integer
Usage Constraints: 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

Type: string
Usage Constraints: 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

Type: integer [bytes]
Usage Constraints: 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.

SSLInsecureRenegotiation

Type: enum
Possible values: on, off
Usage Constraints: 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

Type: enum
Possible values: on, off
Usage Constraints: optional, advanced
Default: on

The attribute SSLHonorCipherOrder configures that clients prefer the server's cipher preference order.

SSLCompression

Type: enum
Possible values: on, off
Usage Constraints: 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).

SSLSessionTickets

Type: enum
Possible values: on, off
Usage Constraints: optional
default: off

This attribute allows to enable or disable the use of TLS session tickets (RFC 5077). 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

Type: string
Usage Constraints: 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/engines

Note that the value of the attributes SSLCertificateFile and SSLCertificateKeyFile depends on the vendor of the device.

SSLSessionCacheTimeout

Type: integer [s]
Usage Constraints: 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.

Generation of the Apache httpd configuration

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 during this generation process. The check is done by the Apache web server and mod_ssl.

Configuring SSLCipherSuites per Protocol

You can configure different SSLCipherSuites per protocol by using the SSLCipherSuite element for example like that:

            <SSL
                SSLCACertificateFile=""
                SSLCACertificatePath=""
                SSLCertificateFile="mycert.pem"
                SSLCertificateKeyFile=""
                SSLCipherSuite="ECDHE-RSA-CHACHA20-POLY1305"
                SSLOptions="+OptRenegotiate"
                SSLProtocol="-all +TLSv1.2 +TLSv1.3"
            >
            <SSLCipherSuite value="TLSv1.3 TLS_AES_256_GCM_SHA384"/>
            <SSLCipherSuite value="SSL DHE-RSA-AES128-GCM-SHA256"/>
            </SSL>

With this configuration, for the TLSv1.3 protocol the cipher TLS_AES_256_GCM_SHA384 and for TLSv1.2 and below the DHE-RSA-AES128-GCM-SHA256 cipher.

HTTP/2 configuration

nevisProxy accepts incoming requests using the protocol HTTP/1.1 by default. Each connector can be configured to process requests using HTTP/2 and/or HTTP/1.1 by adding the tag <H2> in the <Connector> tag, for example:

<H2
  H2Direct="on"
  Protocols="h2 h2c http/1.1"
/>

Client certificates and HTTP/2

Support of client certificates is experimental with HTTP/2. See SSLVerifyClient and IdentityCreationFilter's ClientCert for details.

Some HTTP/2 features are provided outside of the <H2> tag, see Server Push and Early Hints.

The tag <H2> provides the following attributes:

H2Direct

Type: Type: Enum
Possible values: on, off
Usage Constraints: optional
Default: not set, that is on for h2c, off for h2 protocol

This directive toggles the usage of the HTTP/2 Direct Mode. Direct communication means that if the first bytes received by the server on a connection match the HTTP/2 preamble, the HTTP/2 protocol is switched to immediately without further negotiation. This mode is defined in RFC 7540 for the cleartext (h2c) case. Its use on TLS connections not mandated by the standard.

For clients that have out-of-band knowledge about a server supporting h2c, direct HTTP/2 saves the client from having to perform an HTTP/1.1 upgrade, resulting in better performance and avoiding the Upgrade restrictions on request bodies.

Protocols

Type: String, space-separated list of protocols
Possible values: h2 (HTTP/2 over TLS), h2c (HTTP/2 over TCP), http/1.1
Usage Constraints: optional
Default: h2 h2c http/1.1

This directive specifies the list of protocols supported by the connector. The list determines the allowed protocols a client may negotiate for this connector.