Expose the negotiated DTLS protocol version

tyhik · web-flow · commit 05ba8d035ea9 · 2026-06-21T11:26:39.000+02:00
diff --git a/crates/proto/src/crypto/mod.rs b/crates/proto/src/crypto/mod.rs
@@ -14,6 +14,7 @@ pub mod dtls {
 
     pub use dimpl::DtlsCertificate as DtlsCert;
     pub use dimpl::KeyingMaterial;
+    pub use dimpl::ProtocolVersion;
     pub use dimpl::SrtpProfile;
     // Note: dimpl::Error is renamed to DtlsImplError to avoid conflict with str0m's DtlsError
     pub use dimpl::{Error as DtlsImplError, Output as DtlsOutput};
diff --git a/crates/proto/src/crypto/provider.rs b/crates/proto/src/crypto/provider.rs
@@ -189,6 +189,9 @@ pub trait DtlsInstance: CryptoSafe {
 
     /// Return true if the instance is operating in the client role.
     fn is_active(&self) -> bool;
+
+    /// Return the negotiated DTLS protocol version. May return `None` before handshake completion.
+    fn protocol_version(&self) -> Option<ProtocolVersion>;
 }
 
 // ============================================================================
diff --git a/crypto/apple-crypto/src/dtls.rs b/crypto/apple-crypto/src/dtls.rs
@@ -7,6 +7,7 @@ use std::sync::Arc;
 use std::time::Instant;
 use str0m_proto::crypto::CryptoError;
 use str0m_proto::crypto::DtlsVersion;
+use str0m_proto::crypto::dtls::ProtocolVersion;
 use str0m_proto::crypto::dtls::{DtlsCert, DtlsImplError, DtlsInstance, DtlsOutput, DtlsProvider};
 
 // Certificate Generation
@@ -164,6 +165,10 @@ impl DtlsInstance for AppleCryptoDtlsInstance {
     fn is_active(&self) -> bool {
         self.dtls.is_active()
     }
+
+    fn protocol_version(&self) -> Option<ProtocolVersion> {
+        self.dtls.protocol_version()
+    }
 }
 
 #[cfg(test)]
diff --git a/crypto/aws-lc-rs/src/dtls.rs b/crypto/aws-lc-rs/src/dtls.rs
@@ -5,6 +5,7 @@ use std::time::Instant;
 
 use str0m_proto::crypto::CryptoError;
 use str0m_proto::crypto::DtlsVersion;
+use str0m_proto::crypto::dtls::ProtocolVersion;
 use str0m_proto::crypto::dtls::{DtlsCert, DtlsImplError, DtlsInstance, DtlsOutput, DtlsProvider};
 
 // ============================================================================
@@ -106,4 +107,8 @@ impl DtlsInstance for AwsLcRsDtlsInstance {
     fn is_active(&self) -> bool {
         self.dtls.is_active()
     }
+
+    fn protocol_version(&self) -> Option<ProtocolVersion> {
+        self.dtls.protocol_version()
+    }
 }
diff --git a/crypto/openssl/src/dtls_dimpl.rs b/crypto/openssl/src/dtls_dimpl.rs
@@ -4,6 +4,7 @@ use std::sync::Arc;
 use std::time::Instant;
 
 use str0m_proto::crypto::dtls::DtlsImplError;
+use str0m_proto::crypto::dtls::ProtocolVersion;
 use str0m_proto::crypto::dtls::{DtlsCert, DtlsInstance, DtlsOutput, DtlsProvider};
 use str0m_proto::crypto::{CryptoError, DtlsVersion};
 
@@ -107,4 +108,8 @@ impl DtlsInstance for DimplDtlsInstance {
     fn is_active(&self) -> bool {
         self.dtls.is_active()
     }
+
+    fn protocol_version(&self) -> Option<ProtocolVersion> {
+        self.dtls.protocol_version()
+    }
 }
diff --git a/crypto/openssl/src/dtls_ossl.rs b/crypto/openssl/src/dtls_ossl.rs
@@ -13,7 +13,7 @@ use openssl::ssl::{SslOptions, SslStream, SslVerifyMode};
 use openssl::x509::X509;
 
 use str0m_proto::DATAGRAM_MTU_TARGET;
-use str0m_proto::crypto::dtls::{DtlsCert, KeyingMaterial, SrtpProfile};
+use str0m_proto::crypto::dtls::{DtlsCert, KeyingMaterial, ProtocolVersion, SrtpProfile};
 use str0m_proto::crypto::dtls::{DtlsImplError, DtlsInstance, DtlsOutput, DtlsProvider};
 use str0m_proto::crypto::{CryptoError, DtlsVersion};
 
@@ -611,6 +611,10 @@ impl DtlsInstance for OsslDtlsInstance {
     fn is_active(&self) -> bool {
         self.inner.is_active().unwrap_or(false)
     }
+
+    fn protocol_version(&self) -> Option<ProtocolVersion> {
+        Some(ProtocolVersion::DTLS1_2)
+    }
 }
 
 // ============================================================================
diff --git a/crypto/rust-crypto/src/dtls.rs b/crypto/rust-crypto/src/dtls.rs
@@ -5,6 +5,7 @@ use std::time::Instant;
 
 use str0m_proto::crypto::CryptoError;
 use str0m_proto::crypto::DtlsVersion;
+use str0m_proto::crypto::dtls::ProtocolVersion;
 use str0m_proto::crypto::dtls::{DtlsCert, DtlsImplError, DtlsInstance, DtlsOutput, DtlsProvider};
 
 // ============================================================================
@@ -106,4 +107,8 @@ impl DtlsInstance for RustCryptoDtlsInstance {
     fn is_active(&self) -> bool {
         self.dtls.is_active()
     }
+
+    fn protocol_version(&self) -> Option<ProtocolVersion> {
+        self.dtls.protocol_version()
+    }
 }
diff --git a/crypto/wincrypto/src/dtls_dimpl.rs b/crypto/wincrypto/src/dtls_dimpl.rs
@@ -5,6 +5,7 @@ use std::time::Instant;
 
 use str0m_proto::crypto::CryptoError;
 use str0m_proto::crypto::DtlsVersion;
+use str0m_proto::crypto::dtls::ProtocolVersion;
 use str0m_proto::crypto::dtls::{DtlsCert, DtlsImplError, DtlsInstance, DtlsOutput, DtlsProvider};
 
 use dimpl::{Config, Dtls, DtlsCertificate};
@@ -97,6 +98,10 @@ impl DtlsInstance for WinCryptoDtlsInstance {
     fn is_active(&self) -> bool {
         self.dtls.is_active()
     }
+
+    fn protocol_version(&self) -> Option<ProtocolVersion> {
+        self.dtls.protocol_version()
+    }
 }
 
 // ============================================================================
diff --git a/crypto/wincrypto/src/dtls_schannel.rs b/crypto/wincrypto/src/dtls_schannel.rs
@@ -5,7 +5,7 @@ use std::sync::{Arc, LazyLock, Mutex};
 use std::time::{Duration, Instant};
 use str0m_proto::DATAGRAM_MTU_TARGET;
 use str0m_proto::crypto::dtls::{DtlsCert, DtlsImplError, DtlsInstance, DtlsOutput, DtlsProvider};
-use str0m_proto::crypto::dtls::{KeyingMaterial, SrtpProfile};
+use str0m_proto::crypto::dtls::{KeyingMaterial, ProtocolVersion, SrtpProfile};
 use str0m_proto::crypto::{CryptoError, DtlsVersion};
 
 use crate::sys::{Certificate, Dtls, DtlsEvent};
@@ -248,4 +248,8 @@ impl DtlsInstance for WinCryptoDtlsInstance {
     fn is_active(&self) -> bool {
         self.dtls.is_client().unwrap_or(false)
     }
+
+    fn protocol_version(&self) -> Option<ProtocolVersion> {
+        Some(ProtocolVersion::DTLS1_2)
+    }
 }
diff --git a/src/change/direct.rs b/src/change/direct.rs
@@ -4,6 +4,7 @@ use crate::Rtc;
 use crate::RtcError;
 use crate::channel::ChannelId;
 use crate::crypto::Fingerprint;
+use crate::crypto::dtls::ProtocolVersion;
 use crate::media::{Media, MediaKind};
 use crate::rtp_::MidRid;
 use crate::rtp_::{Mid, Rid, Ssrc};
@@ -100,6 +101,15 @@ impl<'a> DirectApi<'a> {
         self.rtc.dtls.remote_fingerprint()
     }
 
+    /// Returns the negotiated DTLS protocol version.
+    ///
+    /// Call this after receiving [`crate::Event::Connected`]
+    /// to learn the negotiated DTLS version. Before the handshake completes,
+    /// this may return `None`
+    pub fn dtls_protocol_version(&self) -> Option<ProtocolVersion> {
+        self.rtc.dtls.protocol_version()
+    }
+
     /// Sets the remote DTLS fingerprint.
     pub fn set_remote_fingerprint(&mut self, dtls_fingerprint: Fingerprint) {
         self.rtc.remote_fingerprint = Some(dtls_fingerprint);
diff --git a/src/crypto/mod.rs b/src/crypto/mod.rs
@@ -12,6 +12,7 @@ pub mod dtls {
 
     pub use dimpl::DtlsCertificate as DtlsCert;
     pub use dimpl::KeyingMaterial;
+    pub use dimpl::ProtocolVersion;
     pub use dimpl::SrtpProfile;
     // Note: dimpl::Error is renamed to DtlsImplError to avoid conflict with str0m's DtlsError
     pub use super::provider::DtlsVersion;
diff --git a/src/dtls.rs b/src/dtls.rs
@@ -6,7 +6,7 @@ use std::time::Instant;
 
 use crate::crypto::Fingerprint;
 use crate::crypto::Sha256Provider;
-use crate::crypto::dtls::{DtlsCert, DtlsOutput};
+use crate::crypto::dtls::{DtlsCert, DtlsOutput, ProtocolVersion};
 use crate::crypto::dtls::{DtlsInstance, DtlsProvider, DtlsVersion};
 use crate::crypto::{CryptoError, DtlsError};
 use crate::io::DatagramSend;
@@ -113,6 +113,11 @@ impl Dtls {
         self.remote_fingerprint.as_ref()
     }
 
+    /// The negotiated DTLS protocol version, or `None` before handshake completion.
+    pub fn protocol_version(&self) -> Option<ProtocolVersion> {
+        self.instance.protocol_version()
+    }
+
     /// Set the remote fingerprint (extracted from peer certificate).
     pub fn set_remote_fingerprint(&mut self, fingerprint: Fingerprint) {
         self.remote_fingerprint = Some(fingerprint);
diff --git a/tests/handshake-direct.rs b/tests/handshake-direct.rs
@@ -7,6 +7,7 @@ use std::time::{Duration, Instant};
 
 use str0m::channel::{ChannelConfig, ChannelId, Reliability};
 use str0m::config::{DtlsVersion, Fingerprint};
+use str0m::crypto::dtls::ProtocolVersion;
 use str0m::ice::IceCreds;
 use str0m::net::{Protocol, Receive};
 use str0m::{Candidate, Event, IceConnectionState, Input, Output, Rtc, RtcConfig, RtcError};
@@ -226,6 +227,8 @@ fn run_direct_handshake(
                     &server_packets_sent_clone,
                 )?;
 
+                timing.dtls_protocol_version = rtc.direct_api().dtls_protocol_version();
+
                 Ok(timing)
             })();
 
@@ -300,6 +303,8 @@ fn run_direct_handshake(
                     &client_packets_sent_clone,
                 )?;
 
+                timing.dtls_protocol_version = rtc.direct_api().dtls_protocol_version();
+
                 Ok(timing)
             })();
 
