CryptoContextCtrl Class Reference

The implementation for a SRTCP cryptographic context. More...

#include <CryptoContextCtrl.h>

Collaboration diagram for CryptoContextCtrl:

Public Member Functions
	CryptoContextCtrl (uint32 ssrc)
	Constructor for empty SRTP cryptographic context. More...
	CryptoContextCtrl (uint32 ssrc, const int32 ealg, const int32 aalg, uint8 *masterKey, int32 masterKeyLength, uint8 *masterSalt, int32 masterSaltLength, int32 ekeyl, int32 akeyl, int32 skeyl, int32 tagLength)
	Constructor for an active SRTP cryptographic context. More...
	~CryptoContextCtrl ()
	Destructor. More...
void	srtcpEncrypt (uint8 *rtp, size_t len, uint64 index, uint32 ssrc)
	Perform SRTP encryption. More...
void	srtcpAuthenticate (uint8 *rtp, size_t len, uint32 roc, uint8 *tag)
	Compute the authentication tag. More...
void	deriveSrtcpKeys ()
	Perform key derivation according to SRTP specification. More...
bool	checkReplay (uint32 newSeqNumber)
	Check for packet replay. More...
void	update (uint32 newSeqNumber)
	Update the SRTP packet index. More...
int32	getTagLength () const
	Get the length of the SRTP authentication tag in bytes. More...
int32	getMkiLength () const
	Get the length of the MKI in bytes. More...
uint32	getSsrc () const
	Get the SSRC of this SRTP Cryptograhic context. More...
CryptoContextCtrl *	newCryptoContextForSSRC (uint32 ssrc)
	Derive a new Crypto Context for use with a new SSRC. More...

Private Attributes
uint32	ssrcCtx
bool	using_mki
uint32	mkiLength
uint8 *	mki
uint32	s_l
uint64	replay_window
uint8 *	master_key
uint32	master_key_length
uint8 *	master_salt
uint32	master_salt_length
int32	n_e
uint8 *	k_e
int32	n_a
uint8 *	k_a
int32	n_s
uint8 *	k_s
int32	ealg
int32	aalg
int32	ekeyl
int32	akeyl
int32	skeyl
int32	tagLength
void *	macCtx
void *	cipher
void *	f8Cipher

Detailed Description

The implementation for a SRTCP cryptographic context.

This class holds data and provides functions that implement a cryptographic context for SRTP, Refer to RFC 3711, chapter 3.2 for some more detailed information about the SRTP cryptographic context.

Each SRTP cryptographic context maintains a RTP source identified by its SSRC. Thus you can independently protect each source inside a RTP session.

Key management mechanisms negotiate the parameters for the SRTP cryptographic context, such as master key, key length, authentication length and so on. The key management mechanisms are not part of SRTP. Refer to MIKEY (RFC 3880) or to Phil Zimmermann's ZRTP protocol (draft-zimmermann-avt-zrtp-01). After key management negotiated the data the application can setup the SRTCP cryptographic context and enable SRTCP processing.

Author

Israel Abad i_aba.nosp@m.d@te.nosp@m.rra.e.nosp@m.s

Erik Eliasson elias.nosp@m.son@.nosp@m.it.kt.nosp@m.h.se

Johan Bilien jobi@.nosp@m.via..nosp@m.ecp.f.nosp@m.r

Joachim Orrblad joach.nosp@m.im@o.nosp@m.rrbla.nosp@m.d.co.nosp@m.m

Werner Dittmann Werne.nosp@m.r.Di.nosp@m.ttman.nosp@m.n@t-.nosp@m.onlin.nosp@m.e.de

Definition at line 61 of file CryptoContextCtrl.h.

Constructor & Destructor Documentation

NAMESPACE_COMMONCPP CryptoContextCtrl::CryptoContextCtrl

(

uint32

ssrc

)

Constructor for empty SRTP cryptographic context.

This constructor creates an empty SRTP cryptographic context were all algorithms are set to the null algorithm, that is no SRTP processing is performed.

Parameters

ssrc	The RTP SSRC that this SRTP cryptographic context protects.

Definition at line 44 of file CryptoContextCtrl.cpp.

CryptoContextCtrl::CryptoContextCtrl	(	uint32	ssrc,
		const int32	ealg,
		const int32	aalg,
		uint8 *	masterKey,
		int32	masterKeyLength,
		uint8 *	masterSalt,
		int32	masterSaltLength,
		int32	ekeyl,
		int32	akeyl,
		int32	skeyl,
		int32	tagLength
	)

