srtp

package module
v3.0.7 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 12, 2025 License: MIT Imports: 21 Imported by: 15

README


Pion SRTP

A Go implementation of SRTP

Pion SRTP Sourcegraph Widget join us on Discord Follow us on Bluesky
GitHub Workflow Status Go Reference Coverage Status Go Report Card


Roadmap

The library is used as a part of our WebRTC implementation. Please refer to that roadmap to track our major milestones.

Community

Pion has an active community on the Discord.

Follow the Pion Bluesky or Pion Twitter for project updates and important WebRTC news.

We are always looking to support your projects. Please reach out if you have something to build! If you need commercial support or don't want to use public methods you can contact us at team@pion.ly

Contributing

Check out the contributing wiki to join the group of amazing people making this project possible

License

MIT License - see LICENSE for full text

Documentation

Overview

Package srtp implements Secure Real-time Transport Protocol

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrFailedToVerifyAuthTag is returned when decryption fails due to invalid authentication tag.
	ErrFailedToVerifyAuthTag = errors.New("failed to verify auth tag")
	// ErrMKINotFound is returned when decryption fails due to unknown MKI value in packet.
	ErrMKINotFound = errors.New("MKI not found")
)

Functions

This section is empty.

Types

type Config 

type Config struct {
	Keys                SessionKeys
	Profile             ProtectionProfile
	BufferFactory       func(packetType packetio.BufferPacketType, ssrc uint32) io.ReadWriteCloser
	LoggerFactory       logging.LoggerFactory
	AcceptStreamTimeout time.Time

	// List of local/remote context options.
	// ReplayProtection is enabled on remote context by default.
	// Default replay protection window size is 64.
	LocalOptions, RemoteOptions []ContextOption
}

Config is used to configure a session. You can provide either a KeyingMaterialExporter to export keys or directly pass the keys themselves. After a Config is passed to a session it must not be modified.

func (*Config) ExtractSessionKeysFromDTLS 

func (c *Config) ExtractSessionKeysFromDTLS(exporter KeyingMaterialExporter, isClient bool) error

ExtractSessionKeysFromDTLS allows setting the Config SessionKeys by extracting them from DTLS. This behavior is defined in RFC5764: https://tools.ietf.org/html/rfc5764

type Context 

type Context struct {
	// contains filtered or unexported fields
}

Context represents a SRTP cryptographic context. Context can only be used for one-way operations. it must either used ONLY for encryption or ONLY for decryption. Note that Context does not provide any concurrency protection: access to a Context from multiple goroutines requires external synchronization.

func CreateContext 

func CreateContext(
	masterKey, masterSalt []byte,
	profile ProtectionProfile,
	opts ...ContextOption,
) (c *Context, err error)

CreateContext creates a new SRTP Context.

CreateContext receives variable number of ContextOption-s. Passing multiple options which set the same parameter let the last one valid. Following example create SRTP Context with replay protection with window size of 256. 

decCtx, err := srtp.CreateContext(key, salt, profile, srtp.SRTPReplayProtection(256))

func (*Context) AddCipherForMKI added in v3.0.3 

func (c *Context) AddCipherForMKI(mki, masterKey, masterSalt []byte) error

AddCipherForMKI adds new MKI with associated masker key and salt. Context must be created with MasterKeyIndicator option to enable MKI support. MKI must be unique and have the same length as the one used for creating Context. Operation is not thread-safe, you need to provide synchronization with decrypting packets.

func (*Context) DecryptRTCP 

func (c *Context) DecryptRTCP(dst, encrypted []byte, header *rtcp.Header) ([]byte, error)

DecryptRTCP decrypts a buffer that contains a RTCP packet.

func (*Context) DecryptRTP 

func (c *Context) DecryptRTP(dst, encrypted []byte, header *rtp.Header) ([]byte, error)

DecryptRTP decrypts a RTP packet with an encrypted payload.

func (*Context) EncryptRTCP 

func (c *Context) EncryptRTCP(dst, decrypted []byte, header *rtcp.Header) ([]byte, error)

EncryptRTCP Encrypts a RTCP packet.

func (*Context) EncryptRTP 

func (c *Context) EncryptRTP(dst []byte, plaintext []byte, header *rtp.Header) ([]byte, error)

EncryptRTP marshals and encrypts an RTP packet, writing to the dst buffer provided. If the dst buffer does not have the capacity to hold `len(plaintext) + 10` bytes, a new one will be allocated and returned. If a rtp.Header is provided, it will be Unmarshaled using the plaintext.

func (*Context) Index 

