DTLSTransport

Provides access to DTLS transport for secure RTP/RTCP packet transmission

Overview

The DTLSTransport allows an application access to information about the DTLS transport over which RTP and RTCP packets are sent and received by RTPSender and RTPReceiver, as well as other data such as SCTP packets sent and received by data channels.

This is part of the ORTC API. It is not meant to be used together with the basic WebRTC API.

Type Definition

dtlstransport.go

type DTLSTransport struct {
    // Contains internal state management for DTLS transport
}

Constructor

NewDTLSTransport

Creates a new DTLSTransport over an ICE transport.

dtlstransport.go

func (api *API) NewDTLSTransport(
    transport *ICETransport, 
    certificates []Certificate,
) (*DTLSTransport, error)

transport · *ICETransport · required

The underlying ICE transport to use

certificates · []Certificate

List of certificates to use for DTLS. If empty, a certificate will be generated automatically.

return · *DTLSTransport, error

Returns a new DTLSTransport instance or an error if creation fails

Example:

api := webrtc.NewAPI()
iceTransport := webrtc.NewICETransport(gatherer, api.LoggerFactory)

// Option 1: Auto-generate certificate
dtls, err := api.NewDTLSTransport(iceTransport, []webrtc.Certificate{})

// Option 2: Use custom certificates
cert, _ := webrtc.GenerateCertificate(key)
dtls, err := api.NewDTLSTransport(iceTransport, []webrtc.Certificate{*cert})

if err != nil {
    panic(err)
}

Methods

Start

Starts DTLS transport negotiation with the parameters of the remote DTLS transport.

dtlstransport.go

func (t *DTLSTransport) Start(remoteParameters DTLSParameters) error

remoteParameters · DTLSParameters · required

Remote DTLS parameters including fingerprints and role

Show DTLSParameters structure

Role · DTLSRole

DTLS role (Auto, Client, Server)

Fingerprints · []DTLSFingerprint

Certificate fingerprints for verification

Show DTLSFingerprint structure

Algorithm · string

Hash algorithm (e.g., “sha-256”)

Value · string

Fingerprint value

return · error

Returns nil on success, or an error if the transport cannot be started

Example:

remoteParams := webrtc.DTLSParameters{
    Role: webrtc.DTLSRoleAuto,
    Fingerprints: []webrtc.DTLSFingerprint{
        {
            Algorithm: "sha-256",
            Value:     "AA:BB:CC:...",
        },
    },
}

err := dtls.Start(remoteParams)
if err != nil {
    panic(err)
}

Stop

Stops and closes the DTLSTransport.

dtlstransport.go

func (t *DTLSTransport) Stop() error

return · error

Returns nil on success, or an error if stopping fails

Example:

err := dtls.Stop()
if err != nil {
    panic(err)
}

State

Returns the current DTLS transport state.

dtlstransport.go

func (t *DTLSTransport) State() DTLSTransportState

return · DTLSTransportState

The current state (New, Connecting, Connected, Closed, Failed)

Example:

state := dtls.State()
fmt.Printf("DTLS state: %s\n", state)

ICETransport

Returns the currently-configured ICETransport.

dtlstransport.go

func (t *DTLSTransport) ICETransport() *ICETransport

return · *ICETransport

Returns the underlying ICE transport or nil if not configured

Example:

iceTransport := dtls.ICETransport()
if iceTransport != nil {
    fmt.Printf("ICE transport state: %s\n", iceTransport.State())
}

GetLocalParameters

Returns the DTLS parameters of the local DTLSTransport.

dtlstransport.go

func (t *DTLSTransport) GetLocalParameters() (DTLSParameters, error)

return · DTLSParameters, error

Returns the local DTLS parameters or an error

Example:

params, err := dtls.GetLocalParameters()
if err != nil {
    panic(err)
}
for _, fp := range params.Fingerprints {
    fmt.Printf("Fingerprint (%s): %s\n", fp.Algorithm, fp.Value)
}

GetRemoteCertificate

Returns the certificate chain in use by the remote side.

dtlstransport.go

func (t *DTLSTransport) GetRemoteCertificate() []byte

return · []byte

Returns the raw DER-encoded remote certificate, or an empty slice if not yet selected

Example:

cert := dtls.GetRemoteCertificate()
if len(cert) > 0 {
    fmt.Printf("Remote certificate size: %d bytes\n", len(cert))
}

OnStateChange

Sets a handler that fires when the DTLS connection state changes.

dtlstransport.go

func (t *DTLSTransport) OnStateChange(f func(DTLSTransportState))

f · func(DTLSTransportState) · required

Callback function that receives state change notifications

Example:

