webrtc_sctp_chunk (webrtc v0.1.0)
View SourceSCTP packet and chunk codec (RFC 9260 §3, RFC 3758, RFC 4820, RFC 6525, RFC 8260, RFC 9653).
This module is pure: it turns binaries into #sctp_packet{} records and chunk terms and back. Parameters and error causes inside chunks are handled by webrtc_sctp_param. The association logic lives elsewhere.
Packets: decode/1 parses the 12 byte common header and the chunks. It does not verify the checksum; the checksum field holds the wire value read as <<Crc:32/little>>, which equals webrtc_sctp_crc32c:crc32c/1 of the packet (checksum zeroed) when the packet is intact. Use checksum_ok/2 to verify it. encode/2 writes the CRC32c, or 0 with #{checksum => zero} (RFC 9653).
Chunk terms, chunk():
#sctp_data{}: DATA (type 0) whenidatais false, I-DATA (type 64) when true. For DATAmidis the 16-bit SSN andfsnis 0. For I-DATA the last header word is the PPID whenbeginningis set (fsnis then 0) and the FSN otherwise (ppidis then 0 after decode).#sctp_init{}: INIT (ackfalse, type 1) or INIT ACK (type 2).#sctp_sack{}: gaps as{Start, End}offsets, dups as TSNs, in wire order.{heartbeat, Info},{heartbeat_ack, Info}:Infois the value of the Heartbeat Info parameter.{abort, T, [cause()]},{op_error, [cause()]}(ERROR chunk),{shutdown, CumTsn},shutdown_ack,{cookie_echo, Cookie},cookie_ack,{shutdown_complete, T}.{forward_tsn, NewCumTsn, [{Sid, Ssn}]}(RFC 3758),{i_forward_tsn, NewCumTsn, [{Sid, Unordered, Mid}]}(RFC 8260).{reconfig, [reconf_param()]}(RFC 6525),{pad, NBytes}(RFC 4820).{unknown_chunk, Type, Flags, Value}for any other type; it encodes back to the original chunk.
Decoding is strict (RFC 9260 §3.2) and never raises. Error reasons:
too_short: the packet is shorter than the 12 byte header.trailing_bytes: 1 to 3 bytes left after a chunk and its padding, or a partial padding after the last chunk.{bad_chunk, Type}: a chunk length below 4 or past the end of the packet, a fixed-size chunk with the wrong length, a SACK whose length does not match its counts, a HEARTBEAT without Heartbeat Info, an empty RE-CONFIG, or bytes left inside a chunk that do not form a parameter or cause.{bad_param, Type},{bad_cause, Code}: a malformed parameter or error cause inside a chunk (seewebrtc_sctp_param).
Flags of chunks other than DATA, I-DATA, ABORT and SHUTDOWN COMPLETE are ignored on decode and written as 0. Chunks are padded with zero bytes; the padding of the last parameter or cause inside a chunk is not counted in the chunk length on encode, and both forms are accepted on decode.
Summary
Functions
Verify the checksum of a packet: true when the CRC32c is correct, or when AcceptZero is true and the wire checksum is 0 (RFC 9653). False for binaries shorter than 12 bytes.
Encoded size of a chunk including its padding. Constant time for DATA and I-DATA chunks.
Decode a packet. The checksum is not verified.
Decode the chunk area of a packet (the bytes after the 12 byte common header).
Encode a packet with a CRC32c checksum.
Encode a packet. #{checksum => zero} writes a zero checksum (RFC 9653); the default is crc32c. The checksum field of the record is ignored.
Encode one chunk, padded with zero bytes to a multiple of 4.
What to do with a chunk type this endpoint does not understand (RFC 9260 §3.2, the upper two bits of the type): 00 stop processing the packet, 01 stop and report, 10 skip the chunk, 11 skip and report.
Types
-type chunk() :: data_chunk() | init_chunk() | sack_chunk() | {heartbeat, Info :: binary()} | {heartbeat_ack, Info :: binary()} | {abort, T :: boolean(), [webrtc_sctp_param:cause()]} | {shutdown, CumTsn :: u32()} | shutdown_ack | cookie_ack | {op_error, [webrtc_sctp_param:cause()]} | {cookie_echo, Cookie :: binary()} | {shutdown_complete, T :: boolean()} | {forward_tsn, NewCumTsn :: u32(), [{Sid :: u16(), Ssn :: u16()}]} | {i_forward_tsn, NewCumTsn :: u32(), [{Sid :: u16(), Unordered :: boolean(), Mid :: u32()}]} | {reconfig, [webrtc_sctp_param:reconf_param(), ...]} | {pad, NBytes :: non_neg_integer()} | {unknown_chunk, Type :: 0..255, Flags :: 0..255, Value :: binary()}.
-type encode_opts() :: #{checksum => crc32c | zero}.
-type error_reason() :: too_short | trailing_bytes | {bad_chunk, 0..255} | webrtc_sctp_param:error_reason().
-type packet() :: #sctp_packet{src_port :: 0..65535, dst_port :: 0..65535, vtag :: 0..4294967295, checksum :: 0..4294967295, chunks :: [term()]}.
-type sack_chunk() ::
#sctp_sack{cum_tsn :: 0..4294967295,
a_rwnd :: 0..4294967295,
gaps :: [{0..65535, 0..65535}],
dups :: [0..4294967295]}.
-type u16() :: 0..65535.
-type u32() :: 0..4294967295.
Functions
Verify the checksum of a packet: true when the CRC32c is correct, or when AcceptZero is true and the wire checksum is 0 (RFC 9653). False for binaries shorter than 12 bytes.
-spec chunk_size(chunk()) -> pos_integer().
Encoded size of a chunk including its padding. Constant time for DATA and I-DATA chunks.
-spec decode(binary()) -> {ok, packet()} | {error, error_reason()}.
Decode a packet. The checksum is not verified.
-spec decode_chunks(binary()) -> {ok, [chunk()]} | {error, error_reason()}.
Decode the chunk area of a packet (the bytes after the 12 byte common header).
Encode a packet with a CRC32c checksum.
-spec encode(packet(), encode_opts()) -> binary().
Encode a packet. #{checksum => zero} writes a zero checksum (RFC 9653); the default is crc32c. The checksum field of the record is ignored.
Encode one chunk, padded with zero bytes to a multiple of 4.
-spec unrecognized_chunk_action(0..255) -> {stop | skip, Report :: boolean()}.
What to do with a chunk type this endpoint does not understand (RFC 9260 §3.2, the upper two bits of the type): 00 stop processing the packet, 01 stop and report, 10 skip the chunk, 11 skip and report.