View Source ExDTLS (ExDTLS v0.15.1)
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.
Summary
Functions
Starts performing DTLS handshake.
Generates a new key/certificate pair.
Gets current, local certificate.
Returns an SHA-256 digest of the DER representation of the X509 certificate.
Gets peer certificate.
Gets current, local private key.
Handles peer's packets.
Handles timeout.
Initializes ExDTLS
.
Types
@type dtls() :: reference()
A reference to ExDTLS
native.
@type opts_t() :: [ mode: :client | :server, dtls_srtp: boolean(), pkey: binary(), cert: binary(), verify_peer: boolean() ]
Type describing ExDTLS configuration.
See init/1
for the meaning of each option
@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
Functions
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.
generate_key_cert(not_before \\ -31_536_000, not_after \\ 31_536_000)
View SourceGenerates 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.
Gets current, local certificate.
Returns DER representation in binary format.
Returns an SHA-256 digest of the DER representation of the X509 certificate.
Gets peer certificate.
Returns DER representation in binary format or nil
when no certificate was presented by the peer or no connection
was established.
Gets current, local private key.
Returns key specific representation in binary format.
@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()} | {: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
.
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.
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 orfalse
if a normal one. Defaults tofalse
.pkey
- private key to use in this SSL context. Must correspond tocert
. If bothpkey
andcert
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 topkey
. If bothpkey
andcert
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
usesSSL_CTX_set_verify
withSSL_VERIFY_PEER | SSL_VERIFY_FAIL_IF_NO_PEER_CERT
. Note that ifverify_peer
isfalse
,get_peer_cert/1
called onExDTLS
working in the server mode, will always returnnil
. Defaults tofalse
.