RFC 9147
The Datagram Transport Layer Security (DTLS) Protocol Version 1.3
RFC 9147: DTLS 1.3 🎀
Okay bestie, this is the spec for DTLS 1.3, the version of Datagram Transport Layer Security that lets apps send encrypted, tamper-proof messages over UDP 🦋. Here's the title block in plain English:
- Title: The Datagram Transport Layer Security (DTLS) Protocol Version 1.3
- Authors: E. Rescorla (Mozilla), H. Tschofenig (Arm Limited), and N. Modadugu (Google, Inc.) 👑
- Publisher: IETF (Internet Engineering Task Force)
- Category and status: Standards Track
- Date: April 2022
- ISSN: 2070-1721
- Obsoletes: RFC 6347, which is DTLS 1.2. So this one replaces it! 💅
Abstract ✨
Okay so this document specifies version 1.3 of DTLS 🌸 It lets client/server apps talk over the Internet in a way that's built to stop eavesdropping, tampering, and message forgery. Iconic behavior, honestly 😭
DTLS 1.3 is based on TLS 1.3 and gives you equivalent security guarantees, except for order protection and non-replayability 🙈 Datagram semantics from the underlying transport are kept intact too.
This document obsoletes RFC 6347.
Status of This Memo 📜
This is an Internet Standards Track document.
It's a product of the Internet Engineering Task Force (IETF), so it represents the consensus of the IETF community. It went through public review and got approved for publication by the Internet Engineering Steering Group (IESG). For more on Internet Standards, check Section 2 of RFC 7841 🧚
Info about the current status of this doc, any errata, and how to send feedback lives at https://www.rfc-editor.org/info/rfc9147.
Copyright Notice 💜
Copyright (c) 2022 IETF Trust and the persons identified as the document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info), as in effect on the date of publication. Please read these carefully, because they spell out your rights and restrictions for this doc. Code Components pulled out of this document must include Revised BSD License text, as described in Section 4.e of the Trust Legal Provisions, and they come without warranty, as described in the Revised BSD License.
This document may contain material from IETF Documents or IETF Contributions published or made publicly available before November 10, 2008. The people controlling the copyright in some of that material may not have granted the IETF Trust the right to allow modifications outside the IETF Standards Process. Without an adequate license from those copyright holders, this document may not be modified outside the IETF Standards Process, and derivative works of it may not be created outside the IETF Standards Process. The exceptions are formatting it for publication as an RFC and translating it into languages other than English.
Table of Contents 🗺️
1. Introduction
2. Conventions and Terminology
3. DTLS Design Rationale and Overview
3.1. Packet Loss
3.2. Reordering
3.3. Fragmentation
3.4. Replay Detection
4. The DTLS Record Layer
4.1. Demultiplexing DTLS Records
4.2. Sequence Number and Epoch
4.2.1. Processing Guidelines
4.2.2. Reconstructing the Sequence Number and Epoch
4.2.3. Record Number Encryption
4.3. Transport Layer Mapping
4.4. PMTU Issues
4.5. Record Payload Protection
4.5.1. Anti-Replay
4.5.2. Handling Invalid Records
4.5.3. AEAD Limits
5. The DTLS Handshake Protocol
5.1. Denial-of-Service Countermeasures
5.2. DTLS Handshake Message Format
5.3. ClientHello Message
5.4. ServerHello Message
5.5. Handshake Message Fragmentation and Reassembly
5.6. EndOfEarlyData Message
5.7. DTLS Handshake Flights
5.8. Timeout and Retransmission
5.8.1. State Machine
5.8.2. Timer Values
5.8.3. Large Flight Sizes
5.8.4. State Machine Duplication for Post-Handshake Messages
5.9. Cryptographic Label Prefix
5.10. Alert Messages
5.11. Establishing New Associations with Existing Parameters
6. Example of Handshake with Timeout and Retransmission
6.1. Epoch Values and Rekeying
7. ACK Message
7.1. Sending ACKs
7.2. Receiving ACKs
7.3. Design Rationale
8. Key Updates
9. Connection ID Updates
9.1. Connection ID Example
10. Application Data Protocol
11. Security Considerations
12. Changes since DTLS 1.2
13. Updates Affecting DTLS 1.2
14. IANA Considerations
15. References
15.1. Normative References
15.2. Informative References
Appendix A. Protocol Data Structures and Constant Values
A.1. Record Layer
A.2. Handshake Protocol
A.3. ACKs
A.4. Connection ID Management
Appendix B. Analysis of Limits on CCM Usage
B.1. Confidentiality Limits
B.2. Integrity Limits
B.3. Limits for AEAD_AES_128_CCM_8
Appendix C. Implementation Pitfalls
Contributors
Authors' Addresses1. Introduction 🌈
Okay, the main goal of TLS is to set up an authenticated channel between two peers that's protected for both confidentiality and integrity 🔐 TLS has two layers, the TLS record protocol and the TLS handshake protocol. But TLS needs a reliable transport underneath it, which is usually TCP [RFC0793] 🙄
Some apps use UDP [RFC0768] as their transport instead, so DTLS was made to give those apps communication security too. DTLS is deliberately built to look as much like TLS as possible, so there's less new security stuff to invent and more code and infrastructure can be reused ✨
DTLS 1.0 [RFC4347] started out as a delta from TLS 1.1 [RFC4346], and DTLS 1.2 [RFC6347] was a series of deltas to TLS 1.2 [RFC5246]. There is no DTLS 1.1, because that version number got skipped so it would match TLS 🦋 This specification describes the newest version of DTLS as a delta from TLS 1.3 [TLS13]. It obsoletes DTLS 1.2.
Implementations that speak both DTLS 1.2 and DTLS 1.3 can interoperate with ones that only speak DTLS 1.2 (they just use DTLS 1.2, obviously). It's the same deal as TLS 1.3 and TLS 1.2, see Appendix D of [TLS13] for the details. Backwards compatibility with DTLS 1.0 is possible, but using DTLS 1.0 is not recommended, as explained in Section 3.1.2 of [RFC7525]. [DEPRECATE] forbids the use of DTLS 1.0 💀
2. Conventions and Terminology 🎀
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here. So lowercase doesn't count, bestie 🙈
Here are the terms we use:
- client: The endpoint that starts the DTLS connection.
- association: Shared state between two endpoints, set up with a DTLS handshake.
- connection: A synonym for association.
- endpoint: Either the client or the server of the connection.
- epoch: One set of cryptographic keys used for encryption and decryption.
- handshake: The initial negotiation between client and server that sets the connection's parameters.
- peer: An endpoint. When we're talking about one particular endpoint, "peer" means the endpoint on the other side, the one that's remote to our main subject.
- receiver: An endpoint that's receiving records.
- sender: An endpoint that's transmitting records.
- server: The endpoint that did not start the DTLS connection.
- CID: Connection ID.
- MSL: Maximum Segment Lifetime.
The reader is expected to know [TLS13]. Like in TLS 1.3, the HelloRetryRequest has the same format as a ServerHello message. For convenience, though, we talk about HelloRetryRequest as if it's its own distinct message 💅
DTLS 1.3 uses network byte order (big-endian) for encoding messages, based on the encoding format defined in [TLS13] and the earlier (D)TLS specs.
You should also know [RFC9146], because this doc applies the CID functionality to DTLS 1.3 🧚
The figures in this document show different combinations of DTLS protocol exchanges. The symbols mean:
+indicates noteworthy extensions sent in the previously noted message.*indicates optional or situation-dependent messages/extensions that are not always sent.{}indicates messages protected using keys derived from a[sender]_handshake_traffic_secret.[]indicates messages protected using keys derived fromtraffic_secret_N.
3. DTLS Design Rationale and Overview 🦋
The basic design philosophy of DTLS is to build "TLS over datagram transport" 💖 Datagram transport doesn't require or provide reliable or in-order delivery of data, and DTLS keeps that property for application data. Apps like media streaming, Internet telephony, and online gaming use datagram transport because their data is delay-sensitive ⚡ Those apps behave the same when DTLS secures their traffic, since DTLS doesn't make up for lost or reordered data. Low-latency streaming and gaming use DTLS to protect data (for example, to protect a WebRTC data channel), while telephony uses DTLS for key establishment and the Secure Real-time Transport Protocol (SRTP) for protecting the data [RFC5763] 🎧
TLS can't be used directly over datagram transports for four reasons:
- TLS relies on an implicit sequence number on records. If a record doesn't arrive, the recipient uses the wrong sequence number when it tries to remove record protection from later records. DTLS fixes this by adding sequence numbers to records 🔢
- The TLS handshake is a lock-step cryptographic protocol. Messages have to be sent and received in a defined order, and any other order is an error. The DTLS handshake includes message sequence numbers so fragmented messages can be reassembled and delivered in order even when datagrams are lost or reordered 🧩
- Handshake messages can be bigger than a single datagram can hold. DTLS adds fields to handshake messages to support fragmentation and reassembly 📦
- Datagram transport protocols are open to abusive behavior that leads to denial-of-service (DoS) attacks against nonparticipants. DTLS adds a return-routability check, and DTLS 1.3 uses the TLS 1.3 HelloRetryRequest message for it (see Section 5.1 for details) 🛡️
3.1. Packet Loss 🕒
Okay so DTLS handles packet loss with a super simple retransmission timer ⏰ Figure 1 shows the basic idea using the first phase of the handshake, bestie 🎀
Client Server
------ ------
ClientHello ------>
X<-- HelloRetryRequest
(lost)
[Timer Expires]
ClientHello ------>
(retransmit)Figure 1: DTLS Retransmission Example
Once the client has sent its ClientHello, it's waiting to hear back with a HelloRetryRequest or a ServerHello from the server 👀 If the timer goes off before anything shows up, the client can't tell which one got lost, the ClientHello or the server's reply, so it just retransmits the ClientHello 🔁 When the server gets that retransmission, it knows to send its HelloRetryRequest or ServerHello again. Iconic teamwork 🫶
The server runs its own retransmission timer for the messages it sends (except the HelloRetryRequest) and resends them when that timer expires ✨ The HelloRetryRequest is left out on purpose, because skipping retransmission for it means the server doesn't have to store any state 🧠 It's also designed to be small enough that it never gets fragmented, so there's no mess about interleaving several HelloRetryRequests 💅
For more detail on timeouts and retransmission, see Section 5.8 🦋
3.2. Reordering 🔀
In DTLS, every handshake message gets its own specific sequence number 🔢 When a peer receives a handshake message, it can quickly check whether it's the next one it was expecting 👀 If it is, great, it gets processed right away 🎉 If not, it gets queued up and handled later, once all the earlier messages have shown up 💜
3.3. Fragmentation 🧩
TLS and DTLS handshake messages can be seriously chunky, up to 2^24-1 bytes in theory and many kilobytes in practice 😭 Meanwhile, UDP datagrams are often capped at under 1500 bytes if you don't want IP fragmentation, so there's a mismatch 🙈 To fix that, each DTLS handshake message can get fragmented across several DTLS records, and each record is meant to fit in a single UDP datagram (see Section 4.4 for guidance) 📦 Every DTLS handshake message carries both a fragment offset and a fragment length, so a recipient who has all the bytes of a handshake message can put the original unfragmented message back together 🧩✨
3.4. Replay Detection 🚫
DTLS optionally supports record replay detection 🛡️ It uses the same technique as IPsec AH/ESP, which is a bitmap window of received records 🪟 Records that are too old to fit in the window, and records that have already been received, get silently discarded 🤫 The replay detection feature is optional because duplicate packets aren't always malicious. They can also show up from routing errors 🗺️ Applications might be able to spot duplicate packets and tweak how they send data because of that 🤓
4. The DTLS Record Layer 📦
The DTLS 1.3 record layer is different from the TLS 1.3 record layer, and it's also different from the DTLS 1.2 record layer 💖 The main differences are:
- The DTLSCiphertext structure leaves out the superfluous version number and type fields 🧹
- DTLS adds an epoch and a sequence number to the TLS record header 🔢 The sequence number lets the recipient correctly decrypt and verify DTLS records 🔓 The number of bits used for the epoch and sequence number fields in the DTLSCiphertext structure has been cut down from previous versions ✂️
- The DTLS epoch in DTLSPlaintext is 2 octets long, for compatibility with DTLS 1.2 💕 That value is set to the least significant 2 octets of the connection epoch, which is an 8 octet counter that goes up on every KeyUpdate 📈 See Section 4.2 for details. The sequence number is set to the low order 48 bits of the 64 bit sequence number. Plaintext records MUST NOT be sent with sequence numbers that would exceed 2^48-1, so the upper 16 bits will always be 0 🙅♀️
- The DTLSCiphertext structure has a variable-length header 🌈
DTLSPlaintext records are used to send unprotected records, and DTLSCiphertext records are used to send protected records 🔐
The DTLS record formats are shown below. Unless explicitly stated, the meaning of the fields is unchanged from previous TLS/DTLS versions 🎀
struct {
ContentType type;
ProtocolVersion legacy_record_version;
uint16 epoch = 0
uint48 sequence_number;
uint16 length;
opaque fragment[DTLSPlaintext.length];
} DTLSPlaintext;
struct {
opaque content[DTLSPlaintext.length];
ContentType type;
uint8 zeros[length_of_padding];
} DTLSInnerPlaintext;
struct {
opaque unified_hdr[variable];
opaque encrypted_record[length];
} DTLSCiphertext;Figure 2: DTLS 1.3 Record Formats
Here's what the fields mean 👑
legacy_record_version: This value MUST be set to {254, 253} for all records other than the initial ClientHello (i.e., one not generated after a HelloRetryRequest), where it may also be {254, 255} for compatibility purposes. It MUST be ignored for all purposes. See [TLS13], Appendix D.1 for the rationale for this 🧐epoch: The least significant 2 bytes of the connection epoch value 🔢unified_hdr: The unified header (unified_hdr) is a structure of variable length, shown in Figure 3 🧩encrypted_record: The encrypted form of the serialized DTLSInnerPlaintext structure 🔒
0 1 2 3 4 5 6 7
+-+-+-+-+-+-+-+-+
|0|0|1|C|S|L|E E|
+-+-+-+-+-+-+-+-+
| Connection ID | Legend:
| (if any, |
/ length as / C - Connection ID (CID) present
| negotiated) | S - Sequence number length
+-+-+-+-+-+-+-+-+ L - Length present
| 8 or 16 bit | E - Epoch
|Sequence Number|
+-+-+-+-+-+-+-+-+
| 16 bit Length |
| (if present) |
+-+-+-+-+-+-+-+-+Figure 3: DTLS 1.3 Unified Header
Here's how the unified header bits work 🦋
- Fixed Bits: The three high bits of the first byte of the unified header are set to 001. This makes sure the value fits within the DTLS region when multiplexing is done as described in [RFC7983]. It also makes it possible to tell encrypted DTLS 1.3 records apart from encrypted DTLS 1.2 records when they're carried on the same host/port quartet. That multiplexing only works when CIDs [RFC9146] are in use, and in that case DTLS 1.2 records will have the content type tls12_cid (25) 🤩
- C: The C bit (0x10) is set if the Connection ID is present 🆔
- S: The S bit (0x08) indicates the size of the sequence number. 0 means an 8-bit sequence number, and 1 means 16-bit. Implementations MAY mix sequence numbers of different lengths on the same connection 🔀
- L: The L bit (0x04) is set if the length is present 📏
- E: The two low bits (0x03) include the low-order two bits of the epoch 🔢
- Connection ID: A variable-length CID. The CID functionality is described in [RFC9146]. An example can be found in Section 9.1 🪪
- Sequence Number: The low-order 8 or 16 bits of the record sequence number. This value is 16 bits if the S bit is set to 1, and 8 bits if the S bit is 0 🔢
- Length: Identical to the length field in a TLS 1.3 record 📐
As with previous versions of DTLS, multiple DTLSPlaintext and DTLSCiphertext records can be packed into the same underlying transport datagram 📬
Figure 4 shows different record headers, bestie 👀
0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7
+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+
| Content Type | |0|0|1|1|1|1|E E| |0|0|1|0|0|0|E E|
+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+
| 16 bit | | | |8 bit Seq. No. |
| Version | / Connection ID / +-+-+-+-+-+-+-+-+
+-+-+-+-+-+-+-+-+ | | | |
| 16 bit | +-+-+-+-+-+-+-+-+ | Encrypted |
| Epoch | | 16 bit | / Record /
+-+-+-+-+-+-+-+-+ |Sequence Number| | |
| | +-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+
| | | 16 bit |
| 48 bit | | Length | DTLSCiphertext
|Sequence Number| +-+-+-+-+-+-+-+-+ Structure
| | | | (minimal)
| | | Encrypted |
+-+-+-+-+-+-+-+-+ / Record /
| 16 bit | | |
| Length | +-+-+-+-+-+-+-+-+
+-+-+-+-+-+-+-+-+
| | DTLSCiphertext
| | Structure
/ Fragment / (full)
| |
+-+-+-+-+-+-+-+-+
DTLSPlaintext
StructureFigure 4: DTLS 1.3 Header Examples
The length field MAY be omitted by clearing the L bit, which means the record consumes the entire rest of the datagram in the lower level transport 🌊 In that case, it's not possible to have multiple DTLSCiphertext format records without length fields in the same datagram 🙅♀️ Omitting the length field MUST only be used for the last record in a datagram 🏁 Implementations MAY mix records with and without length fields on the same connection 🎭
If a Connection ID is negotiated, it MUST be contained in all datagrams 🆔 Sending implementations MUST NOT mix records from multiple DTLS associations in the same datagram 🚫 If the second or later record has a connection ID that doesn't correspond to the same association used for the previous records, the rest of the datagram MUST be discarded 🗑️
When expanded, the epoch and sequence number can be combined into an unpacked RecordNumber structure, as shown below 🧮
struct {
uint64 epoch;
uint64 sequence_number;
} RecordNumber;This 128-bit value is used in the ACK message, and also in the "record_sequence_number" input to the Authenticated Encryption with Associated Data (AEAD) function 🔐 The entire header value shown in Figure 4 (but before record number encryption, see Section 4.2.3) is used as the additional data value for the AEAD function 🧁 For instance, if the minimal variant is used, the Associated Data (AD) is 2 octets long 📏 Note that this design is different from the additional data calculation for DTLS 1.2 and for DTLS 1.2 with Connection IDs. In DTLS 1.3, the 64-bit sequence_number is used as the sequence number for the AEAD computation, and unlike DTLS 1.2, the epoch is not included 💅✨
4.1. Demultiplexing DTLS Records ✨
okay so DTLS 1.3's header is way more complicated to demux than DTLS 1.2 🫠 in 1.2 the content type was always just the first byte, but now the first byte is doing a lot 💅 Figure 5 shows how it works: the first byte decides how an incoming DTLS record gets demuxed. The first 3 bits of that byte tell a DTLS 1.3 encrypted record apart from the record types used in older DTLS versions and from the plaintext DTLS 1.3 types. So the range 32 (0b0010 0000) to 63 (0b0011 1111) has to stay off-limits for future IANA allocations, or demuxing gets messy 🙈 (see Section 14). Here's how implementations can demux DTLS 1.3 records by checking the first byte:
- If the first byte is alert(21), handshake(22), or ack(proposed, 26), the record MUST be interpreted as a DTLSPlaintext record.
- If the first byte is any other value, then receivers MUST check to see if the leading bits of the first byte are 001. If so, the implementation MUST process the record as DTLSCiphertext; the true content type will be inside the protected portion.
- Otherwise, the record MUST be rejected as if it had failed deprotection, as described in Section 4.5.2.
Figure 5 shows this demultiplexing procedure graphically, taking DTLS 1.3 and earlier versions of DTLS into account. It's giving flowchart 🦋
+----------------+
| Outer Content |
| Type (OCT) |
| |
| OCT == 20 -+--> ChangeCipherSpec (DTLS <1.3)
| OCT == 21 -+--> Alert (Plaintext)
| OCT == 22 -+--> DTLSHandshake (Plaintext)
| OCT == 23 -+--> Application Data (DTLS <1.3)
| OCT == 24 -+--> Heartbeat (DTLS <1.3)
packet --> | OCT == 25 -+--> DTLSCiphertext with CID (DTLS 1.2)
| OCT == 26 -+--> ACK (DTLS 1.3, Plaintext)
| |
| | /+----------------+\
| 31 < OCT < 64 -+--> |DTLSCiphertext |
| | |(header bits |
| else | | start with 001)|
| | | /+-------+--------+\
+-------+--------+ |
| |
v Decryption |
+---------+ +------+
| Reject | |
+---------+ v
+----------------+
| Decrypted |
| Content Type |
| (DCT) |
| |
| DCT == 21 -+--> Alert
| DCT == 22 -+--> DTLSHandshake
| DCT == 23 -+--> Application Data
| DCT == 24 -+--> Heartbeat
| DCT == 26 -+--> ACK
| else ------+--> Error
+----------------+
Figure 5: Demultiplexing DTLS 1.2 and DTLS 1.3 Records4.2. Sequence Number and Epoch
DTLS uses an explicit or partly explicit sequence number, not an implicit one, carried in the sequence_number field of the record. Sequence numbers are tracked separately for each epoch, and each sequence_number starts at 0 for every epoch 🌸
The epoch number starts at zero and goes up each time the keying material changes and a sender aims to rekey. More details are in Section 6.1.
4.2.1. Processing Guidelines
Because DTLS records could be reordered, a record from epoch M may be received after epoch N (where N > M) has begun. Implementations SHOULD discard records from earlier epochs, but MAY choose to retain keying material from previous epochs for up to the default MSL specified for TCP [RFC0793] to allow for packet reordering. (Note that the intention here is that implementers use the current guidance from the IETF for MSL, as specified in [RFC0793] or successors, not that they attempt to interrogate the MSL that the system TCP stack is using.)
Conversely, it is possible for records that are protected with the new epoch to be received prior to the completion of a handshake. For instance, the server may send its Finished message and then start transmitting data. Implementations MAY either buffer or discard such records, though when DTLS is used over reliable transports (e.g., SCTP [RFC4960]), they SHOULD be buffered and processed once the handshake completes. Note that TLS's restrictions on when records may be sent still apply, and the receiver treats the records as if they were sent in the right order 🧚
Implementations MUST send retransmissions of lost messages using the same epoch and keying material as the original transmission.
Implementations MUST either abandon an association or rekey prior to allowing the sequence number to wrap.
Implementations MUST NOT allow the epoch to wrap, but instead MUST establish a new association, terminating the old association. That's a hard no on epoch wraparound, bestie 💀
4.2.2. Reconstructing the Sequence Number and Epoch
When receiving protected DTLS records, the recipient doesn't have a full epoch or sequence number value in the record, so there's some room for ambiguity 👀 Because the full sequence number is used to compute the per-record nonce and the epoch determines the keys, failing to reconstruct these values means failing to deprotect the record. So implementations MAY use a mechanism of their choice to determine the full values. This section gives an algorithm that's comparatively simple, and implementations are RECOMMENDED to follow it.
If the epoch bits match those of the current epoch, then implementations SHOULD reconstruct the sequence number by computing the full sequence number which is numerically closest to one plus the sequence number of the highest successfully deprotected record in the current epoch.
During the handshake phase, the epoch bits unambiguously indicate the correct key to use. After the handshake is complete, if the epoch bits do not match those from the current epoch, implementations SHOULD use the most recent past epoch which has matching bits, and then reconstruct the sequence number for that epoch as described above.
4.2.3. Record Number Encryption
In DTLS 1.3, when records are encrypted, the record sequence numbers are encrypted too 🔐 The basic pattern is that the underlying encryption algorithm used with the AEAD algorithm generates a mask, which is then XORed with the sequence number.
When the AEAD is based on AES, the mask is generated by computing AES-ECB on the first 16 bytes of the ciphertext:
Mask = AES-ECB(sn_key, Ciphertext[0..15])When the AEAD is based on ChaCha20, the mask is generated by treating the first 4 bytes of the ciphertext as the block counter and the next 12 bytes as the nonce, then passing them to the ChaCha20 block function (Section 2.3 of [CHACHA]):
Mask = ChaCha20(sn_key, Ciphertext[0..3], Ciphertext[4..15])The sn_key is computed as follows:
[sender]_sn_key = HKDF-Expand-Label(Secret, "sn", "", key_length)[sender] denotes the sending side. The per-epoch Secret value to be used is described in Section 7.3 of [TLS13]. Note that a new key is used for each epoch. Because the epoch is sent in the clear, this doesn't result in ambiguity ✨
The encrypted sequence number is computed by XORing the leading bytes of the mask with the on-the-wire representation of the sequence number. Decryption is done by the same process.
This procedure requires the ciphertext length to be at least 16 bytes. Receivers MUST reject shorter records as if they had failed deprotection, as described in Section 4.5.2. Senders MUST pad short plaintexts out (using the conventional record padding mechanism) to make a suitable-length ciphertext. Most of the DTLS AEAD algorithms have a 16 byte authentication tag and need no padding. However, some algorithms, such as TLS_AES_128_CCM_8_SHA256, have a shorter authentication tag and may require padding for short inputs.
Future cipher suites, which are not based on AES or ChaCha20, MUST define their own record sequence number encryption in order to be used with DTLS.
Note that sequence number encryption only applies to the DTLSCiphertext structure and not to the DTLSPlaintext structure, even though DTLSPlaintext also contains a sequence number 🙃
4.3. Transport Layer Mapping
DTLS messages MAY be fragmented into multiple DTLS records. Each DTLS record MUST fit within a single datagram. To avoid IP fragmentation, clients of the DTLS record layer SHOULD attempt to size records so that they fit within any Path MTU (PMTU) estimates obtained from the record layer. For more info about PMTU issues, see Section 4.4.
Multiple DTLS records MAY be placed in a single datagram. Records are encoded consecutively. The length field from DTLS records containing that field can be used to determine the boundaries between records. The final record in a datagram can omit the length field. The first byte of the datagram payload MUST be the beginning of a record. Records MUST NOT span datagrams.
DTLS records without CIDs don't contain any association identifiers, so applications have to arrange multiplexing between associations. With UDP, the host/port number is used to look up the right security association for incoming records without CIDs 🦋
Some transports, such as DCCP [RFC4340], provide their own sequence numbers. When carried over those transports, both the DTLS and the transport sequence numbers will be present. Although this adds a small amount of inefficiency, the transport layer and DTLS sequence numbers serve different purposes, so for conceptual simplicity, it is superior to use both sequence numbers 💖
Some transports provide congestion control for traffic carried over them. If the congestion window is sufficiently narrow, DTLS handshake retransmissions may be held rather than transmitted immediately, potentially leading to timeouts and spurious retransmission. When DTLS is used over such transports, care should be taken not to overrun the likely congestion window. [RFC5238] defines a mapping of DTLS to DCCP that takes these issues into account 🎀
4.4. PMTU Issues 🎀
Okay so, bestie, DTLS's whole philosophy is to leave PMTU discovery to the application 💅. BUT it can't completely ignore the PMTU, and there are three reasons why 😭:
- The DTLS record framing expands the datagram size, thus lowering the effective PMTU from the application's perspective.
- In some implementations, the application may not directly talk to the network, in which case the DTLS stack may absorb ICMP "Datagram Too Big" indications [RFC1191] or ICMPv6 "Packet Too Big" indications [RFC4443].
- The DTLS handshake messages can exceed the PMTU.
To deal with the first two issues, the DTLS record layer SHOULD behave as described below 🫶.
If PMTU estimates are available from the underlying transport protocol, they should be made available to upper layer protocols ✨. Specifically:
- For DTLS over UDP, the upper layer protocol SHOULD be allowed to obtain the PMTU estimate maintained in the IP layer 🦋.
- For DTLS over DCCP, the upper layer protocol SHOULD be allowed to obtain the current estimate of the PMTU 🌸.
- For DTLS over TCP or SCTP, which automatically fragment and reassemble datagrams, there is no PMTU limitation. However, the upper layer protocol MUST NOT write any record that exceeds the maximum record size of 2^14 bytes 💀.
The DTLS record layer SHOULD also allow the upper layer protocol to discover the amount of record expansion expected by the DTLS processing. Alternately, it MAY report PMTU estimates minus the estimated expansion from the transport layer and DTLS record framing 🧚.
Note that DTLS does not defend against spoofed ICMP messages, so implementations SHOULD ignore any such messages that indicate PMTUs below the IPv4 and IPv6 minimums of 576 and 1280 bytes, respectively 🙈.
If there is a transport protocol indication that the PMTU was exceeded (either via ICMP or via a refusal to send the datagram as in Section 14 of [RFC4340]), then the DTLS record layer MUST inform the upper layer protocol of the error 🔥.
The DTLS record layer SHOULD NOT interfere with upper layer protocols performing PMTU discovery, whether via [RFC1191] and [RFC4821] for IPv4 or via [RFC8201] for IPv6. In particular:
- Where allowed by the underlying transport protocol, the upper layer protocol SHOULD be allowed to set the state of the Don't Fragment (DF) bit (in IPv4) or prohibit local fragmentation (in IPv6) 👑.
- If the underlying transport protocol allows the application to request PMTU probing (e.g., DCCP), the DTLS record layer SHOULD honor this request 🌈.
The final issue is the DTLS handshake protocol. From the perspective of the DTLS record layer, this is merely another upper layer protocol. BUT DTLS handshakes happen infrequently and only involve a few round trips, so the handshake protocol's PMTU handling puts a premium on rapid completion over accurate PMTU discovery ⭐. To allow connections under these circumstances, DTLS implementations SHOULD follow these rules:
- If the DTLS record layer informs the DTLS handshake layer that a message is too big, the handshake layer SHOULD immediately attempt to fragment the message, using any existing information about the PMTU 🍓.
- If repeated retransmissions do not result in a response, and the PMTU is unknown, subsequent retransmissions SHOULD back off to a smaller record size, fragmenting the handshake message as appropriate. This specification does not specify an exact number of retransmits to attempt before backing off, but 2-3 seems appropriate 💜.
4.5. Record Payload Protection 💖
Like TLS, DTLS transmits data as a series of protected records. The rest of this section describes the details of that format ✨.
4.5.1. Anti-Replay 🦋
Each DTLS record contains a sequence number to provide replay protection. Sequence number verification SHOULD be performed using the following sliding window procedure, borrowed from Section 3.4.3 of [RFC4303]. Because each epoch resets the sequence number space, a separate sliding window is needed for each epoch 🌸.
The received record counter for an epoch MUST be initialized to zero when that epoch is first used. For each received record, the receiver MUST verify that the record contains a sequence number that does not duplicate the sequence number of any other record received in that epoch during the lifetime of the association. This check SHOULD happen after deprotecting the record, because otherwise the record discard might itself serve as a timing channel for the record number. Note that computing the full record number from the partial one is still a potential timing channel for the record number, though a less powerful one than whether the record was deprotected 👀.
Duplicates are rejected through the use of a sliding receive window. (How the window is implemented is a local matter, but the following text describes the functionality that the implementation must exhibit.) The receiver SHOULD pick a window large enough to handle any plausible reordering, which depends on the data rate. (The receiver does not notify the sender of the window size.) 🧚
The "right" edge of the window represents the highest validated sequence number value received in the epoch. Records that contain sequence numbers lower than the "left" edge of the window are rejected. Records falling within the window are checked against a list of received records within the window. An efficient means for performing this check, based on the use of a bit mask, is described in Section 3.4.3 of [RFC4303]. If the received record falls within the window and is new, or if the record is to the right of the window, then the record is new 🎀.
The window MUST NOT be updated due to a received record until that record has been deprotected successfully 🫶.
4.5.2. Handling Invalid Records 💅
Unlike TLS, DTLS is resilient in the face of invalid records (e.g., invalid formatting, length, MAC, etc.). Honestly iconic 👑. In general, invalid records SHOULD be silently discarded, thus preserving the association; however, an error MAY be logged for diagnostic purposes. Implementations which choose to generate an alert instead MUST generate fatal alerts to avoid attacks where the attacker repeatedly probes the implementation to see how it responds to various types of error.
Note that if DTLS is run over UDP, then any implementation which does this will be extremely susceptible to DoS attacks, because UDP forgery is so easy. Thus, generating fatal alerts is NOT RECOMMENDED for such transports, both to increase the reliability of DTLS service and to avoid the risk of spoofing attacks sending traffic to unrelated third parties 😭🚨
If DTLS is being carried over a transport that is resistant to forgery (e.g., SCTP with SCTP-AUTH), then it is safer to send alerts, because an attacker will have difficulty forging a datagram that will not be rejected by the transport layer 🛡️.
Note that because invalid records are rejected at a layer lower than the handshake state machine, they do not affect pending retransmission timers ⏰.
4.5.3. AEAD Limits 🌈
Section 5.5 of [TLS13] defines limits on the number of records that can be protected using the same keys. These limits are specific to an AEAD algorithm and apply equally to DTLS. Implementations SHOULD NOT protect more records than allowed by the limit specified for the negotiated AEAD. Implementations SHOULD initiate a key update before reaching this limit 🔐.
[TLS13] does not specify a limit for AEAD_AES_128_CCM, but the analysis in Appendix B shows that a limit of 2^23 packets can be used to obtain the same confidentiality protection as the limits specified in TLS 🍓.
The usage limits defined in TLS 1.3 exist for protection against attacks on confidentiality and apply to successful applications of AEAD protection. The integrity protections in authenticated encryption also depend on limiting the number of attempts to forge packets. TLS achieves this by closing connections after any record fails an authentication check. In comparison, DTLS ignores any packet that cannot be authenticated, allowing multiple forgery attempts 🙃.
Implementations MUST count the number of received packets that fail authentication with each key. If the number of packets that fail authentication exceeds a limit that is specific to the AEAD in use, an implementation SHOULD immediately close the connection. Implementations SHOULD initiate a key update with update_requested before reaching this limit. Once a key update has been initiated, the previous keys can be dropped when the limit is reached, rather than closing the connection. Applying a limit reduces the probability that an attacker is able to successfully forge a packet; see [AEBounds] and [ROBUST] 🔒.
For AEAD_AES_128_GCM, AEAD_AES_256_GCM, and AEAD_CHACHA20_POLY1305, the limit on the number of records that fail authentication is 2^36. Note that the analysis in [AEBounds] supports a higher limit for AEAD_AES_128_GCM and AEAD_AES_256_GCM, but this specification recommends a lower limit. For AEAD_AES_128_CCM, the limit on the number of records that fail authentication is 2^23.5; see Appendix B 🧮.
The AEAD_AES_128_CCM_8 AEAD, as used in TLS_AES_128_CCM_8_SHA256, does not have a limit on the number of records that fail authentication that both limits the probability of forgery by the same amount and does not expose implementations to the risk of denial of service; see Appendix B.3. Therefore, TLS_AES_128_CCM_8_SHA256 MUST NOT be used in DTLS without additional safeguards against forgery. Implementations MUST set usage limits for AEAD_AES_128_CCM_8 based on an understanding of any additional forgery protections that are used 🥺.
Any TLS cipher suite that is specified for use with DTLS MUST define limits on the use of the associated AEAD function that preserves margins for both confidentiality and integrity. That is, limits MUST be specified for the number of packets that can be authenticated, and for the number of packets that can fail authentication before a key update is required. Providing a reference to any analysis upon which values are based, and any assumptions used in that analysis, allows limits to be adapted to varying usage conditions 📚.
5. The DTLS Handshake Protocol 🤝
DTLS 1.3 reuses the TLS 1.3 handshake messages and flows, with the following changes:
- To handle message loss, reordering, and fragmentation, modifications to the handshake header are necessary.
- Retransmission timers are introduced to handle message loss.
- A new ACK content type has been added for reliable message delivery of handshake messages.
In addition, DTLS reuses TLS 1.3's "cookie" extension to provide a return-routability check as part of connection establishment. This is an important DoS prevention mechanism for UDP-based protocols. TCP-based protocols don't need it, because TCP establishes return-routability as part of the connection establishment 🌟.
DTLS implementations do not use the TLS 1.3 "compatibility mode" described in Appendix D.4 of [TLS13]. DTLS servers MUST NOT echo the legacy_session_id value from the client, and endpoints MUST NOT send ChangeCipherSpec messages 🚫.
With these exceptions, the DTLS message formats, flows, and logic are the same as those of TLS 1.3 💜.
5.1. Denial-of-Service Countermeasures 🛡️
Okay bestie, datagram security protocols are literally so vulnerable to DoS attacks 😭 Two of them are the big worries:
- An attacker can eat up the server's resources by sending a stream of handshake initiation requests. That makes the server allocate state and maybe do expensive cryptographic operations 💀
- An attacker can use the server as an amplifier 📣 by sending connection initiation messages with a forged source address that belongs to a victim. The server then sends its response to the victim and floods it. Depending on the parameters you picked, that response can be pretty huge, like a Certificate message does.
To counter both of these, DTLS borrows the stateless cookie technique from Photuris [RFC2522] and IKE [RFC7296] ✨ When the client sends its ClientHello to the server, the server MAY respond with a HelloRetryRequest message. The HelloRetryRequest message, along with the "cookie" extension, is defined in TLS 1.3 🎀 The HelloRetryRequest message contains a stateless cookie (see [TLS13], Section 4.2.2). The client MUST send a new ClientHello with the cookie added as an extension. The server then checks the cookie and only keeps going with the handshake if it's valid. This forces the attacker/client to actually be able to receive the cookie, which makes spoofed-IP DoS attacks way harder 🦋 This mechanism does not provide any defense against DoS attacks mounted from valid IP addresses. Sorry bestie 🙈
The DTLS 1.3 spec changes how cookies get exchanged compared to DTLS 1.2 🌈 DTLS 1.3 reuses the HelloRetryRequest message and passes the cookie to the client via an extension. The client that gets the cookie uses that same extension to put the cookie into a ClientHello message later on. DTLS 1.2, on the other hand, used a separate message, the HelloVerifyRequest, to hand over a cookie, and it didn't use the extension mechanism at all. For backwards compatibility reasons, the cookie field in the ClientHello is still there in DTLS 1.3, but a DTLS 1.3-compliant server implementation just ignores it 💅
Here's the exchange, shown in Figure 6. The figure only focuses on the cookie exchange, so all the other extensions are left out 🧚
Client Server
------ ------
ClientHello ------>
<----- HelloRetryRequest
+ cookie
ClientHello ------>
+ cookie
[Rest of handshake]Figure 6: DTLS Exchange with HelloRetryRequest Containing the "cookie" Extension
The "cookie" extension is defined in Section 4.2.2 of [TLS13]. When the client sends the initial ClientHello, it doesn't have a cookie yet. So in this case the "cookie" extension is omitted, and the legacy_cookie field in the ClientHello message MUST be set to a zero-length vector (i.e., a zero-valued single byte length field) 🫶
When the client is responding to a HelloRetryRequest, it MUST create a new ClientHello message following the description in Section 4.1.2 of [TLS13] ✨
If the HelloRetryRequest message is used, then the initial ClientHello and the HelloRetryRequest both get included in the calculation of the transcript hash 🔥 The computation of the message hash for the HelloRetryRequest is done according to the description in Section 4.4.1 of [TLS13].
The handshake transcript doesn't get reset with the second ClientHello, and a stateless server-cookie implementation needs the content or hash of the initial ClientHello (and HelloRetryRequest) to be stored in the cookie 🍓 The initial ClientHello is included in the handshake transcript as a synthetic "message_hash" message, so only the hash value is needed for the handshake to complete, though the complete HelloRetryRequest contents are still needed.
When the second ClientHello arrives, the server can check that the cookie is valid and that the client can actually receive packets at the given IP address 👑 If the client's apparent IP address is embedded in the cookie, then an attacker can't generate an acceptable ClientHello that looks like it's coming from some other user. Iconic 😭
One possible attack on this scheme is for the attacker to collect a bunch of cookies from different addresses where it controls endpoints, and then reuse them to attack the server 💀 The server can defend against that by changing the secret value frequently, which invalidates those old cookies. But if the server wants to let legitimate clients get through the transition (for example, a client got a cookie with Secret 1 and then sent the second ClientHello after the server switched to Secret 2), the server can keep a limited window where it accepts both secrets. [RFC7296] suggests adding a key identifier to cookies so this case can be detected. Another option is just trying to verify with both secrets. It is RECOMMENDED that servers implement a key rotation scheme that allows the server to manage keys with overlapping lifetimes. 🔑
Alternatively, the server can store timestamps in the cookie and reject any cookies that were generated outside a certain interval of time ⏰
DTLS servers SHOULD perform a cookie exchange whenever a new handshake is being performed 🌸 If the server is running in an environment where amplification isn't a problem, e.g., where ICE [RFC8445] has been used to establish bidirectional connectivity, the server MAY be configured not to perform a cookie exchange. The default SHOULD be that the exchange is performed, though. On top of that, the server MAY choose not to do a cookie exchange when a session is resumed, or, more generically, when the DTLS handshake uses a PSK-based key exchange and the IP address matches one associated with the PSK. Servers that process 0-RTT requests and send 0.5-RTT responses without a cookie exchange risk getting used in an amplification attack if the size of outgoing messages greatly exceeds the size of the ones that are received 📣 A server SHOULD limit the amount of data it sends toward a client address to three times the amount of data sent by the client, before it verifies that the client is able to receive data at that address. A client address is valid after a cookie exchange or handshake completion. Clients MUST be prepared to do a cookie exchange with every handshake. Also note that cookies are only valid for the existing handshake and cannot be stored for future handshakes 🙅♀️
If a server receives a ClientHello with an invalid cookie, it MUST terminate the handshake with an "illegal_parameter" alert. This lets the client restart the connection from scratch without a cookie 🔄
As described in Section 4.1.4 of [TLS13], clients MUST abort the handshake with an "unexpected_message" alert in response to any second HelloRetryRequest that was sent in the same connection (i.e., where the ClientHello was itself in response to a HelloRetryRequest) 🚫
DTLS clients that don't want to receive a Connection ID SHOULD still offer the "connection_id" extension [RFC9146] unless there's an application profile that says otherwise. This lets a server that wants to receive a CID negotiate one 🦋
5.2. DTLS Handshake Message Format 📜
DTLS uses the same Handshake messages as TLS 1.3 🥰 However, before they get transmitted, they're converted into DTLSHandshake messages, which carry extra data needed to support message loss, reordering, and message fragmentation ✨
enum {
client_hello(1),
server_hello(2),
new_session_ticket(4),
end_of_early_data(5),
encrypted_extensions(8),
request_connection_id(9), /* New */
new_connection_id(10), /* New */
certificate(11),
certificate_request(13),
certificate_verify(15),
finished(20),
key_update(24),
message_hash(254),
(255)
} HandshakeType;
struct {
HandshakeType msg_type; /* handshake type */
uint24 length; /* bytes in message */
uint16 message_seq; /* DTLS-required field */
uint24 fragment_offset; /* DTLS-required field */
uint24 fragment_length; /* DTLS-required field */
select (msg_type) {
case client_hello: ClientHello;
case server_hello: ServerHello;
case end_of_early_data: EndOfEarlyData;
case encrypted_extensions: EncryptedExtensions;
case certificate_request: CertificateRequest;
case certificate: Certificate;
case certificate_verify: CertificateVerify;
case finished: Finished;
case new_session_ticket: NewSessionTicket;
case key_update: KeyUpdate;
case request_connection_id: RequestConnectionId;
case new_connection_id: NewConnectionId;
} body;
} DTLSHandshake;In DTLS 1.3, the message transcript is computed over the original TLS 1.3-style Handshake messages, without the message_seq, fragment_offset, and fragment_length values 🧠 This is a change from DTLS 1.2, where those values were included in the transcript.
The first message each side sends in each association always has message_seq = 0 🌱 Whenever a new message is generated, the message_seq value goes up by one. When a message gets retransmitted, the old message_seq value is reused, i.e., it's not incremented. From the point of view of the DTLS record layer, the retransmission is a brand-new record, and this record will have a new DTLSPlaintext.sequence_number value 🔁
Note: In DTLS 1.2,message_seqwas reset to zero in case of a rehandshake (i.e., renegotiation). A rehandshake in DTLS 1.2 kind of looks like a post-handshake message exchange in DTLS 1.3. However, in DTLS 1.3 themessage_seqis not reset, so you can tell a retransmission apart from a previously sent post-handshake message versus a newly sent one 🫠
DTLS implementations keep track of (at least notionally) a next_receive_seq counter 🧮 This counter starts out at zero. When a handshake message comes in, if its message_seq value matches next_receive_seq, then next_receive_seq is incremented and the message is processed. If the sequence number is less than next_receive_seq, the message MUST be discarded. If the sequence number is greater than next_receive_seq, the implementation SHOULD queue the message but MAY discard it. (This is a simple space/bandwidth trade-off ⚖️)
Besides the handshake messages that the TLS 1.3 spec deprecates, DTLS 1.3 also deprecates the HelloVerifyRequest message that was originally defined in DTLS 1.0 💀 DTLS 1.3-compliant implementations MUST NOT use the HelloVerifyRequest to execute a return-routability check. A dual-stack DTLS 1.2 / DTLS 1.3 client MUST, however, be prepared to interact with a DTLS 1.2 server 🌈
5.3. ClientHello Message ✨
okay so the ClientHello a DTLS 1.3 client sends is not the same as the TLS 1.3 one 👀 here's the shape, bestie 💅
uint16 ProtocolVersion;
opaque Random[32];
uint8 CipherSuite[2]; /* Cryptographic suite selector */
struct {
ProtocolVersion legacy_version = { 254,253 }; // DTLSv1.2
Random random;
opaque legacy_session_id<0..32>;
opaque legacy_cookie<0..2^8-1>; // DTLS
CipherSuite cipher_suites<2..2^16-2>;
opaque legacy_compression_methods<1..2^8-1>;
Extension extensions<8..2^16-1>;
} ClientHello;Now the fields, one by one 🎀
legacy_version: in older DTLS versions this field did the version negotiating and held the highest version the client supported 🕰️. Plot twist: loads of servers don't handle negotiation properly, which causes "version intolerance" 💀. That's when a server bounces a perfectly fine ClientHello just because its version number is higher than the server knows. In DTLS 1.3, the client spells out its version preferences in thesupported_versionsextension (see Section 4.2.1 of [TLS13]), andlegacy_versionMUST be set to{254, 253}, which was the version number for DTLS 1.2 🎀. Thesupported_versionsentries for DTLS 1.0 and DTLS 1.2 are0xfeffand0xfefd(to match the wire versions), and0xfefcis the one that means DTLS 1.3 🦋.random: same as TLS 1.3, with one twist 🌈. The downgrade sentinels from Section 4.1.3 of [TLS13] (for when TLS 1.2 and TLS 1.1 and below get negotiated) apply to DTLS 1.2 and DTLS 1.0, respectively.legacy_session_id: older TLS and DTLS versions had a "session resumption" feature, which got merged with pre-shared keys (PSK) in 1.3 🧚. So a client with a cached session ID from a pre-DTLS 1.3 server SHOULD set this field to that value. Otherwise it MUST be a zero-length vector (i.e., a zero-valued single byte length field) 🫶.legacy_cookie: a DTLS 1.3-only client MUST set this field to zero length 🙈. If a DTLS 1.3 ClientHello comes in with any other value here, the server MUST abort the handshake with an "illegal_parameter" alert.cipher_suites: same as TLS 1.3; only suites with DTLS-OK=Y may be used 🔐.legacy_compression_methods: same as TLS 1.3 🍓.extensions: same as TLS 1.3 🌸.
5.4. ServerHello Message 🌸
the DTLS 1.3 ServerHello is basically the TLS 1.3 ServerHello, except legacy_version is set to 0xfefd, which says DTLS 1.2 🫠.
5.5. Handshake Message Fragmentation and Reassembly 🧩
as covered in Section 4.3, one or more handshake messages can ride in a single datagram. BUT handshake messages can be bigger than what the underlying datagram transport allows 😬. DTLS fixes this by fragmenting a handshake message across a bunch of records, each of which can go out in its own datagram, so IP fragmentation gets avoided ✨.
when the sender transmits a handshake message, it chops the message into N contiguous data ranges. The ranges MUST NOT overlap. Then it makes N DTLSHandshake messages, all with the same message_seq value as the original. Each new message gets labeled with fragment_offset (the number of bytes in previous fragments) and fragment_length (the length of this fragment). The length field is the same in every message as in the original message 📏. An unfragmented message is just a degenerate case where fragment_offset=0 and fragment_length=length. Each handshake message fragment placed into a record MUST be delivered in a single UDP datagram 📦.
when a DTLS implementation gets a handshake message fragment for the next expected handshake message sequence number, it MUST process it. It can either buffer it until it has the entire handshake message, or process any in-order portions as they come 🏃. The transcript is made of complete TLS Handshake messages (reassembled as necessary). Note that this means removing the message_seq, fragment_offset, and fragment_length fields to create the Handshake structure 🔍.
DTLS implementations MUST be able to handle overlapping fragment ranges. This lets senders retransmit handshake messages with smaller fragment sizes if the PMTU estimate changes 📉. Senders MUST NOT change handshake message bytes upon retransmission. Receivers MAY check that retransmitted bytes are identical, and SHOULD abort the handshake with an "illegal_parameter" alert if the value of a byte changes 🚨.
Note that, as with TLS, multiple handshake messages can be placed in the same DTLS record, as long as there's room and they're part of the same flight. So there are two acceptable ways to pack two DTLS handshake messages into the same datagram: in the same record, or in separate records 💜.
5.6. EndOfEarlyData Message 🏁
okay the DTLS 1.3 handshake has one important difference from the TLS 1.3 handshake: the EndOfEarlyData message is omitted from both the wire AND the handshake transcript 🫣. Why? Because DTLS records have epochs, so EndOfEarlyData isn't necessary to figure out when the early data is complete. And since DTLS is lossy, attackers can trivially pull off the deletion attacks that EndOfEarlyData prevents in TLS 😈. Servers SHOULD NOT accept records from epoch 1 indefinitely once they are able to process records from epoch 3. Reordering of IP packets can make records from epoch 1 arrive after records from epoch 3, but that's not likely to persist for very long relative to the round trip time ⏱️. Servers could discard epoch 1 keys after the first epoch 3 data arrives, or keep them around for processing epoch 1 data for a short period. (See Section 6.1 for the definitions of each epoch 🦋.)
5.7. DTLS Handshake Flights
Okay bestie, so DTLS handshake messages get grouped into flights 💌 A flight starts when one peer sends its handshake messages and ends when the other peer sends back the response it's waiting for ✨ Table 1 is the full cheat sheet of which message combos count as flights 📋
+======+========+========+===================================+
| Note | Client | Server | Handshake Messages |
+======+========+========+===================================+
| | x | | ClientHello |
+------+--------+--------+-----------------------------------+
| | | x | HelloRetryRequest |
+------+--------+--------+-----------------------------------+
| | | x | ServerHello, EncryptedExtensions, |
| | | | CertificateRequest, Certificate, |
| | | | CertificateVerify, Finished |
+------+--------+--------+-----------------------------------+
| 1 | x | | Certificate, CertificateVerify, |
| | | | Finished |
+------+--------+--------+-----------------------------------+
| 1 | | x | NewSessionTicket |
+------+--------+--------+-----------------------------------+
Table 1: Flight Handshake Message CombinationsRemarks 🎀
- Table 1 does not highlight any of the optional messages 🌸
- Regarding note (1): When a handshake flight is sent without any expected response, as is the case with the client's final flight or with the NewSessionTicket message, the flight must be acknowledged with an ACK message 🫶
Here come some example message exchanges so you can see the flight concept in action 🦋 They use the notational conventions from [TLS13], so bookmark that one 🔖
Client Server
+--------+ ClientHello | Flight | --------> +--------+
+--------+ <-------- HelloRetryRequest | Flight |
- cookie +--------+
+--------+ ClientHello | Flight |
- cookie --------> +--------+
ServerHello {EncryptedExtensions} +--------+ {CertificateRequest*} | Flight | {Certificate*} +--------+ {CertificateVerify*} {Finished} <-------- [Application Data*]
{Certificate*} +--------+ {CertificateVerify*} | Flight | {Finished} --------> +--------+ [Application Data] +--------+ <-------- [ACK] | Flight | [Application Data*] +--------+
[Application Data] <-------> [Application Data]
Figure 7: Message Flights for a Full DTLS Handshake (with Cookie Exchange)
ClientHello +--------+
- pre_shared_key | Flight |
- psk_key_exchange_modes +--------+
- key_share* -------->
ServerHello
- pre_shared_key +--------+
- key_share* | Flight | {EncryptedExtensions} +--------+ <-------- {Finished} [Application Data*] +--------+ {Finished} --------> | Flight | [Application Data*] +--------+
+--------+ <-------- [ACK] | Flight | [Application Data*] +--------+
[Application Data] <-------> [Application Data]
Figure 8: Message Flights for Resumption and PSK Handshake (without Cookie Exchange)
Client Server
ClientHello
- early_data
- psk_key_exchange_modes +--------+
- key_share* | Flight |
- pre_shared_key +--------+ (Application Data*) -------->
ServerHello
- pre_shared_key
- key_share* +--------+ {EncryptedExtensions} | Flight | {Finished} +--------+ <-------- [Application Data*]
+--------+ {Finished} --------> | Flight | [Application Data*] +--------+
+--------+ <-------- [ACK] | Flight | [Application Data*] +--------+
[Application Data] <-------> [Application Data]
Figure 9: Message Flights for the Zero-RTT Handshake
Client Server
+--------+ <-------- [NewSessionTicket] | Flight | +--------+
+--------+ [ACK] --------> | Flight | +--------+
Figure 10: Message Flights for the NewSessionTicket Message
And the last bit 💜 KeyUpdate, NewConnectionId, and RequestConnectionId all follow the same vibe as NewSessionTicket: one message from one side, then an ACK from the other 🌈 Iconic consistency, honestly 💅
## 5.8. Timeout and Retransmission
### 5.8.1. State Machine ✨
okay so DTLS keeps timeouts and retransmits super simple 💅 the whole thing runs on the state machine in Figure 11, and it's giving tidy 🦋
+-----------+
| PREPARING |
+----------> | |
| +-----------+ | ||
|---|---|---|
| Buffer next flight | ||
| \ | / | |
| +-----------+ | ||
| SENDING | <------------------+ | |
| +-----------+ |
Receive | | | next | | Send flight or partial | flight | | flight |
| Set retransmit timer | |
|---|---|
| \ | / |
| +-----------+ |
+------------| WAITING |-------------------+
| +-----> | Timer expires | |
|---|---|---|
| +-----------+ | ||
| +----------+ | +--------------------+ | |
| Receive record | Read retransmit or ACK |
Receive | (Maybe Send ACK) | last | | flight | | Receive ACK
| for last flight |
|/ |
+-----------+ |
| <---------+ | |
|---|---|
| FINISHED |
+-----------+
| / | \ |
+---+
Server read retransmit Retransmit ACK
Figure 11: DTLS Timeout and Retransmission State Machine
so the state machine has **four basic states** 🌈: `PREPARING`, `SENDING`, `WAITING`, and `FINISHED`.
in `PREPARING`, the implementation does all the computing needed to get the next flight of messages ready 🧚. then it buffers them for sending (emptying the transmission buffer first) and moves on to `SENDING`.
in `SENDING`, the implementation transmits the buffered flight. if it has already gotten one or more ACKs (see Section 7) from the peer, then it SHOULD omit any messages or message fragments that were already acknowledged 🫶. once everything's sent, it sets a retransmit timer and enters `WAITING`.
there are **four ways** to leave `WAITING` 👑:
1. The retransmit timer expires: the implementation moves to `SENDING`, where it retransmits the flight, adjusts and re-arms the retransmit timer (see Section 5.8.2), and goes back to `WAITING`.
2. The implementation reads an ACK from the peer: when it gets an ACK for a partial flight (as mentioned in Section 7.1), it moves to `SENDING`, where it retransmits the unacknowledged part of the flight, adjusts and re-arms the retransmit timer, and goes back to `WAITING`. When it gets an ACK for a complete flight, it cancels all retransmissions and either stays in `WAITING`, or, if the ACK was for the final flight, moves to `FINISHED` 🎀.
3. The implementation reads a retransmitted flight from the peer when none of the messages it sent in response to that flight have been acknowledged: it moves to `SENDING`, where it retransmits the flight, adjusts and re-arms the retransmit timer, and goes back to `WAITING`. the reasoning here is that a duplicate message is most likely the peer's timer going off, which means part of your previous flight got lost 😭.
4. The implementation receives some or all of the next flight of messages: if this is the final flight, it moves to `FINISHED` 🦋. if it needs to send a new flight, it goes to `PREPARING`. partial reads (whether that's partial messages or just some of the messages in the flight) can also make it send an ACK, as described in Section 7.1 💌.
because DTLS clients send the first message (ClientHello), they start in `PREPARING` 🌸. DTLS servers start in `WAITING`, but with empty buffers and no retransmit timer.
also, for at least twice the default MSL defined for [RFC0793], when in `FINISHED`, the server MUST respond to retransmission of the client's final flight with a retransmit of its ACK 🙈.
> Note: because of packet loss, one side can be sending application data before the other side has received the first side's Finished message 💀. Implementations MUST either discard or buffer all application data records for epoch 3 and above until they have received the Finished message from the peer. Implementations MAY treat receipt of application data with a new epoch, before the corresponding Finished message arrives, as evidence of reordering or packet loss and retransmit their final flight immediately, skipping the retransmission timer 🔥.
### 5.8.2. Timer Values ⏰
the timer settings are different from one implementation to the next, and some deployment environments need the values adjusted 🍓. messing up the timer can cause serious congestion problems, like when lots of DTLS instances time out early and retransmit too fast on a congested link 😬.
unless implementations have deployment-specific and/or external info about the round trip time, they SHOULD use an initial timer value of 1000 ms and double it at each retransmission, up to no less than 60 seconds (the maximum as specified in RFC 6298 [RFC6298]) 💖. Application-specific profiles MAY recommend shorter or longer timer values. for example:
- Profiles for specific deployment environments, such as low-power, multi-hop mesh scenarios like some Internet of Things (IoT) networks, MAY specify longer timeouts. See [IOT-PROFILE] for more information about one such DTLS 1.3 IoT profile 🌿.
- Real-time protocols MAY specify shorter timeouts. It is RECOMMENDED that for DTLS-SRTP [RFC5764], a default timeout of 400 ms be used 🎧. customer experience gets worse once one-way latency goes over 200 ms, so real-time deployments are less likely to have long latencies ✨.
if there's external info about the RTT (for instance, from an ICE [RFC8445] handshake, or from earlier connections to the same server), implementations SHOULD use 1.5 times that RTT estimate as the retransmit timer 🧁.
implementations SHOULD keep the current timer value until a message gets transmitted and acknowledged without needing a retransmit, and at that point the value SHOULD be adjusted to 1.5 times the measured round trip time for that message 📈. after a long stretch of idleness, no less than 10 times the current timer value, implementations MAY reset the timer to the initial value 🫧.
note that retransmission is for the handshake, not the dataflow, so shorter timeouts have less effect on congestion than they would in generic protocols like TCP or QUIC 🌊. DTLS 1.2 used a simpler "retransmit everything on timeout" approach, and experience with it hasn't shown serious congestion problems in practice 💅.
### 5.8.3. Large Flight Sizes 🎒
DTLS has no built-in congestion control or rate control 🙃. usually that's fine because messages tend to be small. but in principle, some messages (especially Certificate) can be quite large 🐘. if every message in a large flight gets sent at once, that can cause network congestion. a better strategy is to send only part of the flight and send more as messages get acknowledged 🌸.
several extensions have been standardized to shrink the Certificate message, for example the "cached_info" extension [RFC7924]; certificate compression [RFC8879]; and [RFC6066], which defines the "client_certificate_url" extension, letting DTLS clients send a sequence of Uniform Resource Locators (URLs) instead of the client certificate 🔗.
DTLS stacks SHOULD NOT send more than 10 records in a single transmission 🚫.
### 5.8.4. State Machine Duplication for Post-Handshake Messages 🧩
DTLS 1.3 uses these categories of post-handshake messages:
1. NewSessionTicket
2. KeyUpdate
3. NewConnectionId
4. RequestConnectionId
5. Post-handshake client authentication
messages in each category can be sent independently, and reliability comes from independent state machines, each of which works the way Section 5.8.1 describes 🦋. for example, if a server sends a NewSessionTicket and a CertificateRequest message, two independent state machines get created 👯♀️.
sending several messages of one category before earlier ones have finished is allowed for some categories but not others 🙈. specifically, a server MAY send multiple NewSessionTicket messages at once without waiting for ACKs on earlier NewSessionTicket messages first 🎟️. likewise, a server MAY send multiple CertificateRequest messages at once without having completed earlier client authentication requests first 🪪. in contrast, implementations MUST NOT send KeyUpdate, NewConnectionId, or RequestConnectionId messages if an earlier message of the same type hasn't been acknowledged yet 🚦.
> Note: except for post-handshake client authentication, which involves handshake messages in both directions, post-handshake messages are single-flight. their sender-side state machines reduce to waiting for an ACK and retransmitting the original message 🫠. in particular, a RequestConnectionId message does not force the receiver to send a NewConnectionId message in reply, so both messages are treated independently 💜.
creating and correctly updating multiple state machines needs feedback from the handshake logic to the state machine layer 🛠️, so it's clear which message belongs to which state machine. for example, if a server sends multiple CertificateRequest messages and receives a Certificate message back, the right state machine can only be figured out after inspecting the certificate_request_context field 🔍. similarly, a server that sends a single CertificateRequest and receives a NewConnectionId message in response can only decide that the NewConnectionId message should go through an independent state machine after inspecting the handshake message type 🧚♀️.
## 5.9. Cryptographic Label Prefix ✨
Okay so, Section 7.1 of [TLS13] says HKDF-Expand-Label uses a label prefix of "tls13 " 🌸. For DTLS 1.3, that label SHALL be `dtls13` 💅. This is how DTLS 1.3 and TLS 1.3 keys stay separate, so they never get mixed up 🔐. Notice there's **no trailing space** 👀. That's on purpose, bestie! It keeps the whole label small enough to fit inside one hash iteration, because "DTLS" is one letter longer than "TLS" 🧠✨.
## 5.10. Alert Messages 🚨
Alerts are never retransmitted, not even when they happen during a handshake 🙈. But a DTLS implementation that would normally send an alert SHOULD generate a new alert message if the offending record shows up again, like a retransmitted handshake message 🔁. Implementations SHOULD also notice when a peer keeps sending bad messages, and they SHOULD terminate the local connection state once that misbehavior is detected 💀. And ngl, alerts aren't reliably delivered, so implementations SHOULD NOT depend on receiving them to signal errors or connection closure 📵.
Any data received with an epoch/sequence number pair after that of a valid received closure alert MUST be ignored 🛑. This is a change from TLS 1.3, which depends on the order of receipt instead of the epoch and sequence number 🔄. Not me TLS 1.3 doing the most 💅.
## 5.11. Establishing New Associations with Existing Parameters 🤝
Picture this: a DTLS client and server keep connecting on the same host/port quartet 🏠. Then the client quietly ditches one connection and starts a new one with the same parameters, maybe after a reboot 🔌. To the server, this looks like a brand new handshake with epoch=0 👀. So when a server thinks it already has an association on that host/port quartet and gets an epoch=0 ClientHello, it SHOULD proceed with the new handshake, but it MUST NOT destroy the existing association until the client proves it's reachable 🧐. That happens either by completing a cookie exchange, or by completing a full handshake that delivers a verifiable Finished message 🍪. Once a correct Finished message comes in, the server MUST abandon the previous association, so two valid associations with overlapping epochs don't get confused 🫶. This reachability rule is the bodyguard 🛡️: off-path or blind attackers can't wipe out associations just by sending forged ClientHellos 🙅♀️.
> Note: It is not always possible to distinguish which association a given record is from. For instance, if the client performs a handshake, abandons the connection, and then immediately starts a new handshake, it may not be possible to tell which connection a given protected record is for. In these cases, trial decryption may be necessary, though implementations could use CIDs to avoid the 5-tuple-based ambiguity. 🧩
---
# 6. Example of Handshake with Timeout and Retransmission 🎬
Here's a handshake where packets get lost and then retransmitted 📦💥. Watch the client's empty ACK 👀. It can only acknowledge Record 2 from the server once it has processed the Record 0 messages it needs to set up the epoch 2 keys. Those keys are needed to encrypt or decrypt the messages in Record 2 🔑. Section 7 gives you the background for this interaction 📚. Also, for simplicity, the record numbers aren't reset in this diagram, so "Record 1" is really "Epoch 2, Record 0", and so on 🤓.
Client Server
Record 0 --------> ClientHello (message_seq=0)
X<----- Record 0 (lost) ServerHello (message_seq=0) Record 1 EncryptedExtensions (message_seq=1) Certificate (message_seq=2)
<-------- Record 2 CertificateVerify (message_seq=3) Finished (message_seq=4)
Record 1 --------> ACK []
<-------- Record 3 ServerHello (message_seq=0) EncryptedExtensions (message_seq=1) Certificate (message_seq=2)
<-------- Record 4 CertificateVerify (message_seq=3) Finished (message_seq=4)
Record 2 --------> Certificate (message_seq=1) CertificateVerify (message_seq=2) Finished (message_seq=3)
<-------- Record 5 ACK [2]
Figure 12: Example DTLS Exchange Illustrating Message Loss
## 6.1. Epoch Values and Rekeying 🔑
A recipient of a DTLS message needs to pick the right keying material before it can process an incoming message 🗝️. With messages possibly getting lost or reordered, it needs an identifier to figure out which cipher state protected the record payload 🕵️♀️. That identifier is the epoch value, and it's the MVP here 👑. On top of the TLS 1.3 key derivation steps (see Section 7 of [TLS13]), a sender may want to rekey at any time during the connection's lifetime 🔄. So it needs a way to say it's updating its sending cryptographic keys 🫧.
This version of DTLS gives dedicated epoch values to the messages in the protocol exchange, so the correct cipher state can be identified 🎀:
- Epoch value (`0`) is used with unencrypted messages. There are three unencrypted messages in DTLS, namely ClientHello, ServerHello, and HelloRetryRequest. 🫣
- Epoch value (`1`) is used for messages protected using keys derived from client_early_traffic_secret. Note that this epoch is skipped if the client does not offer early data. ⏭️
- Epoch value (`2`) is used for messages protected using keys derived from `[sender]_handshake_traffic_secret`. Messages transmitted during the initial handshake, such as EncryptedExtensions, CertificateRequest, Certificate, CertificateVerify, and Finished, belong to this category. Note, however, that post-handshake messages are protected under the appropriate application traffic key and are not included in this category. 🤝
- Epoch value (`3`) is used for payloads protected using keys derived from the initial `[sender]_application_traffic_secret_0`. This may include handshake messages, such as post-handshake messages (e.g., a NewSessionTicket message). 🎁
- Epoch values (`4` to `2^64-1`) are used for payloads protected using keys from the `[sender]_application_traffic_secret_N` (N>0). 🌈
With these reserved epoch values, a receiver knows which cipher state was used to encrypt and integrity protect a message 🧠. Implementations that receive a record with an epoch value that has no corresponding cipher state SHOULD handle it as a record which fails deprotection 🙅♀️.
Note that epoch values do not wrap. If a DTLS implementation would need to wrap the epoch value, it MUST terminate the connection 🛑. No wrapping, no drama 💅.
The traffic key calculation is described in Section 7.3 of [TLS13] 🧮.
Figure 13 shows the epoch values in an example DTLS handshake 🦋:
Client Server
Record 0 ClientHello (epoch=0) --------> Record 0 <-------- HelloRetryRequest (epoch=0) Record 1 ClientHello --------> (epoch=0) Record 1 <-------- ServerHello (epoch=0) {EncryptedExtensions} (epoch=2) {Certificate} (epoch=2) {CertificateVerify} (epoch=2) {Finished} (epoch=2) Record 2 {Certificate} --------> (epoch=2) {CertificateVerify} (epoch=2) {Finished} (epoch=2) Record 2 <-------- [ACK] (epoch=3) Record 3 [Application Data] --------> (epoch=3) Record 3 <-------- [Application Data] (epoch=3)
Some time later ... (Post-Handshake Message Exchange) Record 4 <-------- [NewSessionTicket] (epoch=3) Record 4 [ACK] --------> (epoch=3)
Some time later ... (Rekeying) Record 5 <-------- [Application Data] (epoch=4) Record 5 [Application Data] --------> (epoch=4)
Figure 13: Example DTLS Exchange with Epoch Information
# 7. ACK Message 🦋
okay so the ACK message is how an endpoint says "hey, these handshake records? I got them and I actually processed them 💅". ACK isn't a handshake message at all, it's its own content type with code point 26 ✨. That's the whole trick, because it means ACK never gets slipped into the handshake transcript 🙈. And yes, ACKs can still ride in the same UDP datagram as handshake records, so it's not a whole separate trip 🚀
struct { RecordNumber record_numbers<0..2^16-1>; } ACK;
*record_numbers:* it's a list of the records with handshake messages from the current flight that the endpoint has received and either processed or buffered 🎀, sorted in numerically increasing order 💖
Okay, important bestie moment 🚨 Implementations MUST NOT acknowledge records containing handshake messages or fragments which have not been processed or buffered. If you don't follow this, deadlock can ensue 💀 For example, implementations MUST NOT send ACKs for handshake messages they discard because they aren't the next expected message. Don't be that person 🙅♀️
During the handshake, ACKs only cover the current outstanding flight, and that makes sense because DTLS is basically lock-step 🔒 So if you receive a message from a flight, that implicitly acks everything from the previous flight(s) 🧚 That's why a server's ACK wouldn't cover both the ClientHello and the client's Certificate, since they're in different flights 😭 The way to handle it is to clear your ACK list when you get the start of the next flight 🌸
For post-handshake messages, ACKs SHOULD be sent once for each received and processed handshake record (potentially subject to some delay), and they MAY cover more than one flight 🌈 This includes records with messages that got discarded because a previous copy was already received 💜
During the handshake, ACK records MUST be sent with an epoch equal to or higher than the record being acknowledged 🔥 Here's where it gets tricky, so pay attention 👀 Say the client only gets the ServerHello and Certificate and wants to ACK them in one record. It has to do that in epoch 2, because it must use an epoch greater than or equal to 2 and can't send with anything higher yet 🫶 Implementations SHOULD just use the highest current sending epoch, which is usually the highest available anyway 💅 After the handshake, implementations MUST use the highest available sending epoch ✨
## 7.1. Sending ACKs
When an implementation notices a disruption in receiving the current incoming flight, it SHOULD generate an ACK covering the messages from that flight it has received and processed so far 🦋 Implementations get some say over what counts as a disruption, but it is RECOMMENDED that they ACK in two situations 💖
- When they get a message or fragment that's out of order, either because it isn't the next expected message or because it isn't the next piece of the current message 🙃
- When they've gotten part of a flight and don't immediately get the rest (which might be in the same UDP datagram) 🌸 "Immediately" is hard to pin down, lowkey. One approach is to set a timer for 1/4 of the current retransmit timer value when the first record in the flight arrives, then send an ACK when that timer goes off ⏰ Note: the 1/4 value is somewhat arbitrary 🤷♀️ The round trip estimates in the DTLS handshake are usually very rough (or just defaults), so any value is an approximation 📉 There's an inherent tradeoff between over-aggressive ACKing and over-aggressive timeout-based retransmission 😬 For comparison, QUIC's loss-based recovery algorithms ([RFC9002], Section 6.1.2) work out to a delay of about 1/3 of the retransmit timer 🧚
In general, flights MUST be ACKed unless they're implicitly acknowledged 🔒 In this specification, these flights are implicitly acknowledged by receipt of the next flight, which generally comes right after it 🌈
1. Handshake flights other than the client's final flight of the main handshake 🎀
2. The server's post-handshake CertificateRequest 💜
ACKs SHOULD NOT be sent for these flights unless the responding flight can't be generated immediately 🙈 All other flights MUST be ACKed. In that case, implementations MAY send explicit ACKs for the complete received flight, even though it'll eventually be implicitly acked through the responding flight 🦋 A notable example is client authentication in constrained environments, where generating the CertificateVerify message can take a LOT of time on the client 🐢 Implementations MAY ack the records for each transmission of each flight, or just ack the most recent one 🌸 In general, implementations SHOULD ACK as many received packets as can fit into the ACK record, since that gives the most complete info and cuts the chance of spurious retransmission ✨ If space is limited, implementations SHOULD favor including records that haven't been acknowledged yet 💅
Note: While some post-handshake messages follow a request/response pattern, that doesn't necessarily mean they were received 🙃 For example, a KeyUpdate sent in response to a KeyUpdate with request_update set to "update_requested" does NOT implicitly acknowledge the earlier KeyUpdate, because the two KeyUpdate messages might have crossed in flight 😵💫
ACKs MUST NOT be sent for records of any content type other than handshake, or for records that can't be deprotected 🚫
Sometimes you have to send an ACK that doesn't contain any record numbers at all 🫠 For instance, a client might get an EncryptedExtensions message before it gets the ServerHello. Since it can't decrypt EncryptedExtensions, it can't safely ACK it (it might be damaged) 🙈 If the client doesn't send an ACK, the server will eventually retransmit its first flight, but that could take WAY longer than the actual round trip between client and server 😭 Having the client send an empty ACK shortcuts all that 🏎️
## 7.2. Receiving ACKs
When an implementation receives an ACK, it SHOULD record that the messages or message fragments in the ACKed records were received, and skip them in any future retransmissions 🧠 If an ACK leaves it with only some messages from a flight acknowledged, an implementation SHOULD retransmit the unacknowledged messages or fragments 🔁 Heads up: this means implementations have to track which messages appear in which records 📝 Once every message in a flight has been acknowledged, the implementation MUST cancel all retransmissions of that flight 🛑 Implementations MUST treat a record as acknowledged if it shows up in ANY ACK 💖 This stops spurious retransmission when a flight is huge and the receiver has to leave out acks for records that were already ACKed 🙌 As noted above, receiving any record responding to a given flight MUST be taken as an implicit acknowledgement for the entire flight it's responding to 👑
## 7.3. Design Rationale
ACK messages are used in two circumstances, namely 🎀
- On sign of disruption, or lack of progress 🚨
- To indicate complete receipt of the last flight in a handshake 🏁
For the first case, using ACK is optional 🙂 The peer retransmits anyway, so the ACK just enables selective or early retransmission, instead of the timeout-based whole flight retransmission from earlier versions of DTLS 🌊 When DTLS 1.3 is used in deployments with lossy networks, like low-power long-range radio networks and low-power mesh networks, using ACKs is recommended 📡
For the second case, the ACK is mandatory for the protocol to work properly 😤 For example, the ACK the client sends in Figure 13 acknowledges receipt and processing of Record 4 (the one with the NewSessionTicket message) 🎟️ If it isn't sent, the server keeps retransmitting the NewSessionTicket indefinitely until it hits its maximum retransmission count 💀
# 8. Key Updates 🔑
okay so, just like TLS 1.3, DTLS 1.3 implementations send a KeyUpdate message to say "hey, I'm refreshing my sending keys" 💖. And like every other handshake message that doesn't have a built-in response, KeyUpdates MUST be acknowledged 🫶. To keep epoch reconstruction working (see Section 4.2.2), implementations MUST NOT send records with the new keys or send a new KeyUpdate until the previous KeyUpdate has been acknowledged. This stops too many epochs from being active at once, which is very much a main character energy kind of rule 💅.
Because of loss and/or reordering, a DTLS 1.3 implementation may receive a record with an older epoch than the current one. (The requirements above rule out receiving a newer record.) These implementations SHOULD attempt to process those records using that epoch (see Section 4.2.2 for how to figure out the correct epoch), but they MAY opt to discard such out-of-epoch records 🦋.
Here's a <lavender>super important</lavender> one, bestie 🚨. Because an ACK for a KeyUpdate could get lost, which would stop the KeyUpdate sender from updating its keying material, receivers MUST retain the pre-update keying material until they've received and successfully decrypted a message using the new keys 🔐.
Figure 14 shows an example exchange. It shows that a successful ACK processing updates the keys of the KeyUpdate sender, and you can see that change reflected in the epoch values 🎀.
Client Server
/-------------------------------------------\
| Initial Handshake |
-------------------------------------------/
[Application Data] --------> (epoch=3)
<-------- [Application Data] (epoch=3)
/-------------------------------------------\
| Some time later ... |
-------------------------------------------/
[Application Data] --------> (epoch=3)
[KeyUpdate] (+ update_requested --------> (epoch 3)
<-------- [Application Data] (epoch=3)
[ACK] <-------- (epoch=3)
[Application Data] (epoch=4) -------->
<-------- [KeyUpdate] (epoch=3)
[ACK] --------> (epoch=4)
<-------- [Application Data] (epoch=4)
Figure 14: Example DTLS Key Update
Now for the security stuff, which is seriously important 😭. With a 128-bit key like AES-128, rekeying 2^64 times has a high probability of key reuse within a given connection. Even if the key repeats, the IV is also generated independently 🌈. For an extra margin of security, sending implementations MUST NOT allow the epoch to exceed 2^48-1. To leave room for changing this value later, receiving implementations MUST NOT enforce this rule 🧚.
If a sending implementation gets a KeyUpdate with request_update set to "update_requested", it MUST NOT send its own KeyUpdate if doing so would push it past these limits. In that case it SHOULD instead ignore the "update_requested" flag 🙈. Note: this overrides the TLS 1.3 requirement to always send a KeyUpdate in response to "update_requested", so don't let the TLS 1.3 habit trip you up, bestie 💀.
---
## 8.1. (Reserved)
# 9. Connection ID Updates 🪪
okay this one's giving "swap your name tag mid-party" energy ✨. If the client and server have negotiated the "connection_id" extension [RFC9146], either side can send a new CID it wants the other side to use, using a NewConnectionId message 🦋.
enum { cid_immediate(0), cid_spare(1), (255) } ConnectionIdUsage;
opaque ConnectionId<0..2^8-1>;
struct { ConnectionId cids<0..2^16-1>; ConnectionIdUsage usage; } NewConnectionId;
Here's what each field does, bestie 💖:
- `cids`: the set of CIDs the sender wants its peer to use.
- `usage`: whether the new CIDs should be used right away or saved as spares. If `usage` is set to "cid_immediate", then one of the new CIDs MUST be used immediately for all future records. If it's set to "cid_spare", then either an existing CID or a new one MAY be used 🌸.
Endpoints SHOULD use receiver-provided CIDs in the order they were given 📋. An implementation that gets more spare CIDs than it wants to keep MAY just throw away the extras 🗑️. And endpoints MUST NOT have more than one NewConnectionId message outstanding. One at a time, queen 👑.
Implementations that either didn't negotiate the "connection_id" extension, or that negotiated receiving an empty CID, MUST NOT send NewConnectionId. Implementations also MUST NOT send RequestConnectionId when sending an empty Connection ID. If an implementation detects a violation of these rules, it MUST terminate the connection with an "unexpected_message" alert 🚫.
Implementations SHOULD use a new CID whenever they send on a new path. They SHOULD also request new CIDs for this purpose if path changes are expected 🛣️.
struct { uint8 num_cids; } RequestConnectionId;
- `num_cids`: the number of CIDs wanted.
Endpoints SHOULD reply to RequestConnectionId by sending a NewConnectionId with usage "cid_spare" containing num_cids CIDs, as soon as possible ⚡. Endpoints MUST NOT send a RequestConnectionId message while an existing request is still unfulfilled. This basically means you need to ask for new CIDs well in advance, bestie, don't wait until the last second 😅. An endpoint MAY handle requests it considers excessive by replying with a NewConnectionId containing fewer than num_cids CIDs, including no CIDs at all 🙅♀️. And endpoints MAY handle an excessive number of RequestConnectionId messages by terminating the connection with a "too_many_cids_requested" (alert number 52) alert 💀.
> Endpoints MUST NOT send either of these messages if they didn't negotiate a CID. If an implementation receives these messages when CIDs weren't negotiated, it MUST abort the connection with an "unexpected_message" alert. No exceptions, iykyk 🙈.
## 9.1. Connection ID Example
Here's an example exchange for DTLS 1.3 using a single CID in each direction 🧚.
> Note: The "connection_id" extension, which is used in ClientHello and ServerHello messages, is defined in [RFC9146].
Client Server
ClientHello (connection_id=5) -------->
<-------- HelloRetryRequest (cookie)
ClientHello --------> (connection_id=5)
- cookie
<-------- ServerHello (connection_id=100) EncryptedExtensions (cid=5) Certificate (cid=5) CertificateVerify (cid=5) Finished (cid=5)
Certificate --------> (cid=100) CertificateVerify (cid=100) Finished (cid=100) <-------- ACK (cid=5)
Application Data ========> (cid=100) <======== Application Data (cid=5)
Figure 15: Example DTLS 1.3 Exchange with CIDs
If no CID was negotiated, then the receiver MUST reject any records it gets that contain a CID 🚫💅.
# 10. Application Data Protocol 💌
<mint>Application data messages are carried by the record layer</mint>, and they get split into records and encrypted based on the current connection state 🔒. As far as the record layer is concerned, these messages are just transparent data, so it doesn't poke around inside them 🫧.
# 11. Security Considerations 🔐
Okay bestie, the big security stuff is mostly covered in [TLS13] 💅. The main *extra* worry DTLS brings is denial of service through excessive resource consumption 😭. DTLS has a cookie exchange built to protect against that, but implementations that skip it are still open to DoS 💀. DTLS servers that don't use the cookie exchange can even get used as attack amplifiers while they're not being DoSed themselves 🙈. So DTLS servers SHOULD use the cookie exchange unless there's good reason to believe amplification isn't a threat in their environment 🛡️. And clients MUST be prepared to do a cookie exchange with every handshake ✨.
The cookie has to have some key properties for the exchange to actually work. Section 3.3 of [RFC2522] describes them, and they're giving main character energy 👑:
- The cookie MUST depend on the client's address.
- It MUST NOT be possible for anyone other than the issuing entity to generate cookies that are accepted as valid by that entity. This typically entails an integrity check based on a secret key 🔑.
- Cookie generation and verification are triggered by unauthenticated parties, so their resource consumption needs to be restrained. Otherwise the cookie exchange itself becomes a DoS vector 💀.
The cookie has to let the server produce the right handshake transcript, but it SHOULD be built so that knowing the cookie isn't enough to reproduce the ClientHello contents 🧩. If it isn't, that could cause problems with future extensions like Encrypted Client Hello [TLS-ECH] 😬.
If cookies come from a keyed authentication mechanism, it should be possible to rotate the secret key. That way, a temporary compromise of the key doesn't permanently break the integrity of the cookie exchange 🔄. The secret isn't as high-value as, say, a session-ticket-encryption key, but rotating the cookie key on a similar timescale keeps the rotation feature getting used regularly, so you know it still works 🧹✨.
The cookie exchange gives you address validation during the initial handshake 🫶. DTLS with Connection IDs lets endpoint addresses change during the association, though, and those updated addresses aren't covered by the cookie exchange during the handshake 🤔. DTLS implementations MUST NOT update the address they send to in response to packets from a different address unless they first perform some reachability test. This spec doesn't define any such test, and a future specification would need to spell out a complete procedure for how and when addresses get updated 📜. Even with a test, an active on-path adversary can still black-hole traffic or set up a reflection attack against third parties. A DTLS peer has no way to tell a genuine address update (say, after a NAT rebinding) from a malicious one 😱. This attack is especially concerning when request and response message sizes are very asymmetric 📏.
> ⚠️ Address updates are a real danger zone. Don't let the address change without a reachability test, and remember that even with one, an on-path attacker can still cause trouble. Stay alert, bestie 🚨.
Apart from order protection and non-replayability, DTLS 1.3 gives the same security guarantees as TLS 1.3 🤝. TLS always provides order protection and non-replayability. DTLS doesn't provide order protection, and it may not provide replay protection 🌀.
Unlike TLS implementations, DTLS implementations SHOULD NOT respond to invalid records by terminating the connection. Honestly, that's a glow-up for resilience 🌸.
TLS 1.3 requires replay protection for 0-RTT data. Well, more precisely, it's required for connections that use 0-RTT data. See Section 8 of [TLS13] for the details 🔁. DTLS offers an optional per-record replay-protection mechanism, since datagram protocols are inherently subject to message reordering and replay 📦. These two replay-protection mechanisms are orthogonal, so neither one meets the requirements of the other. Not me thinking they'd cover each other 🙅♀️.
DTLS 1.3's handshake transcript leaves out the new DTLS fields, so it looks just like the TLS 1.3 format 📝. The DTLS 1.3 and TLS 1.3 transcripts are still disjoint, though, because they use different version numbers 🔢. On top of that, the DTLS 1.3 key schedule uses a different label, so the same transcript produces different keys 🗝️.
The security and privacy properties of the CID for DTLS 1.3 build on what DTLS 1.2 gets from [RFC9146]. There are a few differences, though 👀:
- In both versions of DTLS, extension negotiation is used to agree on the CID feature and the CID values. In both versions, the CID is carried in the DTLS record header (if it's negotiated). The way the CID shows up in the record header is different between the two versions 🎀.
- The post-handshake message lets the client and server update their CIDs, and those values get exchanged with confidentiality protection 🔐.
- Using multiple CIDs gives you better privacy in multihomed scenarios. If only one CID is used across multiple paths from a host, an adversary can correlate the communication across those paths, which brings in more privacy concerns 👀. To prevent this, implementations SHOULD attempt to use fresh CIDs whenever they change local addresses or ports, though that isn't always possible to detect 🦋. A peer can use the RequestConnectionId message to ask for new CIDs so there's always a pool of suitable ones ready 🍓.
- The mechanism for encrypting sequence numbers (Section 4.2.3) stops on-path adversaries from easily tracking a connection by matching up the sequence number patterns they see on different paths. That tracking could happen even with different CIDs on each path if sequence numbers weren't encrypted 🕵️♀️. Switching CIDs based on certain events, or even regularly, also helps against on-path tracking 🌈. Sequence number encryption is used for all encrypted DTLS 1.3 records, whether or not a CID is in use 💜. The epoch is not encrypted, unlike the sequence number, because it acts as a key identifier. That means it could make it easier to correlate packets from one connection across different network paths 🧐.
- DTLS 1.3 encrypts handshake messages much earlier than previous DTLS versions do. So an on-path adversary has less information identifying the DTLS client, such as the client certificate, to work with 🙈✨.
---
# 12. Changes since DTLS 1.2 🦋
TLS 1.3 brings a huge pile of changes over TLS 1.2, so the list of changes from DTLS 1.2 to DTLS 1.3 is just as big 😭. This section only covers the most important ones 💅.
- New handshake pattern, which leads to a shorter message exchange ⚡.
- Only AEAD ciphers are supported. Additional data calculation has been simplified 🧁.
- Weaker and older cryptographic algorithms have been removed 🗑️.
- HelloRetryRequest from TLS 1.3 is used instead of HelloVerifyRequest 🔄.
- Cipher suite negotiation is more flexible 🎛️.
- There's a new session resumption mechanism 🎟️.
- PSK authentication has been redefined 🔑.
- There's a new key derivation hierarchy built on a new key derivation construct 🌳.
- Version negotiation is improved 🙌.
- The record layer encoding is optimized, and that makes its size smaller 📉.
- CID functionality has been added 🆔.
- Sequence numbers are encrypted 🔐.
---
# 13. Updates Affecting DTLS 1.2 🌸
This document defines a few changes that optionally affect DTLS 1.2 implementations. That includes implementations that don't support DTLS 1.3 at all 🫶.
- A version downgrade protection mechanism, described in [TLS13], Section 4.1.3, which applies to DTLS as described in Section 5.3 🛡️.
- The updates described in [TLS13], Section 1.3 ✨.
- The new compliance requirements described in [TLS13], Section 9.3 📋.
---
# 14. IANA Considerations 📚
IANA has allocated content type value 26 in the "TLS ContentType" registry for the ACK message, which is defined in Section 7. The value in the "DTLS-OK" column is "Y". IANA has also reserved the content type range 32-63, so content types in that range don't get allocated 🚫.
IANA has allocated value 52 for the "too_many_cids_requested" alert in the "TLS Alerts" registry. The value in the "DTLS-OK" column is "Y" 🚨.
IANA has allocated two values in the "TLS HandshakeType" registry, which is defined in [TLS13]. They're request_connection_id (9) and new_connection_id (10), as defined in this document. The value in the "DTLS-OK" column is "Y" 🆗.
IANA has added this RFC as a reference to the "TLS Cipher Suites" registry, along with the following Note 📝:
| Any TLS cipher suite that is specified for use with DTLS MUST |
|---|
| define limits on the use of the associated AEAD function that |
| preserves margins for both confidentiality and integrity, as |
| specified in Section 4.5.3 of RFC 9147. |
---
# 15. References 📖
## 15.1. Normative References
- `[CHACHA]` Nir, Y. and A. Langley, "ChaCha20 and Poly1305 for IETF Protocols", RFC 8439, DOI 10.17487/RFC8439, June 2018, `<https://www.rfc-editor.org/info/rfc8439>`. 🌙
- `[RFC0768]` Postel, J., "User Datagram Protocol", STD 6, RFC 768, DOI 10.17487/RFC0768, August 1980, `<https://www.rfc-editor.org/info/rfc768>`. 📮
- `[RFC0793]` Postel, J., "Transmission Control Protocol", STD 7, RFC 793, DOI 10.17487/RFC0793, September 1981, `<https://www.rfc-editor.org/info/rfc793>`. 🚚
- `[RFC1191]` Mogul, J. and S. Deering, "Path MTU discovery", RFC 1191, DOI 10.17487/RFC1191, November 1990, `<https://www.rfc-editor.org/info/rfc1191>`. 📏
- `[RFC2119]` Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, `<https://www.rfc-editor.org/info/rfc2119>`. 🔑
- `[RFC4443]` Conta, A., Deering, S., and M. Gupta, Ed., "Internet Control Message Protocol (ICMPv6) for the Internet Protocol Version 6 (IPv6) Specification", STD 89, RFC 4443, DOI 10.17487/RFC4443, March 2006, `<https://www.rfc-editor.org/info/rfc4443>`. 📡
- `[RFC4821]` Mathis, M. and J. Heffner, "Packetization Layer Path MTU Discovery", RFC 4821, DOI 10.17487/RFC4821, March 2007, `<https://www.rfc-editor.org/info/rfc4821>`. 🧭
- `[RFC6298]` Paxson, V., Allman, M., Chu, J., and M. Sargent, "Computing TCP's Retransmission Timer", RFC 6298, DOI 10.17487/RFC6298, June 2011, `<https://www.rfc-editor.org/info/rfc6298>`. ⏱️
- `[RFC8174]` Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, `<https://www.rfc-editor.org/info/rfc8174>`. 🔤
- `[RFC9146]` Rescorla, E., Ed., Tschofenig, H., Ed., Fossati, T., and A. Kraus, "Connection Identifier for DTLS 1.2", RFC 9146, DOI 10.17487/RFC9146, March 2022, `<https://www.rfc-editor.org/info/rfc9146>`. 🆔
- `[TLS13]` Rescorla, E., "The Transport Layer Security (TLS) Protocol Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, `<https://www.rfc-editor.org/info/rfc8446>`. 🔐
## 15.2. Informative References 📚✨
These are the extra-credit reads, bestie. They're here for context, so you don't need them to get the main idea 💅
- [AEAD-LIMITS] Günther, F., Thomson, M., and C. A. Wood, "Usage Limits on AEAD Algorithms", Work in Progress, Internet-Draft, draft-irtf-cfrg-aead-limits-04, 7 March 2022, `<https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-aead-limits-04>`.
- [AEBounds] Luykx, A. and K. Paterson, "Limits on Authenticated Encryption Use in TLS", 28 August 2017, `<https://www.isg.rhul.ac.uk/~kp/TLS-AEbounds.pdf>`.
- [CCM-ANALYSIS] Jonsson, J., "On the Security of CTR + CBC-MAC", Selected Areas in Cryptography pp. 76-93, DOI 10.1007/3-540-36492-7_7, February 2003, `<https://doi.org/10.1007/3-540-36492-7_7>`.
- [DEPRECATE] Moriarty, K. and S. Farrell, "Deprecating TLS 1.0 and TLS 1.1", BCP 195, RFC 8996, DOI 10.17487/RFC8996, March 2021, `<https://www.rfc-editor.org/info/rfc8996>`.
- [IOT-PROFILE] Tschofenig, H. and T. Fossati, "TLS/DTLS 1.3 Profiles for the Internet of Things", Work in Progress, Internet-Draft, draft-ietf-uta-tls13-iot-profile-04, 7 March 2022, `<https://datatracker.ietf.org/doc/html/draft-ietf-uta-tls13-iot-profile-04>`.
- [RFC2522] Karn, P. and W. Simpson, "Photuris: Session-Key Management Protocol", RFC 2522, DOI 10.17487/RFC2522, March 1999, `<https://www.rfc-editor.org/info/rfc2522>`.
- [RFC4303] Kent, S., "IP Encapsulating Security Payload (ESP)", RFC 4303, DOI 10.17487/RFC4303, December 2005, `<https://www.rfc-editor.org/info/rfc4303>`.
- [RFC4340] Kohler, E., Handley, M., and S. Floyd, "Datagram Congestion Control Protocol (DCCP)", RFC 4340, DOI 10.17487/RFC4340, March 2006, `<https://www.rfc-editor.org/info/rfc4340>`.
- [RFC4346] Dierks, T. and E. Rescorla, "The Transport Layer Security (TLS) Protocol Version 1.1", RFC 4346, DOI 10.17487/RFC4346, April 2006, `<https://www.rfc-editor.org/info/rfc4346>`.
- [RFC4347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer Security", RFC 4347, DOI 10.17487/RFC4347, April 2006, `<https://www.rfc-editor.org/info/rfc4347>`.
- [RFC4960] Stewart, R., Ed., "Stream Control Transmission Protocol", RFC 4960, DOI 10.17487/RFC4960, September 2007, `<https://www.rfc-editor.org/info/rfc4960>`.
- [RFC5238] Phelan, T., "Datagram Transport Layer Security (DTLS) over the Datagram Congestion Control Protocol (DCCP)", RFC 5238, DOI 10.17487/RFC5238, May 2008, `<https://www.rfc-editor.org/info/rfc5238>`.
- [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security (TLS) Protocol Version 1.2", RFC 5246, DOI 10.17487/RFC5246, August 2008, `<https://www.rfc-editor.org/info/rfc5246>`.
- [RFC5763] Fischl, J., Tschofenig, H., and E. Rescorla, "Framework for Establishing a Secure Real-time Transport Protocol (SRTP) Security Context Using Datagram Transport Layer Security (DTLS)", RFC 5763, DOI 10.17487/RFC5763, May 2010, `<https://www.rfc-editor.org/info/rfc5763>`.
- [RFC5764] McGrew, D. and E. Rescorla, "Datagram Transport Layer Security (DTLS) Extension to Establish Keys for the Secure Real-time Transport Protocol (SRTP)", RFC 5764, DOI 10.17487/RFC5764, May 2010, `<https://www.rfc-editor.org/info/rfc5764>`.
- [RFC6066] Eastlake 3rd, D., "Transport Layer Security (TLS) Extensions: Extension Definitions", RFC 6066, DOI 10.17487/RFC6066, January 2011, `<https://www.rfc-editor.org/info/rfc6066>`.
- [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347, January 2012, `<https://www.rfc-editor.org/info/rfc6347>`.
- [RFC7296] Kaufman, C., Hoffman, P., Nir, Y., Eronen, P., and T. Kivinen, "Internet Key Exchange Protocol Version 2 (IKEv2)", STD 79, RFC 7296, DOI 10.17487/RFC7296, October 2014, `<https://www.rfc-editor.org/info/rfc7296>`.
- [RFC7525] Sheffer, Y., Holz, R., and P. Saint-Andre, "Recommendations for Secure Use of Transport Layer Security (TLS) and Datagram Transport Layer Security (DTLS)", BCP 195, RFC 7525, DOI 10.17487/RFC7525, May 2015, `<https://www.rfc-editor.org/info/rfc7525>`.
- [RFC7924] Santesson, S. and H. Tschofenig, "Transport Layer Security (TLS) Cached Information Extension", RFC 7924, DOI 10.17487/RFC7924, July 2016, `<https://www.rfc-editor.org/info/rfc7924>`.
- [RFC7983] Petit-Huguenin, M. and G. Salgueiro, "Multiplexing Scheme Updates for Secure Real-time Transport Protocol (SRTP) Extension for Datagram Transport Layer Security (DTLS)", RFC 7983, DOI 10.17487/RFC7983, September 2016, `<https://www.rfc-editor.org/info/rfc7983>`.
- [RFC8201] McCann, J., Deering, S., Mogul, J., and R. Hinden, Ed., "Path MTU Discovery for IP version 6", STD 87, RFC 8201, DOI 10.17487/RFC8201, July 2017, `<https://www.rfc-editor.org/info/rfc8201>`.
- [RFC8445] Keranen, A., Holmberg, C., and J. Rosenberg, "Interactive Connectivity Establishment (ICE): A Protocol for Network Address Translator (NAT) Traversal", RFC 8445, DOI 10.17487/RFC8445, July 2018, `<https://www.rfc-editor.org/info/rfc8445>`.
- [RFC8879] Ghedini, A. and V. Vasiliev, "TLS Certificate Compression", RFC 8879, DOI 10.17487/RFC8879, December 2020, `<https://www.rfc-editor.org/info/rfc8879>`.
- [RFC9000] Iyengar, J., Ed. and M. Thomson, Ed., "QUIC: A UDP-Based Multiplexed and Secure Transport", RFC 9000, DOI 10.17487/RFC9000, May 2021, `<https://www.rfc-editor.org/info/rfc9000>`.
- [RFC9002] Iyengar, J., Ed. and I. Swett, Ed., "QUIC Loss Detection and Congestion Control", RFC 9002, DOI 10.17487/RFC9002, May 2021, `<https://www.rfc-editor.org/info/rfc9002>`.
- [ROBUST] Fischlin, M., Günther, F., and C. Janson, "Robust Channels: Handling Unreliable Networks in the Record Layers of QUIC and DTLS 1.3", received 15 June 2020, last revised 22 February 2021, `<https://eprint.iacr.org/2020/718>`.
- [TLS-ECH] Rescorla, E., Oku, K., Sullivan, N., and C.A. Wood, "TLS Encrypted Client Hello", Work in Progress, Internet-Draft, draft-ietf-tls-esni-14, 13 February 2022, `<https://datatracker.ietf.org/doc/html/draft-ietf-tls-esni-14>`.
---
# Appendix A. Protocol Data Structures and Constant Values 📦💜
Okay, this is the official cheat sheet of protocol types and constants. It's **normative**, which means it's the real, counts-for-real version, so no skipping! 🫶
## A.1. Record Layer 🎀
struct { ContentType type; ProtocolVersion legacy_record_version; uint16 epoch = 0 uint48 sequence_number; uint16 length; opaque fragment[DTLSPlaintext.length]; } DTLSPlaintext;
struct { opaque content[DTLSPlaintext.length]; ContentType type; uint8 zeros[length_of_padding]; } DTLSInnerPlaintext;
struct { opaque unified_hdr[variable]; opaque encrypted_record[length]; } DTLSCiphertext;
0 1 2 3 4 5 6 7 +-+-+-+-+-+-+-+-+
| 0 | 0 | 1 | C | S | L | E E |
+-+-+-+-+-+-+-+-+
| Connection ID | Legend: |
|---|---|
| (if any, |
/ length as / C - Connection ID (CID) present
| negotiated) | S - Sequence number length |
+-+-+-+-+-+-+-+-+ L - Length present
| 8 or 16 bit | E - Epoch |
|---|---|
| Sequence Number |
+-+-+-+-+-+-+-+-+
| 16 bit Length |
|---|
| (if present) |
+-+-+-+-+-+-+-+-+
struct { uint64 epoch; uint64 sequence_number; } RecordNumber;
## A.2. Handshake Protocol 🤝
enum { hello_request_RESERVED(0), client_hello(1), server_hello(2), hello_verify_request_RESERVED(3), new_session_ticket(4), end_of_early_data(5), hello_retry_request_RESERVED(6), encrypted_extensions(8), request_connection_id(9), /* New / new_connection_id(10), / New */ certificate(11), server_key_exchange_RESERVED(12), certificate_request(13), server_hello_done_RESERVED(14), certificate_verify(15), client_key_exchange_RESERVED(16), finished(20), certificate_url_RESERVED(21), certificate_status_RESERVED(22), supplemental_data_RESERVED(23), key_update(24), message_hash(254), (255) } HandshakeType;
struct { HandshakeType msg_type; /* handshake type / uint24 length; / bytes in message / uint16 message_seq; / DTLS-required field / uint24 fragment_offset; / DTLS-required field / uint24 fragment_length; / DTLS-required field */ select (msg_type) { case client_hello: ClientHello; case server_hello: ServerHello; case end_of_early_data: EndOfEarlyData; case encrypted_extensions: EncryptedExtensions; case certificate_request: CertificateRequest; case certificate: Certificate; case certificate_verify: CertificateVerify; case finished: Finished; case new_session_ticket: NewSessionTicket; case key_update: KeyUpdate; case request_connection_id: RequestConnectionId; case new_connection_id: NewConnectionId; } body; } Handshake;
uint16 ProtocolVersion; opaque Random[32];
uint8 CipherSuite[2]; /* Cryptographic suite selector */
struct { ProtocolVersion legacy_version = { 254,253 }; // DTLSv1.2 Random random; opaque legacy_session_id<0..32>; opaque legacy_cookie<0..2^8-1>; // DTLS CipherSuite cipher_suites<2..2^16-2>; opaque legacy_compression_methods<1..2^8-1>; Extension extensions<8..2^16-1>; } ClientHello;
## A.3. ACKs ✅
struct { RecordNumber record_numbers<0..2^16-1>; } ACK;
## A.4. Connection ID Management 🆔
enum { cid_immediate(0), cid_spare(1), (255) } ConnectionIdUsage;
opaque ConnectionId<0..2^8-1>;
struct { ConnectionId cids<0..2^16-1>; ConnectionIdUsage usage; } NewConnectionId;
struct { uint8 num_cids; } RequestConnectionId;
Appendix B. Analysis of Limits on CCM Usage ✨
okay bestie, this appendix is the math behind how long you can keep using one set of keys with AEAD_AES_128_CCM 🔐💅 TLS 1.3 and [AEBounds] don't spell out key usage limits for this cipher, but DTLS NEEDS limits so that both confidentiality AND integrity stay safe 😭🫶 so this section writes that analysis down, using [CCM-ANALYSIS] as the foundation, and the limits it gets are based on the ones picked in [TLS13] 🌸
the math uses multiplication (*), division (/), exponentiation (^), and parentheses for precedence 🧮 the variables are:
<pink>t</pink>: the size of the authentication tag in bits. for this cipher it's 128 🎀
<pink>n</pink>: the size of the block function in bits. for this cipher, n is 128 💜
<pink>l</pink>: the number of blocks in each packet (see below) 🦋
<pink>q</pink>: the number of genuine packets created and protected by endpoints. this is the bound on how many packets can be protected before you have to update keys 🔑✨
<pink>v</pink>: the number of forged packets endpoints will accept. this is the bound on how many forged packets an endpoint can reject before updating keys 🙈
the analysis of AEAD_AES_128_CCM counts how many block operations go into making each message 🧁 to keep things simple, and to match how [AEBounds] analyzes the other AEAD functions, this assumes a packet length of 2^10 blocks and a packet size limit of 2^14 bytes 🌈
for AEAD_AES_128_CCM, the total number of block cipher operations is the sum of: the length of the associated data in blocks, the length of the ciphertext in blocks, and the length of the plaintext in blocks, plus 1 🍓 in this analysis that simplifies to twice the max record length in blocks (so 2l = 2^11) 💖 this works because the associated data is limited to one block 🫶
## B.1. Confidentiality Limits 🔒
okay so for confidentiality, Theorem 2 in [CCM-ANALYSIS] says an attacker gets a distinguishing advantage over an ideal pseudorandom permutation (PRP) of no more than:
(2l * q)^2 / 2^n
for a target advantage in a single-key setting of 2^-60, which is the same target TLS 1.3 uses (per [AEAD-LIMITS]) 🎯 this gives the relation:
q <= 2^23
which means endpoints cannot protect more than 2^23 packets with the same set of keys without an attacker gaining a bigger advantage than the 2^-60 target 💀 not it!! 🙅♀️
## B.2. Integrity Limits 🛡️
for integrity, Theorem 1 in [CCM-ANALYSIS] says an attacker gains an advantage over an ideal PRP of no more than:
v / 2^t + (2l * (v + q))^2 / 2^n
the goal is to keep this advantage to 2^-57, to match the target in TLS 1.3 (per [AEAD-LIMITS]) 🌟 since t and n are both 128, the first term is negligible next to the second, so it can be dropped without really changing the result ✨ this gives:
v + q <= 2^24.5
using the 2^23 value we already got for q and rounding, this leads to an upper limit on v of 2^23.5 💅 so endpoints cannot try to authenticate more than 2^23.5 packets with the same set of keys without an attacker gaining a bigger advantage than the 2^-57 target 🫠
## B.3. Limits for AEAD_AES_128_CCM_8 🌸
the TLS_AES_128_CCM_8_SHA256 cipher suite uses the AEAD_AES_128_CCM_8 function, which has a short authentication tag (t=64) 🎀
the confidentiality limits of AEAD_AES_128_CCM_8 are the same as for AEAD_AES_128_CCM, because they don't depend on the tag length; see Appendix B.1 🔁
the shorter 64-bit tag means the simplification from Appendix B.2 does NOT apply to AEAD_AES_128_CCM_8 😬 if the goal is to keep the same margins as the other cipher suites, then the limit on forgeries is mostly set by the first term of the advantage formula:
v <= 2^7
since this counts attempts that FAIL authentication, applying this limit might be doable in some environments 🤞 BUT applying it in an implementation meant for general use leaves connections open to a cheap denial-of-service attack 😱🚨
> this analysis backs up the view that TLS_AES_128_CCM_8_SHA256 is not suitable for general use 💀 specifically, TLS_AES_128_CCM_8_SHA256 cannot be used without additional measures to prevent forgery of records, or to mitigate the effect of forgeries 🛑 this might need a look at the constraints in a particular deployment or application 🔍 for instance, it might be possible to set a different target for the advantage an attacker gains, based on the constraints of a specific DTLS usage 🧠
Appendix C. Implementation Pitfalls 🐛
okay so besides the TLS stuff that has caused interop and security problems (Appendix C.3 of [TLS13]), DTLS brings a few NEW potential sources of trouble 😩 here they are, bestie:
- <hotpink>do you correctly handle messages received from multiple epochs during a key transition?</hotpink> this includes finding the right key, AND doing replay detection if it's enabled 🔑
- <hotpink>do you retransmit handshake messages that are not (implicitly or explicitly) acknowledged (Section 5.8)?</hotpink> 🔁
- <hotpink>do you correctly handle handshake message fragments received, including when they're out of order?</hotpink> 🧩
- <hotpink>do you correctly handle handshake messages received out of order? this may include either buffering or discarding them.</hotpink> 📦
- <hotpink>do you limit how much data you send to a peer before its address is validated?</hotpink> 🚦
- <hotpink>do you verify that the explicit record length is contained within the datagram it's in?</hotpink> 👀
Contributors 🎀✨
okay so many people have worked on previous DTLS versions 🫶 they're acknowledged in the older DTLS specs or in the referenced specs, so go give them some love 💖
Hanno Becker
Arm Limited
Email: Hanno.Becker@arm.com
David Benjamin
Google
Email: davidben@google.com
Thomas Fossati
Arm Limited
Email: thomas.fossati@arm.com
Tobias Gondrom
Huawei
Email: tobias.gondrom@gondrom.org
Felix Günther
ETH Zurich
Email: mail@felixguenther.info
Benjamin Kaduk
Akamai Technologies
Email: kaduk@mit.edu
Ilari Liusvaara
Independent
Email: ilariliusvaara@welho.com
Martin Thomson
Mozilla
Email: martin.thomson@gmail.com
Christopher A. Wood
Cloudflare
Email: caw@heapingbits.net
Yin Xinxing
Huawei
Email: yinxinxing@huawei.com
---
the sequence number encryption concept is taken from QUIC [RFC9000] 🧚 we'd like to thank the authors of RFC 9000 for their work 🙌 Felix Günther and Martin Thomson contributed the analysis in Appendix B 🧠👑 we'd also like to thank Jonathan Hammell, Bernard Aboba, and Andy Cunningham for their review comments 🥰
and the IESG members get a shoutout too for their review comments: Martin Duke, Erik Kline, Francesca Palombini, Lars Eggert, Zaheduzzaman Sarker, John Scudder, Éric Vyncke, Robert Wilton, Roman Danyliw, Benjamin Kaduk, Murray Kucherawy, Martin Vigoureux, and Alvaro Retana 👏💜
Authors' Addresses 📮🌈
Eric Rescorla
Mozilla
Email: ekr@rtfm.com
Hannes Tschofenig
Arm Limited
Email: hannes.tschofenig@arm.com
Nagendra Modadugu
Google, Inc.
Email: nagendra@cs.stanford.edu
📦 where this page comes from
- ietf: rfc9147 2022-04
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms