2 * Copyright 2022 The OpenSSL Project Authors. All Rights Reserved.
4 * Licensed under the Apache License 2.0 (the "License"). You may not use
5 * this file except in compliance with the License. You can obtain a copy
6 * in the file LICENSE in the source distribution or at
7 * https://www.openssl.org/source/license.html
10 #ifndef OSSL_QUIC_WIRE_PKT_H
11 # define OSSL_QUIC_WIRE_PKT_H
13 # include <openssl/ssl.h>
14 # include "internal/packet_quic.h"
15 # include "internal/quic_types.h"
17 # ifndef OPENSSL_NO_QUIC
19 # define QUIC_VERSION_NONE ((uint32_t)0) /* Used for version negotiation */
20 # define QUIC_VERSION_1 ((uint32_t)1) /* QUIC v1 */
22 /* QUIC logical packet type. These do not match wire values. */
23 # define QUIC_PKT_TYPE_INITIAL 1
24 # define QUIC_PKT_TYPE_0RTT 2
25 # define QUIC_PKT_TYPE_HANDSHAKE 3
26 # define QUIC_PKT_TYPE_RETRY 4
27 # define QUIC_PKT_TYPE_1RTT 5
28 # define QUIC_PKT_TYPE_VERSION_NEG 6
31 * Determine encryption level from packet type. Returns QUIC_ENC_LEVEL_NUM if
32 * the packet is not of a type which is encrypted.
34 static ossl_inline ossl_unused uint32_t
35 ossl_quic_pkt_type_to_enc_level(uint32_t pkt_type)
38 case QUIC_PKT_TYPE_INITIAL:
39 return QUIC_ENC_LEVEL_INITIAL;
40 case QUIC_PKT_TYPE_HANDSHAKE:
41 return QUIC_ENC_LEVEL_HANDSHAKE;
42 case QUIC_PKT_TYPE_0RTT:
43 return QUIC_ENC_LEVEL_0RTT;
44 case QUIC_PKT_TYPE_1RTT:
45 return QUIC_ENC_LEVEL_1RTT;
47 return QUIC_ENC_LEVEL_NUM;
51 static ossl_inline ossl_unused uint32_t
52 ossl_quic_enc_level_to_pkt_type(uint32_t enc_level)
55 case QUIC_ENC_LEVEL_INITIAL:
56 return QUIC_PKT_TYPE_INITIAL;
57 case QUIC_ENC_LEVEL_HANDSHAKE:
58 return QUIC_PKT_TYPE_HANDSHAKE;
59 case QUIC_ENC_LEVEL_0RTT:
60 return QUIC_PKT_TYPE_0RTT;
61 case QUIC_ENC_LEVEL_1RTT:
62 return QUIC_PKT_TYPE_1RTT;
68 /* Determine if a packet type contains an encrypted payload. */
69 static ossl_inline ossl_unused int
70 ossl_quic_pkt_type_is_encrypted(uint32_t pkt_type)
73 case QUIC_PKT_TYPE_RETRY:
74 case QUIC_PKT_TYPE_VERSION_NEG:
81 /* Determine if a packet type contains a PN field. */
82 static ossl_inline ossl_unused int
83 ossl_quic_pkt_type_has_pn(uint32_t pkt_type)
86 * Currently a packet has a PN iff it is encrypted. This could change
89 return ossl_quic_pkt_type_is_encrypted(pkt_type);
93 * Determine if a packet type can appear with other packets in a datagram. Some
94 * packet types must be the sole packet in a datagram.
96 static ossl_inline ossl_unused int
97 ossl_quic_pkt_type_can_share_dgram(uint32_t pkt_type)
100 * Currently only the encrypted packet types can share a datagram. This
101 * could change someday.
103 return ossl_quic_pkt_type_is_encrypted(pkt_type);
107 * Determine if the packet type must come at the end of the datagram (due to the
108 * lack of a length field).
110 static ossl_inline ossl_unused int
111 ossl_quic_pkt_type_must_be_last(uint32_t pkt_type)
114 * Any packet type which cannot share a datagram obviously must come last.
115 * 1-RTT also must come last as it lacks a length field.
117 return !ossl_quic_pkt_type_can_share_dgram(pkt_type)
118 || pkt_type == QUIC_PKT_TYPE_1RTT;
122 * Smallest possible QUIC packet size as per RFC (aside from version negotiation
125 # define QUIC_MIN_VALID_PKT_LEN_CRYPTO 21
126 # define QUIC_MIN_VALID_PKT_LEN_VERSION_NEG 7
127 # define QUIC_MIN_VALID_PKT_LEN QUIC_MIN_VALID_PKT_LEN_VERSION_NEG
129 typedef struct quic_pkt_hdr_ptrs_st QUIC_PKT_HDR_PTRS;
132 * QUIC Packet Header Protection
133 * =============================
135 * Functions to apply and remove QUIC packet header protection. A header
136 * protector is initialised using ossl_quic_hdr_protector_init and must be
137 * destroyed using ossl_quic_hdr_protector_cleanup when no longer needed.
139 typedef struct quic_hdr_protector_st {
140 OSSL_LIB_CTX *libctx;
142 EVP_CIPHER_CTX *cipher_ctx;
145 } QUIC_HDR_PROTECTOR;
147 # define QUIC_HDR_PROT_CIPHER_AES_128 1
148 # define QUIC_HDR_PROT_CIPHER_AES_256 2
149 # define QUIC_HDR_PROT_CIPHER_CHACHA 3
152 * Initialises a header protector.
155 * The header protection cipher method to use. One of
156 * QUIC_HDR_PROT_CIPHER_*. Must be chosen based on negotiated TLS cipher
160 * This must be the "quic hp" key derived from a traffic secret.
162 * The length of the quic_hp_key must correspond to that expected for the
165 * The header protector performs amortisable initialisation in this function,
166 * therefore a header protector should be used for as long as possible.
168 * Returns 1 on success and 0 on failure.
170 int ossl_quic_hdr_protector_init(QUIC_HDR_PROTECTOR *hpr,
171 OSSL_LIB_CTX *libctx,
174 const unsigned char *quic_hp_key,
175 size_t quic_hp_key_len);
178 * Destroys a header protector. This is also safe to call on a zero-initialized
179 * OSSL_QUIC_HDR_PROTECTOR structure which has not been initialized, or which
180 * has already been destroyed.
182 void ossl_quic_hdr_protector_cleanup(QUIC_HDR_PROTECTOR *hpr);
185 * Removes header protection from a packet. The packet payload must currently be
186 * encrypted (i.e., you must remove header protection before decrypting packets
187 * received). The function examines the header buffer to determine which bytes
188 * of the header need to be decrypted.
190 * If this function fails, no data is modified.
192 * This is implemented as a call to ossl_quic_hdr_protector_decrypt_fields().
194 * Returns 1 on success and 0 on failure.
196 int ossl_quic_hdr_protector_decrypt(QUIC_HDR_PROTECTOR *hpr,
197 QUIC_PKT_HDR_PTRS *ptrs);
200 * Applies header protection to a packet. The packet payload must already have
201 * been encrypted (i.e., you must apply header protection after encrypting
202 * a packet). The function examines the header buffer to determine which bytes
203 * of the header need to be encrypted.
205 * This is implemented as a call to ossl_quic_hdr_protector_encrypt_fields().
207 * Returns 1 on success and 0 on failure.
209 int ossl_quic_hdr_protector_encrypt(QUIC_HDR_PROTECTOR *hpr,
210 QUIC_PKT_HDR_PTRS *ptrs);
213 * Removes header protection from a packet. The packet payload must currently
214 * be encrypted. This is a low-level function which assumes you have already
215 * determined which parts of the packet header need to be decrypted.
218 * The range of bytes in the packet to be used to generate the header
219 * protection mask. It is permissible to set sample_len to the size of the
220 * remainder of the packet; this function will only use as many bytes as
221 * needed. If not enough sample bytes are provided, this function fails.
224 * The first byte of the QUIC packet header to be decrypted.
227 * Pointer to the start of the PN field. The caller is responsible
228 * for ensuring at least four bytes follow this pointer.
230 * Returns 1 on success and 0 on failure.
232 int ossl_quic_hdr_protector_decrypt_fields(QUIC_HDR_PROTECTOR *hpr,
233 const unsigned char *sample,
235 unsigned char *first_byte,
236 unsigned char *pn_bytes);
239 * Works analogously to ossl_hdr_protector_decrypt_fields, but applies header
240 * protection instead of removing it.
242 int ossl_quic_hdr_protector_encrypt_fields(QUIC_HDR_PROTECTOR *hpr,
243 const unsigned char *sample,
245 unsigned char *first_byte,
246 unsigned char *pn_bytes);
252 * This structure provides a logical representation of a QUIC packet header.
254 * QUIC packet formats fall into the following categories:
256 * Long Packets, which is subdivided into five possible packet types:
257 * Version Negotiation (a special case);
263 * Short Packets, which comprises only a single packet type (1-RTT).
265 * The packet formats vary and common fields are found in some packets but
266 * not others. The below table indicates which fields are present in which
267 * kinds of packet. * indicates header protection is applied.
269 * SLLLLL Legend: 1=1-RTT, i=Initial, 0=0-RTT, h=Handshake
270 * 1i0hrv r=Retry, v=Version Negotiation
272 * 1i0hrv Header Form (0=Short, 1=Long)
273 * 1i0hr Fixed Bit (always 1)
277 * 1i0h * Packet Number Length
278 * i0hr? Long Packet Type
279 * i0h Type-Specific Bits
280 * i0hr Version (note: always 0 for Version Negotiation packets)
281 * 1i0hrv Destination Connection ID
282 * i0hrv Source Connection ID
283 * 1i0h * Packet Number
287 * r Retry Integrity Tag
289 * For each field below, the conditions under which the field is valid are
290 * specified. If a field is not currently valid, it is initialized to a zero or
293 typedef struct quic_pkt_hdr_st {
294 /* [ALL] A QUIC_PKT_TYPE_* value. Always valid. */
295 unsigned int type :8;
297 /* [S] Value of the spin bit. Valid if (type == 1RTT). */
298 unsigned int spin_bit :1;
301 * [S] Value of the Key Phase bit in the short packet.
302 * Valid if (type == 1RTT && !partial).
304 unsigned int key_phase :1;
307 * [1i0h] Length of packet number in bytes. This is the decoded value.
308 * Valid if ((type == 1RTT || (version && type != RETRY)) && !partial).
310 unsigned int pn_len :4;
313 * [ALL] Set to 1 if this is a partial decode because the packet header
314 * has not yet been deprotected. pn_len, pn and key_phase are not valid if
317 unsigned int partial :1;
320 * [ALL] Whether the fixed bit was set. Note that only Version Negotiation
321 * packets are allowed to have this unset, so this will always be 1 for all
322 * other packet types (decode will fail if it is not set). Ignored when
323 * encoding unless encoding a Version Negotiation packet.
325 unsigned int fixed :1;
328 * The unused bits in the low 4 bits of a Retry packet header's first byte.
329 * This is used to ensure that Retry packets have the same bit-for-bit
330 * representation in their header when decoding and encoding them again.
331 * This is necessary to validate Retry packet headers.
333 unsigned int unused :4;
335 /* [L] Version field. Valid if (type != 1RTT). */
338 /* [ALL] The destination connection ID. Always valid. */
339 QUIC_CONN_ID dst_conn_id;
342 * [L] The source connection ID.
343 * Valid if (type != 1RTT).
345 QUIC_CONN_ID src_conn_id;
348 * [1i0h] Relatively-encoded packet number in raw, encoded form. The correct
349 * decoding of this value is context-dependent. The number of bytes valid in
350 * this buffer is determined by pn_len above. If the decode was partial,
351 * this field is not valid.
353 * Valid if ((type == 1RTT || (version && type != RETRY)) && !partial).
358 * [i] Token field in Initial packet. Points to memory inside the decoded
359 * PACKET, and therefore is valid for as long as the PACKET's buffer is
360 * valid. token_len is the length of the token in bytes.
362 * Valid if (type == INITIAL).
364 const unsigned char *token;
368 * [ALL] Payload length in bytes.
370 * Though 1-RTT, Retry and Version Negotiation packets do not contain an
371 * explicit length field, this field is always valid and is used by the
372 * packet header encoding and decoding routines to describe the payload
373 * length, regardless of whether the packet type encoded or decoded uses an
374 * explicit length indication.
379 * Pointer to start of payload data in the packet. Points to memory inside
380 * the decoded PACKET, and therefore is valid for as long as the PACKET'S
381 * buffer is valid. The length of the buffer in bytes is in len above.
383 * For Version Negotiation packets, points to the array of supported
386 * For Retry packets, points to the Retry packet payload, which comprises
387 * the Retry Token followed by a 16-byte Retry Integrity Tag.
389 * Regardless of whether a packet is a Version Negotiation packet (where the
390 * payload contains a list of supported versions), a Retry packet (where the
391 * payload contains a Retry Token and Retry Integrity Tag), or any other
392 * packet type (where the payload contains frames), the payload is not
393 * validated and the user must parse the payload bearing this in mind.
395 * If the decode was partial (partial is set), this points to the start of
396 * the packet number field, rather than the protected payload, as the length
397 * of the packet number field is unknown. The len field reflects this in
398 * this case (i.e., the len field is the number of payload bytes plus the
399 * number of bytes comprising the PN).
401 const unsigned char *data;
405 * Extra information which can be output by the packet header decode functions
406 * for the assistance of the header protector. This avoids the header protector
407 * needing to partially re-decode the packet header.
409 struct quic_pkt_hdr_ptrs_st {
410 unsigned char *raw_start; /* start of packet */
411 unsigned char *raw_sample; /* start of sampling range */
412 size_t raw_sample_len; /* maximum length of sampling range */
415 * Start of PN field. Guaranteed to be NULL unless at least four bytes are
416 * available via this pointer.
418 unsigned char *raw_pn;
422 * If partial is 1, reads the unprotected parts of a protected packet header
423 * from a PACKET, performing a partial decode.
425 * If partial is 0, the input is assumed to have already had header protection
426 * removed, and all header fields are decoded.
428 * If nodata is 1, the input is assumed to have no payload data in it. Otherwise
429 * payload data must be present.
431 * On success, the logical decode of the packet header is written to *hdr.
432 * hdr->partial is set or cleared according to whether a partial decode was
433 * performed. *ptrs is filled with pointers to various parts of the packet
436 * In order to decode short packets, the connection ID length being used must be
437 * known contextually, and should be passed as short_conn_id_len. If
438 * short_conn_id_len is set to an invalid value (a value greater than
439 * QUIC_MAX_CONN_ID_LEN), this function fails when trying to decode a short
440 * packet, but succeeds for long packets.
442 * Returns 1 on success and 0 on failure.
444 int ossl_quic_wire_decode_pkt_hdr(PACKET *pkt,
445 size_t short_conn_id_len,
449 QUIC_PKT_HDR_PTRS *ptrs);
452 * Encodes a packet header. The packet is written to pkt.
454 * The length of the (encrypted) packet payload should be written to hdr->len
455 * and will be placed in the serialized packet header. The payload data itself
456 * is not copied; the caller should write hdr->len bytes of encrypted payload to
457 * the WPACKET immediately after the call to this function. However,
458 * WPACKET_reserve_bytes is called for the payload size.
460 * This function does not apply header protection. You must apply header
461 * protection yourself after calling this function. *ptrs is filled with
462 * pointers which can be passed to a header protector, but this must be
463 * performed after the encrypted payload is written.
465 * The pointers in *ptrs are direct pointers into the WPACKET buffer. If more
466 * data is written to the WPACKET buffer, WPACKET buffer reallocations may
467 * occur, causing these pointers to become invalid. Therefore, you must not call
468 * any write WPACKET function between this call and the call to
469 * ossl_quic_hdr_protector_encrypt. This function calls WPACKET_reserve_bytes
470 * for the payload length, so you may assume hdr->len bytes are already free to
471 * write at the WPACKET cursor location once this function returns successfully.
472 * It is recommended that you call this function, write the encrypted payload,
473 * call ossl_quic_hdr_protector_encrypt, and then call
474 * WPACKET_allocate_bytes(hdr->len).
476 * Version Negotiation and Retry packets do not use header protection; for these
477 * header types, the fields in *ptrs are all written as zero. Version
478 * Negotiation, Retry and 1-RTT packets do not contain a Length field, but
479 * hdr->len bytes of data are still reserved in the WPACKET.
481 * If serializing a short packet and short_conn_id_len does not match the DCID
482 * specified in hdr, the function fails.
484 * Returns 1 on success and 0 on failure.
486 int ossl_quic_wire_encode_pkt_hdr(WPACKET *pkt,
487 size_t short_conn_id_len,
488 const QUIC_PKT_HDR *hdr,
489 QUIC_PKT_HDR_PTRS *ptrs);
492 * Retrieves only the DCID from a packet header. This is intended for demuxer
493 * use. It avoids the need to parse the rest of the packet header twice.
495 * Information on packet length is not decoded, as this only needs to be used on
496 * the first packet in a datagram, therefore this takes a buffer and not a
499 * Returns 1 on success and 0 on failure.
501 int ossl_quic_wire_get_pkt_hdr_dst_conn_id(const unsigned char *buf,
503 size_t short_conn_id_len,
504 QUIC_CONN_ID *dst_conn_id);
507 * Precisely predicts the encoded length of a packet header structure.
509 * May return 0 if the packet header is not valid, but the fact that this
510 * function returns non-zero does not guarantee that
511 * ossl_quic_wire_encode_pkt_hdr() will succeed.
513 int ossl_quic_wire_get_encoded_pkt_hdr_len(size_t short_conn_id_len,
514 const QUIC_PKT_HDR *hdr);
517 * Packet Number Encoding
518 * ======================
522 * Decode an encoded packet header QUIC PN.
524 * enc_pn is the raw encoded PN to decode. enc_pn_len is its length in bytes as
525 * indicated by packet headers. largest_pn is the largest PN successfully
526 * processed in the relevant PN space.
528 * The resulting PN is written to *res_pn.
530 * Returns 1 on success or 0 on failure.
532 int ossl_quic_wire_decode_pkt_hdr_pn(const unsigned char *enc_pn,
538 * Determine how many bytes should be used to encode a PN. Returns the number of
539 * bytes (which will be in range [1, 4]).
541 int ossl_quic_wire_determine_pn_len(QUIC_PN pn, QUIC_PN largest_acked);
544 * Encode a PN for a packet header using the specified number of bytes, which
545 * should have been determined by calling ossl_quic_wire_determine_pn_len. The
546 * PN encoding process is done in two parts to allow the caller to override PN
547 * encoding length if it wishes.
549 * Returns 1 on success and 0 on failure.
551 int ossl_quic_wire_encode_pkt_hdr_pn(QUIC_PN pn,
552 unsigned char *enc_pn,
556 * Retry Integrity Tags
557 * ====================
560 # define QUIC_RETRY_INTEGRITY_TAG_LEN 16
563 * Validate a retry integrity tag. Returns 1 if the tag is valid.
565 * Must be called on a hdr with a type of QUIC_PKT_TYPE_RETRY with a valid data
568 * client_initial_dcid must be the original DCID used by the client in its first
569 * Initial packet, as this is used to calculate the Retry Integrity Tag.
571 * Returns 0 if the tag is invalid, if called on any other type of packet or if
572 * the body is too short.
574 int ossl_quic_validate_retry_integrity_tag(OSSL_LIB_CTX *libctx,
576 const QUIC_PKT_HDR *hdr,
577 const QUIC_CONN_ID *client_initial_dcid);
580 * Calculates a retry integrity tag. Returns 0 on error, for example if hdr does
581 * not have a type of QUIC_PKT_TYPE_RETRY.
583 * client_initial_dcid must be the original DCID used by the client in its first
584 * Initial packet, as this is used to calculate the Retry Integrity Tag.
586 * tag must point to a buffer of QUIC_RETRY_INTEGRITY_TAG_LEN bytes in size.
588 * Note that hdr->data must point to the Retry packet body, and hdr->len must
589 * include the space for the Retry Integrity Tag. (This means that you can
590 * easily fill in a tag in a Retry packet you are generating by calling this
591 * function and passing (hdr->data + hdr->len - QUIC_RETRY_INTEGRITY_TAG_LEN) as
592 * the tag argument.) This function fails if hdr->len is too short to contain a
593 * Retry Integrity Tag.
595 int ossl_quic_calculate_retry_integrity_tag(OSSL_LIB_CTX *libctx,
597 const QUIC_PKT_HDR *hdr,
598 const QUIC_CONN_ID *client_initial_dcid,