nio https ingress connector

NIO HTTPS Ingress Connector

Version: 17.07

Supported Since: 17.01

What is NIO HTTPS Ingress Connector?

As the name implies, NIO HTTPS Ingress connector can be considered as the secured version of the NIO HTTP Ingress Connector. That is, all the requests received and responses sent by this connector will be encrypted. In order to achieve that, this connector can be configured to use SSL (Secure Socket Layer) security and TLS (Transport Layer Security).

In addition to the basic configurations required for the NIO HTTP Ingress Connector, NIO HTTPS Ingress Connector require several other configurations to be done. For example, in order to validate remote server/client certificates, this connector need a trust store to be configured. An introduction to all those configurations and how can they be configured will be shown in the following sections of this documentation.

In order to use the HTTPS NIO Ingress Connector, you must first select the HTTP NIO Connector dependency from the connector list when you are creating an empty Ultra project. If you have already created a project, you can add the HTTP NIO Connector dependency via Component Registry. From Tools menu, select Ultra Studio → Component Registry and from the Connectors list, select the HTTP NIO Connector dependency.
https ingress connector 1

Out Ports

Processor

The message received to the NIO HTTPS Ingress Connector from a HTTP Client will be emitted from this out port

On Exception

The message will be emitted from this out port if the Ingress Connector fails to process the message payload

Input

The message sent to this out port will be sent as the response to the HTTP Client which initiated the request

Parameters

* marked fields are mandatory

HTTP Port *

Basic

The port on which the ingress connector will be listening on.

Service Path *

Basic

The request path to which this connector will be subscribed to. Only the requests received through "HTTP Port" with the path "Service Path" will be received by this connector.

Response Timeout

Advanced

Timeout in milliseconds after which the request times out. That is, if a response hasn’t been received to the input port of the ingress connector to be sent to the client as the response within the given timeout, the request times out.

Identity Store Location *

SSL Configuration

Path to the identity key store where the key-pair used for this ingress connector’s identity is located.

Identity Store Password *

SSL Configuration

Password of the identity key store located at Identity Store Location

Identity Key Password *

SSL Configuration

Password used to protect the private key of the identity key-pair.

Trust Store Location

SSL Configuration

Path to the key store where this ingress connector’s trusted certificates are located at

Trust Store Password

SSL Configuration

Password used to protect the trust store located at Trust Store Location

SSL Client Verification

SSL Configuration

Indicates whether to validate the clients certificates when accepting a connection by the ingress connector. Allowed values are,

  1. none - no remote client validation happens

  2. optional - remote certificates are validated if presented by the client, otherwise not

  3. required - Always perform validations on remote clients

Prevent Client Certificate Verification

SSL Configuration

Indicates whether or not to validate client certificates. This parameter should be turned to true only in non-production usages. Turning this parameter on will cause no remote client certificate to be validated even if you had specified SSL Client Verification to required. Therefore always be careful when turning on this parameter.

SSL Protocol Version

SSL Configuration

Specify which protocol version to be used for HTTPS connections. This parameter defaults to TLS. Available values are,

  1. TLS

  2. TLSv1

  3. TLSv1.1

  4. TLSv1.2

You can chose the TLS version depending on the level of security your ingress connector is expected to have when transporting data.

Supported TLS Versions

SSL Configuration

The set of TLS versions to be enabled for this Ingress Connector given here as a comma separated string.

Supported Cipher Suits

SSL Configuration

The set of cipher suites to be enabled should be given here as a comma separated string. This is an advanced SSL configuration where only the specified set of cipher suits will be used to encrypt connections between the ingress connector and the clients.

IO Thread Count

Transport Configuration

Number of IO Threads to be used in-order to accept HTTP requests

Local Bind Address

Transport Configuration

The local address to bind when the Ingress Connector is started. If not specified, binds on all interfaces by default

Connection Debugging Enabled

Transport Configuration

Whether to enable connection debug or not. Connection debug gives you a log if something went wrong in connection level. By default this will be enabled.

