Provided by: libccrtp-doc_2.0.6-3_all bug

NAME

       CryptoContextCtrl -

       The implementation for a SRTCP cryptographic context.

SYNOPSIS

       #include <CryptoContextCtrl.h>

   Public Member Functions
       CryptoContextCtrl (uint32 ssrc)
           Constructor for empty SRTP cryptographic context.
       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.
       ~CryptoContextCtrl ()
           Destructor.
       void srtcpEncrypt (uint8 *rtp, size_t len, uint64 index, uint32 ssrc)
           Perform SRTP encryption.
       void srtcpAuthenticate (uint8 *rtp, size_t len, uint32 roc, uint8 *tag)
           Compute the authentication tag.
       void deriveSrtcpKeys ()
           Perform key derivation according to SRTP specification.
       bool checkReplay (uint32 newSeqNumber)
           Check for packet replay.
       void update (uint32 newSeqNumber)
           Update the SRTP packet index.
       int32 getTagLength () const
           Get the length of the SRTP authentication tag in bytes.
       int32 getMkiLength () const
           Get the length of the MKI in bytes.
       uint32 getSsrc () const
           Get the SSRC of this SRTP Cryptograhic context.
       CryptoContextCtrl * newCryptoContextForSSRC (uint32 ssrc)
           Derive a new Crypto Context for use with a new SSRC.

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_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

   CryptoContextCtrl::CryptoContextCtrl (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.

   CryptoContextCtrl::CryptoContextCtrl (uint32ssrc, 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.
           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.

Member Function Documentation

   bool CryptoContextCtrl::checkReplay (uint32newSeqNumber)
       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 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.

   int32 CryptoContextCtrl::getMkiLength () const [inline]
       Get the length of the MKI in bytes.

       Returns:
           the length of the MKI.

   uint32 CryptoContextCtrl::getSsrc () const [inline]
       Get the SSRC of this SRTP Cryptograhic context.

       Returns:
           the SSRC.

   int32 CryptoContextCtrl::getTagLength () const [inline]
       Get the length of the SRTP authentication tag in bytes.

       Returns:
           the length of the authentication tag.

   CryptoContextCtrl* CryptoContextCtrl::newCryptoContextForSSRC (uint32ssrc)
       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 CryptoContextCtrl::srtcpAuthenticate (uint8 *rtp, size_tlen, 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 CryptoContextCtrl::srtcpEncrypt (uint8 *rtp, size_tlen, 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 CryptoContextCtrl::update (uint32newSeqNumber)
       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.

Author

       Generated automatically by Doxygen for ccRTP from the source code.