libSRTP  2.1.0-pre
Functions
Secure RTCP

Secure RTCP functions are used to protect RTCP traffic. More...

Functions

srtp_err_status_t srtp_protect_rtcp (srtp_t ctx, void *rtcp_hdr, int *pkt_octet_len)
 srtp_protect_rtcp() is the Secure RTCP sender-side packet processing function. More...
 
srtp_err_status_t srtp_protect_rtcp_mki (srtp_t ctx, void *rtcp_hdr, int *pkt_octet_len, unsigned int use_mki, unsigned int mki_index)
 srtp_protect_rtcp_mki() is the Secure RTCP sender-side packet processing function that can utilize mki. More...
 
srtp_err_status_t srtp_unprotect_rtcp (srtp_t ctx, void *srtcp_hdr, int *pkt_octet_len)
 srtp_unprotect_rtcp() is the Secure RTCP receiver-side packet processing function. More...
 
srtp_err_status_t srtp_unprotect_rtcp_mki (srtp_t ctx, void *srtcp_hdr, int *pkt_octet_len, unsigned int use_mki)
 srtp_unprotect_rtcp() is the Secure RTCP receiver-side packet processing function. More...
 

Detailed Description

RTCP is the control protocol for RTP. libSRTP protects RTCP traffic in much the same way as it does RTP traffic. The function srtp_protect_rtcp() applies cryptographic protections to outbound RTCP packets, and srtp_unprotect_rtcp() verifies the protections on inbound RTCP packets.

A note on the naming convention: srtp_protect_rtcp() has an srtp_t as its first argument, and thus has `srtp_' as its prefix. The trailing `_rtcp' indicates the protocol on which it acts.

Function Documentation

srtp_err_status_t srtp_protect_rtcp ( srtp_t  ctx,
void *  rtcp_hdr,
int *  pkt_octet_len 
)

The function call srtp_protect_rtcp(ctx, rtp_hdr, len_ptr) applies SRTCP protection to the RTCP packet rtcp_hdr (which has length *len_ptr) using the SRTP session context ctx. If srtp_err_status_ok is returned, then rtp_hdr points to the resulting SRTCP packet and *len_ptr is the number of octets in that packet; otherwise, no assumptions should be made about the value of either data elements.

Warning
This function assumes that it can write the authentication tag into the location in memory immediately following the RTCP packet, and assumes that the RTCP packet is aligned on a 32-bit boundary.
This function assumes that it can write SRTP_MAX_TRAILER_LEN+4 into the location in memory immediately following the RTCP packet. Callers MUST ensure that this much writable memory is available in the buffer that holds the RTCP packet.
Parameters
ctxis the SRTP context to use in processing the packet.
rtcp_hdris a pointer to the RTCP packet (before the call); after the function returns, it points to the srtp packet.
pkt_octet_lenis a pointer to the length in octets of the complete RTCP packet (header and body) before the function call, and of the complete SRTCP packet after the call, if srtp_err_status_ok was returned. Otherwise, the value of the data to which it points is undefined.
Returns
  • srtp_err_status_ok if there were no problems.
  • [other] if there was a failure in the cryptographic mechanisms.
srtp_err_status_t srtp_protect_rtcp_mki ( srtp_t  ctx,
void *  rtcp_hdr,
int *  pkt_octet_len,
unsigned int  use_mki,
unsigned int  mki_index 
)

The function call srtp_protect_rtcp(ctx, rtp_hdr, len_ptr) applies SRTCP protection to the RTCP packet rtcp_hdr (which has length *len_ptr) using the SRTP session context ctx. If srtp_err_status_ok is returned, then rtp_hdr points to the resulting SRTCP packet and *len_ptr is the number of octets in that packet; otherwise, no assumptions should be made about the value of either data elements.

