Implement SPED (STUN Protocol for Embedding DTLS) by fippo · Pull Request #876 · pion/ice

fippo · 2026-01-19T18:06:09Z

(based on #914 )

codecov · 2026-01-19T20:19:36Z

Codecov Report

❌ Patch coverage is 98.89503% with 2 lines in your changes missing coverage. Please review.
✅ Project coverage is 88.65%. Comparing base (1229c56) to head (acaa53d).
⚠️ Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
agent.go	92.85%	1 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #876      +/-   ##
==========================================
+ Coverage   88.25%   88.65%   +0.39%     
==========================================
  Files          46       47       +1     
  Lines        6293     6459     +166     
==========================================
+ Hits         5554     5726     +172     
+ Misses        504      499       -5     
+ Partials      235      234       -1

Flag	Coverage Δ
go	`88.65% <98.89%> (+0.39%)`	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

which will be used in pion#876 where the presence of some attributes depends on whether they were used in the original request.

which will be used in #876 where the presence of some attributes depends on whether they were used in the original request. (split from that to make review simpler, no functional changes)

cnderrauber · 2026-07-13T02:17:52Z

Thank you for this great feature! I have integrated this into the livekit SFU and made some connectivity checks, found 2 regression cases:

The ice-lite agent doesn't ping the remote actively, so the piggyback packets will be sent in response to the remote peer's connectivity check, cost longer than the non-sped case. Fixing this could conflict with spec, maybe we can mark it as an exception.
When a remote peer sends a done signal after the agent is connected while still having inflight piggyback packets, it will mark the state to complete and doesn't have a chance to flush the packets. And also the Piggyback() will swallow all dtls packets but return true in this state (complete after connected).

Both are fixed in our fork livekit@85afccd, livekit@5eec925. Will merge them back to upstream once this PR is merged if they make sense.

fippo · 2026-08-10T18:52:41Z

I gave up and resynced with C++ logic ...

Copilot

Pull request overview

Implements SPED by embedding DTLS handshake packets and acknowledgements in ICE STUN exchanges.

Changes:

Adds the SPED piggybacking state machine and public DTLS hooks.
Integrates SPED attributes into connectivity checks and responses.
Adds state-machine, fallback, and integration tests.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

File	Description
`agent.go`	Initializes SPED and flushes fallback packets.
`selection.go`	Processes SPED attributes during ICE selection.
`piggyback.go`	Implements SPED packet and ACK handling.
`piggyback_test.go`	Tests SPED negotiation and fallback behavior.

Suppressed comments (2)

piggyback.go:188

This transition can leave an unacknowledged local flight in packets, but Complete prevents it from being embedded again. If ICE is already connected, flushOnConnected has already run, so the flight is stranded and the peer's DTLS handshake can stall. Drain outstanding packets as plain DTLS when completing an already-connected controller, and make flushOnConnected also drain Complete for the opposite event ordering.

	if packet == nil && acks == nil && a.piggyback.state == PiggybackingStatePending {
		a.log.Info("Done with the SPED handshake")
		a.piggyback.acks = nil
		a.piggyback.state = PiggybackingStateComplete

piggyback.go:216

A non-nil ACK attribute is treated as final even when it is empty or acknowledges only older packets. After ACK deletion, verify that the outgoing queue is empty before entering Complete; otherwise a reordered connectivity check can permanently stop retransmission of the still-unacknowledged flight.

	// The response to the final flight will not contain DTLS data but an ack.
	if packet == nil && acks != nil && a.piggyback.state == PiggybackingStatePending {
		a.log.Info("Done with the SPED handshake")
		a.piggyback.acks = nil
		a.piggyback.state = PiggybackingStateComplete

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

+				for _, p := range packets {
+					_, _ = pair.Write(p.data)
+				}


JoTurk

sorry for all the back and forth :(

Part of pion/webrtc#3335

fippo · 2026-08-16T09:03:04Z

still reasonable given the amount of cross-repo work required. Now it also seems we need to plumb ice-options if this is to be negotiated with ice-options ...

JoTurk

Just two nits, looks great, thank you and sorry again

JoTurk · 2026-08-16T14:43:41Z

+// flight has to keep it around until it gets acknowledged; that is the server
+// in DTLS 1.2 and the client in DTLS 1.3. The other party has nothing more to
+// send and drops its outgoing packets.
+func (a *Agent) SetDtlsHandshakeComplete(isClient, isDtls13 bool) {


Maybe instead of isdtls13 we should just have uint16 value of the version as a go "enum"

type dtlsVersion uint16 const ( DTLS12 dtlsVersion = 0xfefd DTLS13 dtlsVersion = 0xfefc )

this becomes an export hassle and I do not think we will have DTLS 1.4 anytime soon (and nobody likes 1.0)

I agree but isdtls13 just doesn't feel "right" for a public api, but I don't have a hard feeling about this :)

yeah but ideally DTLS defines its version but ice can't import from DTLS and lots of conversion and ... :-|

We export the versions in dtls/pkg/protocol https://github.com/pion/dtls/blob/main/pkg/protocol/version.go and ice can import them and they are released with v3 so we don't have to wait for v4 :)

yes but that creates a rather awkward dep from ice on dtls...

Ice already imports dtls directly xd https://github.com/pion/ice/blob/main/go.mod

whyyyyyyyyy...

(will update, awkwardness is not on me!)

JoTurk · 2026-08-16T18:10:00Z

Also I wonder if we should move the sped methods into a new optional object that the user can pass to options With sped(controller) so we don't have methods on agents but this isn't a big deal because ice is a due for an api rework and refactor and we can do all of this in the next major release. And release this for now.

zshang-oai · 2026-08-17T17:37:04Z

From my Codex and internal security tool, just for your reference @fippo

Security concern: reportPiggybackingFromMessage extracts DTLS-IN-STUN and DTLS-IN-STUN-ACK without checking whether those attributes appear before MESSAGE-INTEGRITY.
Since STUN integrity only authenticates attributes preceding MESSAGE-INTEGRITY, an attacker could append SPED attributes after a valid integrity field without invalidating the existing HMAC. Those unauthenticated attributes would still reach ReportPiggybacking, potentially injecting DTLS data or modifying ACK state.
Could we either enable strict STUN decoding or explicitly reject SPED attributes appearing after MESSAGE-INTEGRITY? Regression tests should cover both appended DTLS and ACK attributes.

fippo · 2026-08-17T17:40:46Z

pion/stun#273 should be on by default?

JoTurk · 2026-08-17T17:43:47Z

@fippo we're going to tag a new major release for STUN soon because of pion/stun#284 maybe we can switch strict mode to be on by default?

fippo · 2026-08-17T18:52:07Z

@JoTurk ah... we didn't ship that. Yes, lets do it as part of a breaking change.

fippo force-pushed the sped-remainder branch from 4926e2b to 0e2f82c Compare January 19, 2026 18:06

fippo mentioned this pull request Jan 19, 2026

WARP tracking issue pion/webrtc#3335

Open

fippo force-pushed the sped-remainder branch from 0e2f82c to 0652e63 Compare January 19, 2026 20:14

fippo force-pushed the sped-remainder branch 5 times, most recently from 10ebcd0 to 53df31e Compare January 30, 2026 17:37

fippo force-pushed the sped-remainder branch from 53df31e to 5cd2335 Compare March 26, 2026 13:12

fippo marked this pull request as ready for review March 26, 2026 18:53

fippo mentioned this pull request Apr 24, 2026

Make it possible to conditionally insert attributes #914

Merged

fippo added a commit to fippo/pion-ice that referenced this pull request Apr 24, 2026

Make it possible to conditionally add attributes

36cee05

which will be used in pion#876 where the presence of some attributes depends on whether they were used in the original request.

fippo force-pushed the sped-remainder branch from a84baa4 to 9d6609c Compare April 24, 2026 12:02

fippo mentioned this pull request Apr 24, 2026

Fix SPED fallback and write edge cases zshang-oai/ice#1

Draft

fippo added a commit to fippo/pion-ice that referenced this pull request Apr 25, 2026

Make it possible to conditionally add attributes

2339173

which will be used in pion#876 where the presence of some attributes depends on whether they were used in the original request.

fippo added a commit to fippo/pion-ice that referenced this pull request Apr 25, 2026

Make it possible to conditionally add attributes

7d83822

which will be used in pion#876 where the presence of some attributes depends on whether they were used in the original request.

fippo added a commit to fippo/pion-ice that referenced this pull request Apr 25, 2026

Make it possible to conditionally add attributes

1439985

which will be used in pion#876 where the presence of some attributes depends on whether they were used in the original request.

fippo added a commit to fippo/pion-ice that referenced this pull request Apr 25, 2026

Make it possible to conditionally add attributes

df5aa48

which will be used in pion#876 where the presence of some attributes depends on whether they were used in the original request.

fippo added a commit to fippo/pion-ice that referenced this pull request Apr 25, 2026

Make it possible to conditionally add attributes

e613086

which will be used in pion#876 where the presence of some attributes depends on whether they were used in the original request.

fippo added a commit to fippo/pion-ice that referenced this pull request Apr 25, 2026

Make it possible to conditionally add attributes

4a5d40b

which will be used in pion#876 where the presence of some attributes depends on whether they were used in the original request.

fippo force-pushed the sped-remainder branch from 9d6609c to 0ab695f Compare April 25, 2026 17:59

fippo mentioned this pull request Apr 28, 2026

renomination adds attributes after message-integrity and fingerprint #915

Closed

zshang-oai force-pushed the sped-remainder branch from 0ab695f to e9d8b98 Compare April 28, 2026 23:11

fippo force-pushed the sped-remainder branch 2 times, most recently from 1ea6639 to c7f08eb Compare May 4, 2026 12:55

fippo force-pushed the sped-remainder branch from 2f3305b to 95838f7 Compare May 15, 2026 17:49

JoTurk self-requested a review June 2, 2026 12:59

JoTurk reviewed Aug 5, 2026

View reviewed changes

Comment thread piggyback.go

fippo force-pushed the sped-remainder branch 4 times, most recently from ec416a1 to 3d4ec7a Compare August 10, 2026 18:47

JoTurk requested review from JoTurk and a balanced review from Copilot August 15, 2026 21:15

Copilot started reviewing on behalf of JoTurk August 15, 2026 21:16 View session

Copilot AI reviewed Aug 15, 2026

View reviewed changes

Comment thread agent.go Outdated

Comment on lines +801 to +803

for _, p := range packets {

_, _ = pair.Write(p.data)

}

Comment thread piggyback.go

JoTurk reviewed Aug 15, 2026

View reviewed changes

Comment thread piggyback.go Outdated

JoTurk reviewed Aug 15, 2026

View reviewed changes

Comment thread piggyback.go Outdated

JoTurk reviewed Aug 15, 2026

View reviewed changes

fippo added 5 commits August 16, 2026 10:11

Implement SPED (STUN Protocol for Embedding DTLS)

3c573e0

Part of pion/webrtc#3335

Move some sped/piggyback things to separate files

82a6469

Move things around

86f94ea

CR Feedback

cba27e2

Sync with libwebrtc M144

ec4062f

fippo force-pushed the sped-remainder branch from 3d4ec7a to cfaf012 Compare August 16, 2026 08:54

Feedback++

62f0be1

fippo force-pushed the sped-remainder branch from cfaf012 to 62f0be1 Compare August 16, 2026 09:02

JoTurk approved these changes Aug 16, 2026

View reviewed changes

Clones++

52895f5

Import dtls.version

acaa53d

Uh oh!

Conversation

fippo commented Jan 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codecov Bot commented Jan 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

cnderrauber commented Jul 13, 2026

Uh oh!

Uh oh!

fippo commented Aug 10, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

JoTurk left a comment

Choose a reason for hiding this comment

Uh oh!

fippo commented Aug 16, 2026

Uh oh!

JoTurk left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

JoTurk Aug 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

fippo Aug 16, 2026

Choose a reason for hiding this comment

Uh oh!

JoTurk Aug 16, 2026

Choose a reason for hiding this comment

Uh oh!

fippo Aug 16, 2026

Choose a reason for hiding this comment

Uh oh!

JoTurk Aug 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

fippo Aug 16, 2026

Choose a reason for hiding this comment

Uh oh!

JoTurk Aug 16, 2026

Choose a reason for hiding this comment

Uh oh!

fippo Aug 16, 2026

Choose a reason for hiding this comment

Uh oh!

JoTurk commented Aug 16, 2026

Uh oh!

zshang-oai commented Aug 17, 2026

Uh oh!

fippo commented Aug 17, 2026

Uh oh!

JoTurk commented Aug 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

fippo commented Aug 17, 2026

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

5 participants

fippo commented Jan 19, 2026 •

edited

Loading

codecov Bot commented Jan 19, 2026 •

edited

Loading

JoTurk Aug 16, 2026 •

edited

Loading

JoTurk Aug 16, 2026 •

edited

Loading

JoTurk commented Aug 17, 2026 •

edited

Loading