webrtc_stun (webrtc v0.1.0)
View SourceSTUN message codec (RFC 8489), with the ICE (RFC 8445 §16.1) and TURN (RFC 8656 §18) attributes.
This module is pure: it encodes and decodes binaries and verifies MESSAGE-INTEGRITY, MESSAGE-INTEGRITY-SHA256 and FINGERPRINT. It has no notion of transactions or retransmission (see webrtc_stun_tx).
Summary
Functions
Verify message integrity of a raw, already decoded STUN message. MESSAGE-INTEGRITY-SHA256 is preferred when both are present (RFC 8489 §9.1.4). The comparison is constant time.
Decode a STUN message. FINGERPRINT, when present, is verified. MESSAGE-INTEGRITY is not verified here; call check_integrity/2 with the original binary once the key is known.
Encode a message. When integrity is given, MESSAGE-INTEGRITY (or MESSAGE-INTEGRITY-SHA256) is appended after all attributes. When fingerprint is true, FINGERPRINT is appended last (RFC 8489 §14.7).
Return the first attribute named Name.
True when the message carries MESSAGE-INTEGRITY or MESSAGE-INTEGRITY-SHA256.
Cheap test used by the demultiplexer (RFC 7983 §7): first byte in 0..3, a valid length and the magic cookie.
Long-term credential key, MD5 variant (RFC 8489 §9.2.2). The password must already be SASLprep/OpaqueString processed.
Build a success response for Request, reusing its transaction ID.
Types
-type address() :: {inet:ip_address(), inet:port_number()}.
-type attr_name() :: atom() | non_neg_integer().
-type class() :: request | indication | success | error.
-type method() :: binding | allocate | refresh | send | data | create_permission | channel_bind | non_neg_integer().
Functions
Verify message integrity of a raw, already decoded STUN message. MESSAGE-INTEGRITY-SHA256 is preferred when both are present (RFC 8489 §9.1.4). The comparison is constant time.
-spec decode(binary()) -> {ok, #stun{class :: webrtc_stun:class(), method :: webrtc_stun:method(), txid :: <<_:96>>, attrs :: [webrtc_stun:attr()], unknown :: [non_neg_integer()]}} | {error, term()}.
Decode a STUN message. FINGERPRINT, when present, is verified. MESSAGE-INTEGRITY is not verified here; call check_integrity/2 with the original binary once the key is known.
-spec encode(#stun{class :: webrtc_stun:class(), method :: webrtc_stun:method(), txid :: <<_:96>>, attrs :: [webrtc_stun:attr()], unknown :: [non_neg_integer()]}) -> binary().
-spec encode(#stun{class :: webrtc_stun:class(), method :: webrtc_stun:method(), txid :: <<_:96>>, attrs :: [webrtc_stun:attr()], unknown :: [non_neg_integer()]}, encode_opts()) -> binary().
Encode a message. When integrity is given, MESSAGE-INTEGRITY (or MESSAGE-INTEGRITY-SHA256) is appended after all attributes. When fingerprint is true, FINGERPRINT is appended last (RFC 8489 §14.7).
-spec error_reason(300..699) -> binary().
-spec error_response(#stun{class :: webrtc_stun:class(), method :: webrtc_stun:method(), txid :: <<_:96>>, attrs :: [webrtc_stun:attr()], unknown :: [non_neg_integer()]}, 300..699, [attr()]) -> #stun{class :: webrtc_stun:class(), method :: webrtc_stun:method(), txid :: <<_:96>>, attrs :: [webrtc_stun:attr()], unknown :: [non_neg_integer()]}.
-spec get(attr_name(), #stun{class :: webrtc_stun:class(), method :: webrtc_stun:method(), txid :: <<_:96>>, attrs :: [webrtc_stun:attr()], unknown :: [non_neg_integer()]}) -> {ok, term()} | error.
Return the first attribute named Name.
-spec get(attr_name(), #stun{class :: webrtc_stun:class(), method :: webrtc_stun:method(), txid :: <<_:96>>, attrs :: [webrtc_stun:attr()], unknown :: [non_neg_integer()]}, term()) -> term().
-spec has_integrity(#stun{class :: webrtc_stun:class(), method :: webrtc_stun:method(), txid :: <<_:96>>, attrs :: [webrtc_stun:attr()], unknown :: [non_neg_integer()]}) -> boolean().
True when the message carries MESSAGE-INTEGRITY or MESSAGE-INTEGRITY-SHA256.
-spec indication(method(), [attr()]) -> #stun{class :: webrtc_stun:class(), method :: webrtc_stun:method(), txid :: <<_:96>>, attrs :: [webrtc_stun:attr()], unknown :: [non_neg_integer()]}.
Cheap test used by the demultiplexer (RFC 7983 §7): first byte in 0..3, a valid length and the magic cookie.
Long-term credential key, MD5 variant (RFC 8489 §9.2.2). The password must already be SASLprep/OpaqueString processed.
-spec new_txid() -> <<_:96>>.
-spec request(method(), [attr()]) -> #stun{class :: webrtc_stun:class(), method :: webrtc_stun:method(), txid :: <<_:96>>, attrs :: [webrtc_stun:attr()], unknown :: [non_neg_integer()]}.
-spec success(#stun{class :: webrtc_stun:class(), method :: webrtc_stun:method(), txid :: <<_:96>>, attrs :: [webrtc_stun:attr()], unknown :: [non_neg_integer()]}, [attr()]) -> #stun{class :: webrtc_stun:class(), method :: webrtc_stun:method(), txid :: <<_:96>>, attrs :: [webrtc_stun:attr()], unknown :: [non_neg_integer()]}.
Build a success response for Request, reusing its transaction ID.