Provided by: trafficserver_9.2.3+ds-1+deb12u1build4_amd64 
NAME
ssl_multicert.config - Traffic Server SSL certificate configuration file
The ssl_multicert.config 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.config can be applied to a running Traffic Server using
traffic_ctl config reload.
FORMAT
Each ssl_multicert.config line consists of a sequence of key=value fields that specify how
Traffic Server should use a particular SSL certificate.
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.
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.
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.
dest_ip=111.11.11.1 ssl_cert_name=server.pem
dest_ip=11.1.1.1 ssl_cert_name=server1.pem
dest_ip=* ssl_cert_name=default.pem
The following example configures Traffic Server to use the ECDSA certificate chain
ecdsa.pem or RSA certificate chain rsa.pem for all requests.
dest_ip=* ssl_cert_name=ecdsa.pem,rsa.pem
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.
dest_ip=* ssl_cert_name=ecdsa_pub.pem,rsa_pub.pem ssl_key_name=ecdsa_private.pem,rsa_private.pem
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.
dest_ip=111.11.11.1:8443 ssl_cert_name=server.pem ssl_key_name=serverKey.pem ssl_cert_name=general.pem
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 with a persistent
ticket key.
dest_ip=111.11.11.1 ssl_cert_name=server.pem ssl_ticket_enabled=1 ticket_key_name=ticket.key
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.
dest_ip=111.11.11.1 ssl_cert_name=server.pem 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_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'"
COPYRIGHT
2024, dev@trafficserver.apache.org