Protocol++® (Protocolpp®)  v5.7.0
jdtls13 Class Reference

#include "include/jdtls13.h"

Detailed Description

Datagram Transport Layer Security v1.3 (DTLS13)

For additional information see http://en.wikipedia.org/wiki/Transport_Layer_Security and RFC9147

The DTLS 1.3 protocol is based on the Transport Layer Security (TLS) 1.3 protocol and provides equivalent security guarantees with the exception of order protection, non-replayability. Datagram semantics of the underlying transport are preserved by the DTLS protocol

DTLS Design Rational

The basic design philosophy of DTLS is to construct "TLS over datagram transport" Datagram transport neither requires nor provides reliable or in-order delivery of data. The DTLS protocol preserves this property for application data. Applications such as media streaming, Internet telephony, and online gaming use datagram transport for communication due to the delay-sensitive nature of transported data. The behavior of such applications is unchanged when the DTLS protocol is used to secure communication, since the DTLS protocol does not compensate for lost or reordered data traffic. Note that while low-latency streaming and gaming use DTLS to protect data (e.g., for protection of a WebRTC data channel), telephony utilizes DTLS for key establishment and the Secure Real-time Transport Protocol (SRTP) for protection of data

TLS cannot be used directly over datagram transports for the following four reasons:

  1. TLS relies on an implicit sequence number on records. If a record is not received, then the recipient will use the wrong sequence number when attempting to remove record protection from subsequent records. DTLS solves this problem by adding sequence numbers to records
  2. The TLS handshake is a lock-step cryptographic protocol. Messages must be transmitted and received in a defined order; any other order is an error. The DTLS handshake includes message sequence numbers to enable fragmented message reassembly and in-order delivery in case datagrams are lost or reordered
  3. Handshake messages are potentially larger than can be contained in a single datagram DTLS adds fields to handshake messages to support fragmentation and reassembly
  4. Datagram transport protocols are susceptible to abusive behavior effecting denial-of-service (DoS) attacks against nonparticipants. DTLS adds a return-routability check and DTLS 1.3 uses the TLS 1.3 HelloRetryRequest message
General Message Format of DTLS Records (Packets)

The DTLS Record Layer

The DTLS 1.3 record layer is different from the TLS 1.3 record layer and also different from the DTLS 1.2 record layer

  1. The DTLSCiphertext structure omits the superfluous version number and type fields
  2. DTLS adds an epoch and sequence number to the TLS record header. This sequence number allows the recipient to correctly decrypt and verify DTLS records. However, the number of bits used for the epoch and sequence number fields in the DTLSCiphertext structure has been reduced from those in previous versions
  3. The DTLS epoch serialized in DTLSPlaintext is 2 octets long for compatibility with DTLS 1.2. However, this value is set as the least significant 2 octets of the connection epoch, which is an 8 octet counter incremented on every KeyUpdate. See Section 4.2 for details. The sequence number is set to be 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
  4. 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

General Message Format of DTLS Records (Packets)
  • Fixed Bits: The three high bits of the first byte of the unified header are set to 001 This ensures that the value will fit within the DTLS region when multiplexing is performed as described in [RFC7983]. It also ensures that distinguishing encrypted DTLS 1.3 records from encrypted DTLS 1.2 records is possible when they are carried on the same host/port quartet; such multiplexing is only possible when CIDs [RFC9146] are in use, in which 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, 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: 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 included in the same underlying transport datagram

DTLSv1.3 Header Examples

Sequence Number and Epoch

DTLS uses an explicit or partly explicit sequence number, rather than an implicit one, carried in the sequence_number field of the record. Sequence numbers are maintained separately for each epoch, with each sequence_number initially being 0 for each epoch

The epoch number is initially zero and is incremented each time keying material changes and a sender aims to rekey. More details are provided in Section 6.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

Reconstructing the Sequence Number and Epoch

When receiving protected DTLS records, the recipient does not have a full epoch or sequence number value in the record and so there is some opportunity for ambiguity Because the full sequence number is used to compute the per-record nonce and the epoch determines the keys, failure to reconstruct these values leads to failure to deprotect the record, and so implementations MAY use a mechanism of their choice to determine the full values. This section provides an algorithm which is comparatively simple and which implementations are RECOMMENDED to follow

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

Record Number Encryption

In DTLS 1.3, when records are encrypted, record sequence numbers are also encrypted The basic pattern is that the underlying encryption algorithm used with the AEAD algorithm is used to generate a mask which is then XORed with the sequence numbe

When the AEAD is based on AES, then 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, then 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, 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 does not 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 accomplished 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) in order to make a suitable-length ciphertext. Note that 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 is only applied to the DTLSCiphertext structure and not to the DTLSPlaintext structure, even though it also contains a sequence number

Content Type

This field identifies the Record Layer Protocol Type contained in this Record

DTLS Content Types
HexDecType
0x1521Alert
0x1622Handshake
0x1723Application
0x1824Heartbeat
0x1826Ack

Per-Record Nonce

A 64-bit sequence number is maintained separately for reading and writing records. Each sequence number is set to zero at the beginning of a connection and whenever the key is changed. The sequence number is incremented by one after reading or writing each record. The first record transmitted under a particular set of traffic keys MUST use sequence number 0

Because the size of sequence numbers is 64-bit, they should not wrap. If a DTLS implementation would need to wrap a sequence number, it MUST either re-key (Section 4.6.3) or terminate the connection

