Mututal TLS

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 proxy.config.ssl.client.certification_level setting in 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 proxy.config.ssl.CA.cert.path and proxy.config.ssl.CA.cert.filename in 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 sni.yaml file.

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 following in sni.yaml.

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.yaml

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.yaml policy.

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 sni.yaml. 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.yaml

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:1.2.3.4 -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 proxy.config.ssl.client.private_key.filename and proxy.config.ssl.client.private_key.path.

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 proxy.config.ssl.client.cert.filename in 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).