quic_wire.h@ 108403

最後變更在這個檔案從108403是 108206,由 vboxsync 提交於 5 週前
openssl-3.3.2: Exported all files to OSE and removed .scm-settings bugref:10757
屬性 svn:eol-style 設為 `native` 屬性 svn:keywords 設為 `Author Date Id Revision`
檔案大小: 30.1 KB

行
1	/*
2	* Copyright 2022-2023 The OpenSSL Project Authors. All Rights Reserved.
3	*
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
8	*/
9
10	#ifndef OSSL_INTERNAL_QUIC_WIRE_H
11	# define OSSL_INTERNAL_QUIC_WIRE_H
12	# pragma once
13
14	# include "internal/e_os.h"
15	# include "internal/time.h"
16	# include "internal/quic_types.h"
17	# include "internal/packet_quic.h"
18
19	# ifndef OPENSSL_NO_QUIC
20
21	# define OSSL_QUIC_FRAME_TYPE_PADDING 0x00
22	# define OSSL_QUIC_FRAME_TYPE_PING 0x01
23	# define OSSL_QUIC_FRAME_TYPE_ACK_WITHOUT_ECN 0x02
24	# define OSSL_QUIC_FRAME_TYPE_ACK_WITH_ECN 0x03
25	# define OSSL_QUIC_FRAME_TYPE_RESET_STREAM 0x04
26	# define OSSL_QUIC_FRAME_TYPE_STOP_SENDING 0x05
27	# define OSSL_QUIC_FRAME_TYPE_CRYPTO 0x06
28	# define OSSL_QUIC_FRAME_TYPE_NEW_TOKEN 0x07
29	# define OSSL_QUIC_FRAME_TYPE_MAX_DATA 0x10
30	# define OSSL_QUIC_FRAME_TYPE_MAX_STREAM_DATA 0x11
31	# define OSSL_QUIC_FRAME_TYPE_MAX_STREAMS_BIDI 0x12
32	# define OSSL_QUIC_FRAME_TYPE_MAX_STREAMS_UNI 0x13
33	# define OSSL_QUIC_FRAME_TYPE_DATA_BLOCKED 0x14
34	# define OSSL_QUIC_FRAME_TYPE_STREAM_DATA_BLOCKED 0x15
35	# define OSSL_QUIC_FRAME_TYPE_STREAMS_BLOCKED_BIDI 0x16
36	# define OSSL_QUIC_FRAME_TYPE_STREAMS_BLOCKED_UNI 0x17
37	# define OSSL_QUIC_FRAME_TYPE_NEW_CONN_ID 0x18
38	# define OSSL_QUIC_FRAME_TYPE_RETIRE_CONN_ID 0x19
39	# define OSSL_QUIC_FRAME_TYPE_PATH_CHALLENGE 0x1A
40	# define OSSL_QUIC_FRAME_TYPE_PATH_RESPONSE 0x1B
41	# define OSSL_QUIC_FRAME_TYPE_CONN_CLOSE_TRANSPORT 0x1C
42	# define OSSL_QUIC_FRAME_TYPE_CONN_CLOSE_APP 0x1D
43	# define OSSL_QUIC_FRAME_TYPE_HANDSHAKE_DONE 0x1E
44
45	# define OSSL_QUIC_FRAME_FLAG_STREAM_FIN 0x01
46	# define OSSL_QUIC_FRAME_FLAG_STREAM_LEN 0x02
47	# define OSSL_QUIC_FRAME_FLAG_STREAM_OFF 0x04
48	# define OSSL_QUIC_FRAME_FLAG_STREAM_MASK ((uint64_t)0x07)
49
50	/* Low 3 bits of the type contain flags */
51	# define OSSL_QUIC_FRAME_TYPE_STREAM 0x08 /* base ID */
52	# define OSSL_QUIC_FRAME_TYPE_STREAM_FIN \
53	(OSSL_QUIC_FRAME_TYPE_STREAM \| \
54	OSSL_QUIC_FRAME_FLAG_STREAM_FIN)
55	# define OSSL_QUIC_FRAME_TYPE_STREAM_LEN \
56	(OSSL_QUIC_FRAME_TYPE_STREAM \| \
57	OSSL_QUIC_FRAME_FLAG_STREAM_LEN)
58	# define OSSL_QUIC_FRAME_TYPE_STREAM_LEN_FIN \
59	(OSSL_QUIC_FRAME_TYPE_STREAM \| \
60	OSSL_QUIC_FRAME_FLAG_STREAM_LEN \| \
61	OSSL_QUIC_FRAME_FLAG_STREAM_FIN)
62	# define OSSL_QUIC_FRAME_TYPE_STREAM_OFF \
63	(OSSL_QUIC_FRAME_TYPE_STREAM \| \
64	OSSL_QUIC_FRAME_FLAG_STREAM_OFF)
65	# define OSSL_QUIC_FRAME_TYPE_STREAM_OFF_FIN \
66	(OSSL_QUIC_FRAME_TYPE_STREAM \| \
67	OSSL_QUIC_FRAME_FLAG_STREAM_OFF \| \
68	OSSL_QUIC_FRAME_FLAG_STREAM_FIN)
69	# define OSSL_QUIC_FRAME_TYPE_STREAM_OFF_LEN \
70	(OSSL_QUIC_FRAME_TYPE_STREAM \| \
71	OSSL_QUIC_FRAME_FLAG_STREAM_OFF \| \
72	OSSL_QUIC_FRAME_FLAG_STREAM_LEN)
73	# define OSSL_QUIC_FRAME_TYPE_STREAM_OFF_LEN_FIN \
74	(OSSL_QUIC_FRAME_TYPE_STREAM \| \
75	OSSL_QUIC_FRAME_FLAG_STREAM_OFF \| \
76	OSSL_QUIC_FRAME_FLAG_STREAM_LEN \| \
77	OSSL_QUIC_FRAME_FLAG_STREAM_FIN)
78
79	# define OSSL_QUIC_FRAME_TYPE_IS_STREAM(x) \
80	(((x) & ~OSSL_QUIC_FRAME_FLAG_STREAM_MASK) == OSSL_QUIC_FRAME_TYPE_STREAM)
81	# define OSSL_QUIC_FRAME_TYPE_IS_ACK(x) \
82	(((x) & ~(uint64_t)1) == OSSL_QUIC_FRAME_TYPE_ACK_WITHOUT_ECN)
83	# define OSSL_QUIC_FRAME_TYPE_IS_MAX_STREAMS(x) \
84	(((x) & ~(uint64_t)1) == OSSL_QUIC_FRAME_TYPE_MAX_STREAMS_BIDI)
85	# define OSSL_QUIC_FRAME_TYPE_IS_STREAMS_BLOCKED(x) \
86	(((x) & ~(uint64_t)1) == OSSL_QUIC_FRAME_TYPE_STREAMS_BLOCKED_BIDI)
87	# define OSSL_QUIC_FRAME_TYPE_IS_CONN_CLOSE(x) \
88	(((x) & ~(uint64_t)1) == OSSL_QUIC_FRAME_TYPE_CONN_CLOSE_TRANSPORT)
89
90	const char *ossl_quic_frame_type_to_string(uint64_t frame_type);
91
92	static ossl_unused ossl_inline int
93	ossl_quic_frame_type_is_ack_eliciting(uint64_t frame_type)
94	{
95	switch (frame_type) {
96	case OSSL_QUIC_FRAME_TYPE_PADDING:
97	case OSSL_QUIC_FRAME_TYPE_ACK_WITHOUT_ECN:
98	case OSSL_QUIC_FRAME_TYPE_ACK_WITH_ECN:
99	case OSSL_QUIC_FRAME_TYPE_CONN_CLOSE_TRANSPORT:
100	case OSSL_QUIC_FRAME_TYPE_CONN_CLOSE_APP:
101	return 0;
102	default:
103	return 1;
104	}
105	}
106
107	/* QUIC Transport Parameter Types */
108	# define QUIC_TPARAM_ORIG_DCID 0x00
109	# define QUIC_TPARAM_MAX_IDLE_TIMEOUT 0x01
110	# define QUIC_TPARAM_STATELESS_RESET_TOKEN 0x02
111	# define QUIC_TPARAM_MAX_UDP_PAYLOAD_SIZE 0x03
112	# define QUIC_TPARAM_INITIAL_MAX_DATA 0x04
113	# define QUIC_TPARAM_INITIAL_MAX_STREAM_DATA_BIDI_LOCAL 0x05
114	# define QUIC_TPARAM_INITIAL_MAX_STREAM_DATA_BIDI_REMOTE 0x06
115	# define QUIC_TPARAM_INITIAL_MAX_STREAM_DATA_UNI 0x07
116	# define QUIC_TPARAM_INITIAL_MAX_STREAMS_BIDI 0x08
117	# define QUIC_TPARAM_INITIAL_MAX_STREAMS_UNI 0x09
118	# define QUIC_TPARAM_ACK_DELAY_EXP 0x0A
119	# define QUIC_TPARAM_MAX_ACK_DELAY 0x0B
120	# define QUIC_TPARAM_DISABLE_ACTIVE_MIGRATION 0x0C
121	# define QUIC_TPARAM_PREFERRED_ADDR 0x0D
122	# define QUIC_TPARAM_ACTIVE_CONN_ID_LIMIT 0x0E
123	# define QUIC_TPARAM_INITIAL_SCID 0x0F
124	# define QUIC_TPARAM_RETRY_SCID 0x10
125
126	/*
127	* QUIC Frame Logical Representations
128	* ==================================
129	*/
130
131	/* QUIC Frame: ACK */
132	typedef struct ossl_quic_ack_range_st {
133	/*
134	* Represents an inclusive range of packet numbers [start, end].
135	* start must be <= end.
136	*/
137	QUIC_PN start, end;
138	} OSSL_QUIC_ACK_RANGE;
139
140	typedef struct ossl_quic_frame_ack_st {
141	/*
142	* A sequence of packet number ranges [[start, end]...].
143	*
144	* The ranges must be sorted in descending order, for example:
145	* [ 95, 100]
146	* [ 90, 92]
147	* etc.
148	*
149	* As such, ack_ranges[0].end is always the highest packet number
150	* being acknowledged and ack_ranges[num_ack_ranges-1].start is
151	* always the lowest packet number being acknowledged.
152	*
153	* num_ack_ranges must be greater than zero, as an ACK frame must
154	* acknowledge at least one packet number.
155	*/
156	OSSL_QUIC_ACK_RANGE *ack_ranges;
157	size_t num_ack_ranges;
158
159	OSSL_TIME delay_time;
160	uint64_t ect0, ect1, ecnce;
161	unsigned int ecn_present : 1;
162	} OSSL_QUIC_FRAME_ACK;
163
164	/* Returns 1 if the given frame contains the given PN. */
165	int ossl_quic_frame_ack_contains_pn(const OSSL_QUIC_FRAME_ACK *ack, QUIC_PN pn);
166
167	/* QUIC Frame: STREAM */
168	typedef struct ossl_quic_frame_stream_st {
169	uint64_t stream_id; /* Stream ID */
170	uint64_t offset; /* Logical offset in stream */
171	uint64_t len; /* Length of data in bytes */
172	const unsigned char *data;
173
174	/*
175	* On encode, this determines whether the len field should be encoded or
176	* not. If zero, the len field is not encoded and it is assumed the frame
177	* runs to the end of the packet.
178	*
179	* On decode, this determines whether the frame had an explicitly encoded
180	* length. If not set, the frame runs to the end of the packet and len has
181	* been set accordingly.
182	*/
183	unsigned int has_explicit_len : 1;
184
185	/* 1 if this is the end of the stream */
186	unsigned int is_fin : 1;
187	} OSSL_QUIC_FRAME_STREAM;
188
189	/* QUIC Frame: CRYPTO */
190	typedef struct ossl_quic_frame_crypto_st {
191	uint64_t offset; /* Logical offset in stream */
192	uint64_t len; /* Length of the data in bytes */
193	const unsigned char *data;
194	} OSSL_QUIC_FRAME_CRYPTO;
195
196	/* QUIC Frame: RESET_STREAM */
197	typedef struct ossl_quic_frame_reset_stream_st {
198	uint64_t stream_id;
199	uint64_t app_error_code;
200	uint64_t final_size;
201	} OSSL_QUIC_FRAME_RESET_STREAM;
202
203	/* QUIC Frame: STOP_SENDING */
204	typedef struct ossl_quic_frame_stop_sending_st {
205	uint64_t stream_id;
206	uint64_t app_error_code;
207	} OSSL_QUIC_FRAME_STOP_SENDING;
208
209	/* QUIC Frame: NEW_CONNECTION_ID */
210	typedef struct ossl_quic_frame_new_conn_id_st {
211	uint64_t seq_num;
212	uint64_t retire_prior_to;
213	QUIC_CONN_ID conn_id;
214	QUIC_STATELESS_RESET_TOKEN stateless_reset;
215	} OSSL_QUIC_FRAME_NEW_CONN_ID;
216
217	/* QUIC Frame: CONNECTION_CLOSE */
218	typedef struct ossl_quic_frame_conn_close_st {
219	unsigned int is_app : 1; /* 0: transport error, 1: app error */
220	uint64_t error_code; /* 62-bit transport or app error code */
221	uint64_t frame_type; /* transport errors only */
222	char reason; / UTF-8 string, not necessarily zero-terminated */
223	size_t reason_len; /* Length of reason in bytes */
224	} OSSL_QUIC_FRAME_CONN_CLOSE;
225
226	/*
227	* QUIC Wire Format Encoding
228	* =========================
229	*
230	* These functions return 1 on success and 0 on failure.
231	*/
232
233	/*
234	* Encodes zero or more QUIC PADDING frames to the packet writer. Each PADDING
235	* frame consumes one byte; num_bytes specifies the number of bytes of padding
236	* to write.
237	*/
238	int ossl_quic_wire_encode_padding(WPACKET *pkt, size_t num_bytes);
239
240	/*
241	* Encodes a QUIC PING frame to the packet writer. This frame type takes
242	* no arguments.
243	*/
244	int ossl_quic_wire_encode_frame_ping(WPACKET *pkt);
245
246	/*
247	* Encodes a QUIC ACK frame to the packet writer, given a logical representation
248	* of the ACK frame.
249	*
250	* The ACK ranges passed must be sorted in descending order.
251	*
252	* The logical representation stores a list of packet number ranges. The wire
253	* encoding is slightly different and stores the first range in the list
254	* in a different manner.
255	*
256	* The ack_delay_exponent argument specifies the index of a power of two by
257	* which the ack->ack_delay field is be divided. This exponent value must match
258	* the value used when decoding.
259	*/
260	int ossl_quic_wire_encode_frame_ack(WPACKET *pkt,
261	uint32_t ack_delay_exponent,
262	const OSSL_QUIC_FRAME_ACK *ack);
263
264	/*
265	* Encodes a QUIC RESET_STREAM frame to the packet writer, given a logical
266	* representation of the RESET_STREAM frame.
267	*/
268	int ossl_quic_wire_encode_frame_reset_stream(WPACKET *pkt,
269	const OSSL_QUIC_FRAME_RESET_STREAM *f);
270
271	/*
272	* Encodes a QUIC STOP_SENDING frame to the packet writer, given a logical
273	* representation of the STOP_SENDING frame.
274	*/
275	int ossl_quic_wire_encode_frame_stop_sending(WPACKET *pkt,
276	const OSSL_QUIC_FRAME_STOP_SENDING *f);
277
278	/*
279	* Encodes a QUIC CRYPTO frame header to the packet writer.
280	*
281	* To create a well-formed frame, the data written using this function must be
282	* immediately followed by f->len bytes of data.
283	*/
284	int ossl_quic_wire_encode_frame_crypto_hdr(WPACKET *hdr,
285	const OSSL_QUIC_FRAME_CRYPTO *f);
286
287	/*
288	* Returns the number of bytes which will be required to encode the given
289	* CRYPTO frame header. Does not include the payload bytes in the count.
290	* Returns 0 if input is invalid.
291	*/
292	size_t ossl_quic_wire_get_encoded_frame_len_crypto_hdr(const OSSL_QUIC_FRAME_CRYPTO *f);
293
294	/*
295	* Encodes a QUIC CRYPTO frame to the packet writer.
296	*
297	* This function returns a pointer to a buffer of f->len bytes which the caller
298	* should fill however it wishes. If f->data is non-NULL, it is automatically
299	* copied to the target buffer, otherwise the caller must fill the returned
300	* buffer. Returns NULL on failure.
301	*/
302	void ossl_quic_wire_encode_frame_crypto(WPACKET pkt,
303	const OSSL_QUIC_FRAME_CRYPTO *f);
304
305	/*
306	* Encodes a QUIC NEW_TOKEN frame to the packet writer.
307	*/
308	int ossl_quic_wire_encode_frame_new_token(WPACKET *pkt,
309	const unsigned char *token,
310	size_t token_len);
311
312	/*
313	* Encodes a QUIC STREAM frame's header to the packet writer. The f->stream_id,
314	* f->offset and f->len fields are the values for the respective Stream ID,
315	* Offset and Length fields.
316	*
317	* If f->is_fin is non-zero, the frame is marked as the final frame in the
318	* stream.
319	*
320	* If f->has_explicit_len is zerro, the frame is assumed to be the final frame
321	* in the packet, which the caller is responsible for ensuring; the Length
322	* field is then omitted.
323	*
324	* To create a well-formed frame, the data written using this function must be
325	* immediately followed by f->len bytes of stream data.
326	*/
327	int ossl_quic_wire_encode_frame_stream_hdr(WPACKET *pkt,
328	const OSSL_QUIC_FRAME_STREAM *f);
329
330	/*
331	* Returns the number of bytes which will be required to encode the given
332	* STREAM frame header. Does not include the payload bytes in the count.
333	* Returns 0 if input is invalid.
334	*/
335	size_t ossl_quic_wire_get_encoded_frame_len_stream_hdr(const OSSL_QUIC_FRAME_STREAM *f);
336
337	/*
338	* Functions similarly to ossl_quic_wire_encode_frame_stream_hdr, but it also
339	* allocates space for f->len bytes of data after the header, creating a
340	* well-formed QUIC STREAM frame in one call.
341	*
342	* A pointer to the bytes allocated for the framme payload is returned,
343	* which the caller can fill however it wishes. If f->data is non-NULL,
344	* it is automatically copied to the target buffer, otherwise the caller
345	* must fill the returned buffer. Returns NULL on failure.
346	*/
347	void ossl_quic_wire_encode_frame_stream(WPACKET pkt,
348	const OSSL_QUIC_FRAME_STREAM *f);
349
350	/*
351	* Encodes a QUIC MAX_DATA frame to the packet writer.
352	*/
353	int ossl_quic_wire_encode_frame_max_data(WPACKET *pkt,
354	uint64_t max_data);
355
356	/*
357	* Encodes a QUIC MAX_STREAM_DATA frame to the packet writer.
358	*/
359	int ossl_quic_wire_encode_frame_max_stream_data(WPACKET *pkt,
360	uint64_t stream_id,
361	uint64_t max_data);
362
363	/*
364	* Encodes a QUIC MAX_STREAMS frame to the packet writer.
365	*
366	* If is_uni is 0, the count specifies the maximum number of
367	* bidirectional streams; else it specifies the maximum number of unidirectional
368	* streams.
369	*/
370	int ossl_quic_wire_encode_frame_max_streams(WPACKET *pkt,
371	char is_uni,
372	uint64_t max_streams);
373
374	/*
375	* Encodes a QUIC DATA_BLOCKED frame to the packet writer.
376	*/
377	int ossl_quic_wire_encode_frame_data_blocked(WPACKET *pkt,
378	uint64_t max_data);
379
380	/*
381	* Encodes a QUIC STREAM_DATA_BLOCKED frame to the packet writer.
382	*/
383	int ossl_quic_wire_encode_frame_stream_data_blocked(WPACKET *pkt,
384	uint64_t stream_id,
385	uint64_t max_stream_data);
386	/*
387	* Encodes a QUIC STREAMS_BLOCKED frame to the packet writer.
388	*
389	* If is_uni is 0, the count specifies the maximum number of
390	* bidirectional streams; else it specifies the maximum number of unidirectional
391	* streams.
392	*/
393	int ossl_quic_wire_encode_frame_streams_blocked(WPACKET *pkt,
394	char is_uni,
395	uint64_t max_streams);
396
397	/*
398	* Encodes a QUIC NEW_CONNECTION_ID frame to the packet writer, given a logical
399	* representation of the NEW_CONNECTION_ID frame.
400	*
401	* The buffer pointed to by the conn_id field must be valid for the duration of
402	* the call.
403	*/
404	int ossl_quic_wire_encode_frame_new_conn_id(WPACKET *pkt,
405	const OSSL_QUIC_FRAME_NEW_CONN_ID *f);
406
407	/*
408	* Encodes a QUIC RETIRE_CONNECTION_ID frame to the packet writer.
409	*/
410	int ossl_quic_wire_encode_frame_retire_conn_id(WPACKET *pkt,
411	uint64_t seq_num);
412
413	/*
414	* Encodes a QUIC PATH_CHALLENGE frame to the packet writer.
415	*/
416	int ossl_quic_wire_encode_frame_path_challenge(WPACKET *pkt,
417	uint64_t data);
418
419	/*
420	* Encodes a QUIC PATH_RESPONSE frame to the packet writer.
421	*/
422	int ossl_quic_wire_encode_frame_path_response(WPACKET *pkt,
423	uint64_t data);
424
425	/*
426	* Encodes a QUIC CONNECTION_CLOSE frame to the packet writer, given a logical
427	* representation of the CONNECTION_CLOSE frame.
428	*
429	* The reason field may be NULL, in which case no reason is encoded. If the
430	* reason field is non-NULL, it must point to a valid UTF-8 string and
431	* reason_len must be set to the length of the reason string in bytes. The
432	* reason string need not be zero terminated.
433	*/
434	int ossl_quic_wire_encode_frame_conn_close(WPACKET *pkt,
435	const OSSL_QUIC_FRAME_CONN_CLOSE *f);
436
437	/*
438	* Encodes a QUIC HANDSHAKE_DONE frame to the packet writer. This frame type
439	* takes no arguiments.
440	*/
441	int ossl_quic_wire_encode_frame_handshake_done(WPACKET *pkt);
442
443	/*
444	* Encodes a QUIC transport parameter TLV with the given ID into the WPACKET.
445	* The payload is an arbitrary buffer.
446	*
447	* If value is non-NULL, the value is copied into the packet.
448	* If it is NULL, value_len bytes are allocated for the payload and the caller
449	* should fill the buffer using the returned pointer.
450	*
451	* Returns a pointer to the start of the payload on success, or NULL on failure.
452	*/
453	unsigned char ossl_quic_wire_encode_transport_param_bytes(WPACKET pkt,
454	uint64_t id,
455	const unsigned char *value,
456	size_t value_len);
457
458	/*
459	* Encodes a QUIC transport parameter TLV with the given ID into the WPACKET.
460	* The payload is a QUIC variable-length integer with the given value.
461	*/
462	int ossl_quic_wire_encode_transport_param_int(WPACKET *pkt,
463	uint64_t id,
464	uint64_t value);
465
466	/*
467	* Encodes a QUIC transport parameter TLV with a given ID into the WPACKET.
468	* The payload is a QUIC connection ID.
469	*/
470	int ossl_quic_wire_encode_transport_param_cid(WPACKET *wpkt,
471	uint64_t id,
472	const QUIC_CONN_ID *cid);
473
474	/*
475	* QUIC Wire Format Decoding
476	* =========================
477	*
478	* These functions return 1 on success or 0 for failure. Typical reasons
479	* why these functions may fail include:
480	*
481	* - A frame decode function is called but the frame in the PACKET's buffer
482	* is not of the correct type.
483	*
484	* - A variable-length field in the encoded frame appears to exceed the bounds
485	* of the PACKET's buffer.
486	*
487	* These functions should be called with the PACKET pointing to the start of the
488	* frame (including the initial type field), and consume an entire frame
489	* including its type field. The expectation is that the caller will have
490	* already discerned the frame type using ossl_quic_wire_peek_frame_header().
491	*/
492
493	/*
494	* Decodes the type field header of a QUIC frame (without advancing the current
495	* position). This can be used to determine the frame type and determine which
496	* frame decoding function to call.
497	*/
498	int ossl_quic_wire_peek_frame_header(PACKET pkt, uint64_t type,
499	int *was_minimal);
500
501	/*
502	* Like ossl_quic_wire_peek_frame_header, but advances the current position
503	* so that the type field is consumed. For advanced use only.
504	*/
505	int ossl_quic_wire_skip_frame_header(PACKET pkt, uint64_t type);
506
507	/*
508	* Determines how many ranges are needed to decode a QUIC ACK frame.
509	*
510	* The number of ranges which must be allocated before the call to
511	* ossl_quic_wire_decode_frame_ack is written to *total_ranges.
512	*
513	* The PACKET is not advanced.
514	*/
515	int ossl_quic_wire_peek_frame_ack_num_ranges(const PACKET *pkt,
516	uint64_t *total_ranges);
517
518	/*
519	* Decodes a QUIC ACK frame. The ack_ranges field of the passed structure should
520	* point to a preallocated array of ACK ranges and the num_ack_ranges field
521	* should specify the length of allocation.
522	*
523	* *total_ranges is written with the number of ranges in the decoded frame,
524	* which may be greater than the number of ranges which were decoded (i.e. if
525	* num_ack_ranges was too small to decode all ranges).
526	*
527	* On success, this function modifies the num_ack_ranges field to indicate the
528	* number of ranges in the decoded frame. This is the number of entries in the
529	* ACK ranges array written by this function; any additional entries are not
530	* modified.
531	*
532	* If the number of ACK ranges in the decoded frame exceeds that in
533	* num_ack_ranges, as many ACK ranges as possible are decoded into the range
534	* array. The caller can use the value written to *total_ranges to detect this
535	* condition, as *total_ranges will exceed num_ack_ranges.
536	*
537	* If ack is NULL, the frame is still decoded, but only *total_ranges is
538	* written. This can be used to determine the number of ranges which must be
539	* allocated.
540	*
541	* The ack_delay_exponent argument specifies the index of a power of two used to
542	* decode the ack_delay field. This must match the ack_delay_exponent value used
543	* to encode the frame.
544	*/
545	int ossl_quic_wire_decode_frame_ack(PACKET *pkt,
546	uint32_t ack_delay_exponent,
547	OSSL_QUIC_FRAME_ACK *ack,
548	uint64_t *total_ranges);
549
550	/*
551	* Decodes a QUIC RESET_STREAM frame.
552	*/
553	int ossl_quic_wire_decode_frame_reset_stream(PACKET *pkt,
554	OSSL_QUIC_FRAME_RESET_STREAM *f);
555
556	/*
557	* Decodes a QUIC STOP_SENDING frame.
558	*/
559	int ossl_quic_wire_decode_frame_stop_sending(PACKET *pkt,
560	OSSL_QUIC_FRAME_STOP_SENDING *f);
561
562	/*
563	* Decodes a QUIC CRYPTO frame.
564	*
565	* f->data is set to point inside the packet buffer inside the PACKET, therefore
566	* it is safe to access for as long as the packet buffer exists. If nodata is
567	* set to 1 then reading the PACKET stops after the frame header and f->data is
568	* set to NULL.
569	*/
570	int ossl_quic_wire_decode_frame_crypto(PACKET *pkt, int nodata,
571	OSSL_QUIC_FRAME_CRYPTO *f);
572
573	/*
574	* Decodes a QUIC NEW_TOKEN frame. *token is written with a pointer to the token
575	* bytes and *token_len is written with the length of the token in bytes.
576	*/
577	int ossl_quic_wire_decode_frame_new_token(PACKET *pkt,
578	const unsigned char **token,
579	size_t *token_len);
580
581	/*
582	* Decodes a QUIC STREAM frame.
583	*
584	* If nodata is set to 1 then reading the PACKET stops after the frame header
585	* and f->data is set to NULL. In this case f->len will also be 0 in the event
586	* that "has_explicit_len" is 0.
587	*
588	* If the frame did not contain an offset field, f->offset is set to 0, as the
589	* absence of an offset field is equivalent to an offset of 0.
590	*
591	* If the frame contained a length field, f->has_explicit_len is set to 1 and
592	* the length of the data is placed in f->len. This function ensures that the
593	* length does not exceed the packet buffer, thus it is safe to access f->data.
594	*
595	* If the frame did not contain a length field, this means that the frame runs
596	* until the end of the packet. This function sets f->has_explicit_len to zero,
597	* and f->len to the amount of data remaining in the input buffer. Therefore,
598	* this function should be used with a PACKET representing a single packet (and
599	* not e.g. multiple packets).
600	*
601	* Note also that this means f->len is always valid after this function returns
602	* successfully, regardless of the value of f->has_explicit_len.
603	*
604	* f->data points inside the packet buffer inside the PACKET, therefore it is
605	* safe to access for as long as the packet buffer exists.
606	*
607	* f->is_fin is set according to whether the frame was marked as ending the
608	* stream.
609	*/
610	int ossl_quic_wire_decode_frame_stream(PACKET *pkt, int nodata,
611	OSSL_QUIC_FRAME_STREAM *f);
612
613	/*
614	* Decodes a QUIC MAX_DATA frame. The Maximum Data field is written to
615	* *max_data.
616	*/
617	int ossl_quic_wire_decode_frame_max_data(PACKET *pkt,
618	uint64_t *max_data);
619
620	/*
621	* Decodes a QUIC MAX_STREAM_DATA frame. The Stream ID is written to *stream_id
622	* and Maximum Stream Data field is written to *max_stream_data.
623	*/
624	int ossl_quic_wire_decode_frame_max_stream_data(PACKET *pkt,
625	uint64_t *stream_id,
626	uint64_t *max_stream_data);
627	/*
628	* Decodes a QUIC MAX_STREAMS frame. The Maximum Streams field is written to
629	* *max_streams.
630	*
631	* Whether the limit concerns bidirectional streams or unidirectional streams is
632	* denoted by the frame type; the caller should examine the frame type to
633	* determine this.
634	*/
635	int ossl_quic_wire_decode_frame_max_streams(PACKET *pkt,
636	uint64_t *max_streams);
637
638	/*
639	* Decodes a QUIC DATA_BLOCKED frame. The Maximum Data field is written to
640	* *max_data.
641	*/
642	int ossl_quic_wire_decode_frame_data_blocked(PACKET *pkt,
643	uint64_t *max_data);
644
645	/*
646	* Decodes a QUIC STREAM_DATA_BLOCKED frame. The Stream ID and Maximum Stream
647	* Data fields are written to stream_id and max_stream_data respectively.
648	*/
649	int ossl_quic_wire_decode_frame_stream_data_blocked(PACKET *pkt,
650	uint64_t *stream_id,
651	uint64_t *max_stream_data);
652
653	/*
654	* Decodes a QUIC STREAMS_BLOCKED frame. The Maximum Streams field is written to
655	* *max_streams.
656	*
657	* Whether the limit concerns bidirectional streams or unidirectional streams is
658	* denoted by the frame type; the caller should examine the frame type to
659	* determine this.
660	*/
661	int ossl_quic_wire_decode_frame_streams_blocked(PACKET *pkt,
662	uint64_t *max_streams);
663
664
665	/*
666	* Decodes a QUIC NEW_CONNECTION_ID frame. The logical representation of the
667	* frame is written to *f.
668	*
669	* The conn_id field is set to point to the connection ID string inside the
670	* packet buffer; it is therefore valid for as long as the PACKET's buffer is
671	* valid. The conn_id_len field is set to the length of the connection ID string
672	* in bytes.
673	*/
674	int ossl_quic_wire_decode_frame_new_conn_id(PACKET *pkt,
675	OSSL_QUIC_FRAME_NEW_CONN_ID *f);
676
677	/*
678	* Decodes a QUIC RETIRE_CONNECTION_ID frame. The Sequence Number field
679	* is written to *seq_num.
680	*/
681	int ossl_quic_wire_decode_frame_retire_conn_id(PACKET *pkt,
682	uint64_t *seq_num);
683
684	/*
685	* Decodes a QUIC PATH_CHALLENGE frame. The Data field is written to *data.
686	*/
687	int ossl_quic_wire_decode_frame_path_challenge(PACKET *pkt,
688	uint64_t *data);
689
690	/*
691	* Decodes a QUIC PATH_CHALLENGE frame. The Data field is written to *data.
692	*/
693	int ossl_quic_wire_decode_frame_path_response(PACKET *pkt,
694	uint64_t *data);
695
696	/*
697	* Decodes a QUIC CONNECTION_CLOSE frame. The logical representation
698	* of the frame is written to *f.
699	*
700	* The reason field is set to point to the UTF-8 reason string inside
701	* the packet buffer; it is therefore valid for as long as the PACKET's
702	* buffer is valid. The reason_len field is set to the length of the
703	* reason string in bytes.
704	*
705	* IMPORTANT: The reason string is not zero-terminated.
706	*
707	* Returns 1 on success or 0 on failure.
708	*/
709	int ossl_quic_wire_decode_frame_conn_close(PACKET *pkt,
710	OSSL_QUIC_FRAME_CONN_CLOSE *f);
711
712	/*
713	* Decodes one or more PADDING frames. PADDING frames have no arguments.
714	*
715	* Returns the number of PADDING frames decoded or 0 on error.
716	*/
717	size_t ossl_quic_wire_decode_padding(PACKET *pkt);
718
719	/*
720	* Decodes a PING frame. The frame has no arguments.
721	*/
722	int ossl_quic_wire_decode_frame_ping(PACKET *pkt);
723
724	/*
725	* Decodes a HANDSHAKE_DONE frame. The frame has no arguments.
726	*/
727	int ossl_quic_wire_decode_frame_handshake_done(PACKET *pkt);
728
729	/*
730	* Peeks at the ID of the next QUIC transport parameter TLV in the stream.
731	* The ID is written to *id.
732	*/
733	int ossl_quic_wire_peek_transport_param(PACKET pkt, uint64_t id);
734
735	/*
736	* Decodes a QUIC transport parameter TLV. A pointer to the value buffer is
737	* returned on success. This points inside the PACKET's buffer and is therefore
738	* valid as long as the PACKET's buffer is valid.
739	*
740	* The transport parameter ID is written to *id (if non-NULL) and the length of
741	* the payload in bytes is written to *len.
742	*
743	* Returns NULL on failure.
744	*/
745	const unsigned char ossl_quic_wire_decode_transport_param_bytes(PACKET pkt,
746	uint64_t *id,
747	size_t *len);
748
749	/*
750	* Decodes a QUIC transport parameter TLV containing a variable-length integer.
751	*
752	* The transport parameter ID is written to *id (if non-NULL) and the value is
753	* written to *value.
754	*/
755	int ossl_quic_wire_decode_transport_param_int(PACKET *pkt,
756	uint64_t *id,
757	uint64_t *value);
758
759	/*
760	* Decodes a QUIC transport parameter TLV containing a connection ID.
761	*
762	* The transport parameter ID is written to *id (if non-NULL) and the value is
763	* written to *value.
764	*/
765	int ossl_quic_wire_decode_transport_param_cid(PACKET *pkt,
766	uint64_t *id,
767	QUIC_CONN_ID *cid);
768
769	/*
770	* Decodes a QUIC transport parameter TLV containing a preferred_address.
771	*/
772	typedef struct quic_preferred_addr_st {
773	uint16_t ipv4_port, ipv6_port;
774	unsigned char ipv4[4], ipv6[16];
775	QUIC_STATELESS_RESET_TOKEN stateless_reset;
776	QUIC_CONN_ID cid;
777	} QUIC_PREFERRED_ADDR;
778
779	int ossl_quic_wire_decode_transport_param_preferred_addr(PACKET *pkt,
780	QUIC_PREFERRED_ADDR *p);
781
782	# endif
783
784	#endif

注意: 瀏覽 TracBrowser 來幫助您使用儲存庫瀏覽器

source: vbox/trunk/src/libs/openssl-3.3.2/include/internal/quic_wire.h@ 108403

以其他格式下載: