ssl_multicert.yaml

The ssl_multicert.yaml file lets you configure Traffic Server to use multiple SSL server certificates to terminate the SSL sessions. If you have a Traffic Server system with more than one IP address assigned to it, then you can assign a different SSL certificate to be served when a client requests a particular IP address or host name.

At configuration time, certificates are parsed to extract the certificate subject and all the DNS subject alternative names. A certificate will be presented for connections requesting any of the hostnames found in the certificate. Wildcard names are supported, but only of the form *.domain.com, ie. where * is the leftmost domain component.

Changes to ssl_multicert.yaml can be applied to a running Traffic Server using traffic_ctl config reload.

Format

The ssl_multicert.yaml file uses YAML format with a top-level ssl_multicert key containing a sequence of certificate entries. Each entry is a mapping with the following keys:

ssl_cert_name: FILENAME[,FILENAME ...]

The name of the file containing the TLS certificate. FILENAME is located relative to the directory specified by the proxy.config.ssl.server.cert.path configuration variable. It may also include the intermediate CA certificates, sorted from leaf to root. At a minimum, the file must include a leaf certificate.

When running with OpenSSL 1.0.2 or later, this directive can be used to configure the intermediate CA chain on a per-certificate basis. Multiple chain files are separated by comma character. For example, it is possible able to configure a ECDSA certificate chain and a RSA certificate chain and serve them simultaneously, allowing OpenSSL to determine which certificate would be used when the TLS session cipher suites are negotiated. Note that the leaf certs in FILENAME1 and FILENAME2 must have the same subjects and alternate names. The first certificate is used to to match the client's SNI request.

You can also configure multiple leaf certificates in a same chain with OpenSSL 1.0.1.

This is the only field that is required to be present (unless action is set to tunnel).

dest_ip: ADDRESS (optional)

The IP (v4 or v6) address that the certificate should be presented on. This is now only used as a fallback in the case that the TLS ServerNameIndication extension is not supported. If ADDRESS is *, the corresponding certificate will be used as the global default fallback if no other match can be made. The address may contain a port specifier, in which case the corresponding certificate will only match for connections accepted on the specified port. IPv6 addresses must be enclosed by square brackets if they have a port, eg, [::1]:80. Care should be taken to make each ADDRESS unique.

ssl_key_name: FILENAME (optional)

The name of the file containing the private key for this certificate. If the key is contained in the certificate file, this field can be omitted, otherwise FILENAME is resolved relative to the proxy.config.ssl.server.private_key.path configuration variable.

ssl_ca_name: FILENAME (optional)

If the certificate is issued by an authority that is not in the system CA bundle, additional certificates may be needed to validate the certificate chain. FILENAME is resolved relative to the proxy.config.ssl.CA.cert.path configuration variable.

ssl_ocsp_name: FILENAME (optional)

The name of the file containing the prefetched OCSP stapling response for this certificate. This field can be omitted to let trafficserver fetch OCSP responses dynamically. Otherwise, when included, the administrator is responsible for updating the file's content. FILENAME is resolved relative to the proxy.config.ssl.ocsp.response.path configuration variable.

ssl_ticket_enabled: 1|0 (optional)

Enable RFC 5077 stateless TLS session tickets. To support this, OpenSSL should be upgraded to version 0.9.8f or higher. This option must be set to 0 to disable session ticket support.

ssl_ticket_number: INTEGER (optional)

Specifies the number of TLSv1.3 session tickets that are issued. This defaults to 2 (the OpenSSL default)

ssl_key_dialog: builtin|"exec:/path/to/program [args]" (optional)

Method used to provide a pass phrase for encrypted private keys. If the pass phrase is incorrect, SSL negotiation for this dest_ip will fail for clients who attempt to connect. Two options are supported: builtin and exec:

builtin - Requests pass phrase via stdin/stdout. User will be

provided the ssl_cert_name and be prompted for the pass phrase. Useful for debugging.

exec: - Executes program /path/to/program and passes args, if

