Skip to main content
Version: 4.6.x.x LTS

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 that is sent to the application server if requested by a SSL/TLS CertificateRequest message. PEM encoded files, and Nevis PKCS#11 URLs are supported.

When setting the bc property ch.nevis.openssl.allowCertificateChain to true, then a certificate chain can be configured.
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 a TLS client certificate may be provided either in the same file as the certificate. PEM encoded files, and Nevis PKCS#11 URLs are supported.

For more information on how to use the GemEngine within the HttpsConnectorServlet, see chapter: "Gemalto GemEngine Support for 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: 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
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.

Note: TLSv1.3 support in the nevisProxy is experimental only. You cannot configure cipher suites for the TLSv1.3 protocol

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: No sign means +.

Note: Separate each entry in the SSL protocol list by a blank. - TLSv1: Can be required with some JSSE implementations (e.g., some BEA WLS versions). It sends a SSL version of 3.1 in the SSL/TLS client hello and enforces TLS 1.0.

  • TLSV1.1: Sends a TLS 1.1 client hello.
  • TLSV1.2: Sends a TLS 1.2 client hello.
  • TLSV1.3: Sends a TLS 1.3 client hello.

Note: Some backends may not understand TLSv1.3 and thus will not be able to tell the proxy to downgrade.

Recommended value: The recommended protocol configuration is "-all +TLSv1.2 +TLSv1.3".

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.