Secure RTP

libSRTP provides functions for protecting RTP and RTCP. See Section Overview for an introduction to the use of the library. More...

## Modules

| Secure RTCP
| Secure RTCP functions are used to protect RTCP traffic.
| data associated to a SRTP session.
| Store custom user data within a SRTP session.
| SRTP events and callbacks
| libSRTP can use a user-provided callback function to handle events.

## Data Structures

struct | srtp_crypto_policy_t
| srtp_crypto_policy_t describes a particular crypto policy that can be applied to an SRTP stream. More...
struct | srtp_ssrc_t
| An srtp_ssrc_t represents a particular SSRC value, or a ‘wildcard’ SSRC. More...
struct | srtp_master_key_t
| srtp_master_key_t represents a master key. There will be a Master Key Index and the Master Key associated with the Master Key Index. Need to also keep track of the Master Key Index Size to correctly read it from a packet. More...
struct | srtp_policy_t
| represents the policy for an SRTP session. More...

## Macros

#define | SRTP_MAX_MKI_LEN 128
#define | SRTP_MAX_TRAILER_LEN (SRTP_MAX_TAG_LEN + SRTP_MAX_MKI_LEN)
| the maximum number of octets added by srtp_protect().
#define | SRTP_SRCTP_INDEX_LEN 4
#define | SRTP_MAX_SRTCP_TRAILER_LEN (SRTP_SRCTP_INDEX_LEN + SRTP_MAX_TAG_LEN + SRTP_MAX_MKI_LEN)
| the maximum number of octets added by srtp_protect().
#define | SRTP_MAX_NUM_MASTER_KEYS 16
#define | srtp_crypto_policy_set_aes_cm_128_hmac_sha1_80(p) srtp_crypto_policy_set_rtp_default(p)
| srtp_crypto_policy_set_aes_cm_128_hmac_sha1_80() sets a crypto policy structure to the SRTP default policy for RTP protection.

## Typedefs

typedef uint32_t | srtp_cipher_type_id_t
| A srtp_cipher_type_id_t is an identifier for a particular cipher type.
typedef uint32_t | srtp_auth_type_id_t
| An srtp_auth_type_id_t is an identifier for a particular authentication function.
typedef struct srtp_crypto_policy_t | srtp_crypto_policy_t
| srtp_crypto_policy_t describes a particular crypto policy that can be applied to an SRTP stream.
typedef struct srtp_master_key_t | srtp_master_key_t
| srtp_master_key_t represents a master key. There will be a Master Key Index and the Master Key associated with the Master Key Index. Need to also keep track of the Master Key Index Size to correctly read it from a packet.
typedef struct srtp_policy_t | srtp_policy_t
| represents the policy for an SRTP session.
typedef srtp_ctx_t * | srtp_t
| An srtp_t points to an SRTP session structure.

## Enumerations

enum

srtp_err_status_t {
srtp_err_status_ok = 0 , srtp_err_status_fail = 1 , srtp_err_status_bad_param = 2 , srtp_err_status_alloc_fail = 3 ,
srtp_err_status_dealloc_fail = 4 , srtp_err_status_init_fail = 5 , srtp_err_status_terminus = 6 , srtp_err_status_auth_fail = 7 ,
srtp_err_status_cipher_fail = 8 , srtp_err_status_replay_fail = 9 , srtp_err_status_replay_old = 10 , srtp_err_status_algo_fail = 11 ,
srtp_err_status_no_such_op = 12 , srtp_err_status_no_ctx = 13 , srtp_err_status_cant_check = 14 , srtp_err_status_key_expired = 15 ,
srtp_err_status_socket_err = 16 , srtp_err_status_signal_err = 17 , srtp_err_status_nonce_bad = 18 , srtp_err_status_read_fail = 19 ,
srtp_err_status_write_fail = 20 , srtp_err_status_parse_err = 21 , srtp_err_status_encode_err = 22 , srtp_err_status_semaphore_err = 23 ,
srtp_err_status_pfkey_err = 24 , srtp_err_status_bad_mki = 25 , srtp_err_status_pkt_idx_old = 26 , srtp_err_status_pkt_idx_adv = 27
}

| srtp_err_status_t defines error codes. More...
enum | srtp_sec_serv_t { sec_serv_none = 0 , sec_serv_conf = 1 , sec_serv_auth = 2 , sec_serv_conf_and_auth = 3 }
| srtp_sec_serv_t describes a set of security services. More...
enum | srtp_ssrc_type_t { ssrc_undefined = 0 , ssrc_specific = 1 , ssrc_any_inbound = 2 , ssrc_any_outbound = 3 }
| srtp_ssrc_type_t describes the type of an SSRC. More...

## Functions

