View Source ExDTLS (ExDTLS v0.14.0)

Module that allows performing DTLS handshake including a DTLS-SRTP one.

ExDTLS executes native OpenSSL functions to perform DTLS handshake. It doesn't create or require any socket. Instead, it returns generated DTLS packets, which then have to be transported to the peer.

Link to this section Summary

Types

A reference to ExDTLS native.

Type describing ExDTLS configuration.

Supported protection profiles.

Functions

Starts performing DTLS handshake.

Generates new certificate.

Gets current certificate.

Returns a digest of the DER representation of the X509 certificate.

Gets current private key.

Handles peer's packets.

Handles timeout.

Initializes ExDTLS.

Link to this section Types

@type dtls() :: reference()

A reference to ExDTLS native.

@type opts_t() :: [
  client_mode: boolean(),
  dtls_srtp: boolean(),
  pkey: binary(),
  cert: binary()
]

Type describing ExDTLS configuration.

See init/1 for the meaning of each option

Link to this type

protection_profile_t()

View Source
@type protection_profile_t() :: 1 | 2 | 7 | 8

Supported protection profiles.

For meaning of these values please refer to https://www.iana.org/assignments/srtp-protection/srtp-protection.xhtml

Link to this section Functions

@spec do_handshake(dtls()) :: {packets :: binary(), timeout :: integer()}

Starts performing DTLS handshake.

Generates initial DTLS packets that have to be passed to the second host. Has to be called by a host working in the client mode.

timeout is a time in ms after which handle_timeout/1 should be called.

@spec generate_cert() :: binary()

Generates new certificate.

Returns DER representation in binary format.

@spec get_cert(dtls()) :: binary()

Gets current certificate.

Returns DER representation in binary format.

Link to this function

get_cert_fingerprint(dtls)

View Source
@spec get_cert_fingerprint(dtls()) :: binary()

Returns a digest of the DER representation of the X509 certificate.

@spec get_pkey(dtls()) :: binary()

Gets current private key.

Returns key specific representation in binary format.

Link to this function

handle_data(dtls, packets)

View Source
@spec handle_data(dtls(), packets :: binary()) ::
  {:ok, packets :: binary()}
  | :handshake_want_read
  | {:handshake_packets, packets :: binary(), timeout :: integer()}
  | {:handshake_finished, local_keying_material :: binary(),
     remote_keying_material :: binary(), protection_profile_t(),
     packets :: binary()}
  | {:handshake_finished, local_keying_material :: binary(),
     remote_keying_material :: binary(), protection_profile_t()}
  | {:connection_closed, reason :: atom()}

Handles peer's packets.

If handshake is finished it returns {:ok, binary()} which is decoded data or {:error, value} if error occurred.

:handshake_packets contains handshake data that has to be sent to the peer. :handshake_want_read means some additional data is needed for continuing handshake. It can be returned when retransmitted packet was passed but timer didn't expired yet. timeout is a time in ms after which handle_timeout/1 should be called.

Both local and remote keying materials consist of master key and master salt.

@spec handle_timeout(dtls()) ::
  :ok | {:retransmit, packets :: binary(), timeout :: integer()}

Handles timeout.

If there is a timeout to handle, this function will return packets that has to be retransmitted and a new timeout in ms after which handle_timeout/1 should be called once agian.

If there is no timeout to handle, simple {:ok, dtls()} tuple is returned.

@spec init(opts :: opts_t()) :: dtls()

Initializes ExDTLS.

Accepts a keyword list with the following options (opts_t/0):

  • client_mode - true if ExDTLS module should work as a client or false if as a server
  • dtls_srtp - true if DTLS-SRTP handshake should be performed or false if a normal one
  • pkey - private key to use in this SSL context. Must correspond to cert
  • cert - certificate to use in this SSL context. Must correspond to pkey

If both pkey and cert are not passed ExDTLS will generate key and certificate on its own.