specified, to the program and reads the output from stdout for the pass phrase. If args are provided then the entire exec: string must be quoted with "" (see examples). Arguments with white space are supported by single quoting ('). The intent is that this program runs a security check to ensure that the system is not compromised by an attacker before providing the pass phrase.

ssl_rpk_enabled: 1|0 (optional)

Set to 1 to offer a raw public key (RFC 7250), derived from this entry's ssl_cert_name/ ssl_key_name, as an alternative to the X.509 certificate for inbound connections matching this entry. The raw public key is offered alongside the certificate, not instead of it: a client that does not support RFC 7250 negotiates a normal certificate exchange instead. Defaults to 0.

Only available in builds linked against a TLS library with RFC 7250 support (OpenSSL 3.2 or later, or a sufficiently recent BoringSSL). If this key is set on a build without that support, Traffic Server logs a warning and ignores it.

HTTP/3 support depends on the QUIC implementation Traffic Server is built with, and is not covered by tests. With quiche, entries apply to HTTP/3 connections as they do to TLS over TCP. With OpenSSL's QUIC, an HTTP/3 connection keeps the certificate types of the default (dest_ip: "*") entry, because QUIC connections select their certificate through a separate callback: the default entry's raw public key settings apply to every HTTP/3 connection, and other entries' settings do not apply to any. No warning is logged.

ssl_client_rpk_ca_name: FILENAME (optional)

The name of the file containing the raw public key(s) (RFC 7250) that a client is trusted to present for mutual TLS on this entry, PEM-encoded. FILENAME is resolved relative to the proxy.config.ssl.CA.cert.path configuration variable. The file may contain more than one key concatenated together, which allows an "old" and "new" key to both be trusted during a planned key rotation.

A client authenticating with a raw public key has no certificate chain to verify, so this trusted set takes the place of the usual client-certificate verification for that connection. An unmatched pin is always fatal to the connection, the same as a failed certificate check -- there is no separate log-only mode.

Replacing the file and running traffic_ctl config reload takes effect for new handshakes, and a TLS session a client authenticated under the old set cannot be resumed under the new one.

This key only has an effect where a client certificate is actually requested, which means either a non-zero proxy.config.ssl.client.certification_level or a sni.yaml verify_client action covering the connection. With neither, no credential is requested and nothing is pinned.

On HTTP/3, see the note under ssl_rpk_enabled above. A verify_client action does not reach an HTTP/3 connection, so there the client certificate level is the only way to request a client credential. With OpenSSL's QUIC, setting this key on the default entry lets a client that prefers raw public keys negotiate one on a connection matching another entry; if that entry has no trusted keys to match it against, the handshake fails rather than falling back to X.509.

Only available in builds linked against a TLS library with RFC 7250 support; see ssl_rpk_enabled above.

action: tunnel (optional)

If set to tunnel, Traffic Server will not participate in the TLS handshake and will blind tunnel the connection instead.

Certificate Selection

Traffic Server attempts two certificate selections during SSL connection setup. An initial selection is made when a TCP connection is accepted. This selection examines the IP address and port that the client is connecting to and chooses the best certificate from the those that have a dest_ip specification. If no matching certificates are found, a default certificate is chosen. The final certificate selection is made during the SSL handshake. At this point, the client may use Server Name Indication to request a specific hostname. Traffic Server will use this request to select a certificate with a matching subject or subject alternative name. Failing that, a wildcard certificate match is attempted. If no match can be made, the initial certificate selection remains in force.

In all cases, Traffic Server attempts to select the most specific match. An address specification that contains a port number will take precedence over a specification that does not contain a port number. A specific certificate subject will take precedence over a wildcard certificate. In the case of multiple matching certificates the first match will be returned to non-SNI capable clients.

Examples

The following example configures Traffic Server to use the SSL certificate server.pem for all requests to the IP address 111.11.11.1 and the SSL certificate server1.pem for all requests to the IP address 11.1.1.1. Connections from all other IP addresses are terminated with the default.pem certificate. Since the private key is included in the certificate files, no private key name is specified.

ssl_multicert:
  - ssl_cert_name: server.pem
    dest_ip: "111.11.11.1"

  - ssl_cert_name: server1.pem
    dest_ip: "11.1.1.1"

  - ssl_cert_name: default.pem
    dest_ip: "*"

The following example configures Traffic Server to use the ECDSA certificate chain ecdsa.pem or RSA certificate chain rsa.pem for all requests.

ssl_multicert:
  - ssl_cert_name: ecdsa.pem,rsa.pem
    dest_ip: "*"

The following example configures Traffic Server to use the ECDSA certificate chain ecdsa.pem or RSA certificate chain rsa.pem for all requests, the public key and private key are in separate PEM files. Note that the number of files in ssl_key_name must match the files in ssl_cert_name, and they should be presented in the same order.

ssl_multicert:
  - ssl_cert_name: ecdsa_pub.pem,rsa_pub.pem
    ssl_key_name: ecdsa_private.pem,rsa_private.pem
    dest_ip: "*"

The following example configures Traffic Server to use the SSL certificate server.pem and the private key serverKey.pem for all requests to port 8443 on IP address 111.11.11.1. The general.pem certificate is used for server name matches.

ssl_multicert:
  - ssl_cert_name: server.pem,general.pem
    ssl_key_name: serverKey.pem
    dest_ip: "111.11.11.1:8443"

The following example configures Traffic Server to use the SSL certificate server.pem for all requests to the IP address 111.11.11.1. Session tickets are enabled.

ssl_multicert:
  - ssl_cert_name: server.pem
    dest_ip: "111.11.11.1"
    ssl_ticket_enabled: 1

The following example configures Traffic Server to use the SSL certificate server.pem and disable session tickets for all requests to the IP address 111.11.11.1.

ssl_multicert:
  - ssl_cert_name: server.pem
    dest_ip: "111.11.11.1"
    ssl_ticket_enabled: 0

The following examples configure Traffic Server to use the SSL certificate server.pem which includes an encrypted private key. The external program /usr/bin/mypass will be called on startup with one parameter (foo) in the first example, and with two parameters (foo) and (ba r) in the second example, the program (mypass) will return the pass phrase to decrypt the keys.

ssl_multicert:
  - ssl_cert_name: server1.pem
    ssl_key_dialog: "exec:/usr/bin/mypass foo"

  - ssl_cert_name: server2.pem
    ssl_key_dialog: "exec:/usr/bin/mypass foo 'ba r'"

The following example configures Traffic Server to use the SSL certificate server.pem for all requests, and offers a raw public key (RFC 7250) alongside it. Clients presenting a raw public key for mutual TLS are checked against client-rpk-trusted.pem instead of the usual certificate chain.

ssl_multicert:
  - dest_ip: "*"
    ssl_cert_name: server.pem
    ssl_key_name: server.key
    ssl_rpk_enabled: 1
    ssl_client_rpk_ca_name: client-rpk-trusted.pem

Migration from ssl_multicert.config

The traffic_ctl command can be used to convert pre-11.x ssl_multicert.config files to the new YAML format:

traffic_ctl config convert ssl_multicert ssl_multicert.config ssl_multicert.yaml

To output to stdout instead of a file, use - as the output path:

traffic_ctl config convert ssl_multicert ssl_multicert.config -