srtp_err_status_t | srtp_init (void)
| srtp_init() initializes the srtp library.
srtp_err_status_t | srtp_shutdown (void)
| srtp_shutdown() de-initializes the srtp library.
srtp_err_status_t | srtp_protect (srtp_t ctx, void *rtp_hdr, int *len_ptr)
| srtp_protect() is the Secure RTP sender-side packet processing function.
srtp_err_status_t | srtp_protect_mki (srtp_ctx_t *ctx, void *rtp_hdr, int *pkt_octet_len, unsigned int use_mki, unsigned int mki_index)
| srtp_protect_mki() is the Secure RTP sender-side packet processing function that can utilize MKI.
srtp_err_status_t | srtp_unprotect (srtp_t ctx, void *srtp_hdr, int *len_ptr)
| srtp_unprotect() is the Secure RTP receiver-side packet processing function.
srtp_err_status_t | srtp_unprotect_mki (srtp_t ctx, void *srtp_hdr, int *len_ptr, unsigned int use_mki)
| srtp_unprotect_mki() is the Secure RTP receiver-side packet processing function that checks for MKI.
srtp_err_status_t | srtp_create (srtp_t *session, const srtp_policy_t *policy)
| srtp_create() allocates and initializes an SRTP session.
srtp_err_status_t | srtp_add_stream (srtp_t session, const srtp_policy_t *policy)
| srtp_add_stream() allocates and initializes an SRTP stream within a given SRTP session.
srtp_err_status_t | srtp_remove_stream (srtp_t session, uint32_t ssrc)
| srtp_remove_stream() deallocates an SRTP stream.
srtp_err_status_t | srtp_update (srtp_t session, const srtp_policy_t *policy)
| srtp_update() updates all streams in the session.
srtp_err_status_t | srtp_update_stream (srtp_t session, const srtp_policy_t *policy)
| srtp_update_stream() updates a SRTP stream.
void | srtp_crypto_policy_set_rtp_default (srtp_crypto_policy_t *p)
| srtp_crypto_policy_set_rtp_default() sets a crypto policy structure to the SRTP default policy for RTP protection.
void | srtp_crypto_policy_set_rtcp_default (srtp_crypto_policy_t *p)
| srtp_crypto_policy_set_rtcp_default() sets a crypto policy structure to the SRTP default policy for RTCP protection.
void | srtp_crypto_policy_set_aes_cm_128_hmac_sha1_32 (srtp_crypto_policy_t *p)
| srtp_crypto_policy_set_aes_cm_128_hmac_sha1_32() sets a crypto policy structure to a short-authentication tag policy
void | srtp_crypto_policy_set_aes_cm_128_null_auth (srtp_crypto_policy_t *p)
| srtp_crypto_policy_set_aes_cm_128_null_auth() sets a crypto policy structure to an encryption-only policy
void | srtp_crypto_policy_set_null_cipher_hmac_sha1_80 (srtp_crypto_policy_t *p)
| srtp_crypto_policy_set_null_cipher_hmac_sha1_80() sets a crypto policy structure to an authentication-only policy
void | srtp_crypto_policy_set_null_cipher_hmac_null (srtp_crypto_policy_t *p)
| srtp_crypto_policy_set_null_cipher_hmac_null() sets a crypto policy structure to use no encryption or authentication.
void | srtp_crypto_policy_set_aes_cm_256_hmac_sha1_80 (srtp_crypto_policy_t *p)
| srtp_crypto_policy_set_aes_cm_256_hmac_sha1_80() sets a crypto policy structure to a encryption and authentication policy using AES-256 for RTP protection.
void | srtp_crypto_policy_set_aes_cm_256_hmac_sha1_32 (srtp_crypto_policy_t *p)
| srtp_crypto_policy_set_aes_cm_256_hmac_sha1_32() sets a crypto policy structure to a short-authentication tag policy using AES-256 encryption.
void | srtp_crypto_policy_set_aes_cm_256_null_auth (srtp_crypto_policy_t *p)
| srtp_crypto_policy_set_aes_cm_256_null_auth() sets a crypto policy structure to an encryption-only policy
void | srtp_crypto_policy_set_aes_cm_192_hmac_sha1_80 (srtp_crypto_policy_t *p)
| srtp_crypto_policy_set_aes_cm_192_hmac_sha1_80() sets a crypto policy structure to a encryption and authentication policy using AES-192 for RTP protection.
void | srtp_crypto_policy_set_aes_cm_192_hmac_sha1_32 (srtp_crypto_policy_t *p)
| srtp_crypto_policy_set_aes_cm_192_hmac_sha1_32() sets a crypto policy structure to a short-authentication tag policy using AES-192 encryption.
void | srtp_crypto_policy_set_aes_cm_192_null_auth (srtp_crypto_policy_t *p)
| srtp_crypto_policy_set_aes_cm_192_null_auth() sets a crypto policy structure to an encryption-only policy
void | srtp_crypto_policy_set_aes_gcm_128_8_auth (srtp_crypto_policy_t *p)
| srtp_crypto_policy_set_aes_gcm_128_8_auth() sets a crypto policy structure to an AEAD encryption policy.
void | srtp_crypto_policy_set_aes_gcm_256_8_auth (srtp_crypto_policy_t *p)
| srtp_crypto_policy_set_aes_gcm_256_8_auth() sets a crypto policy structure to an AEAD encryption policy
void | srtp_crypto_policy_set_aes_gcm_128_8_only_auth (srtp_crypto_policy_t *p)
| srtp_crypto_policy_set_aes_gcm_128_8_only_auth() sets a crypto policy structure to an AEAD authentication-only policy
void | srtp_crypto_policy_set_aes_gcm_256_8_only_auth (srtp_crypto_policy_t *p)
| srtp_crypto_policy_set_aes_gcm_256_8_only_auth() sets a crypto policy structure to an AEAD authentication-only policy
void | srtp_crypto_policy_set_aes_gcm_128_16_auth (srtp_crypto_policy_t *p)
| srtp_crypto_policy_set_aes_gcm_128_16_auth() sets a crypto policy structure to an AEAD encryption policy.
void | srtp_crypto_policy_set_aes_gcm_256_16_auth (srtp_crypto_policy_t *p)
| srtp_crypto_policy_set_aes_gcm_256_16_auth() sets a crypto policy structure to an AEAD encryption policy
srtp_err_status_t | srtp_dealloc (srtp_t s)
| srtp_dealloc() deallocates storage for an SRTP session context.
srtp_err_status_t | srtp_crypto_policy_set_from_profile_for_rtp (srtp_crypto_policy_t *policy, srtp_profile_t profile)
| srtp_crypto_policy_set_from_profile_for_rtp() sets a crypto policy structure to the appropriate value for RTP based on an srtp_profile_t
srtp_err_status_t | srtp_crypto_policy_set_from_profile_for_rtcp (srtp_crypto_policy_t *policy, srtp_profile_t profile)
| srtp_crypto_policy_set_from_profile_for_rtcp() sets a crypto policy structure to the appropriate value for RTCP based on an srtp_profile_t
unsigned int | srtp_profile_get_master_key_length (srtp_profile_t profile)
| returns the master key length for a given SRTP profile
unsigned int | srtp_profile_get_master_salt_length (srtp_profile_t profile)
| returns the master salt length for a given SRTP profile
void | srtp_append_salt_to_key (unsigned char *key, unsigned int bytes_in_key, unsigned char *salt, unsigned int bytes_in_salt)
| appends the salt to the key

