Allow intercepting and injecting DTLS packets by fippo · Pull Request #766 · pion/dtls

fippo · 2025-12-29T08:17:10Z

which allows embedding them into STUN.

conn.go

codecov · 2026-01-07T12:57:22Z

Codecov Report

❌ Patch coverage is 93.26923% with 7 lines in your changes missing coverage. Please review.
✅ Project coverage is 82.62%. Comparing base (d0e736c) to head (d823e41).

Files with missing lines	Patch %	Lines
options.go	90.69%	4 Missing ⚠️
conn.go	95.00%	2 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #766      +/-   ##
==========================================
- Coverage   82.66%   82.62%   -0.05%     
==========================================
  Files         121      121              
  Lines        6853     6917      +64     
==========================================
+ Hits         5665     5715      +50     
- Misses        777      788      +11     
- Partials      411      414       +3

Flag	Coverage Δ
go	`82.62% <93.26%> (-0.05%)`	⬇️

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

☔ View full report in Codecov by Sentry.
📢 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.

fippo · 2026-01-07T13:47:10Z

conn.go

 	if hasHandshake {
+		if c.inboundHandshakePacketNotifier != nil {
+			// Would it be useful to know this was injected?
+			// Should this work on a copy?


I would perfer that we do not implement such logic here, thus the users of this functionality should handle it themselves. I think it's reasonable to assume that it's the same library that would both use inject and the notifier.

Sean-Der · 2026-01-07T18:38:40Z

Sorry if I am being dense @fippo, but how is the experience different then a user getting DTLS traffic via existing APIs?

theodorsm

Thanks for working on this @fippo! I think it's useful functionallity to have for multiple usecases and I think the re-factor makes sense. I have made some comments to your PR.

conn.go

theodorsm · 2026-01-07T18:34:02Z

conn.go

 			}
 			rawPackets = append(rawPackets, rawHandshakePackets...)
 		} else {
 			rawPacket, err := c.processPacket(pkt)


Non-handshake packets are still processed in the writeHandshakePackets. I assume it is only supposed to be done in the writePackets function after this refactor.

if you mean change cipher spec which doesn't have a handshake content type then yes, it is handled here since they need to go into the same network packet as part of a handshake flight (terminology... this one isn't great)

theodorsm · 2026-01-07T18:38:59Z

config.go

+	// OutboundHandshakePacketInterceptor is an optional callback that can be set to
+	// intercept outgoing raw handshake packets. It is called with the raw packet bytes.
+	// The interceptor can decide to drop the packet by returning true.
+	OutboundHandshakePacketInterceptor func(packet []byte) bool


I suggest we could make the interceptors more general and allow for modification of handshake messages, similar to the message hooks above (I already know about some usecases, for example anti-fingerprinting).

OutboundHandshakePacketInterceptor func(packet []byte) []byte and InboundHandshakePacketInterceptor func(packet []byte) []byte. Rather than a bool deciding if we drop a packet, we can drop a packet if the returned byte buffer is empty.

wouldn't such a use-case implement its own flight generator which allows way more flexibility?

theodorsm · 2026-01-07T18:41:47Z

conn_test.go