dtls.OnStateChange(func(state webrtc.DTLSTransportState) {
    fmt.Printf("DTLS state changed to: %s\n", state)
    
    switch state {
    case webrtc.DTLSTransportStateConnected:
        fmt.Println("DTLS handshake complete")
    case webrtc.DTLSTransportStateFailed:
        fmt.Println("DTLS handshake failed")
    case webrtc.DTLSTransportStateClosed:
        fmt.Println("DTLS transport closed")
    }
})

WriteRTCP

Sends user-provided RTCP packets to the connected peer.

dtlstransport.go

func (t *DTLSTransport) WriteRTCP(pkts []rtcp.Packet) (int, error)

pkts · []rtcp.Packet · required

RTCP packets to send

return · int, error

Returns the number of bytes written and any error that occurred

Example:

import "github.com/pion/rtcp"

pkt := &rtcp.PictureLossIndication{
    MediaSSRC: 12345,
}

n, err := dtls.WriteRTCP([]rtcp.Packet{pkt})
if err != nil {
    panic(err)
}
fmt.Printf("Wrote %d bytes\n", n)

States

The DTLSTransport can be in one of the following states:

• DTLSTransportStateNew: Initial state
• DTLSTransportStateConnecting: DTLS handshake in progress
• DTLSTransportStateConnected: DTLS handshake completed successfully
• DTLSTransportStateClosed: Transport has been closed
• DTLSTransportStateFailed: DTLS handshake or connection failed

DTLS Roles

The DTLSTransport can operate in different roles:

• DTLSRoleAuto: Role is determined automatically based on ICE role
• DTLSRoleClient: Acts as DTLS client (initiates handshake)
• DTLSRoleServer: Acts as DTLS server (responds to handshake)

Usage Example

Complete Example

package main

import (
    "fmt"
    "github.com/pion/webrtc/v4"
)

func main() {
    // Create API
    api := webrtc.NewAPI()
    
    // Set up ICE transport
    gatherer, err := api.NewICEGatherer(webrtc.ICEGatherOptions{
        ICEServers: []webrtc.ICEServer{
            {URLs: []string{"stun:stun.l.google.com:19302"}},
        },
    })
    if err != nil {
        panic(err)
    }
    
    iceTransport := webrtc.NewICETransport(gatherer, api.LoggerFactory)
    
    // Create DTLS transport with auto-generated certificate
    dtls, err := api.NewDTLSTransport(iceTransport, []webrtc.Certificate{})
    if err != nil {
        panic(err)
    }
    defer dtls.Stop()
    
    // Set up state change handler
    dtls.OnStateChange(func(state webrtc.DTLSTransportState) {
        fmt.Printf("DTLS state: %s\n", state)
    })
    
    // Get local parameters to send via signaling
    localParams, err := dtls.GetLocalParameters()
    if err != nil {
        panic(err)
    }
    fmt.Printf("Local DTLS fingerprints: %+v\n", localParams.Fingerprints)
    
    // Start ICE
    if err = gatherer.Gather(); err != nil {
        panic(err)
    }
    
    iceRole := webrtc.ICERoleControlling
    if err = iceTransport.Start(nil, remoteICEParams, &iceRole); err != nil {
        panic(err)
    }
    
    // Start DTLS with remote parameters (from signaling)
    remoteParams := webrtc.DTLSParameters{
        Role: webrtc.DTLSRoleAuto,
        Fingerprints: []webrtc.DTLSFingerprint{
            {
                Algorithm: "sha-256",
                Value:     remoteFingerprintValue,
            },
        },
    }
    
    if err = dtls.Start(remoteParams); err != nil {
        panic(err)
    }
    
    // Wait for DTLS to connect
    for dtls.State() != webrtc.DTLSTransportStateConnected {
        if dtls.State() == webrtc.DTLSTransportStateFailed {
            panic("DTLS failed")
        }
        time.Sleep(100 * time.Millisecond)
    }
    
    fmt.Println("DTLS connected successfully!")
    
    // Get remote certificate
    remoteCert := dtls.GetRemoteCertificate()
    fmt.Printf("Remote certificate: %d bytes\n", len(remoteCert))
}

Security Considerations

DTLS certificate fingerprint verification is critical for security. The fingerprints must be exchanged over a secure signaling channel and verified before establishing the DTLS connection.

Fingerprint Verification

The DTLS handshake includes automatic verification of the remote certificate’s fingerprint against the fingerprints provided in the remote parameters. This prevents man-in-the-middle attacks.

Certificate Lifetime

By default, auto-generated certificates are valid for 1 month. For production use, consider:

• Using longer-lived certificates
• Implementing certificate rotation
• Monitoring certificate expiration

See Also

• ICETransport - Underlying ICE transport
• Certificate - DTLS certificate management
• PeerConnection - High-level WebRTC API
• SRTP - Secure RTP specification