You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@trafficserver.apache.org by ml...@apache.org on 2013/10/09 22:28:25 UTC
svn commit: r1530785 - in /trafficserver/site/trunk/content/docs/trunk/admin:
configuration-files/ssl_multicert.config.en.mdtext
getting-started/index.en.mdtext security-options/index.en.mdtext
Author: mlibbey
Date: Wed Oct 9 20:28:25 2013
New Revision: 1530785
URL: http://svn.apache.org/r1530785
Log:
sync security options with the sphinx docs
Modified:
trafficserver/site/trunk/content/docs/trunk/admin/configuration-files/ssl_multicert.config.en.mdtext
trafficserver/site/trunk/content/docs/trunk/admin/getting-started/index.en.mdtext
trafficserver/site/trunk/content/docs/trunk/admin/security-options/index.en.mdtext
Modified: trafficserver/site/trunk/content/docs/trunk/admin/configuration-files/ssl_multicert.config.en.mdtext
URL: http://svn.apache.org/viewvc/trafficserver/site/trunk/content/docs/trunk/admin/configuration-files/ssl_multicert.config.en.mdtext?rev=1530785&r1=1530784&r2=1530785&view=diff
==============================================================================
--- trafficserver/site/trunk/content/docs/trunk/admin/configuration-files/ssl_multicert.config.en.mdtext (original)
+++ trafficserver/site/trunk/content/docs/trunk/admin/configuration-files/ssl_multicert.config.en.mdtext Wed Oct 9 20:28:25 2013
@@ -26,47 +26,81 @@ address assigned to it, then you can ass
certificate to be served when a client requests a particular IP
address.
+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 ssl_multicert.config can be applied to a running
+Traffic Server using traffic_line -x.
+
# Format # {#Format}
-The format of the `ssl_multicert.config` file is:
+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=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`](../records.config#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`](../records.config#proxy.config.ssl.server.private_key.path) configuration variable.
+
- dest_ip=ipaddress ssl_cert_name=cert_name ssl_key_name=key_name
+*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`](../records.config#proxy.config.ssl.CA.cert.path) configuration variable.
-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 [`records.config`](../records.config)'s
-[`proxy.config.ssl.CA.cert.filename`](../records.config#proxy.config.ssl.CA.cert.filename).
-
-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).
+Certificate Selection
+=====================
-# Examples # {#Examples}
+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.
+
+
+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.
+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=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
Modified: trafficserver/site/trunk/content/docs/trunk/admin/getting-started/index.en.mdtext
URL: http://svn.apache.org/viewvc/trafficserver/site/trunk/content/docs/trunk/admin/getting-started/index.en.mdtext?rev=1530785&r1=1530784&r2=1530785&view=diff
==============================================================================
--- trafficserver/site/trunk/content/docs/trunk/admin/getting-started/index.en.mdtext (original)
+++ trafficserver/site/trunk/content/docs/trunk/admin/getting-started/index.en.mdtext Wed Oct 9 20:28:25 2013
@@ -63,6 +63,7 @@ In order to build Traffic Server from so
* flex (for TPROXY)
* hwloc
* lua
+* g++
if you're building from a git clone, you'll also need
Modified: trafficserver/site/trunk/content/docs/trunk/admin/security-options/index.en.mdtext
URL: http://svn.apache.org/viewvc/trafficserver/site/trunk/content/docs/trunk/admin/security-options/index.en.mdtext?rev=1530785&r1=1530784&r2=1530785&view=diff
==============================================================================
--- trafficserver/site/trunk/content/docs/trunk/admin/security-options/index.en.mdtext (original)
+++ trafficserver/site/trunk/content/docs/trunk/admin/security-options/index.en.mdtext Wed Oct 9 20:28:25 2013
@@ -106,32 +106,24 @@ Server connections, you must do the foll
Traffic Server and exchange encryption keys.
* Configure SSL termination options:
* Enable the **SSL termination** option.
- * Set the port number used for SSL communication.
- * Specify the filename and location of the server certificate.
+ * Set the port number used for SSL communication using proxy.config.http.server_ports.
+ * Edit ssl_multicert.config to specify the filename and location of the server certificate.
* (Optional) Configure the use of client certificates:
Client certificates are located on the client. If you configure Traffic Server to require client
certificates, then Traffic Server verifies the client certificate during the SSL handshake that
authenticates the client. If you configure Traffic Server to _not_ require client certificates,
then access to Traffic Server is managed through other Traffic Server options that have been set
(such as rules in the [`ip_allow.config`](../configuration-files/ip_allow.config) file).
- * Specify the filename and location of the Traffic Server private key (if the private key is not
- located in the server certificate file).
- Traffic Server uses its private key during the SSL handshake to decrypt the session encryption keys.
- The private key must be stored and protected against theft.
* (Optional) Configure the use of Certification Authorities (CAs).
CAs add security by verifying the identity of the person requesting a certificate.
In order to accomplish this, we
2. Edit the following variables in the `SSL Termination` section of the `records.config` file:
- * [_`proxy.config.ssl.enabled`_](../configuration-files/records.config#proxy.config.ssl.enabled)
- * [_`proxy.config.ssl.server_port`_](../configuration-files/records.config#proxy.config.ssl.server_port)
+ * [_`proxy.config.http.server_ports`_](../configuration-files/records.config#proxy.config.http.server_ports)
* [_`proxy.config.ssl.client.certification_level`_](../configuration-files/records.config#proxy.config.ssl.client.certification_level)
- * [_`proxy.config.ssl.server.cert.filename`_](../configuration-files/records.config#proxy.config.ssl.server.cert.filename)
* [_`proxy.config.ssl.server.cert.path`_](../configuration-files/records.config#proxy.config.ssl.server.cert.path)
- * [_`proxy.config.ssl.server.private_key.filename`_](../configuration-files/records.config#proxy.config.ssl.server.private_key.filename)
* [_`proxy.config.ssl.server.private_key.path`_](../configuration-files/records.config#proxy.config.ssl.server.private_key.path)
- * [_`proxy.config.ssl.CA.cert.filename`_](../configuration-files/records.config#proxy.config.ssl.CA.cert.filename)
* [_`proxy.config.ssl.CA.cert.path`_](../configuration-files/records.config#proxy.config.ssl.CA.cert.path)
6. Run the command `traffic_line -L` to restart Traffic Server on the local node or `traffic_line -M` to restart Traffic Server on all the nodes in a cluster.
@@ -185,7 +177,7 @@ In order to accomplish this, we:
2. Edit the following variables in the `SSL Termination` section of the `records.config` file:
* [_`proxy.config.ssl.auth.enabled`_](../configuration-files/records.config#proxy.config.ssl.auth.enabled)
- * [`proxy.config.ssl.server_port`](../configuration-files/records.config#proxy.config.ssl.server_port)
+ * [`proxy.config.http.server_ports`](../configuration-files/records.config#proxy.config.http.server_ports)
* [`proxy.config.ssl.client.verify.server`](../configuration-files/records.config#proxy.config.ssl.client.verify.server)
* [`proxy.config.ssl.client.cert.filename`](../configuration-files/records.config#proxy.config.ssl.client.cert.filename)
* [`proxy.config.ssl.client.cert.path`](../configuration-files/records.config#proxy.config.ssl.client.cert.path)