Jerboa v0.2.0 Jerboa.Format
Encode and decode the STUN wire format
Summary
Functions
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!(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 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