func (c *Context) Index(ssrc uint32) (uint32, bool)

Index returns SRTCP index value of specified SSRC.

func (*Context) ROC 

func (c *Context) ROC(ssrc uint32) (uint32, bool)

ROC returns SRTP rollover counter value of specified SSRC.

func (*Context) RemoveMKI added in v3.0.3 

func (c *Context) RemoveMKI(mki []byte) error

RemoveMKI removes one of MKIs. You cannot remove last MKI and one used for encrypting RTP/RTCP packets. Operation is not thread-safe, you need to provide synchronization with decrypting packets.

func (*Context) SetIndex 

func (c *Context) SetIndex(ssrc uint32, index uint32)

SetIndex sets SRTCP index value of specified SSRC.

func (*Context) SetROC 

func (c *Context) SetROC(ssrc uint32, roc uint32)

SetROC sets SRTP rollover counter value of specified SSRC.

func (*Context) SetSendMKI added in v3.0.3 

func (c *Context) SetSendMKI(mki []byte) error

SetSendMKI switches MKI and cipher used for encrypting RTP/RTCP packets. Operation is not thread-safe, you need to provide synchronization with encrypting packets.

type ContextOption 

type ContextOption func(*Context) error

ContextOption represents option of Context using the functional options pattern.

func Cryptex added in v3.0.7 

func Cryptex(cryptexMode CryptexMode) ContextOption

Cryptex allows to enable Cryptex mechanism to completely encrypt RTP Header Extensions and Contributing Sources, as defined in RFC 9335.

func MasterKeyIndicator added in v3.0.3 

func MasterKeyIndicator(mki []byte) ContextOption

MasterKeyIndicator sets RTP/RTCP MKI for the initial master key. Array passed as an argument will be copied as-is to encrypted SRTP/SRTCP packets, so it must be of proper length and in Big Endian format. All MKIs added later using Context.AddCipherForMKI must have the same length as the one used here.

func RolloverCounterCarryingTransform added in v3.0.5 

func RolloverCounterCarryingTransform(mode RCCMode, rocTransmitRate uint16) ContextOption

RolloverCounterCarryingTransform enables Rollover Counter Carrying Transform from RFC 4771. ROC value is sent in Authentication Tag of SRTP packets every rocTransmitRate packets.

RFC 4771 defines 3 RCC modes. pion/srtp supports mode RCCm2 for AES-CM and NULL profiles, and mode RCCm3 for AES-GCM (AEAD) profiles.

From RFC 4771: "[For modes RCCm1 and and RCCm3] the length of the MAC is shorter than the length of the authentication tag. To achieve the same (or less) MAC forgery success probability on all packets when using RCCm1 or RCCm2, as with the default integrity transform in RFC 3711, the tag-length must be set to 14 octets, which means that the length of MAC_tr is 10 octets."

Protection profiles ProtectionProfile*CmHmacSha1_32 uses 4-byte SRTP auth tag, so in RCCm2 mode SRTP packets with ROC will not be integrity protected.

You can increase the length of the authentication tag using SRTPAuthenticationTagLength option to mitigate this issue.

func SRTCPEncryption added in v3.0.3 

func SRTCPEncryption() ContextOption

SRTCPEncryption enables SRTCP encryption.

func SRTCPNoEncryption added in v3.0.3 

func SRTCPNoEncryption() ContextOption

SRTCPNoEncryption disables SRTCP encryption. This option is useful when you want to use NullCipher for SRTCP and keep authentication only. It simplifies debugging and testing, but it is not recommended for production use.

func SRTCPNoReplayProtection 

func SRTCPNoReplayProtection() ContextOption

SRTCPNoReplayProtection disables SRTCP replay protection.

func SRTCPReplayDetectorFactory 

func SRTCPReplayDetectorFactory(fn func() replaydetector.ReplayDetector) ContextOption

SRTCPReplayDetectorFactory sets custom SRTCP replay detector.

func SRTCPReplayProtection 

func SRTCPReplayProtection(windowSize uint) ContextOption

SRTCPReplayProtection sets SRTCP replay protection window size.

func SRTPAuthenticationTagLength added in v3.0.5 

func SRTPAuthenticationTagLength(authTagRTPLen int) ContextOption

SRTPAuthenticationTagLength sets length of SRTP authentication tag in bytes for AES-CM protection profiles. Decreasing the length of the authentication tag is not recommended for production use, as it decreases integrity protection.

Zero value means that there is no authentication tag, what may be useful for debugging and testing.

This option is ignored for AEAD profiles.

