webrtc_stun (webrtc v0.1.0)

View Source

STUN 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

address/0

-type address() :: {inet:ip_address(), inet:port_number()}.

attr/0

-type attr() :: {attr_name(), term()}.

attr_name/0

-type attr_name() :: atom() | non_neg_integer().

class/0

-type class() :: request | indication | success | error.

encode_opts/0

-type encode_opts() :: #{integrity => integrity(), fingerprint => boolean()}.

integrity/0

-type integrity() :: undefined | {sha1, Key :: binary()} | {sha256, Key :: binary()}.

method/0

-type method() ::
          binding | allocate | refresh | send | data | create_permission | channel_bind |
          non_neg_integer().

Functions

check_integrity(_, Key)

-spec check_integrity(binary(), binary()) -> ok | {error, no_integrity | bad_integrity}.

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

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

encode(Stun)

-spec encode(#stun{class :: webrtc_stun:class(),
                   method :: webrtc_stun:method(),
                   txid :: <<_:96>>,
                   attrs :: [webrtc_stun:attr()],
                   unknown :: [non_neg_integer()]}) ->
                binary().

encode(Stun, Opts)

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

error_reason(_)

-spec error_reason(300..699) -> binary().

error_response(Stun, Code, Attrs)

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

get(Name, Stun)

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

get(Name, Stun, Default)

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

has_integrity(Stun)

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

indication(Method, Attrs)

-spec indication(method(), [attr()]) ->
                    #stun{class :: webrtc_stun:class(),
                          method :: webrtc_stun:method(),
                          txid :: <<_:96>>,
                          attrs :: [webrtc_stun:attr()],
                          unknown :: [non_neg_integer()]}.

is_stun(_)

-spec is_stun(binary()) -> boolean().

Cheap test used by the demultiplexer (RFC 7983 §7): first byte in 0..3, a valid length and the magic cookie.

long_term_key(Username, Realm, Password)

-spec long_term_key(binary(), binary(), binary()) -> binary().

Long-term credential key, MD5 variant (RFC 8489 §9.2.2). The password must already be SASLprep/OpaqueString processed.

long_term_key(_, U, R, P)

-spec long_term_key(md5 | sha256, binary(), binary(), binary()) -> binary().

new_txid()

-spec new_txid() -> <<_:96>>.

request(Method, Attrs)

-spec request(method(), [attr()]) ->
                 #stun{class :: webrtc_stun:class(),
                       method :: webrtc_stun:method(),
                       txid :: <<_:96>>,
                       attrs :: [webrtc_stun:attr()],
                       unknown :: [non_neg_integer()]}.

success(Stun, Attrs)

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