webrtc_sctp_chunk (webrtc v0.1.0)

View Source

SCTP 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) when idata is false, I-DATA (type 64) when true. For DATA mid is the 16-bit SSN and fsn is 0. For I-DATA the last header word is the PPID when beginning is set (fsn is then 0) and the FSN otherwise (ppid is then 0 after decode).
  • #sctp_init{}: INIT (ack false, 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}: Info is 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 (see webrtc_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

chunk/0

-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()}.

data_chunk/0

-type data_chunk() ::
          #sctp_data{idata :: boolean(),
                     tsn :: 0..4294967295,
                     sid :: 0..65535,
                     mid :: 0..4294967295,
                     fsn :: 0..4294967295,
                     ppid :: 0..4294967295,
                     unordered :: boolean(),
                     beginning :: boolean(),
                     ending :: boolean(),
                     immediate :: boolean(),
                     data :: binary()}.

encode_opts/0

-type encode_opts() :: #{checksum => crc32c | zero}.

error_reason/0

-type error_reason() ::
          too_short | trailing_bytes | {bad_chunk, 0..255} | webrtc_sctp_param:error_reason().

init_chunk/0

-type init_chunk() ::
          #sctp_init{ack :: boolean(),
                     tag :: 0..4294967295,
                     a_rwnd :: 0..4294967295,
                     os :: 0..65535,
                     mis :: 0..65535,
                     tsn :: 0..4294967295,
                     params :: [term()]}.

packet/0

-type packet() ::
          #sctp_packet{src_port :: 0..65535,
                       dst_port :: 0..65535,
                       vtag :: 0..4294967295,
                       checksum :: 0..4294967295,
                       chunks :: [term()]}.

sack_chunk/0

-type sack_chunk() ::
          #sctp_sack{cum_tsn :: 0..4294967295,
                     a_rwnd :: 0..4294967295,
                     gaps :: [{0..65535, 0..65535}],
                     dups :: [0..4294967295]}.

u16/0

-type u16() :: 0..65535.

u32/0

-type u32() :: 0..4294967295.

Functions

checksum_ok(Bin, AcceptZero)

-spec checksum_ok(binary(), AcceptZero :: boolean()) -> boolean().

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.

chunk_size(Sctp_data)

-spec chunk_size(chunk()) -> pos_integer().

Encoded size of a chunk including its padding. Constant time for DATA and I-DATA chunks.

decode(Bin)

-spec decode(binary()) -> {ok, packet()} | {error, error_reason()}.

Decode a packet. The checksum is not verified.

decode_chunks(Bin)

-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(Packet)

-spec encode(packet()) -> binary().

Encode a packet with a CRC32c checksum.

encode(Sctp_packet, Opts)

-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_chunk(Chunk)

-spec encode_chunk(chunk()) -> binary().

Encode one chunk, padded with zero bytes to a multiple of 4.

unrecognized_chunk_action(Type)

-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.