Warning
This function assumes that it can write the authentication tag into the location in memory immediately following the RTCP packet, and assumes that the RTCP packet is aligned on a 32-bit boundary.
This function assumes that it can write SRTP_MAX_TRAILER_LEN+4 into the location in memory immediately following the RTCP packet. Callers MUST ensure that this much writable memory is available in the buffer that holds the RTCP packet.
Parameters
ctxis the SRTP context to use in processing the packet.
rtcp_hdris a pointer to the RTCP packet (before the call); after the function returns, it points to the srtp packet.
pkt_octet_lenis a pointer to the length in octets of the complete RTCP packet (header and body) before the function call, and of the complete SRTCP packet after the call, if srtp_err_status_ok was returned. Otherwise, the value of the data to which it points is undefined.
use_mkiis a boolean to tell the system if mki is being used. If set to false then will use the first set of session keys. If set to true will use the session keys identified by the mki_index
mki_indexinteger value specifying which set of session kesy should be used if use_mki is set to true.
Returns
  • srtp_err_status_ok if there were no problems.
  • [other] if there was a failure in the cryptographic mechanisms.
srtp_err_status_t srtp_unprotect_rtcp ( srtp_t  ctx,
void *  srtcp_hdr,
int *  pkt_octet_len 
)

The function call srtp_unprotect_rtcp(ctx, srtp_hdr, len_ptr) verifies the Secure RTCP protection of the SRTCP packet pointed to by srtcp_hdr (which has length *len_ptr), using the SRTP session context ctx. If srtp_err_status_ok is returned, then srtcp_hdr points to the resulting RTCP packet and *len_ptr is the number of octets in that packet; otherwise, no assumptions should be made about the value of either data elements.

Warning
This function assumes that the SRTCP packet is aligned on a 32-bit boundary.
Parameters
ctxis a pointer to the srtp_t which applies to the particular packet.
srtcp_hdris a pointer to the header of the SRTCP packet (before the call). After the function returns, it points to the rtp packet if srtp_err_status_ok was returned; otherwise, the value of the data to which it points is undefined.
pkt_octet_lenis a pointer to the length in octets of the complete SRTCP packet (header and body) before the function call, and of the complete rtp packet after the call, if srtp_err_status_ok was returned. Otherwise, the value of the data to which it points is undefined.
Returns
  • srtp_err_status_ok if the RTCP packet is valid.
  • srtp_err_status_auth_fail if the SRTCP packet failed the message authentication check.
  • srtp_err_status_replay_fail if the SRTCP packet is a replay (e.g. has already been processed and accepted).
  • [other] if there has been an error in the cryptographic mechanisms.
srtp_err_status_t srtp_unprotect_rtcp_mki ( srtp_t  ctx,
void *  srtcp_hdr,
int *  pkt_octet_len,
unsigned int  use_mki 
)

The function call srtp_unprotect_rtcp(ctx, srtp_hdr, len_ptr) verifies the Secure RTCP protection of the SRTCP packet pointed to by srtcp_hdr (which has length *len_ptr), using the SRTP session context ctx. If srtp_err_status_ok is returned, then srtcp_hdr points to the resulting RTCP packet and *len_ptr is the number of octets in that packet; otherwise, no assumptions should be made about the value of either data elements.

Warning
This function assumes that the SRTCP packet is aligned on a 32-bit boundary.
Parameters
ctxis a pointer to the srtp_t which applies to the particular packet.
srtcp_hdris a pointer to the header of the SRTCP packet (before the call). After the function returns, it points to the rtp packet if srtp_err_status_ok was returned; otherwise, the value of the data to which it points is undefined.
pkt_octet_lenis a pointer to the length in octets of the complete SRTCP packet (header and body) before the function call, and of the complete rtp packet after the call, if srtp_err_status_ok was returned. Otherwise, the value of the data to which it points is undefined.
Returns
  • srtp_err_status_ok if the RTCP packet is valid.
  • srtp_err_status_auth_fail if the SRTCP packet failed the message authentication check.
  • srtp_err_status_replay_fail if the SRTCP packet is a replay (e.g. has already been processed and accepted).
  • srtp_err_status_bad_mki if the MKI in the packet is not a known MKI id
  • [other] if there has been an error in the cryptographic mechanisms.