## Detailed Description

## Macro Definition Documentation

## srtp_crypto_policy_set_aes_cm_128_hmac_sha1_80

#define srtp_crypto_policy_set_aes_cm_128_hmac_sha1_80 | ( |  | p | ) | srtp_crypto_policy_set_rtp_default(p)

Parameters

  p | is a pointer to the policy structure to be set

The function srtp_crypto_policy_set_aes_cm_128_hmac_sha1_80() is a synonym for srtp_crypto_policy_set_rtp_default(). It conforms to the naming convention used in RFC 4568 (SDP Security Descriptions for Media Streams).

Returns
  void.

## SRTP_MAX_MKI_LEN

#define SRTP_MAX_MKI_LEN 128

SRTP_MAX_MKI_LEN is the maximum size the MKI could be which is 128 bytes

## SRTP_MAX_NUM_MASTER_KEYS

#define SRTP_MAX_NUM_MASTER_KEYS 16

SRTP_MAX_NUM_MASTER_KEYS is the maximum number of Master keys for MKI supported by libSRTP.

## SRTP_MAX_SRTCP_TRAILER_LEN

#define SRTP_MAX_SRTCP_TRAILER_LEN (SRTP_SRCTP_INDEX_LEN + SRTP_MAX_TAG_LEN + SRTP_MAX_MKI_LEN)

SRTP_MAX_SRTCP_TRAILER_LEN is the maximum length of the SRTCP trailer (index, authentication tag and MKI) supported by libSRTP. This value is the maximum number of octets that will be added to an RTCP packet by srtp_protect_rtcp().

## SRTP_MAX_TRAILER_LEN

#define SRTP_MAX_TRAILER_LEN (SRTP_MAX_TAG_LEN + SRTP_MAX_MKI_LEN)

SRTP_MAX_TRAILER_LEN is the maximum length of the SRTP trailer (authentication tag and MKI) supported by libSRTP. This value is the maximum number of octets that will be added to an RTP packet by srtp_protect().

## SRTP_SRCTP_INDEX_LEN

#define SRTP_SRCTP_INDEX_LEN 4

SRTP_SRCTP_INDEX_LEN is the size the SRTCP index which is 4 bytes

## Typedef Documentation

## srtp_auth_type_id_t

typedef uint32_t srtp_auth_type_id_t

An srtp_auth_type_id_t is an integer that represents a particular authentication function type, e.g. HMAC-SHA1. A SRTP_NULL_AUTH is available; this authentication function performs no computation, and can be selected to indicate that no authentication is to take place.

## srtp_cipher_type_id_t

typedef uint32_t srtp_cipher_type_id_t

A srtp_cipher_type_id_t is an integer that represents a particular cipher type, e.g. the Advanced Encryption Standard (AES). A SRTP_NULL_CIPHER is available; this cipher leaves the data unchanged, and can be selected to indicate that no encryption is to take place.

## srtp_crypto_policy_t

typedef struct srtp_crypto_policy_t srtp_crypto_policy_t

A srtp_crypto_policy_t describes a particular cryptographic policy that can be applied to an SRTP or SRTCP stream. An SRTP session policy consists of a list of these policies, one for each SRTP stream in the session.

## srtp_policy_t

typedef struct srtp_policy_t srtp_policy_t

A single srtp_policy_t struct represents the policy for a single SRTP stream, and a linked list of these elements represents the policy for an entire SRTP session. Each element contains the SRTP and SRTCP crypto policies for that stream, a pointer to the SRTP master key for that stream, the SSRC describing that stream, or a flag indicating a ‘wildcard’ SSRC value, and a ‘next’ field that holds a pointer to the next element in the list of policy elements, or NULL if it is the last element.

The wildcard value SSRC_ANY_INBOUND matches any SSRC from an inbound stream that for which there is no explicit SSRC entry in another policy element. Similarly, the value SSRC_ANY_OUTBOUND will matches any SSRC from an outbound stream that does not appear in another policy element. Note that wildcard SSRCs &b cannot be used to match both inbound and outbound traffic. This restriction is intentional, and it allows libSRTP to ensure that no security lapses result from accidental re-use of SSRC values during key sharing.

Warning
  The final element of the list must have its ‘next’ pointer set to NULL.

## srtp_t

typedef srtp_ctx_t* srtp_t

The typedef srtp_t is a pointer to a structure that represents an SRTP session. This datatype is intentionally opaque in order to separate the interface from the implementation.

An SRTP session consists of all of the traffic sent to the RTP and RTCP destination transport addresses, using the RTP/SAVP (Secure Audio/Video Profile). A session can be viewed as a set of SRTP streams, each of which originates with a different participant.

## Enumeration Type Documentation

## srtp_err_status_t

enum srtp_err_status_t

The enumeration srtp_err_status_t defines error codes. Note that the value of srtp_err_status_ok is equal to zero, which can simplify error checking somewhat.

Enumerator
srtp_err_status_ok | nothing to report
srtp_err_status_fail | unspecified failure
srtp_err_status_bad_param | unsupported parameter
srtp_err_status_alloc_fail | couldn't allocate memory
srtp_err_status_dealloc_fail | couldn't deallocate properly
srtp_err_status_init_fail | couldn't initialize
srtp_err_status_terminus | can't process as much data as requested
srtp_err_status_auth_fail | authentication failure
srtp_err_status_cipher_fail | cipher failure
srtp_err_status_replay_fail | replay check failed (bad index)
srtp_err_status_replay_old | replay check failed (index too old)
srtp_err_status_algo_fail | algorithm failed test routine
srtp_err_status_no_such_op | unsupported operation
srtp_err_status_no_ctx | no appropriate context found
srtp_err_status_cant_check | unable to perform desired validation
srtp_err_status_key_expired | can't use key any more
srtp_err_status_socket_err | error in use of socket
srtp_err_status_signal_err | error in use POSIX signals
srtp_err_status_nonce_bad | nonce check failed
srtp_err_status_read_fail | couldn't read data
srtp_err_status_write_fail | couldn't write data
srtp_err_status_parse_err | error parsing data
srtp_err_status_encode_err | error encoding data
srtp_err_status_semaphore_err | error while using semaphores
srtp_err_status_pfkey_err | error while using pfkey
srtp_err_status_bad_mki | error MKI present in packet is invalid
srtp_err_status_pkt_idx_old | packet index is too old to consider
srtp_err_status_pkt_idx_adv | packet index advanced, reset needed