Constructor for an active SRTP cryptographic context.

This constructor creates an active SRTP cryptographic context were algorithms are enabled, keys are computed and so on. This SRTP cryptographic context can protect a RTP SSRC stream.

Parameters

ssrc	The RTP SSRC that this SRTP cryptographic context protects.
ealg	The encryption algorithm to use. Possible values are SrtpEncryptionNull, SrtpEncryptionAESCM, SrtpEncryptionAESF8 . See chapter 4.1.1 for AESCM (Counter mode) and 4.1.2 for AES F8 mode.
aalg	The authentication algorithm to use. Possible values are SrtpEncryptionNull, SrtpAuthenticationSha1Hmac. The only active algorithm here is SHA1 HMAC, a SHA1 based hashed message authentication code as defined in RFC 2104.
masterKey	Pointer to the master key for this SRTP cryptographic context. Must point to masterKeyLength bytes. Refer to chapter 3.2.1 of the RFC about the role of the master key.
masterKeyLength	The length in bytes of the master key in bytes. The length must match the selected encryption algorithm. Because SRTP uses AES based encryption only, then master key length may be 16 or 32 bytes (128 or 256 bit master key)
masterSalt	SRTP uses the master salt to computer the initialization vector that in turn is input to compute the session key, session authentication key and the session salt.
masterSaltLength	The length in bytes of the master salt data in bytes. SRTP uses AES as encryption algorithm. AES encrypts 16 byte blocks (independent of the key length). According to RFC3711 the standard value for the master salt length should be 112 bit (14 bytes).
ekeyl	The length in bytes of the session encryption key that SRTP shall compute and use. Usually the same length as for the master key length. But you may use a different length as well. Be carefull that the key management mechanisms supports different key lengths.
akeyl	The length in bytes of the session authentication key. SRTP computes this key and uses it as input to the authentication algorithm. The standard value is 160 bits (20 bytes).
skeyl	The length in bytes of the session salt. SRTP computes this salt key and uses it as input during encryption. The length usually is the same as the master salt length.
tagLength	The length is bytes of the authentication tag that SRTP appends to the RTP packet. Refer to chapter 4.2. in the RFC 3711.

CryptoContextCtrl::~CryptoContextCtrl

(

)

Destructor.

Cleans the SRTP cryptographic context.

Definition at line 137 of file CryptoContextCtrl.cpp.

Member Function Documentation

bool CryptoContextCtrl::checkReplay

(

uint32

newSeqNumber

)

Check for packet replay.

The method check if a received packet is either to old or was already received.

The method supports a 64 packet history relative the the given sequence number.

Parameters

newSeqNumber

The sequence number of the received RTP packet in host order.

Returns

true if no replay, false if packet is too old ar was already received.

Definition at line 372 of file CryptoContextCtrl.cpp.

void CryptoContextCtrl::deriveSrtcpKeys

(

)

Perform key derivation according to SRTP specification.

This method computes the session key, session authentication key and the session salt key. This method must be called at least once after the SRTP Cryptograhic context was set up.

Parameters

index

The 48 bit SRTP packet index. See the guessIndex method.

Definition at line 327 of file CryptoContextCtrl.cpp.

int32 CryptoContextCtrl::getMkiLength ( ) const

inline

Get the length of the MKI in bytes.

Returns

the length of the MKI.

Definition at line 250 of file CryptoContextCtrl.h.

uint32 CryptoContextCtrl::getSsrc ( ) const

inline

Get the SSRC of this SRTP Cryptograhic context.

Returns

the SSRC.

Definition at line 259 of file CryptoContextCtrl.h.

int32 CryptoContextCtrl::getTagLength ( ) const

inline

Get the length of the SRTP authentication tag in bytes.

Returns

the length of the authentication tag.

Definition at line 240 of file CryptoContextCtrl.h.

CryptoContextCtrl * CryptoContextCtrl::newCryptoContextForSSRC

(

uint32

ssrc

)

Derive a new Crypto Context for use with a new SSRC.

This method returns a new Crypto Context initialized with the data of this crypto context. Replacing the SSRC, Roll-over-Counter, and the key derivation rate the application cab use this Crypto Context to encrypt / decrypt a new stream (Synchronization source) inside one RTP session.

Before the application can use this crypto context it must call the deriveSrtpKeys method.

Parameters

ssrc	The SSRC for this context
roc	The Roll-Over-Counter for this context
keyDerivRate	The key derivation rate for this context

Returns

a new CryptoContext with all relevant data set.

