Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 8 additions & 12 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,9 +23,9 @@ verification and SRTP key export yourself.
### Version selection

Three constructors control which DTLS version is used:
- [`Dtls::new_12`] — explicit DTLS 1.2
- [`Dtls::new_13`] — explicit DTLS 1.3
- [`Dtls::new_auto`] — auto‑sense: the first incoming ClientHello determines
- [`Dtls::new_12`](https://docs.rs/dimpl/latest/dimpl/struct.Dtls.html#method.new_12) — explicit DTLS 1.2
- [`Dtls::new_13`](https://docs.rs/dimpl/latest/dimpl/struct.Dtls.html#method.new_13) — explicit DTLS 1.3
- [`Dtls::new_auto`](https://docs.rs/dimpl/latest/dimpl/struct.Dtls.html#method.new_auto) — auto‑sense: the first incoming ClientHello determines
the version (based on the `supported_versions` extension)

## Cryptography surface
Expand All @@ -44,19 +44,19 @@ Three constructors control which DTLS version is used:
- Not supported: PSK cipher suites.

### Certificate model
During the handshake the engine emits [`Output::PeerCert`] with the peer's
During the handshake the engine emits [`Output::PeerCert`](https://docs.rs/dimpl/latest/dimpl/enum.Output.html#variant.PeerCert) with the peer's
leaf certificate (DER). The crate uses that certificate to verify DTLS
handshake messages, but it does not perform any PKI validation. Your
application is responsible for validating the peer certificate according to
your policy (fingerprint, chain building, name/EKU checks, pinning, etc.).

### Sans‑IO integration model
Drive the engine with three calls:
- [`Dtls::handle_packet`] — feed an entire received UDP datagram.
- [`Dtls::poll_output`] — drain pending output: DTLS records, timers, events.
- [`Dtls::handle_timeout`] — trigger retransmissions/time‑based progress.
- [`Dtls::handle_packet`](https://docs.rs/dimpl/latest/dimpl/struct.Dtls.html#method.handle_packet) — feed an entire received UDP datagram.
- [`Dtls::poll_output`](https://docs.rs/dimpl/latest/dimpl/struct.Dtls.html#method.poll_output) — drain pending output: DTLS records, timers, events.
- [`Dtls::handle_timeout`](https://docs.rs/dimpl/latest/dimpl/struct.Dtls.html#method.handle_timeout) — trigger retransmissions/time‑based progress.

The output is an [`Output`] enum with borrowed references into your provided buffer:
The output is an [`Output`](https://docs.rs/dimpl/latest/dimpl/enum.Output.html) enum with borrowed references into your provided buffer:
- `Packet(&[u8])`: send on your UDP socket
- `Timeout(Instant)`: schedule a timer and call `handle_timeout` at/after it
- `Connected`: handshake complete
Expand Down Expand Up @@ -133,9 +133,5 @@ Rust 1.81.0
[RFC 7714]: https://www.rfc-editor.org/rfc/rfc7714
[RFC 7627]: https://www.rfc-editor.org/rfc/rfc7627

[`Dtls::handle_packet`]: Dtls::handle_packet
[`Dtls::poll_output`]: Dtls::poll_output
[`Dtls::handle_timeout`]: Dtls::handle_timeout


License: MIT OR Apache-2.0
20 changes: 8 additions & 12 deletions src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -21,9 +21,9 @@
//! ## Version selection
//!
//! Three constructors control which DTLS version is used:
//! - [`Dtls::new_12`] — explicit DTLS 1.2
//! - [`Dtls::new_13`] — explicit DTLS 1.3
//! - [`Dtls::new_auto`] — auto‑sense: the first incoming ClientHello determines
//! - [`Dtls::new_12`](https://docs.rs/dimpl/latest/dimpl/struct.Dtls.html#method.new_12) — explicit DTLS 1.2
//! - [`Dtls::new_13`](https://docs.rs/dimpl/latest/dimpl/struct.Dtls.html#method.new_13) — explicit DTLS 1.3
//! - [`Dtls::new_auto`](https://docs.rs/dimpl/latest/dimpl/struct.Dtls.html#method.new_auto) — auto‑sense: the first incoming ClientHello determines
//! the version (based on the `supported_versions` extension)
//!
//! # Cryptography surface
Expand All @@ -42,19 +42,19 @@
//! - Not supported: PSK cipher suites.
//!
//! ## Certificate model
//! During the handshake the engine emits [`Output::PeerCert`] with the peer's
//! During the handshake the engine emits [`Output::PeerCert`](https://docs.rs/dimpl/latest/dimpl/enum.Output.html#variant.PeerCert) with the peer's
//! leaf certificate (DER). The crate uses that certificate to verify DTLS
//! handshake messages, but it does not perform any PKI validation. Your
//! application is responsible for validating the peer certificate according to
//! your policy (fingerprint, chain building, name/EKU checks, pinning, etc.).
//!
//! ## Sans‑IO integration model
//! Drive the engine with three calls:
//! - [`Dtls::handle_packet`] — feed an entire received UDP datagram.
//! - [`Dtls::poll_output`] — drain pending output: DTLS records, timers, events.
//! - [`Dtls::handle_timeout`] — trigger retransmissions/time‑based progress.
//! - [`Dtls::handle_packet`](https://docs.rs/dimpl/latest/dimpl/struct.Dtls.html#method.handle_packet) — feed an entire received UDP datagram.
//! - [`Dtls::poll_output`](https://docs.rs/dimpl/latest/dimpl/struct.Dtls.html#method.poll_output) — drain pending output: DTLS records, timers, events.
//! - [`Dtls::handle_timeout`](https://docs.rs/dimpl/latest/dimpl/struct.Dtls.html#method.handle_timeout) — trigger retransmissions/time‑based progress.
//!
//! The output is an [`Output`] enum with borrowed references into your provided buffer:
//! The output is an [`Output`](https://docs.rs/dimpl/latest/dimpl/enum.Output.html) enum with borrowed references into your provided buffer:
//! - `Packet(&[u8])`: send on your UDP socket
//! - `Timeout(Instant)`: schedule a timer and call `handle_timeout` at/after it
//! - `Connected`: handshake complete
Expand Down Expand Up @@ -134,10 +134,6 @@
//! [RFC 7714]: https://www.rfc-editor.org/rfc/rfc7714
//! [RFC 7627]: https://www.rfc-editor.org/rfc/rfc7627
//!
//! [`Dtls::handle_packet`]: Dtls::handle_packet
//! [`Dtls::poll_output`]: Dtls::poll_output
//! [`Dtls::handle_timeout`]: Dtls::handle_timeout
//!
#![forbid(unsafe_code)]
#![warn(clippy::all)]
#![allow(unknown_lints)]
Expand Down
Loading