trafficserver-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From jpe...@apache.org
Subject git commit: doc: update ssl_multicert.config documentation
Date Thu, 08 Aug 2013 21:14:01 GMT
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 <jpeach@apache.org>
Authored: Thu Aug 8 14:12:07 2013 -0700
Committer: James Peach <jpeach@apache.org>
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
 


Mime
View raw message