Definition at line 424 of file CryptoContextCtrl.cpp.

void CryptoContextCtrl::srtcpAuthenticate	(	uint8 *	rtp,
		size_t	len,
		uint32	roc,
		uint8 *	tag
	)

Compute the authentication tag.

Compute the authentication tag according the the paramters in the SRTP Cryptograhic context.

Parameters

rtp	The RTP packet that contains the data to authenticate.
roc	The 32 bit SRTP roll-over-counter.
tag	Points to a buffer that hold the computed tag. This buffer must be able to hold tagLength bytes.

Definition at line 265 of file CryptoContextCtrl.cpp.

void CryptoContextCtrl::srtcpEncrypt	(	uint8 *	rtp,
		size_t	len,
		uint64	index,
		uint32	ssrc
	)

Perform SRTP encryption.

This method encrypts and decrypts SRTP payload data. Plain data gets encrypted, encrypted data get decrypted.

Parameters

rtp	The RTP packet that contains the data to encrypt.
index	The 48 bit SRTP packet index. See the guessIndex method.
ssrc	The RTP SSRC data in host order.

Definition at line 193 of file CryptoContextCtrl.cpp.

void CryptoContextCtrl::update

(

uint32

newSeqNumber

)

Update the SRTP packet index.

Call this method after all checks were successful. See chapter 3.3.1 in the RFC when to update the ROC and ROC processing.

Parameters

newSeqNumber

The sequence number of the received RTCP packet in host order.

Definition at line 406 of file CryptoContextCtrl.cpp.

Field Documentation

int32 CryptoContextCtrl::aalg

private

Definition at line 311 of file CryptoContextCtrl.h.

int32 CryptoContextCtrl::akeyl

private

Definition at line 313 of file CryptoContextCtrl.h.

void* CryptoContextCtrl::cipher

private

Definition at line 323 of file CryptoContextCtrl.h.

int32 CryptoContextCtrl::ealg

private

Definition at line 310 of file CryptoContextCtrl.h.

int32 CryptoContextCtrl::ekeyl

private

Definition at line 312 of file CryptoContextCtrl.h.

void* CryptoContextCtrl::f8Cipher

private

Definition at line 324 of file CryptoContextCtrl.h.

uint8* CryptoContextCtrl::k_a

private

Definition at line 306 of file CryptoContextCtrl.h.

uint8* CryptoContextCtrl::k_e

private

Definition at line 304 of file CryptoContextCtrl.h.

uint8* CryptoContextCtrl::k_s

private

Definition at line 308 of file CryptoContextCtrl.h.

void* CryptoContextCtrl::macCtx

private

Definition at line 317 of file CryptoContextCtrl.h.

uint8* CryptoContextCtrl::master_key

private

Definition at line 297 of file CryptoContextCtrl.h.

uint32 CryptoContextCtrl::master_key_length

private

Definition at line 298 of file CryptoContextCtrl.h.

uint8* CryptoContextCtrl::master_salt

private

Definition at line 299 of file CryptoContextCtrl.h.

uint32 CryptoContextCtrl::master_salt_length

private

Definition at line 300 of file CryptoContextCtrl.h.

uint8* CryptoContextCtrl::mki

private

Definition at line 290 of file CryptoContextCtrl.h.

uint32 CryptoContextCtrl::mkiLength

private

Definition at line 289 of file CryptoContextCtrl.h.

int32 CryptoContextCtrl::n_a

private

Definition at line 305 of file CryptoContextCtrl.h.

int32 CryptoContextCtrl::n_e

private

Definition at line 303 of file CryptoContextCtrl.h.

int32 CryptoContextCtrl::n_s

private

Definition at line 307 of file CryptoContextCtrl.h.

uint64 CryptoContextCtrl::replay_window

private

Definition at line 295 of file CryptoContextCtrl.h.

uint32 CryptoContextCtrl::s_l

private

Definition at line 292 of file CryptoContextCtrl.h.

int32 CryptoContextCtrl::skeyl

private

Definition at line 314 of file CryptoContextCtrl.h.

uint32 CryptoContextCtrl::ssrcCtx

private

Definition at line 287 of file CryptoContextCtrl.h.

int32 CryptoContextCtrl::tagLength

private

Definition at line 315 of file CryptoContextCtrl.h.

bool CryptoContextCtrl::using_mki

private

Definition at line 288 of file CryptoContextCtrl.h.

---

The documentation for this class was generated from the following files:

• CryptoContextCtrl.h
• CryptoContextCtrl.cpp