From be517592ecd84af989014dc1b4438367f2a6a247 Mon Sep 17 00:00:00 2001 From: James Buckland Date: Mon, 14 Sep 2020 11:41:35 -0400 Subject: [PATCH 1/6] [docs] Add documentation for custom_handshaker extension point Signed-off-by: James Buckland --- .../root/intro/arch_overview/security/ssl.rst | 24 +++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/docs/root/intro/arch_overview/security/ssl.rst b/docs/root/intro/arch_overview/security/ssl.rst index 4a5d4f0ea2469..d5e7246494711 100644 --- a/docs/root/intro/arch_overview/security/ssl.rst +++ b/docs/root/intro/arch_overview/security/ssl.rst @@ -182,6 +182,30 @@ infrastructure. Client TLS authentication filter :ref:`configuration reference `. +.. _arch_overview_ssl_custom_handshaker: + +Custom handshaker extension +--------------------------- + +The :ref:`CommonTlsContext ` +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 +`private key method interface `_. + +To avoid reimplementing all of the ``Ssl::ConnectionInfo`` interface, a custom +implementation might choose to extend +``Envoy::Extensions::TransportSockets::Tls::SslHandshakerImpl``. + +Custom handshakers need to explicitly declare via ``HandshakerCapabilities`` +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 `_ +and demonstrates special-case ``SSL_ERROR`` handling and callbacks. + .. _arch_overview_ssl_trouble_shooting: Trouble shooting From 746846c0aa81ed87811f00fe5b4b385d03d7138d Mon Sep 17 00:00:00 2001 From: James Buckland Date: Mon, 14 Sep 2020 16:04:05 -0400 Subject: [PATCH 2/6] [docs] More permalinks to github from docs Signed-off-by: James Buckland --- docs/root/intro/arch_overview/security/ssl.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/root/intro/arch_overview/security/ssl.rst b/docs/root/intro/arch_overview/security/ssl.rst index d5e7246494711..aa6eea709dabd 100644 --- a/docs/root/intro/arch_overview/security/ssl.rst +++ b/docs/root/intro/arch_overview/security/ssl.rst @@ -187,23 +187,23 @@ Client TLS authentication filter :ref:`configuration reference Custom handshaker extension --------------------------- -The :ref:`CommonTlsContext ` +The :ref:`CommonTlsContext ` 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 `private key method interface `_. -To avoid reimplementing all of the ``Ssl::ConnectionInfo`` interface, a custom +To avoid reimplementing all of the `Ssl::ConnectionInfo `_ interface, a custom implementation might choose to extend -``Envoy::Extensions::TransportSockets::Tls::SslHandshakerImpl``. +`Envoy::Extensions::TransportSockets::Tls::SslHandshakerImpl `_. -Custom handshakers need to explicitly declare via ``HandshakerCapabilities`` +Custom handshakers need to explicitly declare via `HandshakerCapabilities `_ 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 `_ +`this test `_ and demonstrates special-case ``SSL_ERROR`` handling and callbacks. .. _arch_overview_ssl_trouble_shooting: From fe18f80b7a0b4d7595519817408f9a519a2c6111 Mon Sep 17 00:00:00 2001 From: James Buckland Date: Mon, 14 Sep 2020 16:06:39 -0400 Subject: [PATCH 3/6] [docs] Add release note for custom_handshaker field Signed-off-by: James Buckland --- docs/root/version_history/current.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/root/version_history/current.rst b/docs/root/version_history/current.rst index 627d8ad9d0d11..7b83fd34f1678 100644 --- a/docs/root/version_history/current.rst +++ b/docs/root/version_history/current.rst @@ -109,6 +109,7 @@ New Features * 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: 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. +* tls: introduce new :ref:`extension point` for overriding TLS handshaker behavior. * tracing: added ability to set some :ref:`optional segment fields` in the AWS X-Ray tracer. * udp_proxy: added :ref:`hash_policies ` to support hash based routing. * udp_proxy: added :ref:`use_original_src_ip ` option to replicate the downstream remote address of the packets on the upstream side of Envoy. It is similar to :ref:`original source filter `. From d58b61604a13a4f452ef3389fc6a9ce9a824c3fa Mon Sep 17 00:00:00 2001 From: James Buckland Date: Mon, 14 Sep 2020 16:29:44 -0400 Subject: [PATCH 4/6] [misc] Run fix_format. Signed-off-by: James Buckland --- docs/root/version_history/current.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/root/version_history/current.rst b/docs/root/version_history/current.rst index 7b83fd34f1678..646e5633da411 100644 --- a/docs/root/version_history/current.rst +++ b/docs/root/version_history/current.rst @@ -108,8 +108,8 @@ New Features * tap: added :ref:`generic body matcher` 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: 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. * tls: introduce new :ref:`extension point` for overriding TLS handshaker 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` in the AWS X-Ray tracer. * udp_proxy: added :ref:`hash_policies ` to support hash based routing. * udp_proxy: added :ref:`use_original_src_ip ` option to replicate the downstream remote address of the packets on the upstream side of Envoy. It is similar to :ref:`original source filter `. From d6e2debb8cce9cbc9f56ed98124d8c89960cde70 Mon Sep 17 00:00:00 2001 From: James Buckland Date: Tue, 15 Sep 2020 09:01:20 -0400 Subject: [PATCH 5/6] [misc] Fix field_extensions/msg_extensions error in docs. Signed-off-by: James Buckland --- docs/root/intro/arch_overview/security/ssl.rst | 2 +- docs/root/version_history/current.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/root/intro/arch_overview/security/ssl.rst b/docs/root/intro/arch_overview/security/ssl.rst index aa6eea709dabd..ef061349aefea 100644 --- a/docs/root/intro/arch_overview/security/ssl.rst +++ b/docs/root/intro/arch_overview/security/ssl.rst @@ -187,7 +187,7 @@ Client TLS authentication filter :ref:`configuration reference Custom handshaker extension --------------------------- -The :ref:`CommonTlsContext ` +The :ref:`CommonTlsContext ` 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 diff --git a/docs/root/version_history/current.rst b/docs/root/version_history/current.rst index 646e5633da411..bb059b6cf6f2f 100644 --- a/docs/root/version_history/current.rst +++ b/docs/root/version_history/current.rst @@ -108,7 +108,7 @@ New Features * tap: added :ref:`generic body matcher` 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` for overriding TLS handshaker behavior. +* tls: introduce new :ref:`extension point` for overriding TLS handshaker 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` in the AWS X-Ray tracer. * udp_proxy: added :ref:`hash_policies ` to support hash based routing. From 34d85bc536aa2418be9ff413183bbb336c95f358 Mon Sep 17 00:00:00 2001 From: James Buckland Date: Tue, 15 Sep 2020 13:16:43 -0400 Subject: [PATCH 6/6] [docs] Add more links to ssl architecture and release notes Signed-off-by: James Buckland --- docs/root/intro/arch_overview/security/ssl.rst | 4 ++-- docs/root/version_history/current.rst | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/root/intro/arch_overview/security/ssl.rst b/docs/root/intro/arch_overview/security/ssl.rst index ef061349aefea..33ec114b9aae6 100644 --- a/docs/root/intro/arch_overview/security/ssl.rst +++ b/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 `. This allows extending Envoy to support various key management schemes (such as TPM) and TLS acceleration. This mechanism uses `BoringSSL private key method interface `_. @@ -192,7 +192,7 @@ has a ``custom_handshaker`` extension which can be used to override SSL handshak 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 -`private key method interface `_. +:ref:`private key method interface ` described above. To avoid reimplementing all of the `Ssl::ConnectionInfo `_ interface, a custom implementation might choose to extend diff --git a/docs/root/version_history/current.rst b/docs/root/version_history/current.rst index bb059b6cf6f2f..1ee88c864254c 100644 --- a/docs/root/version_history/current.rst +++ b/docs/root/version_history/current.rst @@ -108,7 +108,7 @@ New Features * tap: added :ref:`generic body matcher` 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` for overriding TLS handshaker behavior. +* tls: introduce new :ref:`extension point` for overriding :ref:`TLS handshaker ` 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` in the AWS X-Ray tracer. * udp_proxy: added :ref:`hash_policies ` to support hash based routing.