## srtp_sec_serv_t

enum srtp_sec_serv_t

A srtp_sec_serv_t enumeration is used to describe the particular security services that will be applied by a particular crypto policy (or other mechanism).

Enumerator
sec_serv_none | no services
sec_serv_conf | confidentiality
sec_serv_auth | authentication
sec_serv_conf_and_auth | confidentiality and authentication

## srtp_ssrc_type_t

enum srtp_ssrc_type_t

An srtp_ssrc_type_t enumeration is used to indicate a type of SSRC. See srtp_policy_t for more information.

Enumerator
ssrc_undefined | Indicates an undefined SSRC type.
ssrc_specific | Indicates a specific SSRC value
ssrc_any_inbound | Indicates any inbound SSRC value (i.e. a value that is used in the function srtp_unprotect())
ssrc_any_outbound | Indicates any outbound SSRC value (i.e. a value that is used in the function srtp_protect())

## Function Documentation

## srtp_add_stream()

srtp_err_status_t srtp_add_stream | ( | srtp_t | session,
|  | const srtp_policy_t * | policy
| ) |  |

The function call srtp_add_stream(session, policy) allocates and initializes a new SRTP stream within a given, previously created session, applying the policy given as the other argument to that stream.

Returns
  values:
  - srtp_err_status_ok if stream creation succeeded.
  - srtp_err_status_alloc_fail if stream allocation failed
  - srtp_err_status_init_fail if stream initialization failed.

## srtp_append_salt_to_key()

void srtp_append_salt_to_key | ( | unsigned char * | key,
|  | unsigned int | bytes_in_key,
|  | unsigned char * | salt,
|  | unsigned int | bytes_in_salt
| ) |  |

The function call srtp_append_salt_to_key(k, klen, s, slen) copies the string s to the location at klen bytes following the location k.

Warning
  There must be at least bytes_in_salt + bytes_in_key bytes available at the location pointed to by key.

## srtp_create()

srtp_err_status_t srtp_create | ( | srtp_t * | session,
|  | const srtp_policy_t * | policy
| ) |  |

The function call srtp_create(session, policy) allocates and initializes an SRTP session context, applying the given policy.

Parameters

  session | is a pointer to the SRTP session to which the policy is to be added.
  policy | is the srtp_policy_t struct that describes the policy for the session. The struct may be a single element, or it may be the head of a list, in which case each element of the list is processed. It may also be NULL, in which case streams should be added later using srtp_add_stream(). The final element of the list must have its ‘next’ field set to NULL.

Returns
  - srtp_err_status_ok if creation succeeded.
  - srtp_err_status_alloc_fail if allocation failed.
  - srtp_err_status_init_fail if initialization failed.

## srtp_crypto_policy_set_aes_cm_128_hmac_sha1_32()

void srtp_crypto_policy_set_aes_cm_128_hmac_sha1_32 | ( | srtp_crypto_policy_t * | p | ) |

Parameters

  p | is a pointer to the policy structure to be set

