Provided by: trafficserver_9.2.3+ds-1+deb12u1build4_amd64 bug

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