View Source ExSTUN.Message (ex_stun v0.2.0)

STUN Message

      0                   1                   2                   3
    0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |0 0|     STUN Message Type     |         Message Length        |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |                         Magic Cookie                          |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |                                                               |
   |                     Transaction ID (96 bits)                  |
   |                                                               |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

                Figure 2: Format of STUN Message Header

Summary

Types

Possible decode/1 error reasons.

t()

Functions

Adds attribute to a message.

Authenticates a message.

Decodes a binary into a STUN message.

Encodes a STUN message into a binary.

Gets all attributes of given type from the message.

Gets first attribute of given type from a message.

Create longe-term authentication key.

Creates a new STUN message with a random transaction id.

Creates a new STUN message.

Types

@type decode_error_t() ::
  :not_enough_data
  | :malformed_header
  | :malformed_type
  | :data_after_fingerprint
  | :malformed_attr_padding

Possible decode/1 error reasons.

  • :not_enough_data - provided binary is less than 20 bytes
  • :malformed_header - improper message header e.g. invalid cookie
  • :unknown_method - unknown message type method
  • :data_after_finderprint - fingerprint attribute is followed by other forbidden attributes
  • :malformed_attr_padding - one or more attributes are not followed by long enough padding or padding is not 0.
@type t() :: %ExSTUN.Message{
  attributes: [ExSTUN.Message.RawAttribute.t()],
  fingerprint: boolean(),
  integrity: {boolean(), binary()},
  len_to_int: integer(),
  raw: binary(),
  transaction_id: integer(),
  type: ExSTUN.Message.Type.t()
}

Functions

Link to this function

add_attribute(message, attr)

View Source
@spec add_attribute(t(), ExSTUN.Message.RawAttribute.t()) :: t()

Adds attribute to a message.

@spec authenticate(t(), binary()) :: :ok | {:error, atom()}

Authenticates a message.

key depends on the authentication method. When authenticating using short-term mechanism, it is simply a password. When authenticating using long-term mechanism, use lt_key/3 to obtain the key.

Presence of username, realm and nonce attributes is not checked. Depending on the authentication method and its context (client/server side), user has to perform those checks on their own.

@spec check_fingerprint(t()) :: :ok | {:error, atom()}
@spec decode(binary()) :: {:ok, t()} | {:error, decode_error_t()}

Decodes a binary into a STUN message.

@spec encode(t()) :: binary()

Encodes a STUN message into a binary.

Link to this function

get_all_attributes(msg, attr_mod)

View Source
@spec get_all_attributes(t(), module()) :: {:ok, [struct()]} | {:error, atom()} | nil

Gets all attributes of given type from the message.

attr_mod is a module implementing ExSTUN.Message.Attribute behaviour. Returns nil if there is no attribute of given type.

Link to this function

get_attribute(message, attr_mod)

View Source
@spec get_attribute(t(), module()) :: {:ok, struct()} | {:error, atom()} | nil

Gets first attribute of given type from a message.

attr_mod is a module implementing ExSTUN.Message.Attribute behaviour. Returns nil if there is no attribute of given type.

Link to this function

lt_key(username, password, realm)

View Source
@spec lt_key(binary(), binary(), binary()) :: binary()

Create longe-term authentication key.

Link to this function

new(type, attributes \\ [])

View Source
@spec new(ExSTUN.Message.Type.t(), [struct()]) :: t()

Creates a new STUN message with a random transaction id.

Link to this function

new(transaction_id, type, attributes)

View Source
@spec new(integer(), ExSTUN.Message.Type.t(), [struct()]) :: t()

Creates a new STUN message.

@spec with_fingerprint(t()) :: t()
Link to this function

with_integrity(msg, key)

View Source
@spec with_integrity(t(), binary()) :: t()