View Source ExSTUN.Message (ex_stun v0.1.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

Link to this section Summary

Types

Possible decode/1 error reasons.

t()

Functions

Adds attribute to a message.

Authenticates a message long-term mechanism.

Authenticates a message using short-term mechanism.

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.

Creates a new STUN message with a random transaction id.

Creates a new STUN message.

Link to this section 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()
}

Link to this section 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.

Link to this function

authenticate_lt(msg, password)

View Source
@spec authenticate_lt(t(), binary()) ::
  {:ok, key :: binary()}
  | {:error,
     :no_message_integrity
     | :no_username
     | :no_realm
     | :no_matching_message_integrity
     | atom()}

Authenticates a message long-term mechanism.

password depends on the STUN authentication method and has to be provided from the outside.

key is a key used for calculating MAC and can be used for adding message integrity in a response. See with_integrity/2.

Link to this function

authenticate_st(msg, password)

View Source
@spec authenticate_st(t(), binary()) ::
  {:ok, key :: binary()}
  | {:error, :no_message_integrity | :no_matching_message_integrity | atom()}

Authenticates a message using short-term mechanism.

It is assumed that username attribute of this message is valid.

key is a key used for calculating MAC and can be used for adding message integrity in a response. See with_integrity/2.

@spec check_fingerprint(t()) ::
  :ok | {:error, :no_fingerprint | :no_matching_fingerprint | 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

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