ccRTP 2.1.2
 All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Public Member Functions | Private Attributes
CryptoContext Class Reference

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

#include <CryptoContext.h>

Collaboration diagram for CryptoContext:
Collaboration graph
[legend]

Public Member Functions

 CryptoContext (uint32 ssrc)
 Constructor for empty SRTP cryptographic context. More...
 
 CryptoContext (uint32 ssrc, int32 roc, int64 keyDerivRate, 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...
 
 ~CryptoContext ()
 Destructor. More...
 
void setRoc (uint32 r)
 Set the Roll-Over-Counter. More...
 
uint32 getRoc () const
 Get the Roll-Over-Counter. More...
 
void srtpEncrypt (RTPPacket *rtp, uint64 index, uint32 ssrc)
 Perform SRTP encryption. More...
 
void srtpAuthenticate (RTPPacket *rtp, uint32 roc, uint8 *tag)
 Compute the authentication tag. More...
 
void deriveSrtpKeys (uint64 index)
 Perform key derivation according to SRTP specification. More...
 
uint64 guessIndex (uint16 newSeqNumber)
 Compute (guess) the new SRTP index based on the sequence number of a received RTP packet. More...
 
bool checkReplay (uint16 newSeqNumber)
 Check for packet replay. More...
 
void update (uint16 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...
 
CryptoContext * newCryptoContextForSSRC (uint32 ssrc, int roc, int64 keyDerivRate)
 Derive a new Crypto Context for use with a new SSRC. More...
 

Private Attributes

uint32 ssrcCtx
 
bool using_mki
 
uint32 mkiLength
 
uint8 * mki
 
uint32 roc
 
uint32 guessed_roc
 
uint16 s_l
 
int64 key_deriv_rate
 
uint64 replay_window
 
uint8 * master_key
 
uint32 master_key_length
 
uint32 master_key_srtp_use_nb
 
uint32 master_key_srtcp_use_nb
 
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
 
bool seqNumSet
 
void * macCtx
 
void * cipher
 
void * f8Cipher
 

Detailed Description

The implementation for a SRTP 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 SRTP cryptographic context and enable SRTP processing.

Currently this implementation supports RTP only, not RTCP.

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 82 of file CryptoContext.h.

Constructor & Destructor Documentation

NAMESPACE_COMMONCPP CryptoContext::CryptoContext ( 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
ssrcThe RTP SSRC that this SRTP cryptographic context protects.

Definition at line 43 of file CryptoContext.cpp.

CryptoContext::CryptoContext ( uint32  ssrc,
int32  roc,
int64  keyDerivRate,
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
ssrcThe RTP SSRC that this SRTP cryptographic context protects.
rocThe initial Roll-Over-Counter according to RFC 3711. These are the upper 32 bit of the overall 48 bit SRTP packet index. Refer to chapter 3.2.1 of the RFC.
keyDerivRateThe key derivation rate defines when to recompute the SRTP session keys. Refer to chapter 4.3.1 in the RFC.
ealgThe 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.
aalgThe 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.
masterKeyPointer 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.
masterKeyLengthThe 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)
masterSaltSRTP 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.
masterSaltLengthThe 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).
ekeylThe 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.
akeylThe 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).
skeylThe 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.
tagLengthThe length is bytes of the authentication tag that SRTP appends to the RTP packet. Refer to chapter 4.2. in the RFC 3711.
CryptoContext::~CryptoContext ( )

Destructor.

Cleans the SRTP cryptographic context.

Definition at line 141 of file CryptoContext.cpp.

Member Function Documentation

bool CryptoContext::checkReplay ( uint16  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
newSeqNumberThe 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 414 of file CryptoContext.cpp.

void CryptoContext::deriveSrtpKeys ( uint64  index)

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
indexThe 48 bit SRTP packet index. See the guessIndex method.

Definition at line 337 of file CryptoContext.cpp.

int32 CryptoContext::getMkiLength ( ) const
inline

Get the length of the MKI in bytes.

Returns
the length of the MKI.

Definition at line 320 of file CryptoContext.h.

uint32 CryptoContext::getRoc ( ) const
inline

Get the Roll-Over-Counter.

Ths method get the upper 32 bit of the 48 bit SRTP packet index (the roll-over-part)

Returns
The roll-over-counter

Definition at line 210 of file CryptoContext.h.

uint32 CryptoContext::getSsrc ( ) const
inline

Get the SSRC of this SRTP Cryptograhic context.

Returns
the SSRC.

Definition at line 329 of file CryptoContext.h.

int32 CryptoContext::getTagLength ( ) const
inline

Get the length of the SRTP authentication tag in bytes.

Returns
the length of the authentication tag.

Definition at line 310 of file CryptoContext.h.

uint64_t CryptoContext::guessIndex ( uint16  newSeqNumber)

Compute (guess) the new SRTP index based on the sequence number of a received RTP packet.

The method uses the algorithm show in RFC3711, Appendix A, to compute the new index.

Parameters
newSeqNumberThe sequence number of the received RTP packet in host order.
Returns
The new SRTP packet index

Definition at line 384 of file CryptoContext.cpp.

CryptoContext * CryptoContext::newCryptoContextForSSRC ( uint32  ssrc,
int  roc,
int64  keyDerivRate 
)

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
ssrcThe SSRC for this context
rocThe Roll-Over-Counter for this context
keyDerivRateThe key derivation rate for this context
Returns
a new CryptoContext with all relevant data set.

Definition at line 484 of file CryptoContext.cpp.

void CryptoContext::setRoc ( uint32  r)
inline

Set the Roll-Over-Counter.

Ths method sets the upper 32 bit of the 48 bit SRTP packet index (the roll-over-part)

Parameters
rThe roll-over-counter

Definition at line 198 of file CryptoContext.h.

void CryptoContext::srtpAuthenticate ( RTPPacket *  rtp,
uint32  roc,
uint8 *  tag 
)

Compute the authentication tag.

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

Parameters
rtpThe RTP packet that contains the data to authenticate.
rocThe 32 bit SRTP roll-over-counter.
tagPoints to a buffer that hold the computed tag. This buffer must be able to hold tagLength bytes.

Definition at line 257 of file CryptoContext.cpp.

void CryptoContext::srtpEncrypt ( RTPPacket *  rtp,
uint64  index,
uint32  ssrc 
)

Perform SRTP encryption.

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

Parameters
rtpThe RTP packet that contains the data to encrypt.
indexThe 48 bit SRTP packet index. See the guessIndex method.
ssrcThe RTP SSRC data in host order.

Definition at line 197 of file CryptoContext.cpp.

void CryptoContext::update ( uint16  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
newSeqNumberThe sequence number of the received RTP packet in host order.

Definition at line 459 of file CryptoContext.cpp.

Field Documentation

int32 CryptoContext::aalg
private

Definition at line 386 of file CryptoContext.h.

int32 CryptoContext::akeyl
private

Definition at line 388 of file CryptoContext.h.

void* CryptoContext::cipher
private

Definition at line 399 of file CryptoContext.h.

int32 CryptoContext::ealg
private

Definition at line 385 of file CryptoContext.h.

int32 CryptoContext::ekeyl
private

Definition at line 387 of file CryptoContext.h.

void* CryptoContext::f8Cipher
private

Definition at line 400 of file CryptoContext.h.

uint32 CryptoContext::guessed_roc
private

Definition at line 363 of file CryptoContext.h.

uint8* CryptoContext::k_a
private

Definition at line 381 of file CryptoContext.h.

uint8* CryptoContext::k_e
private

Definition at line 379 of file CryptoContext.h.

uint8* CryptoContext::k_s
private

Definition at line 383 of file CryptoContext.h.

int64 CryptoContext::key_deriv_rate
private

Definition at line 365 of file CryptoContext.h.

void* CryptoContext::macCtx
private

Definition at line 393 of file CryptoContext.h.

uint8* CryptoContext::master_key
private

Definition at line 370 of file CryptoContext.h.

uint32 CryptoContext::master_key_length
private

Definition at line 371 of file CryptoContext.h.

uint32 CryptoContext::master_key_srtcp_use_nb
private

Definition at line 373 of file CryptoContext.h.

uint32 CryptoContext::master_key_srtp_use_nb
private

Definition at line 372 of file CryptoContext.h.

uint8* CryptoContext::master_salt
private

Definition at line 374 of file CryptoContext.h.

uint32 CryptoContext::master_salt_length
private

Definition at line 375 of file CryptoContext.h.

uint8* CryptoContext::mki
private

Definition at line 360 of file CryptoContext.h.

uint32 CryptoContext::mkiLength
private

Definition at line 359 of file CryptoContext.h.

int32 CryptoContext::n_a
private

Definition at line 380 of file CryptoContext.h.

int32 CryptoContext::n_e
private

Definition at line 378 of file CryptoContext.h.

int32 CryptoContext::n_s
private

Definition at line 382 of file CryptoContext.h.

uint64 CryptoContext::replay_window
private

Definition at line 368 of file CryptoContext.h.

uint32 CryptoContext::roc
private

Definition at line 362 of file CryptoContext.h.

uint16 CryptoContext::s_l
private

Definition at line 364 of file CryptoContext.h.

bool CryptoContext::seqNumSet
private

Definition at line 391 of file CryptoContext.h.

int32 CryptoContext::skeyl
private

Definition at line 389 of file CryptoContext.h.

uint32 CryptoContext::ssrcCtx
private

Definition at line 357 of file CryptoContext.h.

int32 CryptoContext::tagLength
private

Definition at line 390 of file CryptoContext.h.

bool CryptoContext::using_mki
private

Definition at line 358 of file CryptoContext.h.

The documentation for this class was generated from the following files:
Generated on Dec 15, 2017 for ccrtp-2.1.2 (*.h and *.cpp) and libzrtpcpp-2.3.4 (*.h), by   doxygen 1.8.6