Skip to content

[docs] Add documentation for custom_handshaker extension point #13083

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
mattklein123 merged 6 commits into from
Sep 15, 2020
Merged

[docs] Add documentation for custom_handshaker extension point #13083

Changes from 1 commit
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
be51759
[docs] Add documentation for custom_handshaker extension point
ambuc Sep 14, 2020
746846c
[docs] More permalinks to github from docs
ambuc Sep 14, 2020
fe18f80
[docs] Add release note for custom_handshaker field
ambuc Sep 14, 2020
d58b616
[misc] Run fix_format.
ambuc Sep 14, 2020
d6e2deb
[misc] Fix field_extensions/msg_extensions error in docs.
ambuc Sep 15, 2020
34d85bc
[docs] Add more links to ssl architecture and release notes
ambuc Sep 15, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 24 additions & 0 deletions docs/root/intro/arch_overview/security/ssl.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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_msg_extensions.transport_sockets.tls.v3.CommonTlsContext>`
Comment thread
ambuc marked this conversation as resolved.
Outdated
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 <https://github.com/google/boringssl/blob/c0b4c72b6d4c6f4828a373ec454bd646390017d4/include/openssl/ssl.h#L1169>`_.
Comment thread
ambuc marked this conversation as resolved.
Outdated

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 <https://github.com/envoyproxy/envoy/blob/master/test/extensions/transport_sockets/tls/handshaker_test.cc#L174>`_
Comment thread
ambuc marked this conversation as resolved.
Outdated
and demonstrates special-case ``SSL_ERROR`` handling and callbacks.

.. _arch_overview_ssl_trouble_shooting:

Trouble shooting
Expand Down