Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: SSL -> TLS #22

Merged
merged 1 commit into from
Aug 18, 2016
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/_static/double_proxy.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
2 changes: 1 addition & 1 deletion docs/_static/front_proxy.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
6 changes: 3 additions & 3 deletions docs/configuration/cluster_manager/cluster.rst
Original file line number Diff line number Diff line change
Expand Up @@ -116,8 +116,8 @@ max_retries
<arch_overview_circuit_break>` for more information.

:ref:`ssl_context <config_cluster_manager_cluster_ssl>`
*(optional, object)* The SSL configuration for connections to the upstream cluster. If no SSL
configuration is specified, SSL will not be used for new connections.
*(optional, object)* The TLS configuration for connections to the upstream cluster. If no TLS
configuration is specified, TLS will not be used for new connections.

.. _config_cluster_manager_cluster_features:

Expand All @@ -128,7 +128,7 @@ features
http2
If *http2* is specified, Envoy will assume that the upstream supports HTTP/2 when making new
HTTP connection pool connections. Currently, Envoy only supports prior knowledge for upstream
connections. Even if SSL is used with ALPN, *http2* must be specified. As an aside this allows
connections. Even if TLS is used with ALPN, *http2* must be specified. As an aside this allows
HTTP/2 connections to happen over plain text.

.. _config_cluster_manager_cluster_http_codec_options:
Expand Down
8 changes: 4 additions & 4 deletions docs/configuration/cluster_manager/cluster_ssl.rst
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
.. _config_cluster_manager_cluster_ssl:

SSL context
TLS context
===========

.. code-block:: json
Expand All @@ -27,7 +27,7 @@ alpn_protocols

cert_chain_file
*(optional, string)* The certificate chain file that should be served by the connection. This is
used to provide a client side SSL certificate to an upstream host.
used to provide a client side TLS certificate to an upstream host.

private_key_file
*(optional, string)* The private key that corresponds to the certificate chain file.
Expand All @@ -45,9 +45,9 @@ verify_subject_alt_name
name matches the specified value.

cipher_suites
*(optional, string)* If specified, the SSL connection will only support the specified cipher list.
*(optional, string)* If specified, the TLS connection will only support the specified cipher list.
If not specified, a default list will be used.

sni
*(optional, string)* If specified, the string will be presented as the SNI during the SSL
*(optional, string)* If specified, the string will be presented as the SNI during the TLS
handshake.
2 changes: 1 addition & 1 deletion docs/configuration/http_conn_man/headers.rst
Original file line number Diff line number Diff line change
Expand Up @@ -47,7 +47,7 @@ Internal services often want to know which service is calling them. This header
external requests, but for internal requests will contain the service cluster of the caller. Note
that in the current implementation, this should be considered a hint as it is set by the caller and
could be easily spoofed by any internal entity. In the future Envoy will support a mutual
authentication SSL mesh which will make this header fully secure. Like *user-agent*, the value
authentication TLS mesh which will make this header fully secure. Like *user-agent*, the value
is determined by the :option:`--service-cluster` command line option.

.. _config_http_conn_man_headers_x-envoy-external-address:
Expand Down
4 changes: 2 additions & 2 deletions docs/configuration/http_conn_man/http_conn_man.rst
Original file line number Diff line number Diff line change
Expand Up @@ -37,11 +37,11 @@ codec_type

http2
The connection manager will assume that the client is speaking HTTP/2 (Envoy does not require
HTTP/2 to take place over SSL or to use ALPN. Prior knowledge is allowed).
HTTP/2 to take place over TLS or to use ALPN. Prior knowledge is allowed).

auto
For every new connection, the connection manager will determine which codec to use. This mode
supports both ALPN for SSL listeners as well as protocol inference for plaintext listeners.
supports both ALPN for TLS listeners as well as protocol inference for plaintext listeners.
If ALPN data is available, it is preferred, otherwise protocol inference is used. In almost
all cases, this is the right option to choose for this setting.

Expand Down
8 changes: 4 additions & 4 deletions docs/configuration/http_conn_man/route_config/vhost.rst
Original file line number Diff line number Diff line change
Expand Up @@ -34,18 +34,18 @@ domains
The first route that matches will be used.

require_ssl
*(optional, string)* Specifies the type of SSL enforcement the virtual host expects. Possible
*(optional, string)* Specifies the type of TLS enforcement the virtual host expects. Possible
values are:

all
All requests must use SSL. If a request is not using SSL, a 302 redirect will be sent telling
All requests must use TLS. If a request is not using TLS, a 302 redirect will be sent telling
the client to use HTTPS.

external_only
External requests must use SSL. If a request is external and it is not using SSL, a 302 redirect
External requests must use TLS. If a request is external and it is not using TLS, a 302 redirect
will be sent telling the client to use HTTPS.

If this option is not specified, there is no SSL requirement for the virtual host.
If this option is not specified, there is no TLS requirement for the virtual host.

:ref:`virtual_clusters <config_http_conn_man_route_table_vcluster>`
*(optional, array)* A list of virtual clusters defined for this virtual host. Virtual clusters
Expand Down
4 changes: 2 additions & 2 deletions docs/configuration/http_conn_man/stats.rst
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ statistics:
:widths: 1, 1, 2

downstream_cx_total, Counter, Total connections
downstream_cx_ssl_total, Counter, Total SSL connections
downstream_cx_ssl_total, Counter, Total TLS connections
downstream_cx_http1_total, Counter, Total HTTP/1.1 connections
downstream_cx_http2_total, Counter, Total HTTP/2 connections
downstream_cx_destroy, Counter, Total connections destroyed
Expand All @@ -21,7 +21,7 @@ statistics:
downstream_cx_destroy_local_active_rq, Counter, Total connections destroyed locally with 1+ active request
downstream_cx_destroy_remote_active_rq, Counter, Total connections destroyed remotely with 1+ active request
downstream_cx_active, Gauge, Total active connections
downstream_cx_ssl_active, Gauge, Total active SSL connections
downstream_cx_ssl_active, Gauge, Total active TLS connections
downstream_cx_http1_active, Gauge, Total active HTTP/1.1 connections
downstream_cx_http2_active, Gauge, Total active HTTP/2 connections
downstream_cx_protocol_error, Counter, Total protocol errors
Expand Down
4 changes: 2 additions & 2 deletions docs/configuration/listeners/listeners.rst
Original file line number Diff line number Diff line change
Expand Up @@ -25,8 +25,8 @@ port
filters are processed sequentially as connection events happen.

:ref:`ssl_context <config_listener_ssl_context>`
*(optional, object)* The :ref:`SSL <arch_overview_ssl>` context configuration for an SSL listener.
If no SSL context block is defined, the listener is a plain text listener.
*(optional, object)* The :ref:`TLS <arch_overview_ssl>` context configuration for a TLS listener.
If no TLS context block is defined, the listener is a plain text listener.

use_proxy_proto
*(optional, boolean)* Whether the listener should expect a
Expand Down
6 changes: 3 additions & 3 deletions docs/configuration/listeners/ssl.rst
Original file line number Diff line number Diff line change
@@ -1,9 +1,9 @@
.. _config_listener_ssl_context:

SSL context
TLS context
===========

SSL :ref:`architecture overview <arch_overview_ssl>`.
TLS :ref:`architecture overview <arch_overview_ssl>`.

.. code-block:: json

Expand Down Expand Up @@ -53,5 +53,5 @@ verify_subject_alt_name
name matches the specified value.

cipher_suites
*(optional, string)* If specified, the SSL listener will only support the specified cipher list.
*(optional, string)* If specified, the TLS listener will only support the specified cipher list.
If not specified, a default list will be used.
12 changes: 6 additions & 6 deletions docs/configuration/listeners/stats.rst
Original file line number Diff line number Diff line change
Expand Up @@ -13,9 +13,9 @@ Every listener has a statistics tree rooted at *listener.<port>.* with the follo
downstream_cx_destroy, Counter, Total destroyed connections
downstream_cx_active, Gauge, Total active connections
downstream_cx_length_ms, Timer, Connection length milliseconds
ssl.connection_error, Counter, Total SSL connection errors
ssl.handshake, Counter, Total SSL connection handshakes
ssl.no_certificate, Counter, Total SSL connections with no client certificate
ssl.fail_verify_san, Counter, Total SSL connections that failed SAN verification
ssl.fail_verify_cert_hash, Counter, Total SSL connections that failed certificate pinning verification
ssl.cipher.<cipher>, Counter, Total SSL connections that used <cipher>
ssl.connection_error, Counter, Total TLS connection errors
ssl.handshake, Counter, Total TLS connection handshakes
ssl.no_certificate, Counter, Total TLS connections with no client certificate
ssl.fail_verify_san, Counter, Total TLS connections that failed SAN verification
ssl.fail_verify_cert_hash, Counter, Total TLS connections that failed certificate pinning verification
ssl.cipher.<cipher>, Counter, Total TLS connections that used <cipher>
10 changes: 5 additions & 5 deletions docs/configuration/network_filters/client_ssl_auth_filter.rst
Original file line number Diff line number Diff line change
@@ -1,9 +1,9 @@
.. _config_network_filters_client_ssl_auth:

Client SSL authentication
Client TLS authentication
=========================

Client SSL authentication filter :ref:`architecture overview <arch_overview_ssl_auth_filter>`.
Client TLS authentication filter :ref:`architecture overview <arch_overview_ssl_auth_filter>`.

.. code-block:: json

Expand Down Expand Up @@ -45,7 +45,7 @@ ip_white_list
Statistics
----------

Every configured client SSL authentication filter has statistics rooted at
Every configured client TLS authentication filter has statistics rooted at
*auth.clientssl.<stat_prefix>.* with the following statistics:

.. csv-table::
Expand All @@ -54,7 +54,7 @@ Every configured client SSL authentication filter has statistics rooted at

update_success, Counter, Total principal update successes
update_failure, Counter, Total principal update failures
auth_no_ssl, Counter, Total connections ignored due to no SSL
auth_no_ssl, Counter, Total connections ignored due to no TLS
auth_ip_white_list, Counter, Total connections allowed due to the IP white list
auth_digest_match, Counter, Total connections allowed due to certificate match
auth_digest_no_match, Counter, Total connections denied due to no certificate match
Expand All @@ -63,7 +63,7 @@ Every configured client SSL authentication filter has statistics rooted at
Runtime
-------

The client SSL authentication filter supports the following runtime settings:
The client TLS authentication filter supports the following runtime settings:

auth.clientssl.refresh_interval_ms
Time in milliseconds between principal refreshes from the authentication service. Default is
Expand Down
2 changes: 1 addition & 1 deletion docs/intro/arch_overview/http_routing.rst
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ request. The router filter supports the following features:
programmatically determine whether routing rules conflict with each other. For this reason we
don’t recommend regex/slug routing at the reverse proxy level, however we may add support in the
future depending on demand.
* SSL redirection at the virtual host level.
* TLS redirection at the virtual host level.
* Path/host redirection at the route level.
* Host rewriting.
* Prefix rewriting.
Expand Down
2 changes: 1 addition & 1 deletion docs/intro/arch_overview/listeners.rst
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ Each listener is independently configured with some number of network level (L3/
<arch_overview_network_filters>`. When a new connection is received on a listener, the configured
connection local filter stack is instantiated and begins processing subsequent events. The generic
listener architecture is used to perform the vast majority of different proxy tasks that Envoy is
used for (e.g., :ref:`rate limiting <arch_overview_rate_limit>`, :ref:`SSL client authentication
used for (e.g., :ref:`rate limiting <arch_overview_rate_limit>`, :ref:`TLS client authentication
<arch_overview_ssl_auth_filter>`, :ref:`HTTP connection management <arch_overview_http_conn_man>`,
MongoDB :ref:`sniffing <arch_overview_mongo>`, raw :ref:`TCP proxy <arch_overview_tcp_proxy>`,
etc.).
Expand Down
2 changes: 1 addition & 1 deletion docs/intro/arch_overview/network_filters.rst
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ filters:
connection and when it is about to send data to a downstream connection.

The API for network level filters is relatively simple since ultimately the filters operate on raw
bytes and a small number of connection events (e.g., SSL handshake complete, connection disconnected
bytes and a small number of connection events (e.g., TLS handshake complete, connection disconnected
locally or remotely, etc.). Filters in the chain can stop and subsequently continue iteration to
further filters. This allows for more complex scenarios such as calling a :ref:`rate limiting
service <arch_overview_rate_limit>`, etc. Envoy already includes several network level filters that
Expand Down
20 changes: 10 additions & 10 deletions docs/intro/arch_overview/ssl.rst
Original file line number Diff line number Diff line change
@@ -1,40 +1,40 @@
.. _arch_overview_ssl:

SSL
TLS
===

Envoy supports both :ref:`SSL termination <config_listener_ssl_context>` in listeners as well as
:ref:`SSL origination <config_cluster_manager_cluster_ssl>` when making connections to upstream
Envoy supports both :ref:`TLS termination <config_listener_ssl_context>` in listeners as well as
:ref:`TLS origination <config_cluster_manager_cluster_ssl>` when making connections to upstream
clusters. Support is sufficient for Envoy to perform standard edge proxy duties for modern web
services as well as to initiate connections with external services that have advanced SSL
requirements (TLS1.2, SNI, etc.). Envoy supports the following SSL features:
services as well as to initiate connections with external services that have advanced TLS
requirements (TLS1.2, SNI, etc.). Envoy supports the following TLS features:

* **Configurable ciphers**: Each SSL listener and client can specify the ciphers that it supports.
* **Configurable ciphers**: Each TLS listener and client can specify the ciphers that it supports.
* **Client certificates**: Upstream/client connections can present a client certificate in addition
to server certificate verification.
* **Certificate verification and pinning**: Certificate verification options include basic chain
verification, subject name verification, and hash pinning.
* **ALPN**: SSL listeners support ALPN. The HTTP connection manager uses this information (in
* **ALPN**: TLS listeners support ALPN. The HTTP connection manager uses this information (in
addition to protocol inference) to determine whether a client is speaking HTTP/1.1 or HTTP/2.
* **SNI**: SNI is currently supported for client connections. Listener support is likely to be added
in the future.

Underlying implementation
-------------------------

Currently Envoy is written to use openssl 1.0.2 as the SSL provider. Swapping in a different
Currently Envoy is written to use openssl 1.0.2 as the TLS provider. Swapping in a different
provider in the future would not be difficult.

.. _arch_overview_ssl_auth_filter:

Authentication filter
---------------------

Envoy provides a network filter that performs SSL client authentication via principals fetched from
Envoy provides a network filter that performs TLS client authentication via principals fetched from
a REST VPN service. This filter matches the presented client certificate hash against the principal
list to determine whether the connection should be allowed or not. Optional IP white listing can
also be configured. This functionality can be used to build edge proxy VPN support for web
infrastructure.

Client SSL authentication filter :ref:`configuration reference
Client TLS authentication filter :ref:`configuration reference
<config_network_filters_client_ssl_auth>`.
6 changes: 3 additions & 3 deletions docs/intro/deployment_types/double_proxy.rst
Original file line number Diff line number Diff line change
Expand Up @@ -6,13 +6,13 @@ Service to service, front proxy, and double proxy

The above diagram shows the :ref:`front proxy <deployment_type_front_proxy>` configuration alongside
another Envoy cluster running as a *double proxy*. The idea behind the double proxy is that it is
more efficient to terminate SSL and client connections as close as possible to the user (shorter
round trip times for the SSL handshake, faster TCP CWND expansion, less chance for packet loss,
more efficient to terminate TLS and client connections as close as possible to the user (shorter
round trip times for the TLS handshake, faster TCP CWND expansion, less chance for packet loss,
etc.). Connections that terminate in the double proxy are then multiplexed onto long lived HTTP/2
connections running in the main data center.

In the above diagram, the front Envoy proxy running in region 1 authenticates itself with the front
Envoy proxy running in region 2 via SSL mutual authentication and pinned certificates. This allows
Envoy proxy running in region 2 via TLS mutual authentication and pinned certificates. This allows
the front Envoy instances running in region 2 to trust elements of the incoming requests that
ordinarily would not be trustable (such as the x-forwaded-for HTTP header).

Expand Down
2 changes: 1 addition & 1 deletion docs/intro/deployment_types/front_proxy.rst
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ The above diagram shows the :ref:`service to service <deployment_type_service_to
configuration sitting behind an Envoy cluster used as an HTTP L7 edge reverse proxy. The
reverse proxy provides the following features:

* Terminates SSL.
* Terminates TLS.
* Supports both HTTP/1.1 and HTTP/2.
* Full HTTP L7 routing support.
* Talks to the service to service Envoy clusters via the standard :ref:`ingress port
Expand Down
4 changes: 2 additions & 2 deletions docs/intro/what_is_envoy.rst
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,7 @@ developer productivity and performance.
:ref:`filter <arch_overview_network_filters>` chain mechanism allows filters to be written to
perform different TCP proxy tasks and inserted into the main server. Filters have already been
written to support various tasks such as raw :ref:`TCP proxy <arch_overview_tcp_proxy>`,
:ref:`HTTP proxy <arch_overview_http_conn_man>`, :ref:`SSL client certificate
:ref:`HTTP proxy <arch_overview_http_conn_man>`, :ref:`TLS client certificate
authentication <arch_overview_ssl_auth_filter>`, etc.

**HTTP L7 filter architecture:** HTTP is such a critical component of modern application
Expand Down Expand Up @@ -93,7 +93,7 @@ shadowing.
communication system, there is benefit in using the same software at the edge (observability,
management, identical service discovery and load balancing algorithms, etc.). Envoy includes enough
features to make it usable as an edge proxy for most modern web application use cases. This includes
:ref:`SSL <arch_overview_ssl>` termination, HTTP/1.1 and HTTP/2 :ref:`support
:ref:`TLS <arch_overview_ssl>` termination, HTTP/1.1 and HTTP/2 :ref:`support
<arch_overview_http_protocols>`, as well as HTTP L7 :ref:`routing <arch_overview_http_routing>`.

**Best in class observability:** As stated above, the primary goal of Envoy is to make the network
Expand Down
2 changes: 1 addition & 1 deletion docs/landing_generated/index.html
Original file line number Diff line number Diff line change
Expand Up @@ -109,7 +109,7 @@ <h4 class="introduction-item-header">
<p><b>HTTP L7 routing:</b> Envoy supports advanced HTTP L7 routing primitives including
redirection, virtual hosts, virtual clusters, matching on different request parameters, etc.
</p>
<p><b>SSL:</b> Envoy supports both SSL termination and initiation, client certificate
<p><b>TLS:</b> Envoy supports both TLS termination and initiation, client certificate
verification, and certificate pinning.</p>
<p><b>GRPC:</b> Envoy has first class support for Google's GRPC framework.</p>
<p><b>MongoDB:</b> Envoy contains a full MongoDB wire format parser that is used to gather
Expand Down
2 changes: 1 addition & 1 deletion docs/landing_source/source/localizable/index.html.erb
Original file line number Diff line number Diff line change
Expand Up @@ -71,7 +71,7 @@ layout: layout
<p><b>HTTP L7 routing:</b> Envoy supports advanced HTTP L7 routing primitives including
redirection, virtual hosts, virtual clusters, matching on different request parameters, etc.
</p>
<p><b>SSL:</b> Envoy supports both SSL termination and initiation, client certificate
<p><b>TLS:</b> Envoy supports both TLS termination and initiation, client certificate
verification, and certificate pinning.</p>
<p><b>GRPC:</b> Envoy has first class support for Google's GRPC framework.</p>
<p><b>MongoDB:</b> Envoy contains a full MongoDB wire format parser that is used to gather
Expand Down
2 changes: 1 addition & 1 deletion docs/operations/admin.rst
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ modify different aspects of the server.

.. http:get:: /certs

List out all loaded SSL certificates, including file name, serial number, and days until
List out all loaded TLS certificates, including file name, serial number, and days until
expiration.

.. http:get:: /clusters
Expand Down