poni
/
harvesting_the_net
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity
You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
master
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from 'd970267b5d'
${ noResults }
harvesting_the_net/text/lib/python3.10/site-packages/trio/_dtls.py

1277 lines
50 KiB
Python
Raw Normal View History Unescape Escape

end
2 years ago
# Implementation of DTLS 1.2, using pyopenssl
# https://datatracker.ietf.org/doc/html/rfc6347
#
# OpenSSL's APIs for DTLS are extremely awkward and limited, which forces us to jump
# through a *lot* of hoops and implement important chunks of the protocol ourselves.
# Hopefully they fix this before implementing DTLS 1.3, because it's a very different
# protocol, and it's probably impossible to pull tricks like we do here.
import struct
import hmac
import os
import enum
from itertools import count
import weakref
import errno
import warnings
import attr
import trio
from trio._util import NoPublicConstructor, Final
MAX_UDP_PACKET_SIZE = 65527
def packet_header_overhead(sock):
if sock.family == trio.socket.AF_INET:
return 28
else:
return 48
def worst_case_mtu(sock):
if sock.family == trio.socket.AF_INET:
return 576 - packet_header_overhead(sock)
else:
return 1280 - packet_header_overhead(sock)
def best_guess_mtu(sock):
return 1500 - packet_header_overhead(sock)
# There are a bunch of different RFCs that define these codes, so for a
# comprehensive collection look here:
# https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml
class ContentType(enum.IntEnum):
change_cipher_spec = 20
alert = 21
handshake = 22
application_data = 23
heartbeat = 24
class HandshakeType(enum.IntEnum):
hello_request = 0
client_hello = 1
server_hello = 2
hello_verify_request = 3
new_session_ticket = 4
end_of_early_data = 4
encrypted_extensions = 8
certificate = 11
server_key_exchange = 12
certificate_request = 13
server_hello_done = 14
certificate_verify = 15
client_key_exchange = 16
finished = 20
certificate_url = 21
certificate_status = 22
supplemental_data = 23
key_update = 24
compressed_certificate = 25
ekt_key = 26
message_hash = 254
class ProtocolVersion:
DTLS10 = bytes([254, 255])
DTLS12 = bytes([254, 253])
EPOCH_MASK = 0xFFFF << (6 * 8)
# Conventions:
# - All functions that handle network data end in _untrusted.
# - All functions end in _untrusted MUST make sure that bad data from the
# network cannot *only* cause BadPacket to be raised. No IndexError or
# struct.error or whatever.
class BadPacket(Exception):
pass
# This checks that the DTLS 'epoch' field is 0, which is true iff we're in the
# initial handshake. It doesn't check the ContentType, because not all
# handshake messages have ContentType==handshake -- for example,
# ChangeCipherSpec is used during the handshake but has its own ContentType.
#
# Cannot fail.
def part_of_handshake_untrusted(packet):
# If the packet is too short, then slicing will successfully return a
# short string, which will necessarily fail to match.
return packet[3:5] == b"\x00\x00"
# Cannot fail
def is_client_hello_untrusted(packet):
try:
return (
packet[0] == ContentType.handshake
and packet[13] == HandshakeType.client_hello
)
except IndexError:
# Invalid DTLS record
return False
# DTLS records are:
# - 1 byte content type
# - 2 bytes version
# - 8 bytes epoch+seqno
# Technically this is 2 bytes epoch then 6 bytes seqno, but we treat it as
# a single 8-byte integer, where epoch changes are represented as jumping
# forward by 2**(6*8).
# - 2 bytes payload length (unsigned big-endian)
# - payload
RECORD_HEADER = struct.Struct("!B2sQH")
def to_hex(data: bytes) -> str: # pragma: no cover
return data.hex()
@attr.frozen
class Record:
content_type: int
version: bytes = attr.ib(repr=to_hex)
epoch_seqno: int
payload: bytes = attr.ib(repr=to_hex)
def records_untrusted(packet):
i = 0
while i < len(packet):
try:
ct, version, epoch_seqno, payload_len = RECORD_HEADER.unpack_from(packet, i)
# Marked as no-cover because at time of writing, this code is unreachable
# (records_untrusted only gets called on packets that are either trusted or that
# have passed is_client_hello_untrusted, which filters out short packets)
except struct.error as exc: # pragma: no cover
raise BadPacket("invalid record header") from exc
i += RECORD_HEADER.size
payload = packet[i : i + payload_len]
if len(payload) != payload_len:
raise BadPacket("short record")
i += payload_len
yield Record(ct, version, epoch_seqno, payload)
def encode_record(record):
header = RECORD_HEADER.pack(
record.content_type,
record.version,
record.epoch_seqno,
len(record.payload),
)
return header + record.payload
# Handshake messages are:
# - 1 byte message type
# - 3 bytes total message length
# - 2 bytes message sequence number
# - 3 bytes fragment offset
# - 3 bytes fragment length
HANDSHAKE_MESSAGE_HEADER = struct.Struct("!B3sH3s3s")
@attr.frozen
class HandshakeFragment:
msg_type: int
msg_len: int
msg_seq: int
frag_offset: int
frag_len: int
frag: bytes = attr.ib(repr=to_hex)
def decode_handshake_fragment_untrusted(payload):
# Raises BadPacket if decoding fails
try:
(
msg_type,
msg_len_bytes,
msg_seq,
frag_offset_bytes,
frag_len_bytes,
) = HANDSHAKE_MESSAGE_HEADER.unpack_from(payload)
except struct.error as exc:
raise BadPacket("bad handshake message header") from exc
# 'struct' doesn't have built-in support for 24-bit integers, so we
# have to do it by hand. These can't fail.
msg_len = int.from_bytes(msg_len_bytes, "big")
frag_offset = int.from_bytes(frag_offset_bytes, "big")
frag_len = int.from_bytes(frag_len_bytes, "big")
frag = payload[HANDSHAKE_MESSAGE_HEADER.size :]
if len(frag) != frag_len:
raise BadPacket("handshake fragment length doesn't match record length")
return HandshakeFragment(
msg_type,
msg_len,
msg_seq,
frag_offset,
frag_len,
frag,
)
def encode_handshake_fragment(hsf):
hs_header = HANDSHAKE_MESSAGE_HEADER.pack(
hsf.msg_type,
hsf.msg_len.to_bytes(3, "big"),
hsf.msg_seq,
hsf.frag_offset.to_bytes(3, "big"),
hsf.frag_len.to_bytes(3, "big"),
)
return hs_header + hsf.frag
def decode_client_hello_untrusted(packet):
# Raises BadPacket if parsing fails
# Returns (record epoch_seqno, cookie from the packet, data that should be
# hashed into cookie)
try:
# ClientHello has to be the first record in the packet
record = next(records_untrusted(packet))
# no-cover because at time of writing, this is unreachable:
# decode_client_hello_untrusted is only called on packets that have passed
# is_client_hello_untrusted, which confirms the content type.
if record.content_type != ContentType.handshake: # pragma: no cover
raise BadPacket("not a handshake record")
fragment = decode_handshake_fragment_untrusted(record.payload)
if fragment.msg_type != HandshakeType.client_hello:
raise BadPacket("not a ClientHello")
# ClientHello can't be fragmented, because reassembly requires holding
# per-connection state, and we refuse to allocate per-connection state
# until after we get a valid ClientHello.
if fragment.frag_offset != 0:
raise BadPacket("fragmented ClientHello")
if fragment.frag_len != fragment.msg_len:
raise BadPacket("fragmented ClientHello")
# As per RFC 6347:
#
# When responding to a HelloVerifyRequest, the client MUST use the
# same parameter values (version, random, session_id, cipher_suites,
# compression_method) as it did in the original ClientHello. The
# server SHOULD use those values to generate its cookie and verify that
# they are correct upon cookie receipt.
#
# However, the record-layer framing can and will change (e.g. the
# second ClientHello will have a new record-layer sequence number). So
# we need to pull out the handshake message alone, discarding the
# record-layer stuff, and then we're going to hash all of it *except*
# the cookie.
body = fragment.frag
# ClientHello is:
#
# - 2 bytes client_version
# - 32 bytes random
# - 1 byte session_id length
# - session_id
# - 1 byte cookie length
# - cookie
# - everything else
#
# So to find the cookie, so we need to figure out how long the
# session_id is and skip past it.
session_id_len = body[2 + 32]
cookie_len_offset = 2 + 32 + 1 + session_id_len
cookie_len = body[cookie_len_offset]
cookie_start = cookie_len_offset + 1
cookie_end = cookie_start + cookie_len
before_cookie = body[:cookie_len_offset]
cookie = body[cookie_start:cookie_end]
after_cookie = body[cookie_end:]
if len(cookie) != cookie_len:
raise BadPacket("short cookie")
return (record.epoch_seqno, cookie, before_cookie + after_cookie)
except (struct.error, IndexError) as exc:
raise BadPacket("bad ClientHello") from exc
@attr.frozen
class HandshakeMessage:
record_version: bytes = attr.ib(repr=to_hex)
msg_type: HandshakeType
msg_seq: int
body: bytearray = attr.ib(repr=to_hex)
# ChangeCipherSpec is part of the handshake, but it's not a "handshake
# message" and can't be fragmented the same way. Sigh.
@attr.frozen
class PseudoHandshakeMessage:
record_version: bytes = attr.ib(repr=to_hex)
content_type: int
payload: bytes = attr.ib(repr=to_hex)
# The final record in a handshake is Finished, which is encrypted, can't be fragmented
# (at least by us), and keeps its record number (because it's in a new epoch). So we
# just pass it through unchanged. (Fortunately, the payload is only a single hash value,
# so the largest it will ever be is 64 bytes for a 512-bit hash. Which is small enough
# that it never requires fragmenting to fit into a UDP packet.
@attr.frozen
class OpaqueHandshakeMessage:
record: Record
# This takes a raw outgoing handshake volley that openssl generated, and
# reconstructs the handshake messages inside it, so that we can repack them
# into records while retransmitting. So the data ought to be well-behaved --
# it's not coming from the network.
def decode_volley_trusted(volley):
messages = []
messages_by_seq = {}
for record in records_untrusted(volley):
# ChangeCipherSpec isn't a handshake message, so it can't be fragmented.
# Handshake messages with epoch > 0 are encrypted, so we can't fragment them
# either. Fortunately, ChangeCipherSpec has a 1 byte payload, and the only
# encrypted handshake message is Finished, whose payload is a single hash value
# -- so 32 bytes for SHA-256, 64 for SHA-512, etc. Neither is going to be so
# large that it has to be fragmented to fit into a single packet.
if record.epoch_seqno & EPOCH_MASK:
messages.append(OpaqueHandshakeMessage(record))
elif record.content_type in (ContentType.change_cipher_spec, ContentType.alert):
messages.append(
PseudoHandshakeMessage(
record.version, record.content_type, record.payload
)
)
else:
assert record.content_type == ContentType.handshake
fragment = decode_handshake_fragment_untrusted(record.payload)
msg_type = HandshakeType(fragment.msg_type)
if fragment.msg_seq not in messages_by_seq:
msg = HandshakeMessage(
record.version,
msg_type,
fragment.msg_seq,
bytearray(fragment.msg_len),
)
messages.append(msg)
messages_by_seq[fragment.msg_seq] = msg
else:
msg = messages_by_seq[fragment.msg_seq]
assert msg.msg_type == fragment.msg_type
assert msg.msg_seq == fragment.msg_seq
assert len(msg.body) == fragment.msg_len
msg.body[
fragment.frag_offset : fragment.frag_offset + fragment.frag_len
] = fragment.frag
return messages
class RecordEncoder:
def __init__(self):
self._record_seq = count()
def set_first_record_number(self, n):
self._record_seq = count(n)
def encode_volley(self, messages, mtu):
packets = []
packet = bytearray()
for message in messages:
if isinstance(message, OpaqueHandshakeMessage):
encoded = encode_record(message.record)
if mtu - len(packet) - len(encoded) <= 0:
packets.append(packet)
packet = bytearray()
packet += encoded
assert len(packet) <= mtu
elif isinstance(message, PseudoHandshakeMessage):
space = mtu - len(packet) - RECORD_HEADER.size - len(message.payload)
if space <= 0:
packets.append(packet)
packet = bytearray()
packet += RECORD_HEADER.pack(
message.content_type,
message.record_version,
next(self._record_seq),
len(message.payload),
)
packet += message.payload
assert len(packet) <= mtu
else:
msg_len_bytes = len(message.body).to_bytes(3, "big")
frag_offset = 0
frags_encoded = 0
# If message.body is empty, then we still want to encode it in one
# fragment, not zero.
while frag_offset < len(message.body) or not frags_encoded:
space = (
mtu
- len(packet)
- RECORD_HEADER.size
- HANDSHAKE_MESSAGE_HEADER.size
)
if space <= 0:
packets.append(packet)
packet = bytearray()
continue
frag = message.body[frag_offset : frag_offset + space]
frag_offset_bytes = frag_offset.to_bytes(3, "big")
frag_len_bytes = len(frag).to_bytes(3, "big")
frag_offset += len(frag)
packet += RECORD_HEADER.pack(
ContentType.handshake,
message.record_version,
next(self._record_seq),
HANDSHAKE_MESSAGE_HEADER.size + len(frag),
)
packet += HANDSHAKE_MESSAGE_HEADER.pack(
message.msg_type,
msg_len_bytes,
message.msg_seq,
frag_offset_bytes,
frag_len_bytes,
)
packet += frag
frags_encoded += 1
assert len(packet) <= mtu
if packet:
packets.append(packet)
return packets
# This bit requires implementing a bona fide cryptographic protocol, so even though it's
# a simple one let's take a moment to discuss the design.
#
# Our goal is to force new incoming handshakes that claim to be coming from a
# given ip:port to prove that they can also receive packets sent to that
# ip:port. (There's nothing in UDP to stop someone from forging the return
# address, and it's often used for stuff like DoS reflection attacks, where
# an attacker tries to trick us into sending data at some innocent victim.)
# For more details, see:
#
# https://datatracker.ietf.org/doc/html/rfc6347#section-4.2.1
#
# To do this, when we receive an initial ClientHello, we calculate a magic
# cookie, and send it back as a HelloVerifyRequest. Then the client sends us a
# second ClientHello, this time with the magic cookie included, and after we
# check that this cookie is valid we go ahead and start the handshake proper.
#
# So the magic cookie needs the following properties:
# - No-one can forge it without knowing our secret key
# - It ensures that the ip, port, and ClientHello contents from the response
# match those in the challenge
# - It expires after a short-ish period (so that if an attacker manages to steal one, it
# won't be useful for long)
# - It doesn't require storing any peer-specific state on our side
#
# To do that, we take the ip/port/ClientHello data and compute an HMAC of them, using a
# secret key we generate on startup. We also include:
#
# - The current time (using Trio's clock), rounded to the nearest 30 seconds
# - A random salt
#
# Then the cookie is the salt and the HMAC digest concatenated together.
#
# When verifying a cookie, we use the salt + new ip/port/ClientHello data to recompute
# the HMAC digest, for both the current time and the current time minus 30 seconds, and
# if either of them match, we consider the cookie good.
#
# Including the rounded-off time like this means that each cookie is good for at least
# 30 seconds, and possibly as much as 60 seconds.
#
# The salt is probably not necessary -- I'm pretty sure that all it does is make it hard
# for an attacker to figure out when our clock ticks over a 30 second boundary. Which is
# probably pretty harmless? But it's easier to add the salt than to convince myself that
# it's *completely* harmless, so, salt it is.
COOKIE_REFRESH_INTERVAL = 30 # seconds
KEY_BYTES = 32
COOKIE_HASH = "sha256"
SALT_BYTES = 8
# 32 bytes was the maximum cookie length in DTLS 1.0. DTLS 1.2 raised it to 255. I doubt
# there are any DTLS 1.0 implementations still in the wild, but really 32 bytes is
# plenty, and it also gets rid of a confusing warning in Wireshark output.
#
# We truncate the cookie to 32 bytes, of which 8 bytes is salt, so that leaves 24 bytes
# of truncated HMAC = 192 bit security, which is still massive overkill. (TCP uses 32
# *bits* for this.) HMAC truncation is explicitly noted as safe in RFC 2104:
# https://datatracker.ietf.org/doc/html/rfc2104#section-5
COOKIE_LENGTH = 32
def _current_cookie_tick():
return int(trio.current_time() / COOKIE_REFRESH_INTERVAL)
# Simple deterministic and invertible serializer -- i.e., a useful tool for converting
# structured data into something we can cryptographically sign.
def _signable(*fields):
out = []
for field in fields:
out.append(struct.pack("!Q", len(field)))
out.append(field)
return b"".join(out)
def _make_cookie(key, salt, tick, address, client_hello_bits):
assert len(salt) == SALT_BYTES
assert len(key) == KEY_BYTES
signable_data = _signable(
salt,
struct.pack("!Q", tick),
# address is a mix of strings and ints, and variable length, so pack
# it into a single nested field
_signable(*(str(part).encode() for part in address)),
client_hello_bits,
)
return (salt + hmac.digest(key, signable_data, COOKIE_HASH))[:COOKIE_LENGTH]
def valid_cookie(key, cookie, address, client_hello_bits):
if len(cookie) > SALT_BYTES:
salt = cookie[:SALT_BYTES]
tick = _current_cookie_tick()
cur_cookie = _make_cookie(key, salt, tick, address, client_hello_bits)
old_cookie = _make_cookie(
key, salt, max(tick - 1, 0), address, client_hello_bits
)
# I doubt using a short-circuiting 'or' here would leak any meaningful
# information, but why risk it when '|' is just as easy.
return hmac.compare_digest(cookie, cur_cookie) | hmac.compare_digest(
cookie, old_cookie
)
else:
return False
def challenge_for(key, address, epoch_seqno, client_hello_bits):
salt = os.urandom(SALT_BYTES)
tick = _current_cookie_tick()
cookie = _make_cookie(key, salt, tick, address, client_hello_bits)
# HelloVerifyRequest body is:
# - 2 bytes version
# - length-prefixed cookie
#
# The DTLS 1.2 spec says that for this message specifically we should use
# the DTLS 1.0 version.
#
# (It also says the opposite of that, but that part is a mistake:
# https://www.rfc-editor.org/errata/eid4103
# ).
#
# And I guess we use this for both the message-level and record-level
# ProtocolVersions, since we haven't negotiated anything else yet?
body = ProtocolVersion.DTLS10 + bytes([len(cookie)]) + cookie
# RFC says have to copy the client's record number
# Errata says it should be handshake message number
# Openssl copies back record sequence number, and always sets message seq
# number 0. So I guess we'll follow openssl.
hs = HandshakeFragment(
msg_type=HandshakeType.hello_verify_request,
msg_len=len(body),
msg_seq=0,
frag_offset=0,
frag_len=len(body),
frag=body,
)
payload = encode_handshake_fragment(hs)
packet = encode_record(
Record(ContentType.handshake, ProtocolVersion.DTLS10, epoch_seqno, payload)
)
return packet
class _Queue:
def __init__(self, incoming_packets_buffer):
self.s, self.r = trio.open_memory_channel(incoming_packets_buffer)
def _read_loop(read_fn):
chunks = []
while True:
try:
chunk = read_fn(2**14) # max TLS record size
except SSL.WantReadError:
break
chunks.append(chunk)
return b"".join(chunks)
async def handle_client_hello_untrusted(endpoint, address, packet):
if endpoint._listening_context is None:
return
try:
epoch_seqno, cookie, bits = decode_client_hello_untrusted(packet)
except BadPacket:
return
if endpoint._listening_key is None:
endpoint._listening_key = os.urandom(KEY_BYTES)
if not valid_cookie(endpoint._listening_key, cookie, address, bits):
challenge_packet = challenge_for(
endpoint._listening_key, address, epoch_seqno, bits
)
try:
async with endpoint._send_lock:
await endpoint.socket.sendto(challenge_packet, address)
except (OSError, trio.ClosedResourceError):
pass
else:
# We got a real, valid ClientHello!
stream = DTLSChannel._create(endpoint, address, endpoint._listening_context)
# Our HelloRetryRequest had some sequence number. We need our future sequence
# numbers to be larger than it, so our peer knows that our future records aren't
# stale/duplicates. But, we don't know what this sequence number was. What we do
# know is:
# - the HelloRetryRequest seqno was copied it from the initial ClientHello
# - the new ClientHello has a higher seqno than the initial ClientHello
# So, if we copy the new ClientHello's seqno into our first real handshake
# record and increment from there, that should work.
stream._record_encoder.set_first_record_number(epoch_seqno)
# Process the ClientHello
try:
stream._ssl.bio_write(packet)
stream._ssl.DTLSv1_listen()
except SSL.Error:
# ...OpenSSL didn't like it, so I guess we didn't have a valid ClientHello
# after all.
return
# Some old versions of OpenSSL have a bug with memory BIOs, where DTLSv1_listen
# consumes the ClientHello out of the BIO, but then do_handshake expects the
# ClientHello to still be in there (but not the one that ships with Ubuntu
# 20.04). In particular, this is known to affect the OpenSSL v1.1.1 that ships
# with Ubuntu 18.04. To work around this, we deliver a second copy of the
# ClientHello after DTLSv1_listen has completed. This is safe to do
# unconditionally, because on newer versions of OpenSSL, the second ClientHello
# is treated as a duplicate packet, which is a normal thing that can happen over
# UDP. For more details, see:
#
# https://github.com/pyca/pyopenssl/blob/e84e7b57d1838de70ab7a27089fbee78ce0d2106/tests/test_ssl.py#L4226-L4293
#
# This was fixed in v1.1.1a, and all later versions. So maybe in 2024 or so we
# can delete this. The fix landed in OpenSSL master as 079ef6bd534d2, and then
# was backported to the 1.1.1 branch as d1bfd8076e28.
stream._ssl.bio_write(packet)
# Check if we have an existing association
old_stream = endpoint._streams.get(address)
if old_stream is not None:
if old_stream._client_hello == (cookie, bits):
# ...This was just a duplicate of the last ClientHello, so never mind.
return
else:
# Ok, this *really is* a new handshake; the old stream should go away.
old_stream._set_replaced()
stream._client_hello = (cookie, bits)
endpoint._streams[address] = stream
endpoint._incoming_connections_q.s.send_nowait(stream)
async def dtls_receive_loop(endpoint_ref, sock):
try:
while True:
try:
packet, address = await sock.recvfrom(MAX_UDP_PACKET_SIZE)
except OSError as exc:
if exc.errno == errno.ECONNRESET:
# Windows only: "On a UDP-datagram socket [ECONNRESET]
# indicates a previous send operation resulted in an ICMP Port
# Unreachable message" -- https://docs.microsoft.com/en-us/windows/win32/api/winsock/nf-winsock-recvfrom
#
# This is totally useless -- there's nothing we can do with this
# information. So we just ignore it and retry the recv.
continue
else:
raise
endpoint = endpoint_ref()
try:
if endpoint is None:
return
if is_client_hello_untrusted(packet):
await handle_client_hello_untrusted(endpoint, address, packet)
elif address in endpoint._streams:
stream = endpoint._streams[address]
if stream._did_handshake and part_of_handshake_untrusted(packet):
# The peer just sent us more handshake messages, that aren't a
# ClientHello, and we thought the handshake was done. Some of
# the packets that we sent to finish the handshake must have
# gotten lost. So re-send them. We do this directly here instead
# of just putting it into the queue and letting the receiver do
# it, because there's no guarantee that anyone is reading from
# the queue, because we think the handshake is done!
await stream._resend_final_volley()
else:
try:
stream._q.s.send_nowait(packet)
except trio.WouldBlock:
stream._packets_dropped_in_trio += 1
else:
# Drop packet
pass
finally:
del endpoint
except trio.ClosedResourceError:
# socket was closed
return
except OSError as exc:
if exc.errno in (errno.EBADF, errno.ENOTSOCK):
# socket was closed
return
else: # pragma: no cover
# ??? shouldn't happen
raise
@attr.frozen
class DTLSChannelStatistics:
incoming_packets_dropped_in_trio: int
class DTLSChannel(trio.abc.Channel[bytes], metaclass=NoPublicConstructor):
"""A DTLS connection.
This class has no public constructor – you get instances by calling
`DTLSEndpoint.serve` or `~DTLSEndpoint.connect`.
.. attribute:: endpoint
The `DTLSEndpoint` that this connection is using.
.. attribute:: peer_address
The IP/port of the remote peer that this connection is associated with.
"""
def __init__(self, endpoint, peer_address, ctx):
self.endpoint = endpoint
self.peer_address = peer_address
self._packets_dropped_in_trio = 0
self._client_hello = None
self._did_handshake = False
# These are mandatory for all DTLS connections. OP_NO_QUERY_MTU is required to
# stop openssl from trying to query the memory BIO's MTU and then breaking, and
# OP_NO_RENEGOTIATION disables renegotiation, which is too complex for us to
# support and isn't useful anyway -- especially for DTLS where it's equivalent
# to just performing a new handshake.
ctx.set_options(SSL.OP_NO_QUERY_MTU | SSL.OP_NO_RENEGOTIATION)
self._ssl = SSL.Connection(ctx)
self._handshake_mtu = None
# This calls self._ssl.set_ciphertext_mtu, which is important, because if you
# don't call it then openssl doesn't work.
self.set_ciphertext_mtu(best_guess_mtu(self.endpoint.socket))
self._replaced = False
self._closed = False
self._q = _Queue(endpoint.incoming_packets_buffer)
self._handshake_lock = trio.Lock()
self._record_encoder = RecordEncoder()
def _set_replaced(self):
self._replaced = True
# Any packets we already received could maybe possibly still be processed, but
# there are no more coming. So we close this on the sender side.
self._q.s.close()
def _check_replaced(self):
if self._replaced:
raise trio.BrokenResourceError(
"peer tore down this connection to start a new one"
)
# XX on systems where we can (maybe just Linux?) take advantage of the kernel's PMTU
# estimate
# XX should we send close-notify when closing? It seems particularly pointless for
# DTLS where packets are all independent and can be lost anyway. We do at least need
# to handle receiving it properly though, which might be easier if we send it...
def close(self):
"""Close this connection.
`DTLSChannel`\\s don't actually own any OS-level resources – the
socket is owned by the `DTLSEndpoint`, not the individual connections. So
you don't really *have* to call this. But it will interrupt any other tasks
calling `receive` with a `ClosedResourceError`, and cause future attempts to use
this connection to fail.
You can also use this object as a synchronous or asynchronous context manager.
"""
if self._closed:
return
self._closed = True
if self.endpoint._streams.get(self.peer_address) is self:
del self.endpoint._streams[self.peer_address]
# Will wake any tasks waiting on self._q.get with a
# ClosedResourceError
self._q.r.close()
def __enter__(self):
return self
def __exit__(self, *args):
self.close()
async def aclose(self):
"""Close this connection, but asynchronously.
This is included to satisfy the `trio.abc.Channel` contract. It's
identical to `close`, but async.
"""
self.close()
await trio.lowlevel.checkpoint()
async def _send_volley(self, volley_messages):
packets = self._record_encoder.encode_volley(
volley_messages, self._handshake_mtu
)
for packet in packets:
async with self.endpoint._send_lock:
await self.endpoint.socket.sendto(packet, self.peer_address)
async def _resend_final_volley(self):
await self._send_volley(self._final_volley)
async def do_handshake(self, *, initial_retransmit_timeout=1.0):
"""Perform the handshake.
Calling this is optional – if you don't, then it will be automatically called
the first time you call `send` or `receive`. But calling it explicitly can be
useful in case you want to control the retransmit timeout, use a cancel scope to
place an overall timeout on the handshake, or catch errors from the handshake
specifically.
It's safe to call this multiple times, or call it simultaneously from multiple
tasks – the first call will perform the handshake, and the rest will be no-ops.
Args:
initial_retransmit_timeout (float): Since UDP is an unreliable protocol, it's
possible that some of the packets we send during the handshake will get
lost. To handle this, DTLS uses a timer to automatically retransmit
handshake packets that don't receive a response. This lets you set the
timeout we use to detect packet loss. Ideally, it should be set to ~1.5
times the round-trip time to your peer, but 1 second is a reasonable
default. There's `some useful guidance here
<https://tlswg.org/dtls13-spec/draft-ietf-tls-dtls13.html#name-timer-values>`__.
This is the *initial* timeout, because if packets keep being lost then Trio
will automatically back off to longer values, to avoid overloading the
network.
"""
async with self._handshake_lock:
if self._did_handshake:
return
timeout = initial_retransmit_timeout
volley_messages = []
volley_failed_sends = 0
def read_volley():
volley_bytes = _read_loop(self._ssl.bio_read)
new_volley_messages = decode_volley_trusted(volley_bytes)
if (
new_volley_messages
and volley_messages
and isinstance(new_volley_messages[0], HandshakeMessage)
and new_volley_messages[0].msg_seq == volley_messages[0].msg_seq
):
# openssl decided to retransmit; discard because we handle
# retransmits ourselves
return []
else:
return new_volley_messages
# If we're a client, we send the initial volley. If we're a server, then
# the initial ClientHello has already been inserted into self._ssl's
# read BIO. So either way, we start by generating a new volley.
try:
self._ssl.do_handshake()
except SSL.WantReadError:
pass
volley_messages = read_volley()
# If we don't have messages to send in our initial volley, then something
# has gone very wrong. (I'm not sure this can actually happen without an
# error from OpenSSL, but we check just in case.)
if not volley_messages: # pragma: no cover
raise SSL.Error("something wrong with peer's ClientHello")
while True:
# -- at this point, we need to either send or re-send a volley --
assert volley_messages
self._check_replaced()
await self._send_volley(volley_messages)
# -- then this is where we wait for a reply --
self.endpoint._ensure_receive_loop()
with trio.move_on_after(timeout) as cscope:
async for packet in self._q.r:
self._ssl.bio_write(packet)
try:
self._ssl.do_handshake()
# We ignore generic SSL.Error here, because you can get those
# from random invalid packets
except (SSL.WantReadError, SSL.Error):
pass
else:
# No exception -> the handshake is done, and we can
# switch into data transfer mode.
self._did_handshake = True
# Might be empty, but that's ok -- we'll just send no
# packets.
self._final_volley = read_volley()
await self._send_volley(self._final_volley)
return
maybe_volley = read_volley()
if maybe_volley:
if (
isinstance(maybe_volley[0], PseudoHandshakeMessage)
and maybe_volley[0].content_type == ContentType.alert
):
# we're sending an alert (e.g. due to a corrupted
# packet). We want to send it once, but don't save it to
# retransmit -- keep the last volley as the current
# volley.
await self._send_volley(maybe_volley)
else:
# We managed to get all of the peer's volley and
# generate a new one ourselves! break out of the 'for'
# loop and restart the timer.
volley_messages = maybe_volley
# "Implementations SHOULD retain the current timer value
# until a transmission without loss occurs, at which
# time the value may be reset to the initial value."
if volley_failed_sends == 0:
timeout = initial_retransmit_timeout
volley_failed_sends = 0
break
else:
assert self._replaced
self._check_replaced()
if cscope.cancelled_caught:
# Timeout expired. Double timeout for backoff, with a limit of 60
# seconds (this matches what openssl does, and also the
# recommendation in draft-ietf-tls-dtls13).
timeout = min(2 * timeout, 60.0)
volley_failed_sends += 1
if volley_failed_sends == 2:
# We tried sending this twice and they both failed. Maybe our
# PMTU estimate is wrong? Let's try dropping it to the minimum
# and hope that helps.
self._handshake_mtu = min(
self._handshake_mtu, worst_case_mtu(self.endpoint.socket)
)
async def send(self, data):
"""Send a packet of data, securely."""
if self._closed:
raise trio.ClosedResourceError
if not data:
raise ValueError("openssl doesn't support sending empty DTLS packets")
if not self._did_handshake:
await self.do_handshake()
self._check_replaced()
self._ssl.write(data)
async with self.endpoint._send_lock:
await self.endpoint.socket.sendto(
_read_loop(self._ssl.bio_read), self.peer_address
)
async def receive(self):
"""Fetch the next packet of data from this connection's peer, waiting if
necessary.
This is safe to call from multiple tasks simultaneously, in case you have some
reason to do that. And more importantly, it's cancellation-safe, meaning that
cancelling a call to `receive` will never cause a packet to be lost or corrupt
the underlying connection.
"""
if not self._did_handshake:
await self.do_handshake()
# If the packet isn't really valid, then openssl can decode it to the empty
# string (e.g. b/c it's a late-arriving handshake packet, or a duplicate copy of
# a data packet). Skip over these instead of returning them.
while True:
try:
packet = await self._q.r.receive()
except trio.EndOfChannel:
assert self._replaced
self._check_replaced()
self._ssl.bio_write(packet)
cleartext = _read_loop(self._ssl.read)
if cleartext:
return cleartext
def set_ciphertext_mtu(self, new_mtu):
"""Tells Trio the `largest amount of data that can be sent in a single packet to
this peer <https://en.wikipedia.org/wiki/Maximum_transmission_unit>`__.
Trio doesn't actually enforce this limit – if you pass a huge packet to `send`,
then we'll dutifully encrypt it and attempt to send it. But calling this method
does have two useful effects:
- If called before the handshake is performed, then Trio will automatically
fragment handshake messages to fit within the given MTU. It also might
fragment them even smaller, if it detects signs of packet loss, so setting
this should never be necessary to make a successful connection. But, the
packet loss detection only happens after multiple timeouts have expired, so if
you have reason to believe that a smaller MTU is required, then you can set
this to skip those timeouts and establish the connection more quickly.
- It changes the value returned from `get_cleartext_mtu`. So if you have some
kind of estimate of the network-level MTU, then you can use this to figure out
how much overhead DTLS will need for hashes/padding/etc., and how much space
you have left for your application data.
The MTU here is measuring the largest UDP *payload* you think can be sent, the
amount of encrypted data that can be handed to the operating system in a single
call to `send`. It should *not* include IP/UDP headers. Note that OS estimates
of the MTU often are link-layer MTUs, so you have to subtract off 28 bytes on
IPv4 and 48 bytes on IPv6 to get the ciphertext MTU.
By default, Trio assumes an MTU of 1472 bytes on IPv4, and 1452 bytes on IPv6,
which correspond to the common Ethernet MTU of 1500 bytes after accounting for
IP/UDP overhead.
"""
self._handshake_mtu = new_mtu
self._ssl.set_ciphertext_mtu(new_mtu)
def get_cleartext_mtu(self):
"""Returns the largest number of bytes that you can pass in a single call to
`send` while still fitting within the network-level MTU.
See `set_ciphertext_mtu` for more details.
"""
if not self._did_handshake:
raise trio.NeedHandshakeError
return self._ssl.get_cleartext_mtu()
def statistics(self):
"""Returns an object with statistics about this connection.
Currently this has only one attribute:
- ``incoming_packets_dropped_in_trio`` (``int``): Gives a count of the number of
incoming packets from this peer that Trio successfully received from the
network, but then got dropped because the internal channel buffer was full. If
this is non-zero, then you might want to call ``receive`` more often, or use a
larger ``incoming_packets_buffer``, or just not worry about it because your
UDP-based protocol should be able to handle the occasional lost packet, right?
"""
return DTLSChannelStatistics(self._packets_dropped_in_trio)
class DTLSEndpoint(metaclass=Final):
"""A DTLS endpoint.
A single UDP socket can handle arbitrarily many DTLS connections simultaneously,
acting as a client or server as needed. A `DTLSEndpoint` object holds a UDP socket
and manages these connections, which are represented as `DTLSChannel` objects.
Args:
socket: (trio.socket.SocketType): A ``SOCK_DGRAM`` socket. If you want to accept
incoming connections in server mode, then you should probably bind the socket to
some known port.
incoming_packets_buffer (int): Each `DTLSChannel` using this socket has its own
buffer that holds incoming packets until you call `~DTLSChannel.receive` to read
them. This lets you adjust the size of this buffer. `~DTLSChannel.statistics`
lets you check if the buffer has overflowed.
.. attribute:: socket
incoming_packets_buffer
Both constructor arguments are also exposed as attributes, in case you need to
access them later.
"""
def __init__(self, socket, *, incoming_packets_buffer=10):
# We do this lazily on first construction, so only people who actually use DTLS
# have to install PyOpenSSL.
global SSL
from OpenSSL import SSL
self.socket = None # for __del__, in case the next line raises
if socket.type != trio.socket.SOCK_DGRAM:
raise ValueError("DTLS requires a SOCK_DGRAM socket")
self.socket = socket
self.incoming_packets_buffer = incoming_packets_buffer
self._token = trio.lowlevel.current_trio_token()
# We don't need to track handshaking vs non-handshake connections
# separately. We only keep one connection per remote address; as soon
# as a peer provides a valid cookie, we can immediately tear down the
# old connection.
# {remote address: DTLSChannel}
self._streams = weakref.WeakValueDictionary()
self._listening_context = None
self._listening_key = None
self._incoming_connections_q = _Queue(float("inf"))
self._send_lock = trio.Lock()
self._closed = False
self._receive_loop_spawned = False
def _ensure_receive_loop(self):
# We have to spawn this lazily, because on Windows it will immediately error out
# if the socket isn't already bound -- which for clients might not happen until
# after we send our first packet.
if not self._receive_loop_spawned:
trio.lowlevel.spawn_system_task(
dtls_receive_loop, weakref.ref(self), self.socket
)
self._receive_loop_spawned = True
def __del__(self):
# Do nothing if this object was never fully constructed
if self.socket is None:
return
# Close the socket in Trio context (if our Trio context still exists), so that
# the background task gets notified about the closure and can exit.
if not self._closed:
try:
self._token.run_sync_soon(self.close)
except RuntimeError:
pass
# Do this last, because it might raise an exception
warnings.warn(
f"unclosed DTLS endpoint {self!r}", ResourceWarning, source=self
)
def close(self):
"""Close this socket, and all associated DTLS connections.
This object can also be used as a context manager.
"""
self._closed = True
self.socket.close()
for stream in list(self._streams.values()):
stream.close()
self._incoming_connections_q.s.close()
def __enter__(self):
return self
def __exit__(self, *args):
self.close()
def _check_closed(self):
if self._closed:
raise trio.ClosedResourceError
async def serve(
self, ssl_context, async_fn, *args, task_status=trio.TASK_STATUS_IGNORED
):
"""Listen for incoming connections, and spawn a handler for each using an
internal nursery.
Similar to `~trio.serve_tcp`, this function never returns until cancelled, or
the `DTLSEndpoint` is closed and all handlers have exited.
Usage commonly looks like::
async def handler(dtls_channel):
...
async with trio.open_nursery() as nursery:
await nursery.start(dtls_endpoint.serve, ssl_context, handler)
# ... do other things here ...
The ``dtls_channel`` passed into the handler function has already performed the
"cookie exchange" part of the DTLS handshake, so the peer address is
trustworthy. But the actual cryptographic handshake doesn't happen until you
start using it, giving you a chance for any last minute configuration, and the
option to catch and handle handshake errors.
Args:
ssl_context (OpenSSL.SSL.Context): The PyOpenSSL context object to use for
incoming connections.
async_fn: The handler function that will be invoked for each incoming
connection.
"""
self._check_closed()
if self._listening_context is not None:
raise trio.BusyResourceError("another task is already listening")
try:
self.socket.getsockname()
except OSError:
raise RuntimeError("DTLS socket must be bound before it can serve")
self._ensure_receive_loop()
# We do cookie verification ourselves, so tell OpenSSL not to worry about it.
# (See also _inject_client_hello_untrusted.)
ssl_context.set_cookie_verify_callback(lambda *_: True)
try:
self._listening_context = ssl_context
task_status.started()
async def handler_wrapper(stream):
with stream:
await async_fn(stream, *args)
async with trio.open_nursery() as nursery:
async for stream in self._incoming_connections_q.r: # pragma: no branch
nursery.start_soon(handler_wrapper, stream)
finally:
self._listening_context = None
def connect(self, address, ssl_context):
"""Initiate an outgoing DTLS connection.
Notice that this is a synchronous method. That's because it doesn't actually
initiate any I/O – it just sets up a `DTLSChannel` object. The actual handshake
doesn't occur until you start using the `DTLSChannel`. This gives you a chance
to do further configuration first, like setting MTU etc.
Args:
address: The address to connect to. Usually a (host, port) tuple, like
``("127.0.0.1", 12345)``.
ssl_context (OpenSSL.SSL.Context): The PyOpenSSL context object to use for
this connection.
Returns:
DTLSChannel
"""
# it would be nice if we could detect when 'address' is our own endpoint (a
# loopback connection), because that can't work
# but I don't see how to do it reliably
self._check_closed()
channel = DTLSChannel._create(self, address, ssl_context)
channel._ssl.set_connect_state()
old_channel = self._streams.get(address)
if old_channel is not None:
old_channel._set_replaced()
self._streams[address] = channel
return channel