ServerTlsOptions

When PingGateway is server-side, applications send requests to PingGateway or request services from PingGateway. PingGateway is acting as a server of the application, and the application is acting as a client.

ServerTlsOptions configures the TLS-protected endpoint when PingGateway is server-side. Use ServerTlsOptions in admin.json.

Usage

{
  "type": "ServerTlsOptions",
  "config": {
    // Use keyManager or sni, not both:
    "keyManager": [ Key manager reference, …],
    "sni": {
      "serverNames": map,
      "defaultSecretId": configuration expression<secret-id>,
      "secretsProvider": SecretsProvider reference
    },
    "trustManager": [ Trust manager reference, …],
    "sslCipherSuites": [ configuration expression<string>, …],
    "sslContextAlgorithm": configuration expression<string>,
    "sslEnabledProtocols": [ configuration expression<string>, …],
    "alpn": {
      "enabled": configuration expression<boolean>
    },
    "clientAuth": configuration expression<enumeration>,
  }
}

Properties

Configure either keyManager or sni, not both.

When both are configured, sni takes precedence and PingGateway logs a warning.
When neither is configured, PingGateway logs a warning and throws an exception.

keyManager

"keyManager": array of key manager references, required if sni isn’t configured

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

sni

"sni": object, required if keyManager isn’t configured

Server Name Indication (SNI) is an extension of the TLS handshake to serve different secret key and certificate pairs to the TLS connections on different server names. Use this property to host multiple domains on the same machine.

During a TLS handshake, vert.x accesses secret key and certificate pairs synchronously; PingGateway loads them in memory at startup, and they must be present. You must restart PingGateway to update a secret key and certificate pair.

Learn more in Serve different certificates for TLS connections to different server names.

serverNames: map, required

A map of one or more data pairs with the format Map<String, String>, where:

The key is the server name provided during TLS handshake or a configuration expression that evaluates to the name.
The value is a string representing the secret ID of the servers' secret key/certificate pair. Alternatively, it can be a configuration expression that evaluates to that string.

The following format is required:

{
  "serverNames": {
    "configuration expression<string>": "configuration expression<string>",
    ...
  }
}

In the following example, the keys and values in the map are strings:

"serverNames": {
  "app1.example.com": "my.app1.secretId",
  "app2.example.com": "my.app2.secretId",
  "*.test.com": "my.wildcard.test.secretId"
}

In the following example, the keys and values in the map are configuration expressions:

"serverNames": {
  "${server.name.available.at.config.time}" : "${secret.id.available.at.config.time}"
}

Note the following points:

One server cannot be mapped to multiple certificates.

PingGateway cannot provide multiple certificates for the same server name, as is allowed by Java’s key managers.
Multiple servers can be mapped to one certificate.

Map server names individually. In the following configuration, both server names use the same certificate:
```
"serverNames": {
  "cat.com" : "my.secret.id",
  "dog.org" : "my.secret.id"
}
```

Use the * wildcard in the server name to map groups of server names. In the following configuration, app1.example.com and app2.example.com use the same certificate:

"serverNames": {
  "*.example.com": "my.wildcard.secret.id"
}

"defaultSecretId": configuration expression<secret-id>, required: The secret ID representing the certificate to use when an unmapped server name is provided during TLS handshake.

This secret ID must point to a CryptoKey.

Learn more in About secrets.

"secretsProvider": SecretsProvider reference, required: The SecretsProvider to query for each secret ID.

trustManager

"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, PingGateway only trusts certificates in that TrustManager. 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 isn’t 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; PingGateway uses the default and system certificates

sslCipherSuites

"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.

Learn about the available cipher suite names in the Java documentation on JSSE Cipher Suite Names.

Default: Allow any cipher suite supported by the JVM.

sslContextAlgorithm

"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

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

Array of protocol names, used to restrict the protocols allowed when negotiating transport layer security for an HTTPS connection.

Learn about the available protocol names in the Java documentation on Additional JSSE Standard Names.

Follow these protocol recommendations:

Use TLS 1.3 when it is supported by available libraries, otherwise use TLS 1.2.
If TLS 1.1 or TLS 1.0 is required for backwards compatibility, use it only with express approval from enterprise security.
Don’t use deprecated versions SSL 3 or SSL 2.

Default: TLS 1.3, TLS 1.2

alpn

"alpn": object, optional

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

"enabled": configuration expression<boolean>, optional

true: Enable ALPN. (Required for HTTP/2 connections over TLS)
false: Disable ALPN.

Default: true

clientAuth

"clientAuth": configuration expression<enumeration>, optional

The authentication expected from the client; one of:

REQUIRED: Require the client to present authentication. If it isn’t presented, then decline the connection.
REQUEST: Request the client to present authentication. If it isn’t presented, then accept the connection anyway.
NONE: Accept the connection without requesting or requiring the client to present authentication.

Default: NONE

PingGateway 2024.11