You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@trafficserver.apache.org by ig...@apache.org on 2013/04/18 11:56:51 UTC
[07/25] git commit: another warnings free file.
another warnings free file.
Project: http://git-wip-us.apache.org/repos/asf/trafficserver/repo
Commit: http://git-wip-us.apache.org/repos/asf/trafficserver/commit/86f4f5c5
Tree: http://git-wip-us.apache.org/repos/asf/trafficserver/tree/86f4f5c5
Diff: http://git-wip-us.apache.org/repos/asf/trafficserver/diff/86f4f5c5
Branch: refs/heads/sphinx-docs
Commit: 86f4f5c596597647fc2067022f86bf5502924ea5
Parents: 00b60cd
Author: Igor Galić <i....@brainsware.org>
Authored: Thu Mar 14 22:14:25 2013 +0100
Committer: Igor Galić <i....@brainsware.org>
Committed: Thu Mar 14 22:14:25 2013 +0100
----------------------------------------------------------------------
doc/source/admin/security-options.en.rst | 247 +++++++++++++++++++++++++
1 files changed, 247 insertions(+), 0 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/86f4f5c5/doc/source/admin/security-options.en.rst
----------------------------------------------------------------------
diff --git a/doc/source/admin/security-options.en.rst b/doc/source/admin/security-options.en.rst
new file mode 100644
index 0000000..9fa423a
--- /dev/null
+++ b/doc/source/admin/security-options.en.rst
@@ -0,0 +1,247 @@
+:title: Security Options Notice: Licensed to the Apache Software
+
+.. Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+Traffic Server provides a number of security features.
+
+This chapter discusses the following topics:
+
+.. toctree::
+ :maxdepth: 2
+
+Controlling Client Access to the Proxy Cache
+============================================
+
+You can configure Traffic Server to allow only certain clients to use
+the proxy cache by editing a configuration file.
+
+2. Add a line in the file ``ip_allow.config`` for each IP address or
+ range of IP addresses allowed to access Traffic Server (refer to
+ `ip\_allow.config <configuration-files/ip_allow.config>`_).
+3. Run the command ``traffic_line -x`` to apply the configuration
+ changes.
+
+Configuring DNS Server Selection (Split DNS)
+============================================
+
+The **Split DNS** option enables you to configure Traffic Server to use
+multiple DNS servers, as dictated by your security requirements. For
+example, you might configure Traffic Server to use one set of DNS
+servers to resolve hostnames on your internal network, while allowing
+DNS servers outside the firewall to resolve hosts on the Internet. This
+maintains the security of your intranet, while continuing to provide
+direct access to sites outside your organization.
+
+To configure Split DNS, you must do the following:
+
+- Specify the rules for performing DNS server selection based on the
+ destination domain, the destination host, or a URL regular
+ expression.
+- Enable the **Split DNS** option.
+
+To do this, we
+
+2. Add rules to the ``splitdns.config`` file. (Refer to
+ ```splitdns.config`` <../configuration-files/splitdns.config>`_.
+3. In the file ``records.config`` the variable
+ `*``proxy.process.dns.splitDNS.enabled``* <configuration-files/records.config#proxy.process.dns.splitDNS.enabled>`_
+ to ``1`` to enable split DNS.
+4. Run the command ``traffic_line -x`` to apply the configuration
+ changes.
+
+Using SSL Termination
+=====================
+
+The Traffic Server **SSL termination** option enables you to secure
+connections in reverse proxy mode between a client and a Traffic Server
+and/or Traffic Server and an origin server.
+
+The following sections describe how to enable and configure the SSL
+termination option.
+
+- Enable and configure SSL termination for client/Traffic Server
+ connections: `Client and Traffic Server
+ Connections <#ClientTSConnections>`_.
+- Enable and configure SSL termination for Traffic Server/origin server
+ connections: `Traffic Server and Origin Server
+ Connections <#TSOriginServerConnections>`_.
+- Enable and configure SSL termination for both client/Traffic Server
+ and Traffic Server/origin server connections: `Client and Traffic
+ Server Connections <#ClientTSConnections>`_ and `Traffic Server and
+ Origin Server Connections <#TSOriginServerConnections>`_,
+ respectively.
+
+Client and Traffic Server Connections
+-------------------------------------
+
+The figure below illustrates communication between a client and Traffic
+Server (and between Traffic Server and an origin server) when the SSL
+termination option is enabled & configured for\ *\* client/Traffic
+Server connections only*\ \*.
+
+.. figure:: _static/images/admin/ssl_c.jpg
+ :align: center
+ :alt: Client and Traffic Server communication using SSL termination
+
+ Client and Traffic Server communication using SSL termination
+
+The figure above depicts the following:
+
+**Step 1:** The client sends an HTTPS request for content. Traffic
+Server receives the request and performs the SSL 'handshake' to
+authenticate the client (depending on the authentication options
+configured) and determine the encryption method that will be used. If
+the client is allowed access, then Traffic Server checks its cache for
+the requested content.
+
+**Step 2:** If the request is a cache hit and the content is fresh, then
+Traffic Server encrypts the content and sends it to the client. The
+client decrypts the content (using the method determined during the
+handshake) and displays it.
+
+**Step 3:** If the request is a cache miss or cached content is stale,
+then Traffic Server communicates with the origin server via HTTP and
+obtains a plain text version of the content. Traffic Server saves the
+plain text version of the content in its cache, encrypts the content,
+and sends it to the client. The client decrypts and displays the
+content.
+
+To configure Traffic Server to use the SSL termination option for
+client/Traffic Server connections, you must do the following:
+
+- Obtain and install an SSL server certificate from a recognized
+ certificate authority. The SSL server certificate contains
+ information that enables the client to authenticate 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.
+ - (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.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>`_
+
+3. 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.
+
+Traffic Server and Origin Server Connections
+--------------------------------------------
+
+The figure below illustrates communication between Traffic Server and an
+origin server when the SSL termination option is enabled for **Traffic
+Server/origin server connections**.
+
+.. figure:: _static/images/admin/ssl_os.jpg
+ :align: center
+ :alt: Traffic Server and origin server communication using SSL termination
+
+ Traffic Server and origin server communication using SSL termination
+
+The figure above depicts the following:
+
+**Step 1:** If a client request is a cache miss or is stale, then
+Traffic Server sends an HTTPS request for the content to the origin
+server. The origin server receives the request and performs the SSL
+handshake to authenticate Traffic Server and determine the encryption
+method to be used.
+
+**Step 2:** If Traffic Server is allowed access, then the origin server
+encrypts the content and sends it to Traffic Server, where it is
+decrypted (using the method determined during the handshake). A plain
+text version of the content is saved in the cache.
+
+**Step 3:** If SSL termination is enabled for client /Traffic Server
+connections, then Traffic Server re-encrypts the content and sends it to
+the client via HTTPS, where it is decrypted and displayed. If SSL
+termination is not enabled for client/Traffic Server connections, then
+Traffic Server sends the plain text version of the content to the client
+via HTTP.
+
+To configure Traffic Server to use the SSL termination option for
+Traffic Server and origin server connections, you must do the following:
+
+- Obtain and install an SSL client certificate from a recognized
+ certificate authority. The SSL client certificate contains
+ information that allows the origin server to authenticate Traffic
+ Server (the client certificate is optional).
+- Configure SSL termination options:
+- Enable the SSL termination option.
+
+ - Set the port number used for SSL communication.
+ - Specify the filename and location of the SSL client certificate
+ (if you choose to use a client certificate).
+ - Specify the filename and location of the Traffic Server private
+ key (if the private key is not located in the client 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.
+ - Configure the use of CAs. CAs allow the Traffic Server that's
+ acting as a client to verify the identity of the server with which
+ it is communicating, thereby enabling exchange of encryption keys.
+
+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.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>`_
+ - ```proxy.config.ssl.client.private_key.filename`` <configuration-files/records.config#proxy.config.ssl.client.private_key.filename>`_
+ - ```proxy.config.ssl.client.private_key.path`` <configuration-files/records.config#proxy.config.ssl.client.private_key.path>`_
+ - ```proxy.config.ssl.client.CA.cert.filename`` <configuration-files/records.config#proxy.config.ssl.client.CA.cert.filename>`_
+ - ```proxy.config.ssl.client.CA.cert.path`` <configuration-files/records.config#proxy.config.ssl.client.CA.cert.path>`_
+
+3. 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.
+