func SRTPEncryption added in v3.0.3 

func SRTPEncryption() ContextOption

SRTPEncryption enables SRTP encryption.

func SRTPNoEncryption added in v3.0.3 

func SRTPNoEncryption() ContextOption

SRTPNoEncryption disables SRTP encryption. This option is useful when you want to use NullCipher for SRTP and keep authentication only. It simplifies debugging and testing, but it is not recommended for production use.

Note: you can also use SRTPAuthenticationTagLength(0) to disable authentication tag too.

func SRTPNoReplayProtection 

func SRTPNoReplayProtection() ContextOption

SRTPNoReplayProtection disables SRTP replay protection.

func SRTPReplayDetectorFactory 

func SRTPReplayDetectorFactory(fn func() replaydetector.ReplayDetector) ContextOption

SRTPReplayDetectorFactory sets custom SRTP replay detector.

func SRTPReplayProtection 

func SRTPReplayProtection(windowSize uint) ContextOption

SRTPReplayProtection sets SRTP replay protection window size.

type CryptexMode added in v3.0.7 

type CryptexMode int

CryptexMode is the mode of Cryptex support for SRTP packets from RFC 9335. 

const (
	// CryptexModeDisabled (default) disables Cryptex support. Received Cryptex SRTP packets with encrypted
	// CSRCs and header extensions will be rejected with an error.
	CryptexModeDisabled CryptexMode = 0
	// CryptexModeEnabled enables Cryptex support when SRTP packets are encrypted. Received SRTP packets
	// with unencrypted CSRCs and header extensions will be accepted and decrypted.
	CryptexModeEnabled CryptexMode = 1
	// CryptexModeRequired enables Cryptex support when SRTP packets are encrypted. Received SRTP packets
	// with unencrypted CSRCs and header extensions will be rejected with an error.
	CryptexModeRequired CryptexMode = 2
)

type KeyingMaterialExporter 

type KeyingMaterialExporter interface {
	ExportKeyingMaterial(label string, context []byte, length int) ([]byte, error)
}

KeyingMaterialExporter allows package SRTP to extract keying material.

type ProtectionProfile 

type ProtectionProfile uint16

ProtectionProfile specifies Cipher and AuthTag details, similar to TLS cipher suite. 

const (
	ProtectionProfileAes128CmHmacSha1_80 ProtectionProfile = 0x0001
	ProtectionProfileAes128CmHmacSha1_32 ProtectionProfile = 0x0002
	ProtectionProfileAes256CmHmacSha1_80 ProtectionProfile = 0x0003
	ProtectionProfileAes256CmHmacSha1_32 ProtectionProfile = 0x0004
	ProtectionProfileNullHmacSha1_80     ProtectionProfile = 0x0005
	ProtectionProfileNullHmacSha1_32     ProtectionProfile = 0x0006
	ProtectionProfileAeadAes128Gcm       ProtectionProfile = 0x0007
	ProtectionProfileAeadAes256Gcm       ProtectionProfile = 0x0008
)

Supported protection profiles See https://www.iana.org/assignments/srtp-protection/srtp-protection.xhtml

AES128_CM_HMAC_SHA1_80 and AES128_CM_HMAC_SHA1_32 are valid SRTP profiles, but they do not have an DTLS-SRTP Protection Profiles ID assigned in RFC 5764. They were in earlier draft of this RFC: https://datatracker.ietf.org/doc/html/draft-ietf-avt-dtls-srtp-03#section-4.1.2 Their IDs are now marked as reserved in the IANA registry. Despite this Chrome supports them: https://chromium.googlesource.com/chromium/deps/libsrtp/+/84122798bb16927b1e676bd4f938a6e48e5bf2fe/srtp/include/srtp.h#694

Null profiles disable encryption, they are used for debugging and testing. They are not recommended for production use. Use of them is equivalent to using ProtectionProfileAes128CmHmacSha1_NN profile with SRTPNoEncryption and SRTCPNoEncryption options.

func (ProtectionProfile) AEADAuthTagLen added in v3.0.3 

func (p ProtectionProfile) AEADAuthTagLen() (int, error)

AEADAuthTagLen returns length of authentication tag in bytes for AEAD protection profiles. For AES ones it returns zero.

func (ProtectionProfile) AuthKeyLen added in v3.0.3 

func (p ProtectionProfile) AuthKeyLen() (int, error)

AuthKeyLen returns length of authentication key in bytes for AES protection profiles. For AEAD ones it returns zero.

func (ProtectionProfile) AuthTagRTCPLen added in v3.0.3 