The function call srtp_crypto_policy_set_aes_cm_128_hmac_sha1_32(&p) sets the srtp_crypto_policy_t at location p to use policy AES_CM_128_HMAC_SHA1_32 as defined in RFC 4568. This policy uses AES-128 Counter Mode encryption and HMAC-SHA1 authentication, with an authentication tag that is only 32 bits long. This length is considered adequate only for protecting audio and video media that use a stateless playback function. See Section 7.5 of RFC 3711 (http://www.ietf.org/rfc/rfc3711.txt).

This function is a convenience that helps to avoid dealing directly with the policy data structure. You are encouraged to initialize policy elements with this function call. Doing so may allow your code to be forward compatible with later versions of libSRTP that include more elements in the srtp_crypto_policy_t datatype.

Warning
  This crypto policy is intended for use in SRTP, but not in SRTCP. It is recommended that a policy that uses longer authentication tags be used for SRTCP. See Section 7.5 of RFC 3711 (http://www.ietf.org/rfc/rfc3711.txt).

Returns
  void.

## srtp_crypto_policy_set_aes_cm_128_null_auth()

void srtp_crypto_policy_set_aes_cm_128_null_auth | ( | srtp_crypto_policy_t * | p | ) |

Parameters

  p | is a pointer to the policy structure to be set

The function call srtp_crypto_policy_set_aes_cm_128_null_auth(&p) sets the srtp_crypto_policy_t at location p to use the SRTP default cipher (AES-128 Counter Mode), but to use no authentication method. This policy is NOT RECOMMENDED unless it is unavoidable; see Section 7.5 of RFC 3711 (http://www.ietf.org/rfc/rfc3711.txt).

This function is a convenience that helps to avoid dealing directly with the policy data structure. You are encouraged to initialize policy elements with this function call. Doing so may allow your code to be forward compatible with later versions of libSRTP that include more elements in the srtp_crypto_policy_t datatype.

Warning
  This policy is NOT RECOMMENDED for SRTP unless it is unavoidable, and it is NOT RECOMMENDED at all for SRTCP; see Section 7.5 of RFC 3711 (http://www.ietf.org/rfc/rfc3711.txt).

Returns
  void.

## srtp_crypto_policy_set_aes_cm_192_hmac_sha1_32()

void srtp_crypto_policy_set_aes_cm_192_hmac_sha1_32 | ( | srtp_crypto_policy_t * | p | ) |

Parameters

  p | is a pointer to the policy structure to be set

The function call srtp_crypto_policy_set_aes_cm_192_hmac_sha1_32(&p) sets the srtp_crypto_policy_t at location p to use policy AES_CM_192_HMAC_SHA1_32 as defined in RFC 6188. This policy uses AES-192 Counter Mode encryption and HMAC-SHA1 authentication, with an authentication tag that is only 32 bits long. This length is considered adequate only for protecting audio and video media that use a stateless playback function. See Section 7.5 of RFC 3711 (http://www.ietf.org/rfc/rfc3711.txt).

This function is a convenience that helps to avoid dealing directly with the policy data structure. You are encouraged to initialize policy elements with this function call. Doing so may allow your code to be forward compatible with later versions of libSRTP that include more elements in the srtp_crypto_policy_t datatype.

Warning
  This crypto policy is intended for use in SRTP, but not in SRTCP. It is recommended that a policy that uses longer authentication tags be used for SRTCP. See Section 7.5 of RFC 3711 (http://www.ietf.org/rfc/rfc3711.txt).

Returns
  void.

## srtp_crypto_policy_set_aes_cm_192_hmac_sha1_80()

void srtp_crypto_policy_set_aes_cm_192_hmac_sha1_80 | ( | srtp_crypto_policy_t * | p | ) |

Parameters

  p | is a pointer to the policy structure to be set

The function call srtp_crypto_policy_set_aes_cm_192_hmac_sha1_80(&p) sets the srtp_crypto_policy_t at location p to use policy AES_CM_192_HMAC_SHA1_80 as defined in RFC 6188. This policy uses AES-192 Counter Mode encryption and HMAC-SHA1 authentication, with an 80 bit authentication tag.

This function is a convenience that helps to avoid dealing directly with the policy data structure. You are encouraged to initialize policy elements with this function call. Doing so may allow your code to be forward compatible with later versions of libSRTP that include more elements in the srtp_crypto_policy_t datatype.

Returns
  void.

## srtp_crypto_policy_set_aes_cm_192_null_auth()

void srtp_crypto_policy_set_aes_cm_192_null_auth | ( | srtp_crypto_policy_t * | p | ) |

Parameters

  p | is a pointer to the policy structure to be set

The function call srtp_crypto_policy_set_aes_cm_192_null_auth(&p) sets the srtp_crypto_policy_t at location p to use the SRTP default cipher (AES-192 Counter Mode), but to use no authentication method. This policy is NOT RECOMMENDED unless it is unavoidable; see Section 7.5 of RFC 3711 (http://www.ietf.org/rfc/rfc3711.txt).

This function is a convenience that helps to avoid dealing directly with the policy data structure. You are encouraged to initialize policy elements with this function call. Doing so may allow your code to be forward compatible with later versions of libSRTP that include more elements in the srtp_crypto_policy_t datatype.

Warning
  This policy is NOT RECOMMENDED for SRTP unless it is unavoidable, and it is NOT RECOMMENDED at all for SRTCP; see Section 7.5 of RFC 3711 (http://www.ietf.org/rfc/rfc3711.txt).

Returns
  void.

## srtp_crypto_policy_set_aes_cm_256_hmac_sha1_32()

void srtp_crypto_policy_set_aes_cm_256_hmac_sha1_32 | ( | srtp_crypto_policy_t * | p | ) |

Parameters

  p | is a pointer to the policy structure to be set

The function call srtp_crypto_policy_set_aes_cm_256_hmac_sha1_32(&p) sets the srtp_crypto_policy_t at location p to use policy AES_CM_256_HMAC_SHA1_32 as defined in RFC 6188. This policy uses AES-256 Counter Mode encryption and HMAC-SHA1 authentication, with an authentication tag that is only 32 bits long. This length is considered adequate only for protecting audio and video media that use a stateless playback function. See Section 7.5 of RFC 3711 (http://www.ietf.org/rfc/rfc3711.txt).

This function is a convenience that helps to avoid dealing directly with the policy data structure. You are encouraged to initialize policy elements with this function call. Doing so may allow your code to be forward compatible with later versions of libSRTP that include more elements in the srtp_crypto_policy_t datatype.

Warning
  This crypto policy is intended for use in SRTP, but not in SRTCP. It is recommended that a policy that uses longer authentication tags be used for SRTCP. See Section 7.5 of RFC 3711 (http://www.ietf.org/rfc/rfc3711.txt).

Returns
  void.

## srtp_crypto_policy_set_aes_cm_256_hmac_sha1_80()

void srtp_crypto_policy_set_aes_cm_256_hmac_sha1_80 | ( | srtp_crypto_policy_t * | p | ) |

Parameters

  p | is a pointer to the policy structure to be set

The function call srtp_crypto_policy_set_aes_cm_256_hmac_sha1_80(&p) sets the srtp_crypto_policy_t at location p to use policy AES_CM_256_HMAC_SHA1_80 as defined in RFC 6188. This policy uses AES-256 Counter Mode encryption and HMAC-SHA1 authentication, with an 80 bit authentication tag.

This function is a convenience that helps to avoid dealing directly with the policy data structure. You are encouraged to initialize policy elements with this function call. Doing so may allow your code to be forward compatible with later versions of libSRTP that include more elements in the srtp_crypto_policy_t datatype.

Returns
  void.

## srtp_crypto_policy_set_aes_cm_256_null_auth()

void srtp_crypto_policy_set_aes_cm_256_null_auth | ( | srtp_crypto_policy_t * | p | ) |

Parameters

  p | is a pointer to the policy structure to be set

The function call srtp_crypto_policy_set_aes_cm_256_null_auth(&p) sets the srtp_crypto_policy_t at location p to use the SRTP default cipher (AES-256 Counter Mode), but to use no authentication method. This policy is NOT RECOMMENDED unless it is unavoidable; see Section 7.5 of RFC 3711 (http://www.ietf.org/rfc/rfc3711.txt).

This function is a convenience that helps to avoid dealing directly with the policy data structure. You are encouraged to initialize policy elements with this function call. Doing so may allow your code to be forward compatible with later versions of libSRTP that include more elements in the srtp_crypto_policy_t datatype.

Warning
  This policy is NOT RECOMMENDED for SRTP unless it is unavoidable, and it is NOT RECOMMENDED at all for SRTCP; see Section 7.5 of RFC 3711 (http://www.ietf.org/rfc/rfc3711.txt).

Returns
  void.

## srtp_crypto_policy_set_aes_gcm_128_16_auth()

void srtp_crypto_policy_set_aes_gcm_128_16_auth | ( | srtp_crypto_policy_t * | p | ) |

Parameters

  p | is a pointer to the policy structure to be set

The function call srtp_crypto_policy_set_aes_gcm_128_16_auth(&p) sets the srtp_crypto_policy_t at location p to use the SRTP default cipher (AES-128 Galois Counter Mode) with 16 octet auth tag. This policy applies confidentiality and authentication to both the RTP and RTCP packets.

This function is a convenience that helps to avoid dealing directly with the policy data structure. You are encouraged to initialize policy elements with this function call. Doing so may allow your code to be forward compatible with later versions of libSRTP that include more elements in the srtp_crypto_policy_t datatype.

Returns
  void.

## srtp_crypto_policy_set_aes_gcm_128_8_auth()

void srtp_crypto_policy_set_aes_gcm_128_8_auth | ( | srtp_crypto_policy_t * | p | ) |

Parameters

  p | is a pointer to the policy structure to be set

The function call srtp_crypto_policy_set_aes_gcm_128_8_auth(&p) sets the srtp_crypto_policy_t at location p to use the SRTP default cipher (AES-128 Galois Counter Mode) with 8 octet auth tag. This policy applies confidentiality and authentication to both the RTP and RTCP packets.

This function is a convenience that helps to avoid dealing directly with the policy data structure. You are encouraged to initialize policy elements with this function call. Doing so may allow your code to be forward compatible with later versions of libSRTP that include more elements in the srtp_crypto_policy_t datatype.

Returns
  void.

## srtp_crypto_policy_set_aes_gcm_128_8_only_auth()

void srtp_crypto_policy_set_aes_gcm_128_8_only_auth | ( | srtp_crypto_policy_t * | p | ) |

Parameters

  p | is a pointer to the policy structure to be set

The function call srtp_crypto_policy_set_aes_gcm_128_8_only_auth(&p) sets the srtp_crypto_policy_t at location p to use the SRTP default cipher (AES-128 Galois Counter Mode) with 8 octet auth tag. This policy applies confidentiality and authentication to the RTP packets, but only authentication to the RTCP packets.

This function is a convenience that helps to avoid dealing directly with the policy data structure. You are encouraged to initialize policy elements with this function call. Doing so may allow your code to be forward compatible with later versions of libSRTP that include more elements in the srtp_crypto_policy_t datatype.

Returns
  void.

## srtp_crypto_policy_set_aes_gcm_256_16_auth()

void srtp_crypto_policy_set_aes_gcm_256_16_auth | ( | srtp_crypto_policy_t * | p | ) |

Parameters

  p | is a pointer to the policy structure to be set

The function call srtp_crypto_policy_set_aes_gcm_256_16_auth(&p) sets the srtp_crypto_policy_t at location p to use the SRTP default cipher (AES-256 Galois Counter Mode) with 16 octet auth tag. This policy applies confidentiality and authentication to both the RTP and RTCP packets.

This function is a convenience that helps to avoid dealing directly with the policy data structure. You are encouraged to initialize policy elements with this function call. Doing so may allow your code to be forward compatible with later versions of libSRTP that include more elements in the srtp_crypto_policy_t datatype.

Returns
  void.

## srtp_crypto_policy_set_aes_gcm_256_8_auth()

void srtp_crypto_policy_set_aes_gcm_256_8_auth | ( | srtp_crypto_policy_t * | p | ) |

Parameters

  p | is a pointer to the policy structure to be set

The function call srtp_crypto_policy_set_aes_gcm_256_8_auth(&p) sets the srtp_crypto_policy_t at location p to use the SRTP default cipher (AES-256 Galois Counter Mode) with 8 octet auth tag. This policy applies confidentiality and authentication to both the RTP and RTCP packets.

This function is a convenience that helps to avoid dealing directly with the policy data structure. You are encouraged to initialize policy elements with this function call. Doing so may allow your code to be forward compatible with later versions of libSRTP that include more elements in the srtp_crypto_policy_t datatype.

Returns
  void.

## srtp_crypto_policy_set_aes_gcm_256_8_only_auth()

void srtp_crypto_policy_set_aes_gcm_256_8_only_auth | ( | srtp_crypto_policy_t * | p | ) |

Parameters

  p | is a pointer to the policy structure to be set

The function call srtp_crypto_policy_set_aes_gcm_256_8_only_auth(&p) sets the srtp_crypto_policy_t at location p to use the SRTP default cipher (AES-256 Galois Counter Mode) with 8 octet auth tag. This policy applies confidentiality and authentication to the RTP packets, but only authentication to the RTCP packets.

This function is a convenience that helps to avoid dealing directly with the policy data structure. You are encouraged to initialize policy elements with this function call. Doing so may allow your code to be forward compatible with later versions of libSRTP that include more elements in the srtp_crypto_policy_t datatype.

Returns
  void.

## srtp_crypto_policy_set_from_profile_for_rtcp()

srtp_err_status_t srtp_crypto_policy_set_from_profile_for_rtcp | ( | srtp_crypto_policy_t * | policy,
|  | srtp_profile_t | profile
| ) |  |

Parameters

  policy | is a pointer to the policy structure to be set
  profile | is an enumeration for the policy to be set

The function call srtp_crypto_policy_set_rtcp_default(&policy, profile) sets the srtp_crypto_policy_t at location policy to the policy for RTCP protection, as defined by the srtp_profile_t profile.

This function is a convenience that helps to avoid dealing directly with the policy data structure. You are encouraged to initialize policy elements with this function call. Doing so may allow your code to be forward compatible with later versions of libSRTP that include more elements in the srtp_crypto_policy_t datatype.

Returns
  values
  - srtp_err_status_ok no problems were encountered
  - srtp_err_status_bad_param the profile is not supported

## srtp_crypto_policy_set_from_profile_for_rtp()

srtp_err_status_t srtp_crypto_policy_set_from_profile_for_rtp | ( | srtp_crypto_policy_t * | policy,
|  | srtp_profile_t | profile
| ) |  |

Parameters

  policy | is a pointer to the policy structure to be set
  profile | is an enumeration for the policy to be set

The function call srtp_crypto_policy_set_rtp_default(&policy, profile) sets the srtp_crypto_policy_t at location policy to the policy for RTP protection, as defined by the srtp_profile_t profile.

This function is a convenience that helps to avoid dealing directly with the policy data structure. You are encouraged to initialize policy elements with this function call. Doing so may allow your code to be forward compatible with later versions of libSRTP that include more elements in the srtp_crypto_policy_t datatype.

Returns
  values
  - srtp_err_status_ok no problems were encountered
  - srtp_err_status_bad_param the profile is not supported

## srtp_crypto_policy_set_null_cipher_hmac_null()

void srtp_crypto_policy_set_null_cipher_hmac_null | ( | srtp_crypto_policy_t * | p | ) |

Parameters

  p | is a pointer to the policy structure to be set

The function call srtp_crypto_policy_set_null_cipher_hmac_null(&p) sets the srtp_crypto_policy_t at location p to use no encryption and no authentication. This policy should only be used for testing and troubleshooting.

This function is a convenience that helps to avoid dealing directly with the policy data structure. You are encouraged to initialize policy elements with this function call. Doing so may allow your code to be forward compatible with later versions of libSRTP that include more elements in the srtp_crypto_policy_t datatype.

Warning
  This policy is NOT RECOMMENDED for SRTP unless there is a requirement to forgo encryption and authentication.

Returns
  void.

## srtp_crypto_policy_set_null_cipher_hmac_sha1_80()

void srtp_crypto_policy_set_null_cipher_hmac_sha1_80 | ( | srtp_crypto_policy_t * | p | ) |

Parameters

  p | is a pointer to the policy structure to be set

The function call srtp_crypto_policy_set_null_cipher_hmac_sha1_80(&p) sets the srtp_crypto_policy_t at location p to use HMAC-SHA1 with an 80 bit authentication tag to provide message authentication, but to use no encryption. This policy is NOT RECOMMENDED for SRTP unless there is a requirement to forgo encryption.

This function is a convenience that helps to avoid dealing directly with the policy data structure. You are encouraged to initialize policy elements with this function call. Doing so may allow your code to be forward compatible with later versions of libSRTP that include more elements in the srtp_crypto_policy_t datatype.

Warning
  This policy is NOT RECOMMENDED for SRTP unless there is a requirement to forgo encryption.

Returns
  void.

## srtp_crypto_policy_set_rtcp_default()

void srtp_crypto_policy_set_rtcp_default | ( | srtp_crypto_policy_t * | p | ) |

Parameters

  p | is a pointer to the policy structure to be set

The function call srtp_crypto_policy_set_rtcp_default(&p) sets the srtp_crypto_policy_t at location p to the SRTP default policy for RTCP protection, as defined in the specification. This function is a convenience that helps to avoid dealing directly with the policy data structure. You are encouraged to initialize policy elements with this function call. Doing so may allow your code to be forward compatible with later versions of libSRTP that include more elements in the srtp_crypto_policy_t datatype.

Returns
  void.

## srtp_crypto_policy_set_rtp_default()

void srtp_crypto_policy_set_rtp_default | ( | srtp_crypto_policy_t * | p | ) |

Parameters

  p | is a pointer to the policy structure to be set

The function call srtp_crypto_policy_set_rtp_default(&p) sets the srtp_crypto_policy_t at location p to the SRTP default policy for RTP protection, as defined in the specification. This function is a convenience that helps to avoid dealing directly with the policy data structure. You are encouraged to initialize policy elements with this function call. Doing so may allow your code to be forward compatible with later versions of libSRTP that include more elements in the srtp_crypto_policy_t datatype.

Returns
  void.

## srtp_dealloc()

srtp_err_status_t srtp_dealloc | ( | srtp_t | s | ) |

The function call srtp_dealloc(s) deallocates storage for the SRTP session context s. This function should be called no more than one time for each of the contexts allocated by the function srtp_create().

Parameters

  s | is the srtp_t for the session to be deallocated.

Returns
  - srtp_err_status_ok if there no problems.
  - srtp_err_status_dealloc_fail a memory deallocation failure occurred.

## srtp_init()

srtp_err_status_t srtp_init | ( | void |  | ) |

Warning
  This function must be called before any other srtp functions.

## srtp_protect()

srtp_err_status_t srtp_protect | ( | srtp_t | ctx,
|  | void * | rtp_hdr,
|  | int * | len_ptr
| ) |  |

The function call srtp_protect(ctx, rtp_hdr, len_ptr) applies SRTP protection to the RTP packet rtp_hdr (which has length *len_ptr) using the SRTP context ctx. If srtp_err_status_ok is returned, then rtp_hdr points to the resulting SRTP 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.

The sequence numbers of the RTP packets presented to this function need not be consecutive, but they must be out of order by less than 2^15 = 32,768 packets.

Warning
  This function assumes that it can write the authentication tag into the location in memory immediately following the RTP packet, and assumes that the RTP packet is aligned on a 32-bit boundary.
  This function assumes that it can write SRTP_MAX_TRAILER_LEN into the location in memory immediately following the RTP packet. Callers MUST ensure that this much writable memory is available in the buffer that holds the RTP packet.

Parameters

  ctx | is the SRTP context to use in processing the packet.
  rtp_hdr | is a pointer to the RTP packet (before the call); after the function returns, it points to the srtp packet.
  len_ptr | is a pointer to the length in octets of the complete RTP packet (header and body) before the function call, and of the complete SRTP 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 no problems
  - srtp_err_status_replay_fail rtp sequence number was non-increasing
  - other failure in cryptographic mechanisms

## srtp_protect_mki()

srtp_err_status_t srtp_protect_mki | ( | srtp_ctx_t * | ctx,
|  | void * | rtp_hdr,
|  | int * | pkt_octet_len,
|  | unsigned int | use_mki,
|  | unsigned int | mki_index
| ) |  |

The function call srtp_protect(ctx, rtp_hdr, len_ptr) applies SRTP protection to the RTP packet rtp_hdr (which has length *len_ptr) using the SRTP context ctx. If srtp_err_status_ok is returned, then rtp_hdr points to the resulting SRTP 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.

The sequence numbers of the RTP packets presented to this function need not be consecutive, but they must be out of order by less than 2^15 = 32,768 packets.

Warning
  This function assumes that it can write the authentication tag into the location in memory immediately following the RTP packet, and assumes that the RTP packet is aligned on a 32-bit boundary.
  This function assumes that it can write SRTP_MAX_TRAILER_LEN into the location in memory immediately following the RTP packet. Callers MUST ensure that this much writable memory is available in the buffer that holds the RTP packet.

Parameters

  ctx | is the SRTP context to use in processing the packet.
  rtp_hdr | is a pointer to the RTP packet (before the call); after the function returns, it points to the srtp packet.
  pkt_octet_len | is a pointer to the length in octets of the complete RTP packet (header and body) before the function call, and of the complete SRTP packet after the call, if srtp_err_status_ok was returned. Otherwise, the value of the data to which it points is undefined.
  use_mki | is 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_index | integer value specifying which set of session keys should be used if use_mki is set to true.

Returns
  - srtp_err_status_ok no problems
  - srtp_err_status_replay_fail rtp sequence number was non-increasing
  - other failure in cryptographic mechanisms

## srtp_remove_stream()

srtp_err_status_t srtp_remove_stream | ( | srtp_t | session,
|  | uint32_t | ssrc
| ) |  |

The function call srtp_remove_stream(session, ssrc) removes the SRTP stream with the SSRC value ssrc from the SRTP session context given by the argument session.

Parameters

  session | is the SRTP session from which the stream will be removed.
  ssrc | is the SSRC value of the stream to be removed in network byte order.

Warning
  Wildcard SSRC values cannot be removed from a session.

Returns
  - srtp_err_status_ok if the stream deallocation succeeded.
  - [other] otherwise.

## srtp_shutdown()

srtp_err_status_t srtp_shutdown | ( | void |  | ) |

Warning
  No srtp functions may be called after calling this function.

## srtp_unprotect()

srtp_err_status_t srtp_unprotect | ( | srtp_t | ctx,
|  | void * | srtp_hdr,
|  | int * | len_ptr
| ) |  |

The function call srtp_unprotect(ctx, srtp_hdr, len_ptr) verifies the Secure RTP protection of the SRTP packet pointed to by srtp_hdr (which has length *len_ptr), using the SRTP context ctx. If srtp_err_status_ok is returned, then srtp_hdr points to the resulting RTP 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.

The sequence numbers of the RTP packets presented to this function need not be consecutive, but they must be out of order by less than 2^15 = 32,768 packets.

Warning
  This function assumes that the SRTP packet is aligned on a 32-bit boundary.

Parameters

  ctx | is the SRTP session which applies to the particular packet.
  srtp_hdr | is a pointer to the header of the SRTP 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.
  len_ptr | is a pointer to the length in octets of the complete srtp 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 RTP packet is valid.
  - srtp_err_status_auth_fail if the SRTP packet failed the message authentication check.
  - srtp_err_status_replay_fail if the SRTP packet is a replay (e.g. packet has already been processed and accepted).
  - [other] if there has been an error in the cryptographic mechanisms.

## srtp_unprotect_mki()

srtp_err_status_t srtp_unprotect_mki | ( | srtp_t | ctx,
|  | void * | srtp_hdr,
|  | int * | len_ptr,
|  | unsigned int | use_mki
| ) |  |

The function call srtp_unprotect(ctx, srtp_hdr, len_ptr) verifies the Secure RTP protection of the SRTP packet pointed to by srtp_hdr (which has length *len_ptr), using the SRTP context ctx. If srtp_err_status_ok is returned, then srtp_hdr points to the resulting RTP 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.

The sequence numbers of the RTP packets presented to this function need not be consecutive, but they must be out of order by less than 2^15 = 32,768 packets.

Warning
  This function assumes that the SRTP packet is aligned on a 32-bit boundary.

Parameters

  ctx | is the SRTP session which applies to the particular packet.
  srtp_hdr | is a pointer to the header of the SRTP 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.
  len_ptr | is a pointer to the length in octets of the complete srtp 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.
  use_mki | is 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

Returns
  - srtp_err_status_ok if the RTP packet is valid.
  - srtp_err_status_auth_fail if the SRTP packet failed the message authentication check.
  - srtp_err_status_replay_fail if the SRTP packet is a replay (e.g. packet 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.

## srtp_update()

srtp_err_status_t srtp_update | ( | srtp_t | session,
|  | const srtp_policy_t * | policy
| ) |  |

The function call srtp_update(session, policy) updates all the streams in the session applying the given policy and key. The existing ROC value of all streams will be preserved.

Parameters

  session | is the SRTP session that contains the streams to be updated.
  policy | is the srtp_policy_t struct that describes the policy for the session. The struct may be a single element, or it may be the head of a list, in which case each element of the list is processed. The final element of the list must have its ‘next’ field set to NULL.

Returns
  - srtp_err_status_ok if stream creation succeed.
  - srtp_err_status_alloc_fail if stream allocation failed
  - srtp_err_status_init_fail if stream initialization failed.
  - [other] otherwise.

## srtp_update_stream()

srtp_err_status_t srtp_update_stream | ( | srtp_t | session,
|  | const srtp_policy_t * | policy
| ) |  |

The function call srtp_update_stream(session, policy) updates the stream(s) in the session that match applying the given policy and key. The existing ROC value of all stream(s) will be preserved.

Parameters

  session | is the SRTP session that contains the streams to be updated.
  policy | is the srtp_policy_t struct that describes the policy for the session.

Returns
  - srtp_err_status_ok if stream creation succeeded.
  - srtp_err_status_alloc_fail if stream allocation failed
  - srtp_err_status_init_fail if stream initialization failed.
  - [other] otherwise.