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 <peter.schultz@classmarkets.com>

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<envoy_api_field_CertificateValidationContext.trusted_ca>` to enable
+  //   verification.
   UpstreamTlsContext tls_context = 11;
 
   oneof protocol_options {

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
+  // a presented peer certificate (e.g. server certificate for clusters or client certificate
-  // will not be verified. By default, a client certificate is optional, unless one of the
+  // for listeners). If not specified and a peer certificate is presented it will not be
-  // additional options (:ref:`require_client_certificate
+  // verified. By default, a client certificate is optional, unless one of the additional
+  // options (:ref:`require_client_certificate
   // <envoy_api_field_DownstreamTlsContext.require_client_certificate>`,
   // :ref:`verify_certificate_hash
   // <envoy_api_field_CertificateValidationContext.verify_certificate_hash>`, or
   // :ref:`verify_subject_alt_name
   // <envoy_api_field_CertificateValidationContext.verify_subject_alt_name>`) is also specified.
+  //
+  // See :ref:`the TLS overview <arch_overview_ssl_enabling_verification>` 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

docs/root/intro/arch_overview/ssl.rst

@@ -29,6 +29,58 @@ Underlying implementation
 Currently Envoy is written to use `BoringSSL <https://boringssl.googlesource.com/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 <envoy_api_msg_UpstreamTlsContext>` and
+:ref:`DownstreamTlsContexts <envoy_api_msg_DownstreamTlsContext>` for other TLS options.
+
 .. _arch_overview_ssl_auth_filter:
 
 Authentication filter