HttpsConnectorServlet

You can use all configuration attributes of the HttpConnectorServlet for the HttpsConnectorServlet as well. The additional TLS attributes must be configured.

Classname

ch::nevis::isiweb4::servlet::connector::http::HttpsConnectorServlet

Library

libHttpConnectorServlet.so.1

Configuration

SSLCACertificateFile

Type: string
Usage Constraint: optional, basic connectivity

Specifies the file containing the CA certificate(s) that are used to check whether the peer’s node certificate is trusted. All the certificates in the file will be verified. PEM encoded files are supported. Nevis PKCS#11 URLs are not supported. If the SSLCACertificateFile attribute is not specified, the peer certificate will be trusted automatically. Mandatory to set if SSLCheckPeerHostname is enabled.

SSLClientCertificateFile

Type: string
Usage Constraint: optional, basic connectivity

The X509 node certificate or certificate chain that is sent to the application server if requested by a SSL/TLS CertificateRequest message. PEM encoded files are supported for node certificates and certificate chains, and Nevis PKCS#11 URLs are supported for node certificates.

If the file contains a certificate chain then the certificates must be in PEM format and must be sorted starting with the subject's certificate (actual client or server certificate), followed by intermediate CA certificates if applicable, and ending at the highest level (root) CA.

In case of a pkcs#11 based HSM (f.ex. Securosys) you can extract the certificate in PEM format via a command similar to this:

/opt/nevisproxy/bin/openssl storeutl -engine /opt/nevisproxy/lib/libnevisproxypkcs11engine.so 'pkcs11:library=/usr/local/primus/lib/libprimusP11.so&dologin=true&objectlabel=proxy.cert&type=cert&pinenv=PKCS11_PIN'

If you specify a certificate chain for an pkcs#11 based HSM then the pkcs#11 URL has to be specified in the parameter SSLClientKeyFile.

For more information on how to use the GemEngine within the HttpsConnectorServlet, see chapter: "Gemalto GemEngine Support for the HttpsConnectorServlet".

Client certificates are experimental when using TLSv1.3..

SSLClientKeyFile

Type: string
Usage Constraint: optional, basic connectivity

The key for an TLS client certificate may be provided either in the same file as the certificate (SSLClientCertificateFile), or it may be provided in a separate file specified with SSLClientKeyFile. Configure only SSLClientCertificate if both the certificate and the key are contained in the same file.

See chapter: "Gemalto Gemengine Support for the HttpsConnectorServlet" for more information on how to use the Gemengine within the HttpsConnectorServlet..

SSLCache

Type: enum: on, session, off
Usage Constraint: optional, advanced
Default: on

This attribute configures the client-side TLS cache.
You can set it to one of the following values:

• on: One TLS session to the content provider is established and used for all requests.
• session: For every session, an individual TLS session to the content provider is established. That session is used only for requests that are associated with that session. If you are using the SSLCache in session mode, the TCP connection pooling configured by the KeepAlive attribute either has to be set false or set to be true, with KeepAlive.ByClient set to true as well.
• off: For every request sent to the content provider, a new TLS session is established.

SSLCipherSuites

Type: string
Usage Constraint: optional
Default and secure 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

This attribute defines the SSL cipher suite to use. You can set all ciphers that are supported by OpenSSL. You can have maximal 2 newline separated lines with the following syntax:
[protocol] cipher-spec

where:

• protocol: The optional protocol specifier can configure the Cipher Suite for a specific SSL version. Possible values include "SSL" for all SSL Protocols up to and including TLSv1.2 and "TLSv1.3" for TLSv1.3. If not set, then SSL is taken.
• cipher-spec: colon-separated cipher-spec string consisting of OpenSSL cipher specifications to configure the Cipher Suite the server is permitted to negotiate in the SSL handshake phase

For a list of TLSv1.3 cipher names, see the OpenSSL documentation (https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set_ciphersuites.html).

Note: TLSv1.3 support in the nevisProxy is experimental only.

SslConnectTimeout

Type: integer
Usage Constraint: optional, scaling

Timeout in milliseconds to open the TLS connection after a successfully opened TCP-connection. The timeouts are related like this:

