CryptoContext(3) | Library Functions Manual | CryptoContext(3) |
NAME¶
CryptoContext - The implementation for a SRTP cryptographic context.SYNOPSIS¶
#include <CryptoContext.h>Public Member Functions¶
CryptoContext (uint32 ssrc)
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_abad@terra.es
Erik Eliasson eliasson@it.kth.se
Johan Bilien jobi@via.ecp.fr
Joachim Orrblad joachim@orrblad.com
Werner Dittmann Werner.Dittmann@t-online.de
Constructor & Destructor Documentation¶
CryptoContext::CryptoContext (uint32ssrc)¶
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.
CryptoContext::CryptoContext (uint32ssrc, int32roc, int64keyDerivRate, const int32ealg, const int32aalg, uint8 *masterKey, int32masterKeyLength, uint8 *masterSalt, int32masterSaltLength, int32ekeyl, int32akeyl, int32skeyl, int32tagLength)¶
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.
roc The 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.
keyDerivRate The key derivation rate defines when to recompute the SRTP
session keys. Refer to chapter 4.3.1 in the RFC.
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.
CryptoContext::~CryptoContext ()¶
Destructor. Cleans the SRTP cryptographic context.Member Function Documentation¶
bool CryptoContext::checkReplay (uint16newSeqNumber)¶
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.
void CryptoContext::deriveSrtpKeys (uint64index)¶
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.
int32 CryptoContext::getMkiLength () const [inline]¶
Get the length of the MKI in bytes. Returns:the length of the MKI.
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
uint32 CryptoContext::getSsrc () const [inline]¶
Get the SSRC of this SRTP Cryptograhic context. Returns:the SSRC.
int32 CryptoContext::getTagLength () const [inline]¶
Get the length of the SRTP authentication tag in bytes. Returns:the length of the authentication tag.
uint64 CryptoContext::guessIndex (uint16newSeqNumber)¶
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:newSeqNumber The sequence number of the received
RTP packet in host order.
Returns:
The new SRTP packet index
CryptoContext* CryptoContext::newCryptoContextForSSRC (uint32ssrc, introc, int64keyDerivRate)¶
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.
void CryptoContext::setRoc (uint32r) [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:r The roll-over-counter
void CryptoContext::srtpAuthenticate ( RTPPacket *rtp, uint32roc, uint8 *tag)¶
Compute the authentication tag. Compute the authentication tag according the the parameters 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.
void CryptoContext::srtpEncrypt ( RTPPacket *rtp, uint64index, uint32ssrc)¶
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.
void CryptoContext::update (uint16newSeqNumber)¶
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
RTP packet in host order.
Author¶
Generated automatically by Doxygen for ccRTP from the source code.Wed Jun 25 2014 | ccRTP |