PingGateway 2025.3

ClientTlsOptions

Configures connections to the TLS-protected endpoint of servers, when PingGateway is client-side.

When PingGateway is client-side, PingGateway sends requests to a proxied application, or requests services from a third-party application. PingGateway is acting as a client of the application, and the application is acting as a server.

Use ClientTlsOptions in ClientHandler, ReverseProxyHandler, and AmService.

Usage

{
  "name": string,
  "type": "ClientTlsOptions",
  "config": {
    "keyManager": [ Key manager reference, ...],
    "trustManager": [ Trust manager reference, ...],
    "sslCipherSuites": [ configuration expression<string>, ...],
    "sslContextAlgorithm": configuration expression<string>,
    "sslEnabledProtocols": [ configuration expression<string>, ...],
    "alpn": object,
    "hostnameVerifier": configuration expression<enumeration>,
    "offloadHandshake": configuration expression<boolean>
  }
}
json

Properties

"keyManager": array of key manager references, optional

One or more of the following objects to serve the same secret key and certificate pair for TLS connections to all server names in the deployment:

Key managers are used to prove the identity of the local peer during TLS handshake, as follows:

  • When ServerTlsOptions is used in an HTTPS connector configuration (server-side), the key managers to which ServerTlsOptions refers are used to prove this PingGateway’s identity to the remote peer (client-side). This is the usual TLS configuration setting (without mTLS).

  • When ClientTlsOptions is used in a ClientHandler or ReverseProxyHandler configuration (client-side), the key managers to which ClientTlsOptions refers are used to prove this PingGateway’s identity to the remote peer (server-side). This configuration is used in mTLS scenarios.

Default: None

"trustManager": array of trust manager references, optional

One or more of the following objects to manage PingGateway’s public key certificates:

When the TrustManager object is configured, only certificates accessible through that TrustManager are trusted. Default and system certificates are no longer trusted.

Trust managers verify the identity of a peer by using certificates, as follows:

  • When ServerTlsOptions is used in an HTTPS connector configuration (server-side), ServerTlsOptions refers to trust managers that verify the remote peer’s identity (client-side). This configuration is used in mTLS scenarios.

  • When ClientTlsOptions is used in a ClientHandler or a ReverseProxyHandler configuration (client-side), ClientTlsOptions refers to trust managers that verify the remote peer’s identity (server-side). This is the usual TLS configuration setting (without mTLS).

If trustManager is not configured, PingGateway uses the default Java truststore to verify the remote peer’s identity. The default Java truststore depends on the Java environment. For example, $JAVA_HOME/lib/security/cacerts.

Default: No trustManager is set, and PingGateway uses the default and system certificates

"sslCipherSuites": array of configuration expression<strings>, optional

Array of cipher suite names, used to restrict the cipher suites allowed when negotiating transport layer security for an HTTPS connection.

For information about the available cipher suite names, refer to the documentation for the Java virtual machine (JVM) where you run PingGateway. For Oracle Java, refer to the list of JSSE Cipher Suite Names.

Default: Allow any cipher suite supported by the JVM.

"sslContextAlgorithm": configuration expression<string>, optional

The SSLContext algorithm name, as listed in the table of SSLContext Algorithms for the Java Virtual Machine (JVM).

Default: TLS

"sslEnabledProtocols": array of configuration expression<strings>, optional

The Java Virtual Machine (JVM) security setting jdk.tls.disabledAlgorithms restricts the Transport Layer Security (TLS) algorithms Java applications like PingGateway can use. The JVM java.security file defines the default list of jdk.tls.disabledAlgorithms.

This PingGateway setting takes an array of protocol names. Use it to further restrict the protocols allowed when negotiating TLS for an HTTPS connection.

Learn more about the protocol names in the JVM documentation, Additional JSSE Standard Names.

Follow these protocol recommendations:

  • Use TLSv1.3 when it is supported by client applications, otherwise use TLSv1.2.

  • Don’t use algorithms listed in jdk.tls.disabledAlgorithms and don’t remove algorithms from the list.

    If applications require disabled algorithms for backwards compatibility, enable them only with express approval from enterprise security.

Default: TLSv1.3, TLSv1.2

"alpn": object, optional

A flag to enable the Application-Layer Protocol Negotiation (ALPN) extension for TLS connections.

{
  "alpn": {
    "enabled": configuration expression<boolean>
  }
}
json
enabled: configuration expression<boolean>, optional

  • true: Enable ALPN. Required for HTTP/2 connections over TLS

  • false: Disable ALPN.

Default: true

"hostnameVerifier": configuration expression<enumeration>, optional

The method to handle hostname verification for outgoing SSL connections.

Use one of the following values:

  • ALLOW_ALL: Allow a certificate issued by a trusted CA for any hostname or domain to be accepted for a connection to any domain.

    If the SSL endpoint uses a raw IP address rather than a fully-qualified hostname, you must configure this property as ALLOW_ALL.

    To prevent the compromise of TLS connections, use ALLOW_ALL in development mode only. In production, use STRICT.

    The ALLOW_ALL setting allows a certificate issued for one company to be accepted as a valid certificate for another company.

  • STRICT: Match the hostname either as the value of the the first CN, or any of the subject-alt names.

    A wildcard can occur in the CN, and in any of the subject-alt names. Wildcards match one domain level, so *.example.com matches www.example.com but not some.host.example.com.

Default: STRICT

"offloadHandshake": configuration expression<boolean>, optional

Whether to offload the handshake processing to a worker thread.

When processing a TLS handshake with revocation checks enabled, the handshake process can take an extended amount of time, blocking the event thread from processing other requests. When this option is true, PingGateway processes the TLS handshake in a separate worker thread. The event thread continues to process other requests.

Default: false

Example

For an example that uses ClientTlsOptions, refer to Configure PingGateway for TLS (client-side).