func (p ProtectionProfile) AuthTagRTCPLen() (int, error)

AuthTagRTCPLen returns length of RTCP authentication tag in bytes for AES protection profiles. 

For AEAD ones it returns zero.

func (ProtectionProfile) AuthTagRTPLen added in v3.0.3 

func (p ProtectionProfile) AuthTagRTPLen() (int, error)

AuthTagRTPLen returns length of RTP authentication tag in bytes for AES protection profiles. For AEAD ones it returns zero.

func (ProtectionProfile) KeyLen added in v3.0.3 

func (p ProtectionProfile) KeyLen() (int, error)

KeyLen returns length of encryption key in bytes. For all profiles except NullHmacSha1_32 and NullHmacSha1_80 is also the length of the session key.

func (ProtectionProfile) SaltLen added in v3.0.3 

func (p ProtectionProfile) SaltLen() (int, error)

SaltLen returns length of salt key in bytes. For all profiles except NullHmacSha1_32 and NullHmacSha1_80 is also the length of the session salt.

func (ProtectionProfile) String added in v3.0.2 

func (p ProtectionProfile) String() string

String returns the name of the protection profile.

type RCCMode added in v3.0.5 

type RCCMode int

RCCMode is the mode of Roll-over Counter Carrying Transform from RFC 4771. 

const (
	// RCCModeNone is the default mode.
	RCCModeNone RCCMode = iota
	// RCCMode1 is RCCm1 mode from RFC 4771. In this mode ROC and truncated auth tag is sent every R-th packet,
	// and no auth tag in other ones. This mode is not supported by pion/srtp.
	RCCMode1
	// RCCMode2 is RCCm2 mode from RFC 4771. In this mode ROC and truncated auth tag is sent every R-th packet,
	// and full auth tag in other ones. This mode is supported for AES-CM and NULL profiles only.
	RCCMode2
	// RCCMode3 is RCCm3 mode from RFC 4771. In this mode ROC is sent every R-th packet (without truncated auth tag),
	// and no auth tag in other ones. This mode is supported for AES-GCM profiles only.
	RCCMode3
)

type ReadStreamSRTCP 

type ReadStreamSRTCP struct {
	// contains filtered or unexported fields
}

ReadStreamSRTCP handles decryption for a single RTCP SSRC.

func (*ReadStreamSRTCP) Close 

func (r *ReadStreamSRTCP) Close() error

Close removes the ReadStream from the session and cleans up any associated state.

func (*ReadStreamSRTCP) GetSSRC 

func (r *ReadStreamSRTCP) GetSSRC() uint32

GetSSRC returns the SSRC we are demuxing for.

func (*ReadStreamSRTCP) Read 

func (r *ReadStreamSRTCP) Read(buf []byte) (int, error)

Read reads and decrypts full RTCP packet from the nextConn.

func (*ReadStreamSRTCP) ReadRTCP 

func (r *ReadStreamSRTCP) ReadRTCP(buf []byte) (int, *rtcp.Header, error)

ReadRTCP reads and decrypts full RTCP packet and its header from the nextConn.

func (*ReadStreamSRTCP) SetReadDeadline 

func (r *ReadStreamSRTCP) SetReadDeadline(t time.Time) error

SetReadDeadline sets the deadline for the Read operation. Setting to zero means no deadline.

type ReadStreamSRTP 

type ReadStreamSRTP struct {
	// contains filtered or unexported fields
}

ReadStreamSRTP handles decryption for a single RTP SSRC.

func (*ReadStreamSRTP) Close 

func (r *ReadStreamSRTP) Close() error

Close removes the ReadStream from the session and cleans up any associated state.

func (*ReadStreamSRTP) GetSSRC 

func (r *ReadStreamSRTP) GetSSRC() uint32

GetSSRC returns the SSRC we are demuxing for.

func (*ReadStreamSRTP) Read 

func (r *ReadStreamSRTP) Read(buf []byte) (int, error)

Read reads and decrypts full RTP packet from the nextConn.

func (*ReadStreamSRTP) ReadRTP 

func (r *ReadStreamSRTP) ReadRTP(buf []byte) (int, *rtp.Header, error)

ReadRTP reads and decrypts full RTP packet and its header from the nextConn.

func (*ReadStreamSRTP) SetReadDeadline 

func (r *ReadStreamSRTP) SetReadDeadline(t time.Time) error

SetReadDeadline sets the deadline for the Read operation. Setting to zero means no deadline.

type SessionKeys 

type SessionKeys struct {
	LocalMasterKey   []byte
	LocalMasterSalt  []byte
	RemoteMasterKey  []byte
	RemoteMasterSalt []byte
}