+	server, err := Server(dtlsnet.PacketConnFromConn(cb), cb.RemoteAddr(), &Config{
+		Certificates: []tls.Certificate{serverCert},
+		OutboundHandshakePacketInterceptor: func(packet []byte) bool {
+			client.InjectPacket(packet, ca.RemoteAddr())


Could you make a seprate test for injected packets? Now the interceptor and the injection functionallity are tested closely together, I would suggest seperating them. Would there be any way of testing the interceptors without using the injection functionallity?

Testing them in complete isolation is only going to result in weaker assertions like "number of handshake packets seen" whereas TestInboundNotifier asserts that what one connection is intercepting (or not) as part of the handshake is seen by the other connection.

theodorsm · 2026-01-07T18:50:17Z

Sorry if I am being dense @fippo, but how is the experience different then a user getting DTLS traffic via existing APIs

@Sean-Der the exisiting API only allows reading and writing application data, not handshake data like what is needed here. The message hooks offers some of the functionality (intercepting ClientHello, ServerHello and CertificateRequest messsages), but not all handshake messages. Correct me if I'm wrong @fippo. Unless there is some other way of getting traffic than the Conn API.

Sean-Der · 2026-01-07T18:56:52Z

@theodorsm aye, thanks for explanation :)

You should have full access to the traffic if you pass your own net.PacketConn like Client/Server

Then if you care about specific messages you can parse things via pkg/protocol

I worry about offering APIs that don't match crypto/tls because honestly they are just way better designers than anything I have done :)

theodorsm · 2026-01-07T19:49:03Z

@Sean-Der ahhh I overlooked this API, thanks, that's much cleaner! Does this solve your usecase @fippo (if so, we should close this PR)? You can take inspiration from pkg/net/net.go.

fippo · 2026-01-07T20:47:42Z

You should have full access to the traffic if you pass your own net.PacketConn like [Client/Server]

I was aware of that but that API operates on []byte which means parsing again and since it does not know the handshake is done (easily), will have to do so for every packet.

theodorsm · 2026-01-07T22:36:39Z

@fippo, with the approach in this PR we are still working with []byte beyond knowing it's a handshake message, further parsing must happen anyways. To filter out the handshake messages from the raw bytes from net.PacketConn you can use RecordLayer.Unmarshal(data []byte) error and check if RecordLayer.Header.ContentType == 22. The content is also parsed so you can check the header type and keep track of the handshake messages, if you see TypeFinished you know the handshake has successfully completed.

theodorsm · 2026-01-08T13:27:55Z

@fippo I agree with Sean about not wanting to offer the InjectPacket API on Conn. However, I think imlementing a custom net.PacketConn that exposes a InjectHandshakePacket would be cleaner, we could offer this in our net package. This custom PacketConn could also support interceptors and notifications. I see crypto/tls has a API for exposing the underlying net.Conn , we could also offer this that would allow for the flexibility needed.

Sean-Der · 2026-01-09T04:19:28Z

@fippo another sticking point is that Justin is planning on using boringssl. So the more logic you can put into pion/webrtc instead of here will make things easier.

Sorry to burn your time :( I just think in the long run it will work better for everyone. I am hesitant to make this library complicated because non-WebRTC users and it gets so much scrutiny.

Doing funky stuff in pion/webrtc ends up being easier. Tell me if I am completely off base though! I purposefully exported all the Handshake parsing code to make stuff easy.

fippo · 2026-01-09T07:32:03Z

BoringSSL needs the same interface changes - a way to get notified about incoming packets and a way to inject a packet (which is a lot simpler there) but usually wouldn't concern itself with parsing of the bytes.

fippo · 2026-01-20T08:28:22Z

new requirement which makes it even less of a fit for net.Conn: the "subscriber" needs to know when a flight is starting or complete and needs to be "flushed" (which is required to invalidate a flight in case of timeout + resend) - OpenSSL does flush but I slightly prefer a signal for start-of-flight but for compat reasons ...

which allows embedding them into STUN.

noop

fippo · 2026-03-26T11:34:18Z

(updated for options which wasn't too bad)

fippo force-pushed the dtls-intercept branch from d60f060 to a743812 Compare December 29, 2025 08:28

fippo commented Dec 29, 2025

View reviewed changes

conn.go Outdated Show resolved Hide resolved

conn.go Outdated Show resolved Hide resolved

fippo force-pushed the dtls-intercept branch 2 times, most recently from 16f2df2 to 787aa43 Compare December 31, 2025 09:58

fippo mentioned this pull request Dec 31, 2025

WARP tracking issue pion/webrtc#3335

Open

fippo force-pushed the dtls-intercept branch from 5f6193c to 09f21b1 Compare January 7, 2026 10:41

fippo force-pushed the dtls-intercept branch 2 times, most recently from ad5d88c to 9a2f30a Compare January 7, 2026 13:27

fippo marked this pull request as ready for review January 7, 2026 13:45

fippo commented Jan 7, 2026

View reviewed changes

theodorsm self-requested a review January 7, 2026 16:55

theodorsm requested changes Jan 7, 2026

View reviewed changes

fippo force-pushed the dtls-intercept branch 2 times, most recently from 2c5c975 to da78a87 Compare January 8, 2026 09:55

fippo force-pushed the dtls-intercept branch 3 times, most recently from b2eb45d to b50dd93 Compare January 21, 2026 08:08

fippo added 2 commits March 26, 2026 11:40

Allow intercepting and injecting DTLS packets

4075670

which allows embedding them into STUN.

Different way to capture the outgoing handshake

4ae6204

noop

fippo added 9 commits March 26, 2026 11:42

Add remoteAddr to inject API

c9c84c5

Add inbound handshake notifier

aab7732

Refactor

920fb40

Fix race

84473cd

Test writing handshake packet using new method

b2bd69c

Better naming

09648f2

Add end-of-flight flag (compat with openssl)

6ca1ae6

Improve test and remove whitespace change

fecd9e4

Migrate to options

d823e41

fippo force-pushed the dtls-intercept branch from cb74550 to d823e41 Compare March 26, 2026 11:20

JoTurk mentioned this pull request Apr 6, 2026

Implement SPED (STUN Protocol for Embedding DTLS) pion/webrtc#3362

Draft

Conversation

fippo commented Dec 29, 2025

Uh oh!

Uh oh!

Uh oh!

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

Uh oh!

Codecov Report

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Sean-Der commented Jan 7, 2026

Uh oh!

theodorsm left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

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

Uh oh!

Uh oh!

Sean-Der commented Jan 7, 2026

Uh oh!

theodorsm commented Jan 7, 2026

Uh oh!

fippo commented Jan 7, 2026

Uh oh!

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

Uh oh!

Uh oh!

theodorsm commented Jan 8, 2026

Uh oh!

Sean-Der commented Jan 9, 2026

Uh oh!

fippo commented Jan 9, 2026

Uh oh!

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

Uh oh!

Uh oh!

fippo commented Mar 26, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

codecov bot commented Jan 7, 2026 •

edited

Loading

theodorsm commented Jan 7, 2026 •

edited

Loading

theodorsm commented Jan 7, 2026 •

edited

Loading

fippo commented Jan 20, 2026 •

edited

Loading