@@ -376,6 +381,26 @@ fn run_direct_handshake(
         "Server should have sent reply"
     );
 
+    // Verify the negotiated DTLS protocol version matches the expected outcome
+    // for the requested (client, server) version combination. DTLS 1.3 and Auto
+    // variants are tested only with dimpl.
+    let expected = match (client_dtls, server_dtls) {
+        (DtlsVersion::Dtls12, _) | (_, DtlsVersion::Dtls12) => ProtocolVersion::DTLS1_2,
+        (DtlsVersion::Dtls13, _) | (_, DtlsVersion::Dtls13) => ProtocolVersion::DTLS1_3,
+        (DtlsVersion::Auto, DtlsVersion::Auto) => ProtocolVersion::DTLS1_3,
+        _ => unreachable!("unexpected DTLS version combo: {client_dtls:?}/{server_dtls:?}"),
+    };
+    assert_eq!(
+        client_timing.dtls_protocol_version,
+        Some(expected),
+        "Client negotiated DTLS version mismatch"
+    );
+    assert_eq!(
+        server_timing.dtls_protocol_version,
+        Some(expected),
+        "Server negotiated DTLS version mismatch"
+    );
+
     Ok(())
 }
 
@@ -516,6 +541,7 @@ struct TimingReport {
     channel_open: Option<Instant>,
     sent_data: Option<Instant>,
     received_data: Option<Instant>,
+    dtls_protocol_version: Option<ProtocolVersion>,
 }
 
 impl TimingReport {

Original file line number	Diff line number	Diff line change
`@@ -189,6 +189,9 @@ pub trait DtlsInstance: CryptoSafe {`
`189`	`189`
`190`	`190`	`/// Return true if the instance is operating in the client role.`
`191`	`191`	`fn is_active(&self) -> bool;`
	`192`	`+`
	`193`	+ /// Return the negotiated DTLS protocol version. May return `None` before handshake completion.
	`194`	`+ fn protocol_version(&self) -> Option<ProtocolVersion>;`
`192`	`195`	`}`
`193`	`196`
`194`	`197`	`// ============================================================================`
Original file line number	Diff line number	Diff line change
`@@ -5,6 +5,7 @@ use std::time::Instant;`
`5`	`5`
`6`	`6`	`use str0m_proto::crypto::CryptoError;`
`7`	`7`	`use str0m_proto::crypto::DtlsVersion;`
	`8`	`+use str0m_proto::crypto::dtls::ProtocolVersion;`
`8`	`9`	`use str0m_proto::crypto::dtls::{DtlsCert, DtlsImplError, DtlsInstance, DtlsOutput, DtlsProvider};`
`9`	`10`
`10`	`11`	`// ============================================================================`
`@@ -106,4 +107,8 @@ impl DtlsInstance for AwsLcRsDtlsInstance {`
`106`	`107`	`fn is_active(&self) -> bool {`
`107`	`108`	`self.dtls.is_active()`
`108`	`109`	`}`
	`110`	`+`
	`111`	`+ fn protocol_version(&self) -> Option<ProtocolVersion> {`
	`112`	`+ self.dtls.protocol_version()`
	`113`	`+ }`
`109`	`114`	`}`
Original file line number	Diff line number	Diff line change
`@@ -4,6 +4,7 @@ use std::sync::Arc;`
`4`	`4`	`use std::time::Instant;`
`5`	`5`
`6`	`6`	`use str0m_proto::crypto::dtls::DtlsImplError;`
	`7`	`+use str0m_proto::crypto::dtls::ProtocolVersion;`
`7`	`8`	`use str0m_proto::crypto::dtls::{DtlsCert, DtlsInstance, DtlsOutput, DtlsProvider};`
`8`	`9`	`use str0m_proto::crypto::{CryptoError, DtlsVersion};`
`9`	`10`
`@@ -107,4 +108,8 @@ impl DtlsInstance for DimplDtlsInstance {`
`107`	`108`	`fn is_active(&self) -> bool {`
`108`	`109`	`self.dtls.is_active()`
`109`	`110`	`}`
	`111`	`+`
	`112`	`+ fn protocol_version(&self) -> Option<ProtocolVersion> {`
	`113`	`+ self.dtls.protocol_version()`
	`114`	`+ }`
`110`	`115`	`}`