@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_key_cert(integer(), integer()) :: {pkey :: binary(), cert :: binary()}

Generates a new key/certificate pair.

This is always 2048-bit RSA key.

not_before and not_after can be used to specify certificate duration in seconds. They have to fit into architecture-dependent integer size. Defaults to (-1 year) - (+ 1 year).

Returns DER representation in binary format.

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

Gets current, local certificate.

Returns DER representation in binary format.

@spec get_cert_fingerprint(binary()) :: binary()

Returns an SHA-256 digest of the DER representation of the X509 certificate.

@spec get_peer_cert(dtls()) :: binary() | nil

Gets peer certificate.

Returns DER representation in binary format or nil when no certificate was presented by the peer or no connection was established.

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

Gets current, local private key.

Returns key specific representation in binary format.

@spec handle_data(dtls(), data :: 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()}
  | {:error, :handshake_error | :peer_closed_for_writing}

Handles peer's packets.

When handshake is finished, calling handle_data will return {:ok, binary()}, which is decoded data.

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

• mode - :client if ExDTLS module should work as a client or :server if as a server. This option is required.

• dtls_srtp - true if DTLS-SRTP handshake should be performed or false if a normal one. Defaults to false.

• pkey - private key to use in this SSL context. Must correspond to cert. If both pkey and cert are not passed, ExDTLS will generate 2048-bit RSA key and certificate on its own.

• cert - certificate to use in this SSL context. Must correspond to pkey. If both pkey and cert are not passed, ExDTLS will generate 2048-bit RSA key and certificate on its own.

• verify_peer - true if peer's certificate should be verified. Default OpenSSL verification is performed except that:

  • self-signed certificates are also accepted
  • verification fails if there is no peer cert

  Under the hood, ExDTLS uses SSL_CTX_set_verify with SSL_VERIFY_PEER | SSL_VERIFY_FAIL_IF_NO_PEER_CERT. Note that if verify_peer is false, get_peer_cert/1 called on ExDTLS working in the server mode, will always return nil. Defaults to false.

@spec write_data(dtls(), data :: binary()) ::
  {:ok, packets :: [binary()]} | {:error, :handshake_not_finished}

Writes data to the DTLS connection.

Generates encrypted packets that need to be passed to the second host.