Configures a TLS context: the identity (key and certificate) presented to the peer, the certificates trusted from it, and handshake parameters such as protocol, ciphers, and client-certificate policy. Attach it to a serviceProxy/api to terminate inbound TLS, or to a target to make an outbound connection over TLS; most attributes and child elements apply to both directions, but a few - such as clientAuth and useAsDefault - only take effect on an inbound context. See tutorials/ssl-tls/10-TLS-Termination.yaml for inbound termination and tutorials/ssl-tls/20-Central-SSL-Config.yaml for sharing one ssl across several APIs via $ref.


 ssl:
   keystore: ... | key: ... | keyGenerator: ...    # this side's identity (pick one)
   [ truststore: ... | trust: ... ]                 # CAs trusted from the peer
   [ acme: ... ]                                    # obtain identity via ACME instead
   [ clientAuth: want | need ]                      # default: not set (inbound only)
   [ protocols: <protocol>[,<protocol>...] ]
   [ ciphers: <cipher>[,<cipher>...] ]
   [ insecureValidation: true | false ]             # default: false
   ...

Example Configuration

api:
   port: 8443
   ssl:
     key:
       private:
         location: membrane-key.pem
       certificates:
         - location: membrane.pem
   flow:
     - log: {}
   target:
     url: https://api.predic8.de

api:
   port: 8443
   ssl:
     key:
       private:
         location: membrane-key.pem
       certificates:
         - location: membrane.pem
   flow:
     - log: {}
   target:
     url: https://api.predic8.de

Syntax

ssl:
  '$ref': <string>
  acme: {}
  algorithm: <string>
  ciphers: <string>
  clientAuth: <string>
  endpointIdentificationAlgorithm: <string>
  ignoreTimestampCheckFailure: <boolean>
  insecureValidation: <boolean>
  key: {}
  keyGenerator: {}
  keystore: {}
  protocol: <string>
  protocols: <string>
  serverName: <string>
  showSSLExceptions: <boolean>
  trust: {}
  truststore: {}
  useAsDefault: <boolean>
  useExperimentalHttp2: <boolean>

ssl:
  '$ref': <string>
  acme: {}
  algorithm: <string>
  ciphers: <string>
  clientAuth: <string>
  endpointIdentificationAlgorithm: <string>
  ignoreTimestampCheckFailure: <boolean>
  insecureValidation: <boolean>
  key: {}
  keyGenerator: {}
  keystore: {}
  protocol: <string>
  protocols: <string>
  serverName: <string>
  showSSLExceptions: <boolean>
  trust: {}
  truststore: {}
  useAsDefault: <boolean>
  useExperimentalHttp2: <boolean>

Attributes

Name	Required	Default	Description	Examples
$ref	false	-	Reference a component defined under components.	-
algorithm	false	java default	getDefaultAlgorithm()	SunX509
ciphers	false	the JVM's default cipher suites, excluding `RC4` and `3DES`, ordered by preference (forward secrecy first, then AEAD, then key/hash strength)	Comma-separated list of cipher suites to allow; an unknown name is rejected at startup. See getSupportedCipherSuites() for the names the JVM supports.	TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
clientAuth	false	not set	Either not set (=no), or want or need.	`need`
endpointIdentificationAlgorithm	false	HTTPS	See setEndpointIdentificationAlgorithm().	-
ignoreTimestampCheckFailure	false	false	Accepts a peer certificate that is expired or not yet valid; the rest of chain validation (issuer signature, trust anchor) is unaffected. For disabling all certificate validation, see `insecureValidation` instead.	-
insecureValidation	false	false	Disables all certificate validation (chain-of-trust and hostname) for this SSL context, equivalent to curl -k; this also makes `ignoreTimestampCheckFailure` redundant. A configured <truststore> or <trust> is ignored while this is set. On an inbound (server) context with clientAuth="need", a client certificate is still required but no longer validated. Only use for testing; never in production, as it removes all protection against man-in-the-middle attacks.	-
protocol	false	TLS	SSLContext.getInstance()	-
protocols	false	all protocols the JVM enables by default, except `SSLv3` and `SSLv2Hello`	Comma-separated list of enabled TLS protocol versions. See SSLSocket.setEnabledProtocols().	TLSv1.2,TLSv1.3
serverName	false	the target's hostname	Hostname sent via the TLS Server Name Indication (SNI, RFC 3546) extension on outbound connections, telling the server which certificate to present. Set to an empty string to send no SNI extension at all.	-
showSSLExceptions	false	false	Logs SSL/TLS handshake exceptions (e.g. an untrusted or expired peer certificate) instead of only failing the connection silently.	-
useAsDefault	false	true	whether to use the SSLContext built from this SSLParser when no SNI header was transmitted.	-
useExperimentalHttp2	false	false	whether to enable receiving HTTP/2 requests. (experimental)	-

Child Structure

Element	Cardinality	Description
acme	0..1	Configures an ACME (RFC 8555) client, e.g. to retrieve TLS certificates from Let's Encrypt.
key	0..1	Used to manually compose the keystore.
keyGenerator	0..1	Used to dynamically generate a key for the incoming connection on the fly.
keystore	0..1	Loads a private key and its certificate chain from a keystore file, to be presented as this side's identity during a TLS handshake (or, inside `wsSecurity`, to sign a message). See `tutorials/web-services-security/50-Sign-And-Validate-Body.yaml`.
trust	0..1	Used to manually compose the truststore.
truststore	0..1	Supplies the CA certificates trusted when validating a peer's certificate chain, for example during a TLS handshake or, inside `wsSecurity`, when verifying a signature. See `tutorials/web-services-security/50-Sign-And-Validate-Body.yaml`.

Can be used in

api components github google httpClientConfig internal ldapUserDataProvider membrane microsoftEntraID proxy proxy-configuration registration serviceProxy soapProxy sslProxy-routerIpResolver stompClient stompProxy target