From 54b1cb971d96804a46b36947ee7e3d0f4f98b34c Mon Sep 17 00:00:00 2001 From: Peter Schultz Date: Thu, 14 Dec 2017 20:29:41 +0100 Subject: [PATCH] Clarify docs on trusted_ca (#343) CertificateValidationContext.trusted_ca is not only for client certificates, but also for server certs. Change the wording to "peer certificates". Also mention that verification is not enabled by default in docs for UpstreamTlsContext. Signed-off-by: Peter Schultz --- api/cds.proto | 6 ++++ api/sds.proto | 10 ++++-- docs/root/intro/arch_overview/ssl.rst | 52 +++++++++++++++++++++++++++ 3 files changed, 65 insertions(+), 3 deletions(-) diff --git a/api/cds.proto b/api/cds.proto index 08419ce5..34459df9 100644 --- a/api/cds.proto +++ b/api/cds.proto @@ -153,6 +153,12 @@ message Cluster { // The TLS configuration for connections to the upstream cluster. If no TLS // configuration is specified, TLS will not be used for new connections. + // + // .. attention:: + // + // Server certificate verification is not enabled by default. Configure + // :ref:`trusted_ca` to enable + // verification. UpstreamTlsContext tls_context = 11; oneof protocol_options { diff --git a/api/sds.proto b/api/sds.proto index f9699da2..172e0eba 100644 --- a/api/sds.proto +++ b/api/sds.proto @@ -139,14 +139,18 @@ message TlsSessionTicketKeys { message CertificateValidationContext { // TLS certificate data containing certificate authority certificates to use in verifying - // a presented client side certificate. If not specified and a client certificate is presented it - // will not be verified. By default, a client certificate is optional, unless one of the - // additional options (:ref:`require_client_certificate + // a presented peer certificate (e.g. server certificate for clusters or client certificate + // for listeners). If not specified and a peer certificate is presented it will not be + // verified. By default, a client certificate is optional, unless one of the additional + // options (:ref:`require_client_certificate // `, // :ref:`verify_certificate_hash // `, or // :ref:`verify_subject_alt_name // `) is also specified. + // + // See :ref:`the TLS overview ` for a list of common + // system CA locations. DataSource trusted_ca = 1; // If specified, Envoy will verify (pin) the hex-encoded SHA-256 hash of diff --git a/docs/root/intro/arch_overview/ssl.rst b/docs/root/intro/arch_overview/ssl.rst index ad6d0d08..508795eb 100644 --- a/docs/root/intro/arch_overview/ssl.rst +++ b/docs/root/intro/arch_overview/ssl.rst @@ -29,6 +29,58 @@ Underlying implementation Currently Envoy is written to use `BoringSSL `_ as the TLS provider. +.. _arch_overview_ssl_enabling_verification: + +Enabling certificate verification +--------------------------------- + +Certificate verification of both upstream and downstream connections is not enabled unless the +validation context specifies one or more trusted authority certificates. + +Example configuration +^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: yaml + + static_resources: + listeners: + - name: listener_0 + address: { socket_address: { address: 127.0.0.1, port_value: 10000 } } + filter_chains: + - filters: + - name: envoy.http_connection_manager + # ... + tls_context: + common_tls_context: + validation_context: + trusted_ca: + filename: /usr/local/my-client-ca.crt + clusters: + - name: some_service + connect_timeout: 0.25s + type: STATIC + lb_policy: ROUND_ROBIN + hosts: [{ socket_address: { address: 127.0.0.2, port_value: 1234 }}] + tls_context: + common_tls_context: + validation_context: + trusted_ca: + filename: /etc/ssl/certs/ca-certificates.crt + +*/etc/ssl/certs/ca-certificates.crt* is the default path for the system CA bundle on Debian systems. +This makes Envoy verify the server identity of *127.0.0.2:1234* in the same way as e.g. cURL does on +standard Debian installations. Common paths for system CA bundles on Linux and BSD are + +* /etc/ssl/certs/ca-certificates.crt (Debian/Ubuntu/Gentoo etc.) +* /etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem (CentOS/RHEL 7) +* /etc/pki/tls/certs/ca-bundle.crt (Fedora/RHEL 6) +* /etc/ssl/ca-bundle.pem (OpenSUSE) +* /usr/local/etc/ssl/cert.pem (FreeBSD) +* /etc/ssl/cert.pem (OpenBSD) + +See the reference for :ref:`UpstreamTlsContexts ` and +:ref:`DownstreamTlsContexts ` for other TLS options. + .. _arch_overview_ssl_auth_filter: Authentication filter