Updated Branches: refs/heads/master 8d7122339 -> 689c6206a
doc: update ssl_multicert.config documentation Project: http://git-wip-us.apache.org/repos/asf/trafficserver/repo Commit: http://git-wip-us.apache.org/repos/asf/trafficserver/commit/689c6206 Tree: http://git-wip-us.apache.org/repos/asf/trafficserver/tree/689c6206 Diff: http://git-wip-us.apache.org/repos/asf/trafficserver/diff/689c6206 Branch: refs/heads/master Commit: 689c6206ad55f87d2061d015c6a4025cb4a006d1 Parents: 8d71223 Author: James Peach <[email protected]> Authored: Thu Aug 8 14:12:07 2013 -0700 Committer: James Peach <[email protected]> Committed: Thu Aug 8 14:12:27 2013 -0700 ---------------------------------------------------------------------- .../configuration/ssl_multicert.config.en.rst | 123 +++++++++++++------ 1 file changed, 85 insertions(+), 38 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/trafficserver/blob/689c6206/doc/reference/configuration/ssl_multicert.config.en.rst ---------------------------------------------------------------------- diff --git a/doc/reference/configuration/ssl_multicert.config.en.rst b/doc/reference/configuration/ssl_multicert.config.en.rst index 8a11e9b..9ce8e93 100644 --- a/doc/reference/configuration/ssl_multicert.config.en.rst +++ b/doc/reference/configuration/ssl_multicert.config.en.rst @@ -21,61 +21,108 @@ ssl_multicert.config .. configfile:: ssl_multicert.config -The :file:`ssl_multicert.config` file lets you configure Traffic Server to -use multiple SSL server certificates with the SSL termination option. 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. +The :file:`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 +<http://en.wikipedia.org/wiki/SubjectAltName>`_. 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 :file:`ssl_multicert.config` can be applied to a running +Traffic Server using :option:`traffic_line -x`. Format ====== -The format of the :file:`ssl_multicert.config` file is: +Each :file:`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=PATH + The name of the file containing the TLS certificate. `PATH` is + located relative to the directory specified by the + ``proxy.config.ssl.server.cert.path`` configuration variable. + This is the only field that is required to be present. + +dest_ip=ADDRESS + 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 + SubjectNameIndication 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. + +ssl_key_name=PATH + 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 `PATH` is resolved relative to the + ``proxy.config.ssl.server.private_key.path`` configuration variable. + +ssl_ca_name=FILENAME + 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. `PATH` is resolved relative to the + ``proxy.config.ssl.CA.cert.path`` configuration variable. + +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 +<http://en.wikipedia.org/wiki/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. -:: - - dest_ip=ipaddress ssl_cert_name=cert_name ssl_key_name=key_name - -where ``ipaddress`` is an IP address assigned to Traffic Server , -``ssl_cert_name`` is the filename of the Traffic Server SSL server -certificate, ``ssl_key_name`` is the filename of the Traffic Server -SSL private key. If the private key is located in the certificate file, -then you do not need to specify the name of the private key. -Additionally ``ssl_ca_name`` can be used to specify the location of a -Certification Authorithy change in case that differs from what is -specified under the :file:`records.config` -``proxy.config.ssl.CA.cert.filename`` value. - -Traffic Server will try to find the files specified in -*``ssl_cert_name``* relative to -```proxy.config.ssl.server.cert.path`` <../records.config#proxy.config.ssl.server.cert.path>`_, -*``ssl_key_name``* relative to -```proxy.config.ssl.server.private_key.path`` <../records.config#proxy.config.ssl.server.private_key.path>`_, -and *``ssl_ca_name``* relative to -```proxy.config.ssl.CA.cert.path`` <../records.config#proxy.config.ssl.CA.cert.path>`_. 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. Since the private key *is* included in the -certificate files, no private key name is specified. +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=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 SSL -certificate ``server.pem`` and the private key ``serverKey.pem`` for all -requests to the IP address 111.11.11.1. Traffic Server uses the SSL -certificate ``server1.pem`` and the private key ``serverKey1.pem`` for -all requests to the IP address 11.1.1.1. +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 ssl_cert_name=server.pem ssl_key_name=serverKey.pem - dest_ip=11.1.1.1 ssl_cert_name=server1.pem ssl_key_name=serverKey1.pem + dest_ip=111.11.11.1:8443 ssl_cert_name=server.pem ssl_key_name=serverKey.pem + ssl_cert_name=general.pem