SessionKeys bundles the keys required to setup an SRTP session.

type SessionSRTCP 

type SessionSRTCP struct {
	// contains filtered or unexported fields
}

SessionSRTCP implements io.ReadWriteCloser and provides a bi-directional SRTCP session SRTCP itself does not have a design like this, but it is common in most applications for local/remote to each have their own keying material. This provides those patterns instead of making everyone re-implement.

func NewSessionSRTCP 

func NewSessionSRTCP(conn net.Conn, config *Config) (*SessionSRTCP, error)

NewSessionSRTCP creates a SRTCP session using conn as the underlying transport.

func (*SessionSRTCP) AcceptStream 

func (s *SessionSRTCP) AcceptStream() (*ReadStreamSRTCP, uint32, error)

AcceptStream returns a stream to handle RTCP for a single SSRC.

func (*SessionSRTCP) Close 

func (s *SessionSRTCP) Close() error

Close ends the session.

func (*SessionSRTCP) OpenReadStream 

func (s *SessionSRTCP) OpenReadStream(ssrc uint32) (*ReadStreamSRTCP, error)

OpenReadStream opens a read stream for the given SSRC, it can be used if you want a certain SSRC, but don't want to wait for AcceptStream.

func (*SessionSRTCP) OpenWriteStream 

func (s *SessionSRTCP) OpenWriteStream() (*WriteStreamSRTCP, error)

OpenWriteStream returns the global write stream for the Session.

type SessionSRTP 

type SessionSRTP struct {
	// contains filtered or unexported fields
}

SessionSRTP implements io.ReadWriteCloser and provides a bi-directional SRTP session SRTP itself does not have a design like this, but it is common in most applications for local/remote to each have their own keying material. This provides those patterns instead of making everyone re-implement.

func NewSessionSRTP 

func NewSessionSRTP(conn net.Conn, config *Config) (*SessionSRTP, error)

NewSessionSRTP creates a SRTP session using conn as the underlying transport.

func (*SessionSRTP) AcceptStream 

func (s *SessionSRTP) AcceptStream() (*ReadStreamSRTP, uint32, error)

AcceptStream returns a stream to handle RTCP for a single SSRC.

func (*SessionSRTP) Close 

func (s *SessionSRTP) Close() error

Close ends the session.

func (*SessionSRTP) OpenReadStream 

func (s *SessionSRTP) OpenReadStream(ssrc uint32) (*ReadStreamSRTP, error)

OpenReadStream opens a read stream for the given SSRC, it can be used if you want a certain SSRC, but don't want to wait for AcceptStream.

func (*SessionSRTP) OpenWriteStream 

func (s *SessionSRTP) OpenWriteStream() (*WriteStreamSRTP, error)

OpenWriteStream returns the global write stream for the Session.

type WriteStreamSRTCP 

type WriteStreamSRTCP struct {
	// contains filtered or unexported fields
}

WriteStreamSRTCP is stream for a single Session that is used to encrypt RTCP.

func (*WriteStreamSRTCP) SetWriteDeadline 

func (w *WriteStreamSRTCP) SetWriteDeadline(t time.Time) error

SetWriteDeadline sets the deadline for the Write operation. Setting to zero means no deadline.

func (*WriteStreamSRTCP) Write 

func (w *WriteStreamSRTCP) Write(b []byte) (int, error)

Write encrypts and writes a full RTCP packets to the nextConn.

func (*WriteStreamSRTCP) WriteRTCP 

func (w *WriteStreamSRTCP) WriteRTCP(header *rtcp.Header, payload []byte) (int, error)

WriteRTCP encrypts a RTCP header and its payload to the nextConn.

type WriteStreamSRTP 

type WriteStreamSRTP struct {
	// contains filtered or unexported fields
}

WriteStreamSRTP is stream for a single Session that is used to encrypt RTP.

func (*WriteStreamSRTP) SetWriteDeadline 

func (w *WriteStreamSRTP) SetWriteDeadline(t time.Time) error

SetWriteDeadline sets the deadline for the Write operation. Setting to zero means no deadline.

func (*WriteStreamSRTP) Write 

func (w *WriteStreamSRTP) Write(b []byte) (int, error)

Write encrypts and writes a full RTP packets to the nextConn.

func (*WriteStreamSRTP) WriteRTP 

func (w *WriteStreamSRTP) WriteRTP(header *rtp.Header, payload []byte) (int, error)

WriteRTP encrypts a RTP packet and writes to the connection.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.