Connection Debug Headers

Transport Configuration

A comma separated list of HTTP headers to be dumped on a connection failure, when connection debugging is enabled. Specify as 'all' to dump all headers or as 'none' to prevent dumping of headers.

Allowed HTTP Methods

Transport Configuration

The HTTP methods allowed for requests processed via this Ingress Connector (multiple methods can be selected)

Zero Copy Enabled

Transport Configuration

Whether to enable zero copying or not. Read more about Zero-Copy

Turn Off Response Compression

Transport Configuration

Whether to turn off the use of Gzip compression even if the request contains an Accept-Encoding header

Compressing Trigger Size

Transport Configuration

The minimum size of a response (in bytes) to trigger compression, if supported by the client. Default value is 2K bytes

Continue on Runtime Exceptions

Transport Configuration

Whether the engine should continue execution on the occurrence of a runtime exception. If set to false, engine will shutdown and restart on such a situation. By default this is enabled.

Continue on checked exceptions

Transport Configuration

Whether the engine should continue execution on the occurrence of a checked exception. If set to false, engine will shutdown and restart on such a situation.

Stop New Connections At Soft Limit

Transport Configuration

The connection limit on which the Ingress Connector should pause accepting new connections. Default value is 4096. In reality this limit maybe surpassed.

Resume New Connections At Soft Limit

Transport Configuration

The connection limit on which the Ingress Connector should resume accepting new connections. Default value is 3072.

Maximum Payload Size

Transport Configuration

The maximum payload size to accept (in bytes). Default value is 1MB.

Tuning parameters

Transport Configuration

Specify a map of HTTP tuning parameters.

http.socket.timeout

TCP level socket timeout

http.connection.timeout

Time limit to establish a TCP level connection

http.tcp.nodelay

Use of nagle algorithm ? - default true

http.jvm.interest-ops-queued

Should NIO interest ops be queued? false for Sun/Oracle JDKs, true for IBM JDK

http.socket.buffer-size

Socket buffer size - default 8K

Simple Use Case

Prerequisites

Since this is a connector written on top of NIO HTTP Ingress Connector, it will be easy for you to understand this connector well if you have some idea about NIO HTTP Ingress Connector.

All the prerequisites mentioned in the NIO HTTP Ingress Connector are required in order to test this connector since this is a connector written on top of NIO HTTP Ingress Connector. Apart from that, it is better if you have pre-configured some trust stores and identity stores to test the HTTPS connections and 2-way SSL like features.

Basic Configurations

Lets consider a simple use case where the ingress connector accepts requests coming from various clients, add a transport header to the requests and send the requests back to the clients. Following figure shows that scenario.

https ingress connector flow
Figure 1. Integration flow

We have the NIO HTTPS Ingress Connector as the connector. Then we have connected the Add Transport Header processing element as the processor of the connector. Then we have connected the ingress connector (through input port) again as the next element of the Add Transport Header processing element.

Following figure show the basic configurations of NIO HTTPS Ingress Connector that has to be provided.

nio https conf
Figure 2. Connector’s basic configurations

port is the port from which the ingress connector will be listening on and service path is the url path to which this connector will be subscribed to. In the example above, requests coming to port 8443 with the request path /service/echo-service will be served by this connector and forwarded through the integration flow. Therefore, our request URL required for testing this integration flow will be http://localhost:8443/service/echo-service.

Then we have to configure the SSL Configurations of the connector as follows.

https ingress connector conf
Figure 3. Connector’s SSL configuration

For HTTPS protocol to work, a trust store which contains the trusted server certificates and an identity store which holds the listener’s identity are required. If those are not provided, the connector will continue with the JRE’s default identity and trust store.

We have to set the transport header in the Add Transport Header processing element’s configuration as follows. You can read more about the Add Transport Header processing element from here. Here, this processing element will add a new transport header FOO: bar to the message and will send the message back to the ingress connector.