tls: add OCSP stapling support with configurable stapling policy

api/envoy/admin/v3/certs.proto

@@ -34,7 +34,7 @@ message Certificate {
   repeated CertificateDetails cert_chain = 2;
 }
 
-// [#next-free-field: 7]
+// [#next-free-field: 8]
 message CertificateDetails {
   option (udpa.annotations.versioning).previous_message_type =
       "envoy.admin.v2alpha.CertificateDetails";
@@ -56,6 +56,9 @@ message CertificateDetails {
 
   // Indicates the time at which the certificate expires.
   google.protobuf.Timestamp expiration_time = 6;
+
+  // Seconds until expiration of the certificate's OCSP response.
+  uint64 seconds_until_ocsp_response_expiration = 7;
 }
 
 message SubjectAlternateName {

api/envoy/extensions/transport_sockets/tls/v3/common.proto

@@ -151,7 +151,11 @@ message TlsCertificate {
   // TLS private key is not password encrypted.
   config.core.v3.DataSource password = 3 [(udpa.annotations.sensitive) = true];
 
-  // [#not-implemented-hide:]
+  // The OCSP response to be stapled with this certificate during the handshake.
+  // The response must be DER-encoded if provided as a ``filename`` or
+  // ``inline_bytes``, and PEM-encoded if provided through ``inline_string``.
+  // The response must be unexpired as of configuration time and pertain to
+  // only one certificate.
   config.core.v3.DataSource ocsp_staple = 4;
 
   // [#not-implemented-hide:]
@@ -205,7 +209,7 @@ message CertificateValidationContext {
     ACCEPT_UNTRUSTED = 1;
   }
 
-  reserved 4;
+  reserved 4, 5;
 
   reserved "verify_subject_alt_name";
 
@@ -312,9 +316,6 @@ message CertificateValidationContext {
   //   <envoy_api_field_extensions.transport_sockets.tls.v3.CertificateValidationContext.trusted_ca>`.
   repeated type.matcher.v3.StringMatcher match_subject_alt_names = 9;
 
-  // [#not-implemented-hide:] Must present a signed time-stamped OCSP response.
-  google.protobuf.BoolValue require_ocsp_staple = 5;
-
   // [#not-implemented-hide:] Must present signed certificate time-stamp.
   google.protobuf.BoolValue require_signed_certificate_timestamp = 6;
 

api/envoy/extensions/transport_sockets/tls/v3/tls.proto

@@ -54,11 +54,31 @@ message UpstreamTlsContext {
   google.protobuf.UInt32Value max_session_keys = 4;
 }
 
-// [#next-free-field: 8]
+// [#next-free-field: 9]
 message DownstreamTlsContext {
   option (udpa.annotations.versioning).previous_message_type =
       "envoy.api.v2.auth.DownstreamTlsContext";
 
+  enum OcspStaplePolicy {
+    // OCSP responses are optional. Invalid or expired OCSP
+    // responses are rejected at config time. If an OCSP
+    // response expires before a config update, it is no
+    // longer stapled.
+    SKIP_STAPLING_IF_EXPIRED = 0;
+
+    // OCSP responses are required on all certificates for a
+    // configuration to be deemed valid. If an OCSP response
+    // expires before a config update, subsequent TLS
+    // handshakes for that certificate are aborted.
+    STAPLING_REQUIRED = 1;
+
+    // OCSP responses are optional. Invalid or expired OCSP
+    // responses are rejected at config time. If an OCSP
+    // response expires before a config update, subsequent
+    // TLS handshakes for that certificate are aborted.
+    REJECT_CONNECTION_ON_EXPIRED = 2;
+  }
+
   // Common TLS context settings.
   CommonTlsContext common_tls_context = 1;
 
@@ -96,6 +116,11 @@ message DownstreamTlsContext {
     lt {seconds: 4294967296}
     gte {}
   }];
+
+  // Config for whether to use certificates if they do not have
+  // an accompanying OCSP response or if the response expires at runtime.
+  // Defaults to SKIP_STAPLING_IF_EXPIRED
+  OcspStaplePolicy ocsp_staple_policy = 8 [(validate.rules).enum = {defined_only: true}];
 }
 
 // TLS context shared by both client and server TLS contexts.

docs/root/configuration/listeners/stats.rst

@@ -29,6 +29,10 @@ Every listener has a statistics tree rooted at *listener.<address>.* with the fo
    ssl.fail_verify_error, Counter, Total TLS connections that failed CA verification
    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.ocsp_staple_failed, Counter, Total TLS connections that failed compliance with the OCSP policy
+   ssl.ocsp_staple_omitted, Counter, Total TLS connections that succeeded without stapling an OCSP response
+   ssl.ocsp_staple_responses, Counter, Total TLS connections where the server was capable of stapling an OCSP response
+   ssl.ocsp_staple_requests, Counter, Total TLS connections where the client requested an OCSP staple
    ssl.ciphers.<cipher>, Counter, Total successful TLS connections that used cipher <cipher>
    ssl.curves.<curve>, Counter, Total successful TLS connections that used ECDHE curve <curve>
    ssl.sigalgs.<sigalg>, Counter, Total successful TLS connections that used signature algorithm <sigalg>

docs/root/configuration/observability/statistics.rst

@@ -25,6 +25,7 @@ Server related statistics are rooted at *server.* with following statistics:
   total_connections, Gauge, Total connections of both new and old Envoy processes
   version, Gauge, Integer represented version number based on SCM revision or :ref:`stats_server_version_override <envoy_v3_api_field_config.bootstrap.v3.Bootstrap.stats_server_version_override>` if set.
   days_until_first_cert_expiring, Gauge, Number of days until the next certificate being managed will expire
+  seconds_until_first_ocsp_response_expiring, Gauge, Number of seconds until the next OCSP response being managed will expire
   hot_restart_epoch, Gauge, Current hot restart epoch -- an integer passed via command line flag `--restart-epoch` usually indicating generation.
   hot_restart_generation, Gauge, Current hot restart generation -- like hot_restart_epoch but computed automatically by incrementing from parent.
   initialization_time_ms, Histogram, Total time taken for Envoy initialization in milliseconds. This is the time from server start-up until the worker threads are ready to accept new connections

docs/root/intro/arch_overview/security/ssl.rst

@@ -110,6 +110,7 @@ Example configuration
             tls_certificates:
               certificate_chain: { "filename": "/cert.crt" }
               private_key: { "filename": "/cert.key" }
+              ocsp_response: { "filename": "/ocsp_response.der" }
             validation_context:
               match_subject_alt_names:
                 exact: "foo"
@@ -149,14 +150,17 @@ certificates. These may be a mix of RSA and P-256 ECDSA certificates. The follow
 
 * Only one certificate of a particular type (RSA or ECDSA) may be specified.
 * Non-P-256 server ECDSA certificates are rejected.
-* If the client supports P-256 ECDSA, a P-256 ECDSA certificate will be selected if present in the
-  :ref:`DownstreamTlsContext <envoy_v3_api_msg_extensions.transport_sockets.tls.v3.DownstreamTlsContext>`.
+* If the client supports P-256 ECDSA, a P-256 ECDSA certificate will be selected if one is present in the
+  :ref:`DownstreamTlsContext <envoy_v3_api_msg_extensions.transport_sockets.tls.v3.DownstreamTlsContext>`
+  that is in compliance with the OCSP policy.
 * If the client only supports RSA certificates, a RSA certificate will be selected if present in the
   :ref:`DownstreamTlsContext <envoy_v3_api_msg_extensions.transport_sockets.tls.v3.DownstreamTlsContext>`.
 * Otherwise, the first certificate listed is used. This will result in a failed handshake if the
   client only supports RSA certificates and the server only has ECDSA certificates.
 * Static and SDS certificates may not be mixed in a given :ref:`DownstreamTlsContext
   <envoy_v3_api_msg_extensions.transport_sockets.tls.v3.DownstreamTlsContext>`.
+* The selected certificate must adhere to the OCSP policy. If no
+  such certificate is found, the connection is refused.
 
 Only a single TLS certificate is supported today for :ref:`UpstreamTlsContexts
 <envoy_v3_api_msg_extensions.transport_sockets.tls.v3.UpstreamTlsContext>`.
@@ -168,6 +172,37 @@ TLS certificates can be specified in the static resource or can be fetched remot
 Certificate rotation is supported for static resources by sourcing :ref:`SDS configuration from the filesystem <xds_certificate_rotation>` or by pushing updates from the SDS server.
 Please see :ref:`SDS <config_secret_discovery_service>` for details.
 
+.. _arch_overview_ssl_ocsp_stapling:
+
+OCSP Stapling
+-------------
+
+:ref:`DownstreamTlsContexts <envoy_v3_api_msg_extensions.transport_sockets.tls.v3.DownstreamTlsContext>` support
+stapling an Online Certificate Status Protocol (OCSP) response to a TLS certificate during the handshake. The
+``ocsp_staple`` field allows the operator to supply a pre-computed OCSP response per-certificate in the context.
+A single response cannot pertain to multiple certificates. OCSP responses must be valid at configuration time,
+but responses may not always be provided and may expire at runtime.
+:ref:`DownstreamTlsContexts <envoy_v3_api_msg_extensions.transport_sockets.tls.v3.DownstreamTlsContext>`
+support an ``ocsp_staple_policy`` field to determine whether envoy should stop using a certificate or
+continue without stapling when its associated OCSP response expires.
+Certificates marked as `must-staple <https://tools.ietf.org/html/rfc7633>`_ require a
+valid OCSP response regardless of the OCSP staple policy. Envoy will not use a must-staple certificate for
+new connections after its OCSP response expires.
+
+The following runtime flags are provided to adjust the requirements of OCSP responses and override
+the OCSP policy. These flags default to ``true``.
+
+* ``envoy.reloadable_features.require_ocsp_response_for_must_staple_certs``: Disabling this allows the operator to omit an OCSP response for must-staple certs in the config.
+* ``envoy.reloadable_features.validate_ocsp_expiration_at_config_time``: Disabling this allows OCSP responses to be expired at configuration time.
+* ``envoy.reloadable_features.validate_ocsp_expiration_on_connection``: Disabling this will staple OCSP responses on new connections even if they are expired.
+
+OCSP responses are ignored for :ref:`UpstreamTlsContexts
+<envoy_v3_api_msg_extensions.transport_sockets.tls.v3.UpstreamTlsContext>`.
+
+.. attention::
+
+  Envoy will reject a new connection if at the time no certificates comply with the OCSP staple policy.
+
 .. _arch_overview_ssl_auth_filter:
 
 Authentication filter

docs/root/version_history/current.rst

@@ -77,6 +77,7 @@ New Features
 * stats: allow configuring histogram buckets for stats sinks and admin endpoints that support it.
 * tap: added :ref:`generic body matcher<envoy_v3_api_msg_config.tap.v3.HttpGenericBodyMatch>` to scan http requests and responses for text or hex patterns.
 * tcp: switched the TCP connection pool to the new "shared" connection pool, sharing a common code base with HTTP and HTTP/2. Any unexpected behavioral changes can be temporarily reverted by setting `envoy.reloadable_features.new_tcp_connection_pool` to false.
+* tls: added OCSP stapling support through the :ref:`ocsp_staple <envoy_v3_api_msg_extensions.transport_sockets.tls.v3.TlsCertificate>` and :ref:`ocsp_staple_policy <envoy_v3_api_msg_extensions.transport_sockets.tls.v3.DownstreamTlsContext>` configuration options. See :ref:`OCSP Stapling <arch_overview_ssl_ocsp_stapling>` for usage and runtime flags.
 * watchdog: support randomizing the watchdog's kill timeout to prevent synchronized kills via a maximium jitter parameter :ref:`max_kill_timeout_jitter<envoy_v3_api_field_config.bootstrap.v3.Watchdog.max_kill_timeout_jitter>`.
 * watchdog: supports an extension point where actions can be registered to fire on watchdog events such as miss, megamiss, kill and multikill. See ref:`watchdog actions<envoy_v3_api_field_config.bootstrap.v3.Watchdog.actions>`.
 * xds: added :ref:`extension config discovery<envoy_v3_api_msg_config.core.v3.ExtensionConfigSource>` support for HTTP filters.