srtp.h File Reference

Go to the source code of this file.

Typedefs
typedef struct srtp_session_t	srtp_session_t

Enumerations
enum	{   SRTP_UNENCRYPTED =0x1 , SRTCP_UNENCRYPTED =0x2 , SRTP_UNAUTHENTICATED =0x4 , SRTP_RCC_MODE1 =0x10 ,   SRTP_RCC_MODE2 =0x20 , SRTP_RCC_MODE3 =0x30 , SRTP_FLAGS_MASK =0x37 }
enum	{ SRTP_ENCR_NULL =0 , SRTP_ENCR_AES_CM =1 , SRTP_ENCR_AES_F8 =2 }
	SRTP encryption algorithms (ciphers); same values as MIKEY. More...
enum	{ SRTP_AUTH_NULL =0 , SRTP_AUTH_HMAC_SHA1 =1 }
	SRTP authenticaton algorithms; same values as MIKEY. More...
enum	{ SRTP_PRF_AES_CM =0 }
	SRTP pseudo random function; same values as MIKEY. More...

Functions
srtp_session_t *	srtp_create (int encr, int auth, unsigned tag_len, int prf, unsigned flags)
	Allocates a Secure RTP one-way session.
void	srtp_destroy (srtp_session_t *s)
	Releases all resources associated with a Secure RTP session.
int	srtp_setkey (srtp_session_t *s, const void *key, size_t keylen, const void *salt, size_t saltlen)
	Sets (or resets) the master key and master salt for a SRTP session.
int	srtp_setkeystring (srtp_session_t *s, const char *key, const char *salt)
	Sets (or resets) the master key and master salt for a SRTP session from hexadecimal strings.
void	srtp_setrcc_rate (srtp_session_t *s, uint16_t rate)
	Sets Roll-over-Counter Carry (RCC) rate for the SRTP session.
int	srtp_send (srtp_session_t *s, uint8_t *buf, size_t *lenp, size_t maxsize)
	Turns a RTP packet into a SRTP packet: encrypt it, then computes the authentication tag and appends it.
int	srtp_recv (srtp_session_t *s, uint8_t *buf, size_t *lenp)
	Turns a SRTP packet into a RTP packet: authenticates the packet, then decrypts it.
int	srtcp_send (srtp_session_t *s, uint8_t *buf, size_t *lenp, size_t maxsiz)
	Turns a RTCP packet into a SRTCP packet: encrypt it, then computes the authentication tag and appends it.
int	srtcp_recv (srtp_session_t *s, uint8_t *buf, size_t *lenp)
	Turns a SRTCP packet into a RTCP packet: authenticates the packet, then decrypts it.

Typedef Documentation

srtp_session_t

typedef struct srtp_session_t srtp_session_t

Enumeration Type Documentation

anonymous enum

anonymous enum

Enumerator
SRTP_UNENCRYPTED
SRTCP_UNENCRYPTED
SRTP_UNAUTHENTICATED
SRTP_RCC_MODE1
SRTP_RCC_MODE2
SRTP_RCC_MODE3
SRTP_FLAGS_MASK

anonymous enum

anonymous enum

SRTP encryption algorithms (ciphers); same values as MIKEY.

Enumerator
SRTP_ENCR_NULL
SRTP_ENCR_AES_CM
SRTP_ENCR_AES_F8

anonymous enum

anonymous enum

SRTP authenticaton algorithms; same values as MIKEY.

Enumerator
SRTP_AUTH_NULL
SRTP_AUTH_HMAC_SHA1

anonymous enum

anonymous enum

SRTP pseudo random function; same values as MIKEY.

Enumerator
SRTP_PRF_AES_CM

Function Documentation

srtcp_recv()

int srtcp_recv	(	srtp_session_t *	s,
		uint8_t *	buf,
		size_t *	lenp
	)

Turns a SRTCP packet into a RTCP packet: authenticates the packet, then decrypts it.

Parameters

s	a valid SRTP session to read from and convert the packet from
buf	RTCP packet to be digested/decrypted
lenp	pointer to the SRTCP packet length on entry, set to the RTCP length on exit (undefined in case of error)

Returns

0 on success, in case of error: EINVAL malformatted SRTCP packet EACCES authentication failed (spoofed packet or out-of-sync)

References srtp_proto_t::mac, srtp_session_t::rtcp, rtcp_digest(), srtp_crypt(), and srtp_session_t::tag_len.

srtcp_send()

int srtcp_send	(	srtp_session_t *	s,
		uint8_t *	buf,
		size_t *	lenp,
		size_t	bufsize
	)

Turns a RTCP packet into a SRTCP packet: encrypt it, then computes the authentication tag and appends it.

Parameters

s	a valid SRTP session to encrypt and authenticate the packet from
buf	RTCP packet to be encrypted/digested
lenp	pointer to the RTCP packet length on entry, set to the SRTCP length on exit (undefined in case of error)
bufsize	size (bytes) of the packet buffer

Returns

0 on success, in case of error: EINVAL malformatted RTCP packet or internal error ENOSPC bufsize is too small (to add index and authentication tag)

References srtp_session_t::flags, srtp_proto_t::mac, srtp_session_t::rtcp, rtcp_digest(), srtp_session_t::rtcp_index, srtcp_crypt(), SRTCP_UNENCRYPTED, and srtp_session_t::tag_len.

srtp_create()

srtp_session_t * srtp_create	(	int	encr,
		int	auth,
		unsigned	tag_len,
		int	prf,
		unsigned	flags
	)

Allocates a Secure RTP one-way session.

The same session cannot be used both ways because this would confuse internal cryptographic counters; it is however of course feasible to open multiple simultaneous sessions with the same master key.

Parameters

