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>

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

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. The SSLCertificateChainFile is deprecated. Use the SSLCertificateFile Apache directive.
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-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	Syntax: SSLCipherSuite [protocol] cipher-spec. 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 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.
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 options are: TLSv1.3 TLSv1.2 TLSv1.1 TLSv1
SSLRequire	string optional, advanced default: not set	Deprecated This parameter is 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, see RFC-8740. They are experimental when using TLSv1.3 due to lack of client/browser support.
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: on	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.

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.