Each AEAD algorithm will specify a range of possible lengths for the per-record nonce, from N_MIN bytes to N_MAX bytes of input ([RFC5116]). The length of the DTLS per-record nonce (iv_length) is set to the larger of 8 bytes and N_MIN for the AEAD algorithm (see [RFC5116] Section 4). An AEAD algorithm where N_MAX is less than 8 bytes MUST NOT be used with DTLS. The per-record nonce for the AEAD construction is formed as follows:

  1. The 64-bit record sequence number is encoded in network byte order and padded to the left with zeros to iv_length
  2. The padded sequence number is XORed with the static client_write_iv or server_write_iv, depending on the role. The resulting quantity (of length iv_length) is used as the per-record nonce

*** Note: This is a different construction from that in DTLS 1.2, which specified a partially explicit nonce ***

ShangMi (SM) Cipher Suites for TLSv1.3

See RFC8998

The SM algorithms are becoming mandatory in China, so this document provides a description of how to use the SM algorithms with TLS 1.3 and specifies a profile of TLS 1.3 so that implementers can produce interworking implementations

This document describes two new cipher suites, a signature algorithm and a key exchange mechanism for the Transport Layer Security (TLS) protocol version 1.3 (TLS 1.3). These all utilize several ShangMi (SM) cryptographic algorithms to fulfill the authentication and confidentiality requirements of TLS 1.3. The new cipher suites are as follows (see also Section 2):

  • CipherSuite TLS_SM4_GCM_SM3 = { 0x00, 0xC6 };
  • CipherSuite TLS_SM4_CCM_SM3 = { 0x00, 0xC7 };

For a more detailed introduction to SM cryptographic algorithms, please see Section 1.1 These cipher suites follow the TLS 1.3 requirements. Specifically, all the cipher suites use SM4 in either Galois/Counter (GCM) mode or Counter with CBC-MAC (CCM) mode to meet the needs of TLS 1.3 to have an encryption algorithm that is Authenticated Encryption with Associated Data (AEAD) capable. The key exchange mechanism utilizes Elliptic Curve Diffie-Hellman Ephemeral (ECDHE) over the SM2 elliptic curve, and the signature algorithm combines the SM3 hash function and the SM2 elliptic curve signature scheme

For details about how these mechanisms negotiate shared encryption keys, authenticate the peer (s), and protect the record structure, please see Section 3

The cipher suites, signature algorithm, and key exchange mechanism defined in this document are not recommended by the IETF. The SM algorithms are becoming mandatory in China, so this document provides a description of how to use them with TLS 1.3 and specifies a profile of TLS 1.3 so that implementers can produce interworking implementations

The SM Algorithms

Several different SM cryptographic algorithms are used to integrate with TLS 1.3, including SM2 for authentication, SM4 for encryption, and SM3 as the hash function

SM2 is a set of cryptographic algorithms based on elliptic curve cryptography, including a digital signature, public key encryption and key exchange scheme. In this document, only the SM2 digital signature algorithm and basic key exchange scheme are involved, which have already been added to ISO/IEC 14888-3:2018 ISO-SM2 SM4 is a block cipher defined in [GBT.32907-2016] and now is being standardized by ISO to ISO/IEC 18033-3:2010 [ISO-SM4]. SM3 is a hash function that produces an output of 256 bits SM3 has already been accepted by ISO in ISO/IEC 10118-3:2018 [ISO-SM3] and has also been described by [GBT.32905-2016]

For API Documentation:

See also
ProtocolPP::jprotocol
ProtocolPP::jdtlsa13
ProtocolPP::jdtls13

For Additional Documentation:

See also
jprotocol
jdtlsa13
jdtls13
Protocol++® (ProtocolPP®) written by : John Peter Greninger • © John Peter Greninger 2015-2024 • All Rights Reserved
All copyrights and trademarks are the property of their respective owners

The source code contained or described herein and all documents related to the source code (herein called "Material") are owned by John Peter Greninger and Sheila Rocha Greninger. Title to the Material remains with John Peter Greninger and Sheila Rocha Greninger. The Material contains trade secrets and proprietary and confidential information of John Peter Greninger and Sheila Rocha Greninger. The Material is protected by worldwide copyright and trade secret laws and treaty provisions. No part of the Material may be used, copied, reproduced, modified, published, uploaded, posted, transmitted, distributed, or disclosed in any way without prior express written consent of John Peter Greninger and Sheila Rocha Greninger (both are required)

No license under any patent, copyright, trade secret, or other intellectual property right is granted to or conferred upon you by disclosure or delivery of the Materials, either expressly, by implication, inducement, estoppel, or otherwise. Any license under such intellectual property rights must be express and approved by John Peter Greninger and Sheila Rocha Greninger in writing

Licensing information can be found at www.protocolpp.com/license with use of the binary forms permitted provided that the following conditions are met:

  • Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution
  • Any and all modifications must be returned to John Peter Greninger at GitHub.com https://github.com/jpgreninger/protocolpp for evaluation. Inclusion of modifications in the source code shall be determined solely by John Peter Greninger. Failure to provide modifications shall render this license NULL and VOID and revoke any rights to use of Protocol++®
  • Commercial use (incidental or not) requires a fee-based license obtainable at www.protocolpp.com/shop
  • Academic or research use requires prior written and notarized permission from John Peter and Sheila Rocha Greninger

Use of the source code requires purchase of the source code. Source code can be purchased at www.protocolpp.com/shop

  • US Copyrights at https://www.copyright.gov/
    • TXu002059872 (Version 1.0.0)
    • TXu002066632 (Version 1.2.7)
    • TXu002082674 (Version 1.4.0)
    • TXu002097880 (Version 2.0.0)
    • TXu002169236 (Version 3.0.1)
    • TXu002182417 (Version 4.0.0)
    • TXu002219402 (Version 5.0.0)
    • TXu002272076 (Version 5.2.1)
    • TXu002383571 (Version 5.4.3)

The name of its contributor may not be used to endorse or promote products derived from this software without specific prior written permission and licensing

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER AND CONTRIBUTOR "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE

The documentation for this class was generated from the following file: