In addition to the standard TLS where the server side provides a certificate for authentication, Traffic Server supports mututal TLS (mTLS) where the client also provides a certificate to the origin for verification.
mTLS from User Agent to Traffic Server¶
In this scenario, Traffic Server is acting as the TLS server. It can request during the TLS handshake that the User Agent provides a certificate. If Traffic Server can verify that the user agent provided certificate is signed by a trusted CA, the TLS handshake will proceed. Otherwise it will fail.
Case 1: Require certificates from all User Agents¶
In this case, you must set the
records.yaml to 2 to require a client certificate from all user agents.
Setting this to 0 means that no client certificate is requested. Setting this to 0 means
that a client certificate is requested but the handshake proceeds even if one is not provided.
There may be problems with some clients and the 1 setting, so staying with values 0 or 2 may be best.
If the certificate_level is set to 2, you must also set
records.yaml to point to a file that contains the certificates of the CA’s that
would have signed the user agent provided certificates that Traffic Server receives.
Case 2: Apply different certificate requirements depending on the domain requested by the User Agent¶
Often there are scenarios where Traffic Server must require client certificates from some user agents
(e.g. trusted parter sites) but not others (e.g. health check requests). In that case, use the
Traffic Server uses the Server Name Indication (SNI) from the TLS Client Hello to distinguish between the different
cases. This is the FQDN value in the
sni.yaml file. To control client certificate requirements use the
“verify_client” keyword which can take on the following values: NONE, MODERATE, or STRICT.
In the case were Traffic Server should require certificates from all domains except the health check domain, hc.example.com,
you should set
proxy.config.ssl.client.certification_level to 2 in
records.yaml and have the
sni: - fqdn: hc.example.com verify_client: NONE
Similarly, if you only wanted to require client certificates for super.sensitive.example.com,
you would set
proxy.config.ssl.client.certification_level to 0 in
records.yaml and have the following in
sni: - fqdn: super.sensitive.example.com verify_client: STRICT
You can also use wildcards in the fqdn names (e.g. ‘foo.com’ or ‘mail..foo.com’).
Awkward healthcheck case¶
Above we showed how you can exempt a health check request from needing to provide a client certificate.
That technique requires the health check requester to provide a SNI value. Unfortunately many older
clients (including many current hardware loadbalancers), do not set the SNI value in the client
hello. From Traffic Server’s perspective the SNI value is the empty string. In that case, the following
sni.yaml should work. It will match on all requests do not provide a SNI and turn off the
client certificate requirement. This is a very broad rule, since it is very easy for a malicious
user to make a request without the SNI set to try to evade the requirements of your
sni: - fqdn: '' verify_client: NONE
Specialize CA Bundle for client cert¶
You can use the verify_client_ca_certs keyword to specialize the CA bundle name in
For example you expect all client certs to be signed by the roots in client_CA_bundle.pem except for
special.example.com where the client certs should be signed by roots in partners_bundle.pem.
Then you would set
proxy.config.ssl.CA.cert.filename to client_CA_bundle.pem in
records.yaml and you would set the following in
sni: - fqdn: special.example.com verify_client_ca_certs: partners_bundle.pem verify_client: STRICT
Guidance for testing¶
If you use curl to test your SNI-based Traffic Server configuration, you must make sure the SNI value is really set in the TLS Client Hello message. If you use the Traffic Server name or address in the URL and explicitly set the host field (as shown below) to indicate the real domain, the SNI value will not be set to the host field value. In the example below the SNI value will not be foo.com
curl -H 'host:foo.com' -k -v https://prod123.example.com/foo
You can use the -resolve option of curl to ensure the sni value is set as shown below or update your local /etc/hosts so the address for your designed domain is the proxy address.
curl -resolve foo.com:443:126.96.36.199 -k -v https://foo.com/foo
mTLS from Traffic Server to Origin¶
In this scenario Traffic Server is the TLS client talking to the upstream origin.
Case 1: Provide one certificate to all potential origins that require a certificate¶
In this case, you would set at least
proxy.config.ssl.client.cert.filename to the name and path
of a file that includes the client certificate and the client private key. You could also set
proxy.config.ssl.client.cert.path to indicate the path of the file.
The private key could be stored in a separate file named by
Case 2: Provide different certificates to origins depending on the specific origin name¶
In this case you would again use the
sni.yaml file. The fqdn would correspond to the SNI
that Traffic Server passes to the origin. Specifically you would set the client_cert and possibly the client_key
values to point to the files containing the client certificate and client keys.
When setting up this case, it is important to understand what value Traffic Server will be using for the SNI name
to origin. By default the value of the Host header in the request to origin will be used for the ssl_server_name
fqdn lookup. If
proxy.config.url_remap.pristine_host_hdr is set, this will be the same host header
value as in the user agent request. You can use
proxy.config.ssl.client.sni_policy to change
Traffic Server to use the remap hostname instead as the fqdn lookup value,
Case 3: Provide different certificates to origins depending on origin name and request URL¶
In this case you use the conf_remap.so plugin on a remap rule to override the cient_cert definition only for
URLs that match that remap rule. You could create the following lines in your
remap.config to override
the value of
records.yaml for specific types of
traffic. In the example below any client traffic with a path that starts with /case1 will use the
customer-case1.pem certificate. Any client traffic directed to the hostname bank.example.com and a path that
starts with /pci will use the pci.pem certificate.
map /case1 https://server.com/case1 @plugin=conf_remap.so @pparam=proxy.config.ssl.client.cert.filename=customer-case1.pem map /case2 https://server.com/case2 @plugin=conf_remap.so @pparam=proxy.config.ssl.client.cert.filename=customer-case2.pem map https://bank.example.com/pci https://pci.server.com/ @plugin=conf_remap.so @param=proxy.config.ss.client.cert.filename=pci.pem
Guidance for testing¶
You will want to verify that Traffic Server will accurately reload to pick up new client certificate files. As time goes one, the life time of certificates shrink from months to weeks or days, so you will most likely need to have Traffic Server reload configurations to load up new certificates without restarting the Traffic Server process (and interrupting customer traffic). The following command should cause updated client certificates and keys to be loaded into the traffic_server process. From there you can verify via your origins that the updated certificates are being offered.
traffic_ctl config reload
If the contents of the certificate files change but the names of the files do not, you may need to touch ssl_multicert.config (for server certs) and sni.yaml (for client certs).