Jerboa

v0.3.0

Jerboa v0.3.0 Jerboa.Format

Encode and decode the STUN wire format

Summary

Types

channel_number()

Represents valid number of TURN channel

Functions

decode(binary, options \\ [])

Decode a binary into a Jerboa.Params or Jerboa.ChannelData struct

decode!(bin, options \\ [])

The same as decode/1 but raises one of various exceptions if the binary doesn’t encode a STUN or ChannelData message

encode(params_or_channel_data, options \\ [])

Encode a complete set of STUN Params or ChannelData into a binary suitable for writing to the network

Types

channel_number() 
channel_number() :: 16384..32767

Represents valid number of TURN channel

Functions

decode(binary, options \\ []) 
decode(binary, options :: Keyword.t) ::
  {:ok, Jerboa.Params.t | Jerboa.ChannelData.t} |
  {:ok, Jerboa.Params.t | Jerboa.ChannelData.t, extra :: binary} |
  {:error, struct}

Decode a binary into a Jerboa.Params or Jerboa.ChannelData struct

Return an :ok tuple or an :error tuple with an error struct if the binary doesn’t encode a ChannelData message, a STUN message, or included message integrity is not valid (see “Verifying message integrity”). Returns {:ok, params, extra} if given binary was longer than declared in STUN or ChannelData header.

Verifying message integrity

This section applies only to STUN messages.

Similarly to encode/2 decoder first looks for username and realm in the decoded message attributes or in the options list if there are no such attributes.

Verification stage of decoding will never cause a decoding failure. To indicate what happened during verification, there are two fields in Jerboa.Params struct: :signed? and :verified?.

:signed? is set to true only if the message being decoded has a MESSAGE-INTEGRITY attribute included. :verified? can never be true if :signed? is false (because there is simply nothing to verify).

:verified? is only set to true when:

  • the message is :signed?
  • username, realm in the message attributes, or were passed as options and secret was passed as option
  • MESSAGE-INTEGRITY was successfully verified using algorithm described in RFC

Otherwise, it’s set to false.

Available options

Same as in encode/2.

decode!(bin, options \\ []) 
decode!(binary, options :: Keyword.t) ::
  Jerboa.Params.t |
  Jerboa.ChannelData.t |
  {Jerboa.Params.t | Jerboa.ChannelData.t, extra :: binary} |
  no_return

The same as decode/1 but raises one of various exceptions if the binary doesn’t encode a STUN or ChannelData message

encode(params_or_channel_data, options \\ []) 
encode(Jerboa.Params.t | Jerboa.ChannelData.t, options :: Keyword.t) :: binary

Encode a complete set of STUN Params or ChannelData into a binary suitable for writing to the network

Calculating message integrity

This section applies only to encoding Jerboa.Params struct.

In order to calculate message integrity over encoded message, encoder must know three values: username (as in USERNAME attribute), realm (REALM) and secret.

Realm and username may be provided as attributes in params struct, or passed in options list. However attribute values will always override those found in options. Secret must be provided in option list.

If any of these values are missing, message integrity won’t be applied and encoding will succeed. None of these values (username, realm or secret) will be validated, so encoding will fail if, for example, provided username is an integer.

Note that passing these values in options list *won’t add them to message attributes list.

Available options

This section applies only to encoding Jerboa.Params struct.

  • :secret - secret used for calculating message integrity
  • :username - username used for calculating message integrity if USERNAME attribute can’t be found in the params struct
  • :realm - realm used for calculating message integrity if REALM attribute can’t be found in params struct