[docs] Add documentation for custom_handshaker extension point

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

@@ -24,7 +24,7 @@ requirements (TLS1.2, SNI, etc.). Envoy supports the following TLS features:
   across hot restarts and between parallel Envoy instances (typically useful in a front proxy
   configuration).
 * **BoringSSL private key methods**: TLS private key operations (signing and decrypting) can be
-  performed asynchronously from an extension. This allows extending Envoy to support various key
+  performed asynchronously from :ref:`an extension <envoy_v3_api_msg_extensions.transport_sockets.tls.v3.PrivateKeyProvider>`. This allows extending Envoy to support various key
   management schemes (such as TPM) and TLS acceleration. This mechanism uses
   `BoringSSL private key method interface <https://github.com/google/boringssl/blob/c0b4c72b6d4c6f4828a373ec454bd646390017d4/include/openssl/ssl.h#L1169>`_.
 
@@ -182,6 +182,30 @@ infrastructure.
 Client TLS authentication filter :ref:`configuration reference
 <config_network_filters_client_ssl_auth>`.
 
+.. _arch_overview_ssl_custom_handshaker:
+
+Custom handshaker extension
+---------------------------
+
+The :ref:`CommonTlsContext <envoy_v3_api_field_extensions.transport_sockets.tls.v3.CommonTlsContext.custom_handshaker>`
+has a ``custom_handshaker`` extension which can be used to override SSL handshake
+behavior entirely. This is useful for implementing any TLS behavior which is
+difficult to express with callbacks. It is not necessary to write a custom
+handshaker to use private key methods, see the
+:ref:`private key method interface <arch_overview_ssl>` described above.
+
+To avoid reimplementing all of the `Ssl::ConnectionInfo <https://github.com/envoyproxy/envoy/blob/64bd6311bcc8f5b18ce44997ae22ff07ecccfe04/include/envoy/ssl/connection.h#L19>`_ interface, a custom
+implementation might choose to extend
+`Envoy::Extensions::TransportSockets::Tls::SslHandshakerImpl <https://github.com/envoyproxy/envoy/blob/64bd6311bcc8f5b18ce44997ae22ff07ecccfe04/source/extensions/transport_sockets/tls/ssl_handshaker.h#L40>`_.
+
+Custom handshakers need to explicitly declare via `HandshakerCapabilities <https://github.com/envoyproxy/envoy/blob/64bd6311bcc8f5b18ce44997ae22ff07ecccfe04/include/envoy/ssl/handshaker.h#L68-L89>`_
+which TLS features they are responsible for. The default Envoy handshaker will
+manage the remainder.
+
+A useful example handshaker, named ``SslHandshakerImplForTest``, lives in
+`this test <https://github.com/envoyproxy/envoy/blob/64bd6311bcc8f5b18ce44997ae22ff07ecccfe04/test/extensions/transport_sockets/tls/handshaker_test.cc#L174-L184>`_
+and demonstrates special-case ``SSL_ERROR`` handling and callbacks.
+
 .. _arch_overview_ssl_trouble_shooting:
 
 Trouble shooting

docs/root/version_history/current.rst

@@ -108,6 +108,7 @@ New Features
 * 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.
 * tcp_proxy: allow earlier network filters to set metadataMatchCriteria on the connection StreamInfo to influence load balancing.
+* tls: introduce new :ref:`extension point<envoy_v3_api_field_extensions.transport_sockets.tls.v3.CommonTlsContext.custom_handshaker>` for overriding :ref:`TLS handshaker <arch_overview_ssl>` behavior.
 * tls: switched from using socket BIOs to using custom BIOs that know how to interact with IoHandles. The feature can be disabled by setting runtime feature `envoy.reloadable_features.tls_use_io_handle_bio` to false.
 * tracing: added ability to set some :ref:`optional segment fields<envoy_v3_api_field_config.trace.v3.XRayConfig.segment_fields>` in the AWS  X-Ray tracer.
 * udp_proxy: added :ref:`hash_policies <envoy_v3_api_msg_extensions.filters.udp.udp_proxy.v3.UdpProxyConfig>` to support hash based routing.