Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/elixir-webrtc/ex_dtls
DTLS and DTLS-SRTP library for Elixir, based on OpenSSL
https://github.com/elixir-webrtc/ex_dtls
dtls dtls-srtp elixir openssl webrtc
Last synced: 21 days ago
JSON representation
DTLS and DTLS-SRTP library for Elixir, based on OpenSSL
- Host: GitHub
- URL: https://github.com/elixir-webrtc/ex_dtls
- Owner: elixir-webrtc
- License: apache-2.0
- Created: 2020-09-14T13:55:06.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2024-09-20T17:25:08.000Z (4 months ago)
- Last Synced: 2024-12-07T23:05:02.558Z (about 1 month ago)
- Topics: dtls, dtls-srtp, elixir, openssl, webrtc
- Language: Elixir
- Homepage:
- Size: 129 KB
- Stars: 13
- Watchers: 4
- Forks: 2
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# ExDTLS
[](https://hex.pm/packages/ex_dtls)
[](https://hexdocs.pm/ex_dtls/)
[](https://github.com/elixir-webrtc/ex_dtls/actions/workflows/ci.yml)
[](https://codecov.io/gh/elixir-webrtc/ex_dtls)
DTLS and DTLS-SRTP library for Elixir, based on [OpenSSL].
`ExDTLS` allows a user to perform DTLS handshake (including DTLS-SRTP one)
without requiring any socket.
Instead, it generates DTLS packets that a user has to transport to the peer.
Thanks to this DTLS handshake can be performed on the third-party socket e.g. one used to
establish a connection via ICE protocol.
Starting from v0.16.0, `ExDTLS` can also be used to send arbitrary data using DTLS datagrams, see `ExDTLS.write_data/2`.
## Installation
The package can be installed by adding `ex_dtls` to your list of dependencies in `mix.exs`:
```elixir
def deps do
[
{:ex_dtls, "~> 0.16.0"}
]
end
```
Please note that `ex_dtls` uses OpenSSL under the hood.
We use `pkg-config` to search for include and lib files so you must make sure
that `openssl.pc` file is searchable by `pkg-config`.
If it is not in the default `pkg-config` search path, locate your `openssl.pc`
and add its parent directory to the `PKG_CONFIG_PATH`.
For example:
```sh
export PKG_CONFIG_PATH=$PKG_CONFIG_PATH:/opt/homebrew/Cellar/openssl@3/3.1.0/lib/pkgconfig
```
If OpenSSL was installed using `brew`, you can use the following syntax
to make sure that the path will still be correct after OpenSSL update:
```sh
export PKG_CONFIG_PATH=$PKG_CONFIG_PATH:$(brew --prefix openssl@3)/lib/pkgconfig
```
## Usage
`ExDTLS` uses OpenSSL under the hood.
Make sure you have it installed on your OS.
Init `ExDTLS` on both peers with:
```elixir
# One peer should be a client (use `mode: :client`) and the other
# one a server (use `mode: :server`).
# DTLS-SRTP is the most common use case for ExDTLS, we'll enable it.
dtls = ExDTLS.init(mode: :client, dtls_srtp: true)
```
On a peer running in a client mode start performing DTLS handshake
```elixir
{packets, timeout} = ExDTLS.do_handshake(dtls)
```
You will obtain initial handshake packets and a `timeout`.
`packets` has to be passed to the second peer (using your own socket UDP).
`timeout` is a time after which `ExDTLS.handle_timeout/1` should be called.
After receiving initial DTLS packets on the second peer pass them to `ExDTLS`:
```elixir
{:handshake_packets, packets, timeout} = ExDTLS.handle_data(dtls, packets)
```
As a result, we will also get some new packets that have to be passed to the first peer.
After some back and forth DTLS handshake should be finished successfully.
The peer that finishes the handshake first will return `{:handshake_finished, local_keying_material, remote_keying_material, protection_profile, packets}` tuple.
These packets have to be sent to the second peer, so it can finish its handshake too and
return `{:handshake_finished, local_keying_material, remote_keying_material, protection_profile}` tuple.
For more complete examples please refer to [ex_webrtc] where we use `ex_dtls`
or to our integration tests.
## Debugging
Add `compiler_flags: ["-DEXDTLS_DEBUG"],` in `bundlex.exs` to
get debug logs from the native code.
## Copyright and License
Copyright 2020, [Software Mansion](https://swmansion.com/?utm_source=git&utm_medium=readme&utm_campaign=ex_dtls)
[](https://swmansion.com/?utm_source=git&utm_medium=readme&utm_campaign=ex_dtls)
Licensed under the [Apache License, Version 2.0](LICENSE)
[OpenSSL]: https://www.openssl.org/
[ex_webrtc]: https://github.com/elixir-webrtc/ex_webrtc