• ConnectTimeout: The timeout to connect to the TCP-connection.
• SslConnectTimeout: The timeout to connect to the TLS-connection once the TCP-connection has been established.
• RequestTimeout: The timeout for a response from the server once the TLS-connection has been established.

CrlFile

Type: string
Usage Constraint: optional

The path to a Crl file (pem format). It will be automatically reloaded if the file is replaced by a newer one. The file modification will be checked in the interval configured under periodicity in the Timer section in the file navajo.xml.

SSLCheckPeerHostname

Type: boolean
Usage Constraint: optional, security/troubleshooting
Default: false
Secure default: true

If enabled, among other validations, the DNS name is checked against the CN/SAN of the certificate. Setting this parameter also requires setting the SSLCACertificateFile.

SSLCheckPeerHostname.AllowWildcards

Type: boolean
Usage Constraint: optional
Default: false
Secure default: false

If set to "true", the system will also accept certificates containing wildcards. This parameter is only evaluated if the attribute SSLCheckPeerHostname is set to "true". For security reasons, we recommend setting this parameter to "false" in production.

SSLProtocol

Type: enum: TLSv1, TLSv1.1, TLSv1.2, TLSv1.3
Usage Constraint: optional
Default: -all +TLSv1.2 +TLSv1.3
Secure default: -all +TLSv1.2 +TLSv1.3

Syntax:
[all] [+/-][TLSv1] [+/-][TLSv1.1] [+/-][TLSv1.2][+/-][TLSv1.3]

No sign means +. Separate each entry in the SSL protocol list by a blank. Some backends may not understand TLSv1.3 and thus will not be able to tell the proxy to downgrade.

SSLDynamicClientCertificate

Type: boolean
Usage Constraint: optional, advanced
Default: false

If set to true, the client certificate used in the TLS handshake will be retrieved from the user session. Consult Enabling dynamic x.509 certificates on how to configure nevisAuth and nevisProxy for use with dynamic client certificates. Due to the fact that the client certificate is session-bound and not statically configured, the following configuration constraints apply:

• SSLCache must be set to either "off" or "session".
• KeepAlive must be set to "false" or KeepAlive.ByClient must be true.
• SSLClientCertificateFile must not be configured.

UseSSL

Type: boolean
Usage Constraint: optional
Default: true

If set to false, the servlet will behave like a HttpConnectorServlet.

SSLSNISupport

Type: boolean
Usage Constraint: optional
Default: true

Enables SNI support for this servlet. In case the backend has multiple name-based virtual servers configured with different certificates, the servlet can securely indicate, as part of the TLS handshake, to which one it intends to connect to. This indication happens at the beginning of the connection and (depending on the backend) it is continuously checked. Therefore, if you set up KeepAlive and dynamic HostNames it will most probably not work because the HostName might change when the connection is re-used.

ConnectionRetries

Type: integer
Usage Constraint: optional, advanced; min: 0, max: 100
Default: 0

Sometimes a TLS connection fails because of some unknown problem (network, etc.). With this parameter you can configure how many times the servlet should try to connect before giving up.

SSLOpenSSLConfCmd

Type: newline-separated string of name/value pairs
Usage Constraint: optional, advanced

This parameter exposes OpenSSL's SSL_CONF API to the proxy, allowing a flexible configuration of OpenSSL parameters without the need of implementing additional parameters when new features are added to OpenSSL. For a list of supported command names, see the section: Supported configuration file commands in the SSL_CONF_cmd(3) manual page for OpenSSL.
Some of the SSLOpenSSLConfCmd commands can be used as an alternative to existing parameters (such as SSLCipherSuite or SSLProtocol), although the syntax / allowable values for the parameters may sometimes differ. First consider if your goal can be achieved using the other parameters available. Contact support before using this parameter.

Remarks

The behavior of many web servers depends on the protocol version and the HTTP header field UserAgent. Therefore, if connection-oriented problems occur, you have to adjust the HttpsConnectorServlet to the behavior of the content provider, which usually uses the attributes SSLProtocol, KeepAlive, Protocol and UserAgent.