encr	encryption algorithm number
auth	authentication algorithm number
tag_len	authentication tag byte length (NOT including RCC)
prf	the pseudo-random family to use for key derivation
flags	OR'ed optional flags.

Returns

NULL in case of error

References srtp_session_t::flags, proto_create(), proto_destroy(), rcc_mode(), srtp_session_t::rtcp, srtp_session_t::rtp, srtp_session_t::rtp_rcc, SRTP_AUTH_HMAC_SHA1, SRTP_AUTH_NULL, SRTP_ENCR_AES_CM, SRTP_ENCR_NULL, SRTP_FLAGS_MASK, SRTP_PRF_AES_CM, and srtp_session_t::tag_len.

Referenced by OpenURL().

srtp_destroy()

void srtp_destroy

(

srtp_session_t *

s

)

Releases all resources associated with a Secure RTP session.

References proto_destroy(), srtp_session_t::rtcp, and srtp_session_t::rtp.

Referenced by Close(), and OpenURL().

srtp_recv()

int srtp_recv	(	srtp_session_t *	s,
		uint8_t *	buf,
		size_t *	lenp
	)

Turns a SRTP packet into a RTP packet: authenticates the packet, then decrypts it.

Parameters

s	a valid SRTP session to authenticate and decrypt the packet from
buf	RTP packet to be digested/decrypted
lenp	pointer to the SRTP packet length on entry, set to the RTP length on exit (undefined in case of error)

Returns

0 on success, in case of error: EINVAL malformatted SRTP packet EACCES authentication failed (spoofed packet or out-of-sync)

References srtp_session_t::flags, srtp_proto_t::mac, rcc_mode(), srtp_session_t::rtp, rtp_digest(), srtp_session_t::rtp_rcc, srtp_session_t::rtp_roc, rtp_seq(), srtp_compute_roc(), srtp_crypt(), SRTP_UNAUTHENTICATED, and srtp_session_t::tag_len.

Referenced by rtp_process().

srtp_send()

int srtp_send	(	srtp_session_t *	s,
		uint8_t *	buf,
		size_t *	lenp,
		size_t	bufsize
	)

Turns a RTP packet into a SRTP packet: encrypt it, then computes the authentication tag and appends it.

Note that you can encrypt packet in disorder.

Parameters

s	a valid SRTP session to convert the packet from and send to
buf	RTP packet to be encrypted/digested
lenp	pointer to the RTP packet length on entry, set to the SRTP length on exit (undefined on non-ENOSPC error)
bufsize	size (bytes) of the packet buffer

Returns

0 on success, an error code otherwise

Return values

EINVAL	malformatted RTP packet or internal error
ENOSPC	bufsize is too small to add authentication tag (lenp will hold the required byte size)
EACCES	packet would trigger a replay error on receiver

References srtp_session_t::flags, srtp_proto_t::mac, rcc_mode(), srtp_session_t::rtp, rtp_digest(), srtp_session_t::rtp_rcc, srtp_session_t::rtp_roc, rtp_seq(), srtp_compute_roc(), srtp_crypt(), SRTP_UNAUTHENTICATED, and srtp_session_t::tag_len.

srtp_setkey()

int srtp_setkey	(	srtp_session_t *	s,
		const void *	key,
		size_t	keylen,
		const void *	salt,
		size_t	saltlen
	)

Sets (or resets) the master key and master salt for a SRTP session.

This must be done at least once before using srtp_send(), srtp_recv(), srtcp_send() or srtcp_recv(). Also, rekeying is required every 2^48 RTP packets or 2^31 RTCP packets (whichever comes first), otherwise the protocol security might be broken.

Returns

0 on success, in case of error: EINVAL invalid or unsupported key/salt sizes combination

References srtp_proto_t::cipher, do_derive(), srtp_session_t::kdr, srtp_proto_t::mac, srtp_session_t::rtcp, srtp_session_t::rtcp_index, srtp_session_t::rtp, srtp_session_t::rtp_roc, srtp_session_t::rtp_seq, srtp_proto_t::salt, SRTCP_AUTH, SRTCP_CRYPT, SRTCP_SALT, SRTP_AUTH, SRTP_CRYPT, and SRTP_SALT.

Referenced by srtp_setkeystring().

srtp_setkeystring()

int srtp_setkeystring	(	srtp_session_t *	s,
		const char *	key,
		const char *	salt
	)

Sets (or resets) the master key and master salt for a SRTP session from hexadecimal strings.

See also srtp_setkey().

Returns

0 on success, in case of error: EINVAL invalid or unsupported key/salt sizes combination

References hexstring(), and srtp_setkey().

Referenced by OpenURL().

srtp_setrcc_rate()

void srtp_setrcc_rate	(	srtp_session_t *	s,
		uint16_t	rate
	)

Sets Roll-over-Counter Carry (RCC) rate for the SRTP session.

If not specified (through this function), the default rate of ONE is assumed (i.e. every RTP packets will carry the RoC). RCC rate is ignored if none of the RCC mode has been selected.

The RCC mode is selected through one of these flags for srtp_create(): SRTP_RCC_MODE1: integrity protection only for RoC carrying packets SRTP_RCC_MODE2: integrity protection for all packets SRTP_RCC_MODE3: no integrity protection

RCC mode 3 is insecure. Compared to plain RTP, it provides confidentiality (through encryption) but is much more prone to DoS. It can only be used if anti-spoofing protection is provided by lower network layers (e.g. IPsec, or trusted routers and proper source address filtering).

If RCC rate is 1, RCC mode 1 and 2 are functionally identical.

Parameters

s	the session to change the RCC for
rate	RoC Carry rate (MUST NOT be zero)

References srtp_session_t::rtp_rcc.