%% Copyright (c) 2023-2024, Loïc Hoguin %% %% Permission to use, copy, modify, and/or distribute this software for any %% purpose with or without fee is hereby granted, provided that the above %% copyright notice and this permission notice appear in all copies. %% %% THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES %% WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF %% MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR %% ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES %% WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN %% ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF %% OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. -module(cow_http3). %% Parsing. -export([parse/1]). -export([parse_unidi_stream_header/1]). -export([code_to_error/1]). %% Building. -export([data/1]). -export([headers/1]). -export([settings/1]). -export([error_to_code/1]). -export([encode_int/1]). -type stream_id() :: non_neg_integer(). -export_type([stream_id/0]). -type push_id() :: non_neg_integer(). -export_type([push_id/0]). -type settings() :: #{ qpack_max_table_capacity => 0..16#3fffffffffffffff, max_field_section_size => 0..16#3fffffffffffffff, qpack_blocked_streams => 0..16#3fffffffffffffff, enable_connect_protocol => boolean() }. -export_type([settings/0]). -type error() :: h3_no_error | h3_general_protocol_error | h3_internal_error | h3_stream_creation_error | h3_closed_critical_stream | h3_frame_unexpected | h3_frame_error | h3_excessive_load | h3_id_error | h3_settings_error | h3_missing_settings | h3_request_rejected | h3_request_cancelled | h3_request_incomplete | h3_message_error | h3_connect_error | h3_version_fallback. -export_type([error/0]). -type frame() :: {data, binary()} | {headers, binary()} | {cancel_push, push_id()} | {settings, settings()} | {push_promise, push_id(), binary()} | {goaway, stream_id() | push_id()} | {max_push_id, push_id()}. -export_type([frame/0]). %% Parsing. -spec parse(binary()) -> {ok, frame(), binary()} | {more, {data, binary()} | ignore, non_neg_integer()} | {ignore, binary()} | {connection_error, h3_frame_error | h3_frame_unexpected | h3_settings_error, atom()} | more. %% %% DATA frames. %% parse(<<0, 0:2, Len:6, Data:Len/binary, Rest/bits>>) -> {ok, {data, Data}, Rest}; parse(<<0, 1:2, Len:14, Data:Len/binary, Rest/bits>>) -> {ok, {data, Data}, Rest}; parse(<<0, 2:2, Len:30, Data:Len/binary, Rest/bits>>) -> {ok, {data, Data}, Rest}; parse(<<0, 3:2, Len:62, Data:Len/binary, Rest/bits>>) -> {ok, {data, Data}, Rest}; %% DATA frames may be split over multiple QUIC packets %% but we want to process them immediately rather than %% risk buffering a very large payload. parse(<<0, 0:2, Len:6, Data/bits>>) when byte_size(Data) < Len -> {more, {data, Data}, Len - byte_size(Data)}; parse(<<0, 1:2, Len:14, Data/bits>>) when byte_size(Data) < Len -> {more, {data, Data}, Len - byte_size(Data)}; parse(<<0, 2:2, Len:30, Data/bits>>) when byte_size(Data) < Len -> {more, {data, Data}, Len - byte_size(Data)}; parse(<<0, 3:2, Len:62, Data/bits>>) when byte_size(Data) < Len -> {more, {data, Data}, Len - byte_size(Data)}; %% %% HEADERS frames. %% parse(<<1, 0:2, 0:6, _/bits>>) -> {connection_error, h3_frame_error, 'HEADERS frames payload CANNOT be 0 bytes wide. (RFC9114 7.1, RFC9114 7.2.2)'}; parse(<<1, 1:2, 0:14, _/bits>>) -> {connection_error, h3_frame_error, 'HEADERS frames payload CANNOT be 0 bytes wide. (RFC9114 7.1, RFC9114 7.2.2)'}; parse(<<1, 2:2, 0:30, _/bits>>) -> {connection_error, h3_frame_error, 'HEADERS frames payload CANNOT be 0 bytes wide. (RFC9114 7.1, RFC9114 7.2.2)'}; parse(<<1, 3:2, 0:62, _/bits>>) -> {connection_error, h3_frame_error, 'HEADERS frames payload CANNOT be 0 bytes wide. (RFC9114 7.1, RFC9114 7.2.2)'}; parse(<<1, 0:2, Len:6, EncodedFieldSection:Len/binary, Rest/bits>>) -> {ok, {headers, EncodedFieldSection}, Rest}; parse(<<1, 1:2, Len:14, EncodedFieldSection:Len/binary, Rest/bits>>) -> {ok, {headers, EncodedFieldSection}, Rest}; parse(<<1, 2:2, Len:30, EncodedFieldSection:Len/binary, Rest/bits>>) -> {ok, {headers, EncodedFieldSection}, Rest}; parse(<<1, 3:2, Len:62, EncodedFieldSection:Len/binary, Rest/bits>>) -> {ok, {headers, EncodedFieldSection}, Rest}; %% %% CANCEL_PUSH frames. %% parse(<<3, 0:2, 1:6, 0:2, PushID:6, Rest/bits>>) -> {ok, {cancel_push, PushID}, Rest}; parse(<<3, 0:2, 2:6, 1:2, PushID:14, Rest/bits>>) -> {ok, {cancel_push, PushID}, Rest}; parse(<<3, 0:2, 4:6, 2:2, PushID:30, Rest/bits>>) -> {ok, {cancel_push, PushID}, Rest}; parse(<<3, 0:2, 8:6, 3:2, PushID:62, Rest/bits>>) -> {ok, {cancel_push, PushID}, Rest}; parse(<<3, _/bits>>) -> {connection_error, h3_frame_error, 'CANCEL_PUSH frames payload MUST be 1, 2, 4 or 8 bytes wide. (RFC9114 7.1, RFC9114 7.2.3)'}; %% %% SETTINGS frames. %% parse(<<4, 0:2, Len:6, Rest/bits>>) when byte_size(Rest) >= Len -> parse_settings_id(Rest, Len, #{}); parse(<<4, 1:2, Len:14, Rest/bits>>) when byte_size(Rest) >= Len -> parse_settings_id(Rest, Len, #{}); parse(<<4, 2:2, Len:30, Rest/bits>>) when byte_size(Rest) >= Len -> parse_settings_id(Rest, Len, #{}); parse(<<4, 3:2, Len:62, Rest/bits>>) when byte_size(Rest) >= Len -> parse_settings_id(Rest, Len, #{}); %% %% PUSH_PROMISE frames. %% parse(<<5, 0:2, Len:6, Rest/bits>>) when byte_size(Rest) >= Len -> parse_push_promise(Rest, Len); parse(<<5, 1:2, Len:14, Rest/bits>>) when byte_size(Rest) >= Len -> parse_push_promise(Rest, Len); parse(<<5, 2:2, Len:30, Rest/bits>>) when byte_size(Rest) >= Len -> parse_push_promise(Rest, Len); parse(<<5, 3:2, Len:62, Rest/bits>>) when byte_size(Rest) >= Len -> parse_push_promise(Rest, Len); %% %% GOAWAY frames. %% parse(<<7, 0:2, 1:6, 0:2, StreamOrPushID:6, Rest/bits>>) -> {ok, {goaway, StreamOrPushID}, Rest}; parse(<<7, 0:2, 2:6, 1:2, StreamOrPushID:14, Rest/bits>>) -> {ok, {goaway, StreamOrPushID}, Rest}; parse(<<7, 0:2, 4:6, 2:2, StreamOrPushID:30, Rest/bits>>) -> {ok, {goaway, StreamOrPushID}, Rest}; parse(<<7, 0:2, 8:6, 3:2, StreamOrPushID:62, Rest/bits>>) -> {ok, {goaway, StreamOrPushID}, Rest}; parse(<<7, 0:2, N:6, _/bits>>) when N =:= 1; N =:= 2; N =:= 4; N =:= 8 -> more; parse(<<7, _/bits>>) -> {connection_error, h3_frame_error, 'GOAWAY frames payload MUST be 1, 2, 4 or 8 bytes wide. (RFC9114 7.1, RFC9114 7.2.6)'}; %% %% MAX_PUSH_ID frames. %% parse(<<13, 0:2, 1:6, 0:2, PushID:6, Rest/bits>>) -> {ok, {max_push_id, PushID}, Rest}; parse(<<13, 0:2, 2:6, 1:2, PushID:14, Rest/bits>>) -> {ok, {max_push_id, PushID}, Rest}; parse(<<13, 0:2, 4:6, 2:2, PushID:30, Rest/bits>>) -> {ok, {max_push_id, PushID}, Rest}; parse(<<13, 0:2, 8:6, 3:2, PushID:62, Rest/bits>>) -> {ok, {max_push_id, PushID}, Rest}; parse(<<13, 0:2, N:6, _/bits>>) when N =:= 1; N =:= 2; N =:= 4; N =:= 8 -> more; parse(<<13, _/bits>>) -> {connection_error, h3_frame_error, 'MAX_PUSH_ID frames payload MUST be 1, 2, 4 or 8 bytes wide. (RFC9114 7.1, RFC9114 7.2.6)'}; %% %% HTTP/2 frame types must be rejected. %% parse(<<2, _/bits>>) -> {connection_error, h3_frame_unexpected, 'HTTP/2 PRIORITY frame not defined for HTTP/3 must be rejected. (RFC9114 7.2.8)'}; parse(<<6, _/bits>>) -> {connection_error, h3_frame_unexpected, 'HTTP/2 PING frame not defined for HTTP/3 must be rejected. (RFC9114 7.2.8)'}; parse(<<8, _/bits>>) -> {connection_error, h3_frame_unexpected, 'HTTP/2 WINDOW_UPDATE frame not defined for HTTP/3 must be rejected. (RFC9114 7.2.8)'}; parse(<<9, _/bits>>) -> {connection_error, h3_frame_unexpected, 'HTTP/2 CONTINUATION frame not defined for HTTP/3 must be rejected. (RFC9114 7.2.8)'}; %% %% Unknown frames must be ignored. parse(<<0:2, Type:6, 0:2, Len:6, Rest/bits>>) when Type =:= 10; Type =:= 11; Type =:= 12; Type > 13 -> parse_ignore(Rest, Len); parse(<<0:2, Type:6, 1:2, Len:14, Rest/bits>>) when Type =:= 10; Type =:= 11; Type =:= 12; Type > 13 -> parse_ignore(Rest, Len); parse(<<0:2, Type:6, 2:2, Len:30, Rest/bits>>) when Type =:= 10; Type =:= 11; Type =:= 12; Type > 13 -> parse_ignore(Rest, Len); parse(<<0:2, Type:6, 3:2, Len:62, Rest/bits>>) when Type =:= 10; Type =:= 11; Type =:= 12; Type > 13 -> parse_ignore(Rest, Len); parse(<<1:2, _:14, 0:2, Len:6, Rest/bits>>) -> parse_ignore(Rest, Len); parse(<<1:2, _:14, 1:2, Len:14, Rest/bits>>) -> parse_ignore(Rest, Len); parse(<<1:2, _:14, 2:2, Len:30, Rest/bits>>) -> parse_ignore(Rest, Len); parse(<<1:2, _:14, 3:2, Len:62, Rest/bits>>) -> parse_ignore(Rest, Len); parse(<<2:2, _:30, 0:2, Len:6, Rest/bits>>) -> parse_ignore(Rest, Len); parse(<<2:2, _:30, 1:2, Len:14, Rest/bits>>) -> parse_ignore(Rest, Len); parse(<<2:2, _:30, 2:2, Len:30, Rest/bits>>) -> parse_ignore(Rest, Len); parse(<<2:2, _:30, 3:2, Len:62, Rest/bits>>) -> parse_ignore(Rest, Len); parse(<<3:2, _:62, 0:2, Len:6, Rest/bits>>) -> parse_ignore(Rest, Len); parse(<<3:2, _:62, 1:2, Len:14, Rest/bits>>) -> parse_ignore(Rest, Len); parse(<<3:2, _:62, 2:2, Len:30, Rest/bits>>) -> parse_ignore(Rest, Len); parse(<<3:2, _:62, 3:2, Len:62, Rest/bits>>) -> parse_ignore(Rest, Len); %% %% Incomplete frames for those we fully process only. %% parse(_) -> more. parse_settings_id(Rest, 0, Settings) -> {ok, {settings, Settings}, Rest}; parse_settings_id(<<0:2, Identifier:6, Rest/bits>>, Len, Settings) when Len >= 1 -> parse_settings_val(Rest, Len - 1, Settings, Identifier); parse_settings_id(<<1:2, Identifier:14, Rest/bits>>, Len, Settings) when Len >= 2 -> parse_settings_val(Rest, Len - 2, Settings, Identifier); parse_settings_id(<<2:2, Identifier:30, Rest/bits>>, Len, Settings) when Len >= 4 -> parse_settings_val(Rest, Len - 4, Settings, Identifier); parse_settings_id(<<3:2, Identifier:62, Rest/bits>>, Len, Settings) when Len >= 8 -> parse_settings_val(Rest, Len - 8, Settings, Identifier); parse_settings_id(_, _, _) -> {connection_error, h3_frame_error, 'SETTINGS payload size exceeds the length given. (RFC9114 7.1, RFC9114 7.2.4)'}. parse_settings_val(<<0:2, Value:6, Rest/bits>>, Len, Settings, Identifier) when Len >= 1 -> parse_settings_id_val(Rest, Len - 1, Settings, Identifier, Value); parse_settings_val(<<1:2, Value:14, Rest/bits>>, Len, Settings, Identifier) when Len >= 2 -> parse_settings_id_val(Rest, Len - 2, Settings, Identifier, Value); parse_settings_val(<<2:2, Value:30, Rest/bits>>, Len, Settings, Identifier) when Len >= 4 -> parse_settings_id_val(Rest, Len - 4, Settings, Identifier, Value); parse_settings_val(<<3:2, Value:62, Rest/bits>>, Len, Settings, Identifier) when Len >= 8 -> parse_settings_id_val(Rest, Len - 8, Settings, Identifier, Value); parse_settings_val(_, _, _, _) -> {connection_error, h3_frame_error, 'SETTINGS payload size exceeds the length given. (RFC9114 7.1, RFC9114 7.2.4)'}. parse_settings_id_val(Rest, Len, Settings, Identifier, Value) -> case Identifier of %% SETTINGS_QPACK_MAX_TABLE_CAPACITY (RFC9204). 1 -> parse_settings_key_val(Rest, Len, Settings, qpack_max_table_capacity, Value); %% SETTINGS_MAX_FIELD_SECTION_SIZE (RFC9114). 6 -> parse_settings_key_val(Rest, Len, Settings, max_field_section_size, Value); %% SETTINGS_QPACK_BLOCKED_STREAMS (RFC9204). 7 -> parse_settings_key_val(Rest, Len, Settings, qpack_blocked_streams, Value); %% SETTINGS_ENABLE_CONNECT_PROTOCOL (RFC9220). 8 when Value =:= 0 -> parse_settings_key_val(Rest, Len, Settings, enable_connect_protocol, false); 8 when Value =:= 1 -> parse_settings_key_val(Rest, Len, Settings, enable_connect_protocol, true); 8 -> {connection_error, h3_settings_error, 'The SETTINGS_ENABLE_CONNECT_PROTOCOL value MUST be 0 or 1. (RFC9220 3, RFC8441 3)'}; _ when Identifier < 6 -> {connection_error, h3_settings_error, 'HTTP/2 setting not defined for HTTP/3 must be rejected. (RFC9114 7.2.4.1)'}; %% Unknown settings must be ignored. _ -> parse_settings_id(Rest, Len, Settings) end. parse_settings_key_val(Rest, Len, Settings, Key, Value) -> case Settings of #{Key := _} -> {connection_error, h3_settings_error, 'A duplicate setting identifier was found. (RFC9114 7.2.4)'}; _ -> parse_settings_id(Rest, Len, Settings#{Key => Value}) end. parse_push_promise(<<0:2, PushID:6, Data/bits>>, Len) -> <> = Data, {ok, {push_promise, PushID, EncodedFieldSection}, Rest}; parse_push_promise(<<1:2, PushID:14, Data/bits>>, Len) -> <> = Data, {ok, {push_promise, PushID, EncodedFieldSection}, Rest}; parse_push_promise(<<2:2, PushID:30, Data/bits>>, Len) -> <> = Data, {ok, {push_promise, PushID, EncodedFieldSection}, Rest}; parse_push_promise(<<3:2, PushID:62, Data/bits>>, Len) -> <> = Data, {ok, {push_promise, PushID, EncodedFieldSection}, Rest}. %% Large ignored frames could lead to DoS. Users of %% this module must limit the size of such frames. parse_ignore(Data, Len) -> case Data of <<_:Len/binary, Rest/bits>> -> {ignore, Rest}; _ -> {more, ignore, Len - byte_size(Data)} end. -spec parse_unidi_stream_header(binary()) -> {ok, control | push | encoder | decoder, binary()} | {undefined, binary()}. parse_unidi_stream_header(<<0, Rest/bits>>) -> {ok, control, Rest}; parse_unidi_stream_header(<<1, Rest/bits>>) -> {ok, push, Rest}; parse_unidi_stream_header(<<2, Rest/bits>>) -> {ok, encoder, Rest}; parse_unidi_stream_header(<<3, Rest/bits>>) -> {ok, decoder, Rest}; parse_unidi_stream_header(<<0:2, _:6, Rest/bits>>) -> {undefined, Rest}; parse_unidi_stream_header(<<1:2, _:14, Rest/bits>>) -> {undefined, Rest}; parse_unidi_stream_header(<<2:2, _:30, Rest/bits>>) -> {undefined, Rest}; parse_unidi_stream_header(<<3:2, _:62, Rest/bits>>) -> {undefined, Rest}. -spec code_to_error(non_neg_integer()) -> error(). code_to_error(16#0100) -> h3_no_error; code_to_error(16#0101) -> h3_general_protocol_error; code_to_error(16#0102) -> h3_internal_error; code_to_error(16#0103) -> h3_stream_creation_error; code_to_error(16#0104) -> h3_closed_critical_stream; code_to_error(16#0105) -> h3_frame_unexpected; code_to_error(16#0106) -> h3_frame_error; code_to_error(16#0107) -> h3_excessive_load; code_to_error(16#0108) -> h3_id_error; code_to_error(16#0109) -> h3_settings_error; code_to_error(16#010a) -> h3_missing_settings; code_to_error(16#010b) -> h3_request_rejected; code_to_error(16#010c) -> h3_request_cancelled; code_to_error(16#010d) -> h3_request_incomplete; code_to_error(16#010e) -> h3_message_error; code_to_error(16#010f) -> h3_connect_error; code_to_error(16#0110) -> h3_version_fallback; %% Unknown/reserved error codes must be treated %% as equivalent to H3_NO_ERROR. code_to_error(_) -> h3_no_error. %% Building. -spec data(iodata()) -> iolist(). data(Data) -> Len = encode_int(iolist_size(Data)), [<<0:8>>, Len, Data]. -spec headers(iodata()) -> iolist(). headers(HeaderBlock) -> Len = encode_int(iolist_size(HeaderBlock)), [<<1:8>>, Len, HeaderBlock]. -spec settings(settings()) -> iolist(). settings(Settings) when Settings =:= #{} -> <<4:8, 0:8>>; settings(Settings) -> Payload = settings_payload(Settings), Len = encode_int(iolist_size(Payload)), [<<4:8>>, Len, Payload]. settings_payload(Settings) -> Payload = [case Key of %% SETTINGS_QPACK_MAX_TABLE_CAPACITY (RFC9204). qpack_max_table_capacity when Value =:= 0 -> <<>>; qpack_max_table_capacity -> [encode_int(1), encode_int(Value)]; %% SETTINGS_MAX_FIELD_SECTION_SIZE (RFC9114). max_header_list_size when Value =:= infinity -> <<>>; max_header_list_size -> [encode_int(6), encode_int(Value)]; %% SETTINGS_QPACK_BLOCKED_STREAMS (RFC9204). qpack_blocked_streams when Value =:= 0 -> <<>>; qpack_blocked_streams -> [encode_int(1), encode_int(Value)]; %% SETTINGS_ENABLE_CONNECT_PROTOCOL (RFC9220). enable_connect_protocol when Value -> [encode_int(8), encode_int(1)]; enable_connect_protocol -> [encode_int(8), encode_int(0)] end || {Key, Value} <- maps:to_list(Settings)], %% Include one reserved identifier in addition. ReservedType = 16#1f * (rand:uniform(148764065110560900) - 1) + 16#21, [encode_int(ReservedType), encode_int(rand:uniform(15384) - 1)|Payload]. -spec error_to_code(error()) -> non_neg_integer(). error_to_code(h3_no_error) -> %% Implementations should select a reserved error code %% with some probability when they would have sent H3_NO_ERROR. (RFC9114 8.1) case rand:uniform(2) of 1 -> 16#0100; 2 -> 16#1f * (rand:uniform(148764065110560900) - 1) + 16#21 end; error_to_code(h3_general_protocol_error) -> 16#0101; error_to_code(h3_internal_error) -> 16#0102; error_to_code(h3_stream_creation_error) -> 16#0103; error_to_code(h3_closed_critical_stream) -> 16#0104; error_to_code(h3_frame_unexpected) -> 16#0105; error_to_code(h3_frame_error) -> 16#0106; error_to_code(h3_excessive_load) -> 16#0107; error_to_code(h3_id_error) -> 16#0108; error_to_code(h3_settings_error) -> 16#0109; error_to_code(h3_missing_settings) -> 16#010a; error_to_code(h3_request_rejected) -> 16#010b; error_to_code(h3_request_cancelled) -> 16#010c; error_to_code(h3_request_incomplete) -> 16#010d; error_to_code(h3_message_error) -> 16#010e; error_to_code(h3_connect_error) -> 16#010f; error_to_code(h3_version_fallback) -> 16#0110. -spec encode_int(0..16#3fffffffffffffff) -> binary(). encode_int(I) when I < 64 -> <<0:2, I:6>>; encode_int(I) when I < 16384 -> <<1:2, I:14>>; encode_int(I) when I < 1073741824 -> <<2:2, I:30>>; encode_int(I) when I < 4611686018427387904 -> <<3:2, I:62>>.