Update libsrtp to upstream 1.5.0

srtp/include/srtp.h

Index: srtp/include/srtp.h
diff --git a/srtp/include/srtp.h b/srtp/include/srtp.h
index eb95e7d47780b2b311bd7b4d9c835f8b2fa77fed..48416d3c1f5e9a8aeffb0f583dd1e95c43e1eaf6 100644
--- a/srtp/include/srtp.h
+++ b/srtp/include/srtp.h
@@ -50,7 +50,10 @@
 extern "C" {
 #endif
 
-#include "crypto_kernel.h" 
+#include <stdint.h>
+#include "crypto.h" 
+#include "crypto_types.h"
+#include "err.h"
 
 /**
  * @defgroup SRTP Secure RTP
@@ -88,6 +91,18 @@ extern "C" {
  */
 #define SRTP_MAX_TRAILER_LEN SRTP_MAX_TAG_LEN 
 
+/*
+ * SRTP_AEAD_SALT_LEN is the length of the SALT values used with 
+ * GCM mode.  GCM mode requires an IV.  The SALT value is used
+ * as part of the IV formation logic applied to each RTP packet.
+ */
+#define SRTP_AEAD_SALT_LEN	12
+#define AES_128_GCM_KEYSIZE_WSALT   SRTP_AEAD_SALT_LEN + 16
+#define AES_192_GCM_KEYSIZE_WSALT   SRTP_AEAD_SALT_LEN + 24
+#define AES_256_GCM_KEYSIZE_WSALT   SRTP_AEAD_SALT_LEN + 32
+
+
+
 /* 
  * nota bene: since libSRTP doesn't support the use of the MKI, the
  * SRTP_MAX_TRAILER_LEN value is just the maximum tag length
@@ -304,6 +319,11 @@ srtp_shutdown(void);
  * packet, and assumes that the RTP packet is aligned on a 32-bit
  * boundary.
  *
+ * @warning 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.
+ * 
  * @param ctx is the SRTP context to use in processing the packet.
  *
  * @param rtp_hdr is a pointer to the RTP packet (before the call); after
@@ -342,8 +362,7 @@ srtp_protect(srtp_t ctx, void *rtp_hdr, int *len_ptr);
  * @warning This function assumes that the SRTP packet is aligned on a
  * 32-bit boundary.
  *
- * @param ctx is a pointer to the srtp_t which applies to the
- * particular packet.
+ * @param ctx is the SRTP session which applies to the particular packet.
  *
  * @param srtp_hdr is a pointer to the header of the SRTP packet
  * (before the call).  after the function returns, it points to the
@@ -376,7 +395,8 @@ srtp_unprotect(srtp_t ctx, void *srtp_hdr, int *len_ptr);
  * initializes an SRTP session context, applying the given policy and
  * key.
  *
- * @param session is the SRTP session to which the policy is to be added.
+ * @param session is a pointer to the SRTP session to which the policy is
+ * to be added.
  * 
  * @param 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
@@ -658,6 +678,178 @@ void crypto_policy_set_aes_cm_256_hmac_sha1_80(crypto_policy_t *p);
 void
 crypto_policy_set_aes_cm_256_hmac_sha1_32(crypto_policy_t *p);
 
+/**
+ * @brief crypto_policy_set_aes_cm_256_null_auth() sets a crypto
+ * policy structure to an encryption-only policy
+ *
+ * @param p is a pointer to the policy structure to be set
+ *
+ * The function call crypto_policy_set_aes_cm_256_null_auth(&p) sets
+ * the 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 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).
+ *
+ * @return void.
+ *
+ */
+void
+crypto_policy_set_aes_cm_256_null_auth(crypto_policy_t *p);
+
+/**
+ * @brief crypto_policy_set_aes_gcm_128_8_auth() sets a crypto
+ * policy structure to an AEAD encryption policy.
+ *
+ * @param p is a pointer to the policy structure to be set 
+ * 
+ * The function call crypto_policy_set_aes_gcm_128_8_auth(&p) sets
+ * the 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 crypto_policy_t datatype.
+ *
+ * @return void.
+ * 
+ */
+void
+crypto_policy_set_aes_gcm_128_8_auth(crypto_policy_t *p);
+
+/**
+ * @brief crypto_policy_set_aes_gcm_256_8_auth() sets a crypto
+ * policy structure to an AEAD encryption policy
+ *
+ * @param p is a pointer to the policy structure to be set 
+ * 
+ * The function call crypto_policy_set_aes_gcm_256_8_auth(&p) sets
+ * the 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 crypto_policy_t datatype.
+ *
+ * @return void.
+ * 
+ */
+void
+crypto_policy_set_aes_gcm_256_8_auth(crypto_policy_t *p);
+
+/**
+ * @brief crypto_policy_set_aes_gcm_128_8_only_auth() sets a crypto
+ * policy structure to an AEAD authentication-only policy
+ *
+ * @param p is a pointer to the policy structure to be set 
+ * 
+ * The function call crypto_policy_set_aes_gcm_128_8_only_auth(&p) sets
+ * the 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 crypto_policy_t datatype.
+ *
+ * @return void.
+ * 
+ */
+void
+crypto_policy_set_aes_gcm_128_8_only_auth(crypto_policy_t *p);
+
+/**
+ * @brief crypto_policy_set_aes_gcm_256_8_only_auth() sets a crypto
+ * policy structure to an AEAD authentication-only policy
+ *
+ * @param p is a pointer to the policy structure to be set 
+ * 
+ * The function call crypto_policy_set_aes_gcm_256_8_only_auth(&p) sets
+ * the 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 crypto_policy_t datatype.
+ *
+ * @return void.
+ * 
+ */
+void
+crypto_policy_set_aes_gcm_256_8_only_auth(crypto_policy_t *p);
+
+/**
+ * @brief crypto_policy_set_aes_gcm_128_16_auth() sets a crypto
+ * policy structure to an AEAD encryption policy.
+ *
+ * @param p is a pointer to the policy structure to be set 
+ * 
+ * The function call crypto_policy_set_aes_gcm_128_16_auth(&p) sets
+ * the 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 crypto_policy_t datatype.
+ *
+ * @return void.
+ * 
+ */
+void
+crypto_policy_set_aes_gcm_128_16_auth(crypto_policy_t *p);
+
+/**
+ * @brief crypto_policy_set_aes_gcm_256_16_auth() sets a crypto
+ * policy structure to an AEAD encryption policy
+ *
+ * @param p is a pointer to the policy structure to be set 
+ * 
+ * The function call crypto_policy_set_aes_gcm_256_16_auth(&p) sets
+ * the 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 crypto_policy_t datatype.
+ *
+ * @return void.
+ * 
+ */
+void
+crypto_policy_set_aes_gcm_256_16_auth(crypto_policy_t *p);
+
 
 /**
  * @brief srtp_dealloc() deallocates storage for an SRTP session
@@ -823,6 +1015,11 @@ append_salt_to_key(unsigned char *key, unsigned int bytes_in_key,
  * packet, and assumes that the RTCP packet is aligned on a 32-bit
  * boundary.
  *
+ * @warning 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.
+ * 
  * @param ctx is the SRTP context to use in processing the packet.
  *
  * @param rtcp_hdr is a pointer to the RTCP packet (before the call); after
@@ -890,6 +1087,57 @@ srtp_unprotect_rtcp(srtp_t ctx, void *srtcp_hdr, int *pkt_octet_len);
  * @}
  */
 
+
+/**
+ * @defgroup User data associated to a SRTP session.
+ * @ingroup  SRTP
+ *
+ * @brief Store custom user data within a SRTP session.
+ *
+ * @{
+ */
+
+/**
+ * @brief srtp_set_user_data() stores the given pointer into the SRTP
+ * session for later retrieval.
+ *
+ * @param ctx is the srtp_t context in which the given data pointer is
+ * stored.
+ *
+ * @param data is a pointer to the custom information (struct, function,
+ * etc) associated with the SRTP session.
+ *
+ * @return void.
+ *
+ */
+
+void
+srtp_set_user_data(srtp_t ctx, void *data);
+
+/**
+ * @brief srtp_get_user_data() retrieves the pointer to the custom data
+ * previously stored with srtp_set_user_data().
+ *
+ * This function is mostly useful for retrieving data associated to a
+ * SRTP session when an event fires. The user can then get such a custom
+ * data by calling this function with the session field of the
+ * srtp_event_data_t struct as argument.
+ *
+ * @param ctx is the srtp_t context in which the given data pointer was
+ * stored.
+ *
+ * @return void* pointer to the user data.
+ *
+ */
+
+void*
+srtp_get_user_data(srtp_t ctx);
+
+/**
+ * @}
+ */
+
+
 /**
  * @defgroup SRTPevents SRTP events and callbacks
  * @ingroup  SRTP
@@ -991,6 +1239,18 @@ err_status_t
 srtp_install_event_handler(srtp_event_handler_func_t func);
 
 /**
+ * @brief Returns the version string of the library. 
+ * 
+ */
+const char *srtp_get_version_string(void);
+
+/**
+ * @brief Returns the numeric representation of the library version. 
+ * 
+ */
+unsigned int srtp_get_version(void);
+
+/**
  * @}
  */
 /* in host order, so outside the #if */