pub struct Dtls { /* private fields */ }Expand description
Sans-IO DTLS endpoint (client or server).
New instances start in the server role. Call
set_active(true) to switch to client before
the handshake begins.
Drive the state machine with handle_packet,
poll_output, and
handle_timeout.
Implementations§
Source§impl Dtls
impl Dtls
Sourcepub fn new_12(
config: Arc<Config>,
certificate: DtlsCertificate,
now: Instant,
) -> Self
pub fn new_12( config: Arc<Config>, certificate: DtlsCertificate, now: Instant, ) -> Self
Create a new DTLS 1.2 instance in the server role.
Call set_active(true) to switch to client
before the handshake begins. The now parameter seeds the internal
time tracking for timeouts and retransmissions.
During the handshake, the peer’s leaf certificate is surfaced via
Output::PeerCert. It is up to the application to validate that
certificate according to its security policy.
Sourcepub fn new_12_psk(config: Arc<Config>, now: Instant) -> Self
pub fn new_12_psk(config: Arc<Config>, now: Instant) -> Self
Create a new DTLS 1.2 PSK-only instance (no certificate).
Call set_active(true) to switch to client
before the handshake begins. The config must have a
PskResolver configured, and for clients a PSK identity
via ConfigBuilder::with_psk_client.
Panics if config has no PSK configured. Without PSK data the
PSK suite filter would leave zero negotiable suites, so failing
fast at construction is preferable to a late handshake error.
Sourcepub fn new_13(
config: Arc<Config>,
certificate: DtlsCertificate,
now: Instant,
) -> Self
pub fn new_13( config: Arc<Config>, certificate: DtlsCertificate, now: Instant, ) -> Self
Create a new DTLS 1.3 instance in the server role.
Call set_active(true) to switch to client
before the handshake begins.
During the handshake, the peer’s leaf certificate is surfaced via
Output::PeerCert. It is up to the application to validate that
certificate according to its security policy.
Sourcepub fn new_auto(
config: Arc<Config>,
certificate: DtlsCertificate,
now: Instant,
) -> Self
pub fn new_auto( config: Arc<Config>, certificate: DtlsCertificate, now: Instant, ) -> Self
Create a new DTLS instance that auto‑senses the version.
Server role (default): starts as a DTLS 1.3 server. If the
peer’s ClientHello does not offer DTLS 1.3 in supported_versions,
the server automatically falls back to DTLS 1.2. This handles
fragmented ClientHellos (e.g. with post-quantum key shares)
correctly because the DTLS 1.3 engine performs full reassembly
before inspecting extensions.
Client role (set_active(true)): the
instance sends a hybrid ClientHello compatible with both DTLS 1.2
and 1.3 servers and forks into the correct handshake once the
server responds. If the configuration only enables PSK DTLS 1.2
suites, new_auto delegates to the DTLS 1.2 PSK state machine.
Sourcepub fn protocol_version(&self) -> Option<ProtocolVersion>
pub fn protocol_version(&self) -> Option<ProtocolVersion>
Returns the negotiated DTLS protocol version.
Returns None for auto-sense instances that have not yet completed
version negotiation (i.e. still in a Pending state).
Sourcepub fn set_active(&mut self, active: bool)
pub fn set_active(&mut self, active: bool)
Switch between server and client roles.
Set active to true for client role, false for server role.
When called on an auto‑sense instance (Dtls::new_auto) the
client sends a hybrid ClientHello compatible with both DTLS 1.2
and 1.3. The version is determined from the server’s first
response.
Sourcepub fn handle_packet(&mut self, packet: &[u8]) -> Result<(), Error>
pub fn handle_packet(&mut self, packet: &[u8]) -> Result<(), Error>
Process an incoming DTLS datagram.
Sourcepub fn poll_output<'a>(&mut self, buf: &'a mut [u8]) -> Output<'a>
pub fn poll_output<'a>(&mut self, buf: &'a mut [u8]) -> Output<'a>
Poll for pending output from the DTLS engine.
Sourcepub fn handle_timeout(&mut self, now: Instant) -> Result<(), Error>
pub fn handle_timeout(&mut self, now: Instant) -> Result<(), Error>
Handle time-based events such as retransmission timers.
Sourcepub fn send_application_data(&mut self, data: &[u8]) -> Result<(), Error>
pub fn send_application_data(&mut self, data: &[u8]) -> Result<(), Error>
Send application data over the established DTLS session.
Returns Error::HandshakePending if the DTLS version has not
yet been resolved (auto-sense pending). Callers should buffer
the data externally and retry after the handshake progresses.
Sourcepub fn close(&mut self) -> Result<(), Error>
pub fn close(&mut self) -> Result<(), Error>
Initiate graceful shutdown by sending a close_notify alert.
Connected (AwaitApplicationData): queues a close_notify alert;
the next poll_output cycle yields it as
Output::Packet.
Handshake in progress: aborts immediately without sending an
alert (no authenticated channel exists). Subsequent calls to
send_application_data will return
an error.
Pending (version not yet resolved): returns
Error::HandshakePending. Callers who want to discard a pending
connection can simply drop the Dtls value.
The alert is not retransmitted (per RFC 6347 §4.2.7 / RFC 9147 §5.10).