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