DTLS support

docs/source/conf.py

@@ -87,6 +87,7 @@ def setup(app):
 intersphinx_mapping = {
     "python": ('https://docs.python.org/3', None),
     "outcome": ('https://outcome.readthedocs.io/en/latest/', None),
+    "pyopenssl": ('https://www.pyopenssl.org/en/stable/', None),
 }
 
 autodoc_member_order = "bysource"

docs/source/reference-io.rst

@@ -258,6 +258,52 @@ you call them before the handshake completes:
 .. autoexception:: NeedHandshakeError
 
 
+Datagram TLS support
+~~~~~~~~~~~~~~~~~~~~
+
+Trio also has support for Datagram TLS (DTLS), which is like TLS but
+for unreliable UDP connections. This can be useful for applications
+where TCP's reliable in-order delivery is problematic, like
+teleconferencing, latency-sensitive games, and VPNs.
+
+Currently, using DTLS with Trio requires PyOpenSSL. We hope to
+eventually allow the use of the stdlib `ssl` module as well, but
+unfortunately that's not yet possible.
+
+.. warning:: Note that PyOpenSSL is in many ways lower-level than the
+   `ssl` module – in particular, it currently **HAS NO BUILT-IN
+   MECHANISM TO VALIDATE CERTIFICATES**. We *strongly* recommend that
+   you use the `service-identity
+   <https://pypi.org/project/service-identity/>`__ library to validate
+   hostnames and certificates.
+
+.. autoclass:: DTLSEndpoint
+
+   .. automethod:: connect
+
+   .. automethod:: serve
+
+   .. automethod:: close
+
+.. autoclass:: DTLSChannel
+   :show-inheritance:
+
+   .. automethod:: do_handshake
+
+   .. automethod:: send
+
+   .. automethod:: receive
+
+   .. automethod:: close
+
+   .. automethod:: aclose
+
+   .. automethod:: set_ciphertext_mtu
+
+   .. automethod:: get_cleartext_mtu
+
+   .. automethod:: statistics
+
 .. module:: trio.socket
 
 Low-level networking with :mod:`trio.socket`

newsfragments/2010.feature.rst

@@ -0,0 +1,4 @@
+Added support for `Datagram TLS
+<https://en.wikipedia.org/wiki/Datagram_Transport_Layer_Security>`__,
+for secure communication over UDP. Currently requires `PyOpenSSL
+<https://pypi.org/p/pyopenssl>`__.

test-requirements.in

@@ -3,15 +3,16 @@ pytest >= 5.0         # for faulthandler in core
 pytest-cov >= 2.6.0
 # ipython 7.x is the last major version supporting Python 3.7
 ipython < 7.32        # for the IPython traceback integration tests
-pyOpenSSL             # for the ssl tests
-trustme               # for the ssl tests
+pyOpenSSL >= 22.0.0   # for the ssl + DTLS tests
+trustme               # for the ssl + DTLS tests
 pylint                # for pylint finding all symbols tests
 jedi                  # for jedi code completion tests
 cryptography>=36.0.0  # 35.0.0 is transitive but fails
 
 # Tools
 black; implementation_name == "cpython"
 mypy; implementation_name == "cpython"
+types-pyOpenSSL; implementation_name == "cpython"
 flake8
 astor          # code generation
 

test-requirements.txt

@@ -134,10 +134,21 @@ traitlets==5.3.0
     #   matplotlib-inline
 trustme==0.9.0
     # via -r test-requirements.in
+types-cryptography==3.3.14
+    # via types-pyopenssl
+types-enum34==1.1.8
+    # via types-cryptography
+types-ipaddress==1.0.7
+    # via types-cryptography
+types-pyopenssl==21.0.3 ; implementation_name == "cpython"
+    # via -r test-requirements.in
 typing-extensions==4.3.0 ; implementation_name == "cpython"
     # via
     #   -r test-requirements.in
+    #   astroid
+    #   black
     #   mypy
+    #   pylint
 wcwidth==0.2.5
     # via prompt-toolkit
 wrapt==1.14.1

trio/__init__.py

@@ -74,6 +74,8 @@
 
 from ._ssl import SSLStream, SSLListener, NeedHandshakeError
 
+from ._dtls import DTLSEndpoint, DTLSChannel
+
 from ._highlevel_serve_listeners import serve_listeners
 
 from ._highlevel_open_tcp_stream import open_tcp_stream