Jerboa v0.2.0 Jerboa.Format

Encode and decode the STUN wire format

Summary

Functions

Decode a binary into a complete set of STUN message parameters

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

Encode a complete set of parameters into a binary suitable writing to the network

Functions

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

Decode a binary into a complete set of STUN message parameters

Return an :ok tuple or an :error tuple with an error struct if the binary doesn’t encode 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 header.

Verifying message integrity

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.Params.t, extra :: binary} |
  no_return

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

encode(params, options \\ [])
encode(Jerboa.Params.t, options :: Keyword.t) :: binary

Encode a complete set of parameters into a binary suitable writing to the network

Calculating message integrity

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

  • :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