ProtoCore v0.0.2
Deterministic, zero-heap network stack for embedded targets
Loading...
Searching...
No Matches
tls13_msg.h
Go to the documentation of this file.
1// Copyright (C) 2026 Douglas Quigg (dstroy0) <dquigg123@gmail.com>
2// SPDX-License-Identifier: AGPL-3.0-or-later
3
4/**
5 * @file pc_tls13_msg.h
6 * @brief TLS 1.3 handshake messages for the QUIC handshake (RFC 8446 sec 4).
7 *
8 * The wire formats of the handshake messages a QUIC server exchanges: it parses the client's
9 * ClientHello and builds its own flight (ServerHello, then the encrypted EncryptedExtensions,
10 * Certificate, CertificateVerify, and Finished). Every message is emitted whole, including the
11 * 4-byte handshake header (msg_type + 24-bit length), because that is what both the CRYPTO stream
12 * carries and the transcript hash covers.
13 *
14 * This server is deliberately a single, spec-valid profile: cipher suite TLS_AES_128_GCM_SHA256,
15 * key share X25519, and an Ed25519 certificate (the only signature scheme we produce - the in-tree
16 * crypto has Ed25519 but no ECDSA P-256 or RSA-PSS). A ClientHello that offers none of these is a
17 * handshake failure, decided by the state machine that drives this module. QUIC transport parameters
18 * ride in the pc_quic_transport_parameters extension (codepoint 0x39, RFC 9001 sec 8.2).
19 *
20 * Pure, zero heap, host-tested against the RFC 8448 sec 3 ServerHello / Certificate / Finished bytes
21 * and by ClientHello field extraction + an Ed25519 CertificateVerify sign/verify round-trip.
22 *
23 * @author Douglas Quigg (dstroy0)
24 * @date 2026
25 */
26
27#ifndef PROTOCORE_TLS13_MSG_H
28#define PROTOCORE_TLS13_MSG_H
29
30#include "protocore_config.h"
31
32// Shared by the HTTP/3 (QUIC) handshake and the DTLS 1.3 handshake: both carry the same TLS 1.3
33// messages, so this module compiles for either. The DTLS-specific additions (HelloRetryRequest, the
34// cookie extension, the sec 4.4.1 message_hash) are used by the DTLS handshake but are valid TLS 1.3.
35#if (PC_ENABLE_HTTP3 || PC_ENABLE_DTLS)
36
37#include <stddef.h>
38#include <stdint.h>
39
40/** @brief TLS handshake message types (RFC 8446 sec 4). */
41struct TlsHs
42{
43 static constexpr uint8_t TLS_HS_CLIENT_HELLO = 1;
44 static constexpr uint8_t TLS_HS_SERVER_HELLO = 2;
45 static constexpr uint8_t TLS_HS_ENCRYPTED_EXTENSIONS = 8;
46 static constexpr uint8_t TLS_HS_CERTIFICATE = 11;
47 static constexpr uint8_t TLS_HS_CERTIFICATE_VERIFY = 15;
48 static constexpr uint8_t TLS_HS_FINISHED = 20;
49};
50
51#define TLS_CIPHER_AES_128_GCM_SHA256 0x1301 ///< the one cipher suite we support
52#define TLS_GROUP_X25519 0x001d ///< the classical key-exchange group we support
53#define TLS_GROUP_X25519MLKEM768 0x11ec ///< PQ/T hybrid group (ML-KEM-768 + X25519), when PC_ENABLE_PQC_KEX
54#define TLS_SIG_ED25519 0x0807 ///< the one signature scheme we produce
55#define TLS_CERT_TYPE_X509 0 ///< RFC 7250 CertificateType: X.509 (IANA "TLS Certificate Types" 0)
56#define TLS_CERT_TYPE_RAW_PUBLIC_KEY 2 ///< RFC 7250 CertificateType: RawPublicKey (IANA 2), when PC_ENABLE_TLS_RPK
57#define TLS_VERSION_1_3 0x0304 ///< supported_versions selected value (TLS 1.3)
58#define PC_TLS_VERSION_DTLS_1_3 0xFEFC ///< supported_versions selected value (DTLS 1.3, RFC 9147)
59#define PC_TLS_LEGACY_VERSION_DTLS 0xFEFD ///< legacy_version on the wire for DTLS (DTLS 1.2)
60#define TLS_EXT_QUIC_TRANSPORT_PARAMS 0x0039 ///< pc_quic_transport_parameters (RFC 9001 sec 8.2)
61
62/** @brief What the state machine needs out of a parsed ClientHello (pointers alias the input). */
63struct Tls13ClientHello
64{
65 const uint8_t *session_id; ///< legacy_session_id (echoed back in ServerHello)
66 uint8_t session_id_len;
67 uint8_t client_x25519[32]; ///< the client's X25519 key_share (valid iff has_key_share or has_hybrid_share)
68 bool has_key_share;
69#if PC_ENABLE_PQC_KEX
70 bool offers_x25519mlkem768; ///< supported_groups contains X25519MLKEM768
71 bool has_hybrid_share; ///< key_share carried an X25519MLKEM768 entry
72 const uint8_t *client_mlkem_ek; ///< the client's ML-KEM-768 encapsulation key (1184 B, aliases input)
73#endif
74 bool offers_tls13; ///< supported_versions contains 0x0304
75 bool offers_x25519; ///< supported_groups contains x25519
76 bool offers_ed25519; ///< signature_algorithms contains ed25519
77#if PC_ENABLE_TLS_RPK
78 bool offers_rpk_server_cert; ///< server_certificate_type (RFC 7250) offered RawPublicKey(2)
79#endif
80 bool offers_h3_alpn; ///< ALPN contains "h3"
81 const uint8_t *pc_quic_tp; ///< raw pc_quic_transport_parameters extension body (or NULL)
82 size_t pc_quic_tp_len;
83 const uint8_t *sni; ///< first server_name host_name (or NULL), not NUL-terminated
84 size_t sni_len;
85 const uint8_t *cookie; ///< cookie extension body echoed after a HelloRetryRequest (or NULL); DTLS §5.1
86 size_t cookie_len;
87 bool has_conn_id; ///< the connection_id extension was present (RFC 9146 / RFC 9147 §9)
88 const uint8_t *conn_id; ///< the CID the client wants the server to use in records sent to it (may be empty)
89 size_t conn_id_len; ///< length of @c conn_id (0..255; 0 = the client wants a zero-length CID)
90};
91
92/**
93 * @brief Parse a ClientHello handshake message (@p msg includes the 4-byte handshake header).
94 *
95 * @param dtls true for a DTLS ClientHello (RFC 9147 §5.3), which carries an extra @c legacy_cookie
96 * field between @c legacy_session_id and @c cipher_suites; false for TLS/QUIC.
97 * @return false if it is not a well-formed ClientHello. Missing/!supported extensions are reported
98 * through the offers_* flags rather than failing the parse, so the caller can send the right alert.
99 */
100bool pc_tls13_parse_client_hello(const uint8_t *msg, size_t len, Tls13ClientHello *out, bool dtls = false);
101
102/**
103 * @brief Build a ServerHello (RFC 8446 sec 4.1.3) selecting TLS 1.3 / AES-128-GCM-SHA256 and a
104 * key_share for @p group.
105 *
106 * @param random 32-byte server random.
107 * @param session_id legacy_session_id_echo (the client's, echoed verbatim; may be NULL if len 0).
108 * @param session_id_len echoed session-id length (0..32).
109 * @param share the server's key_share (X25519 pub for the classical group, or the
110 * ciphertext || X25519 concatenation for X25519MLKEM768).
111 * @param share_len length of @p share (32 for X25519, 1120 for the hybrid).
112 * @param group the selected named group (default TLS_GROUP_X25519).
113 * @param conn_id when non-NULL, emit a connection_id extension (RFC 9146 / RFC 9147 §9)
114 * carrying the server's CID (the id the client must place in records it sends).
115 * @param conn_id_len length of @p conn_id (0..255).
116 * @return bytes written, or 0 on overflow.
117 */
118size_t pc_tls13_build_server_hello(uint8_t *out, size_t cap, const uint8_t random[32], const uint8_t *session_id,
119 uint8_t session_id_len, const uint8_t *share, size_t share_len = 32,
120 uint16_t group = TLS_GROUP_X25519, bool dtls = false,
121 const uint8_t *conn_id = nullptr, size_t conn_id_len = 0);
122
123/**
124 * @brief Build EncryptedExtensions (RFC 8446 sec 4.3.1) carrying ALPN "h3" and the server's
125 * pc_quic_transport_parameters (@p pc_quic_tp, from pc_quic_tp_encode).
126 *
127 * @param rpk_server_cert when true (PC_ENABLE_TLS_RPK), also emit the negotiated
128 * server_certificate_type = RawPublicKey extension (RFC 7250 sec 4.2).
129 * @return bytes written, or 0.
130 */
131size_t pc_tls13_build_encrypted_extensions(uint8_t *out, size_t cap, const uint8_t *pc_quic_tp, size_t pc_quic_tp_len,
132 bool rpk_server_cert = false);
133
134/**
135 * @brief Build a Certificate message (RFC 8446 sec 4.4.2) with an empty request context and one
136 * CertificateEntry wrapping @p cert_der (DER X.509) with no entry extensions. @return bytes written.
137 */
138size_t pc_tls13_build_certificate(uint8_t *out, size_t cap, const uint8_t *cert_der, size_t cert_len);
139
140#if PC_ENABLE_TLS_RPK
141#define PC_TLS13_ED25519_SPKI_LEN 44 ///< DER SubjectPublicKeyInfo for an Ed25519 key (RFC 8410 sec 4)
142
143/**
144 * @brief Write the 44-byte DER @c SubjectPublicKeyInfo for the Ed25519 key @p pub (RFC 8410 sec 4):
145 * the fixed AlgorithmIdentifier (id-Ed25519, OID 1.3.101.112) wrapping the 32-byte key in a BIT STRING.
146 * This is the RFC 7250 RawPublicKey credential. @return PC_TLS13_ED25519_SPKI_LEN, or 0 on overflow.
147 */
148size_t pc_tls13_ed25519_spki(uint8_t *out, size_t cap, const uint8_t pub[32]);
149
150/**
151 * @brief Build a Certificate message (RFC 8446 sec 4.4.2) carrying an RFC 7250 RawPublicKey: one
152 * CertificateEntry whose cert_data is the Ed25519 @c SubjectPublicKeyInfo of @p ed25519_pub (no X.509).
153 * The peer must have negotiated server_certificate_type = RawPublicKey. @return bytes written, or 0.
154 */
155size_t pc_tls13_build_certificate_rpk(uint8_t *out, size_t cap, const uint8_t ed25519_pub[32]);
156#endif
157
158/**
159 * @brief Build a CertificateVerify (RFC 8446 sec 4.4.3) with an Ed25519 signature.
160 *
161 * Signs the sec 4.4.3 content - 64 * 0x20, the context string "TLS 1.3, server CertificateVerify",
162 * a 0x00 separator, then @p transcript_hash (Transcript-Hash of ClientHello..Certificate) - with the
163 * Ed25519 key @p seed, and emits algorithm=ed25519, the 64-byte signature.
164 *
165 * @param transcript_hash 32-byte Transcript-Hash through the Certificate message.
166 * @param seed 32-byte Ed25519 private seed.
167 * @return bytes written, or 0 on overflow.
168 */
169size_t pc_tls13_build_cert_verify(uint8_t *out, size_t cap, const uint8_t transcript_hash[32], const uint8_t seed[32]);
170
171/**
172 * @brief Build a Finished message (RFC 8446 sec 4.4.4) carrying @p verify_data (from
173 * pc_tls13_finished_mac). @return bytes written, or 0 on overflow.
174 */
175size_t pc_tls13_build_finished(uint8_t *out, size_t cap, const uint8_t verify_data[32]);
176
177/**
178 * @brief Assemble the sec 4.4.3 signed content into @p out (64*0x20 || context || 0x00 || hash).
179 *
180 * Exposed so the state machine can also verify a client's CertificateVerify if client auth is ever
181 * added, and so it is directly unit-testable. @p is_server picks the "server"/"client" context word.
182 * @return content length written (always 98 + 32), or 0 on overflow.
183 */
184size_t pc_tls13_cert_verify_content(uint8_t *out, size_t cap, const uint8_t transcript_hash[32], bool is_server);
185
186// ---------------------------------------------------------------------------
187// HelloRetryRequest + cookie (RFC 8446 §4.1.4), used by the DTLS 1.3 handshake
188// ---------------------------------------------------------------------------
189
190/** @brief The fixed HelloRetryRequest random - SHA-256("HelloRetryRequest"), RFC 8446 §4.1.3. A
191 * ServerHello carrying this random _is_ a HelloRetryRequest. 32 bytes. */
192extern const uint8_t pc_tls13_hrr_random[32];
193
194/**
195 * @brief Build a HelloRetryRequest (RFC 8446 §4.1.4): a ServerHello whose random is
196 * @ref pc_tls13_hrr_random, selecting TLS 1.3 / AES-128-GCM-SHA256, asking the client to retry with a
197 * key_share for @p selected_group, and echoing @p cookie in the cookie extension (§4.2.2).
198 *
199 * @param session_id legacy_session_id_echo (the client's, echoed verbatim; may be NULL if len 0).
200 * @param selected_group the NamedGroup the server wants the client's key_share for.
201 * @param cookie the return-routability cookie the client must echo (may be NULL if len 0).
202 * @param dtls true to emit the DTLS 1.3 version codepoints (0xFEFD / 0xFEFC, RFC 9147 §5.3);
203 * false for the TLS 1.3 ones (0x0303 / 0x0304).
204 * @return bytes written, or 0 on overflow.
205 */
206size_t pc_tls13_build_hello_retry_request(uint8_t *out, size_t cap, const uint8_t *session_id, uint8_t session_id_len,
207 uint16_t selected_group, const uint8_t *cookie, size_t cookie_len,
208 bool dtls = false);
209
210/**
211 * @brief Build an EncryptedExtensions (RFC 8446 §4.3.1) for the DTLS profile, which carries no ALPN or
212 * transport parameters. With @p rpk_server_cert (PC_ENABLE_TLS_RPK) it carries the negotiated
213 * server_certificate_type = RawPublicKey extension (RFC 7250 sec 4.2); otherwise the list is empty.
214 * @return bytes written, or 0 on overflow.
215 */
216size_t pc_tls13_build_encrypted_extensions_empty(uint8_t *out, size_t cap, bool rpk_server_cert = false);
217
218/**
219 * @brief Write the synthetic @c message_hash handshake message that replaces ClientHello1 in the
220 * transcript when a HelloRetryRequest is used (RFC 8446 §4.4.1): @c message_hash (254), a 24-bit
221 * length of 32, then @p ch1_hash. @return bytes written (36), or 0 on overflow.
222 */
223size_t pc_tls13_build_message_hash(uint8_t *out, size_t cap, const uint8_t ch1_hash[32]);
224
225#endif // PC_ENABLE_HTTP3 || PC_ENABLE_DTLS
226#endif // PROTOCORE_TLS13_MSG_H
protocore_config.h
User-facing configuration for ProtoCore.