Man Linux: Main Page and Category List

NAME

       CryptoContext -

       The implementation for a SRTP cryptographic context.

SYNOPSIS

       #include <CryptoContext.h>

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

   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:
           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 (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:
           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 (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:
           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 (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:
           newSeqNumber The sequence number of the received RTP packet in host
           order.

       Returns:
           The new SRTP packet index

   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:
           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 (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:
           r The roll-over-counter

   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:
           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, 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.

   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:
           newSeqNumber The sequence number of the received RTP packet in host
           order.

Author

       Generated automatically by Doxygen for ccRTP from the source code.