diff options
Diffstat (limited to 'third_party/srtp/include/srtp.h')
| -rw-r--r-- | third_party/srtp/include/srtp.h | 383 |
1 files changed, 358 insertions, 25 deletions
diff --git a/third_party/srtp/include/srtp.h b/third_party/srtp/include/srtp.h index 21d8531a..81af5198 100644 --- a/third_party/srtp/include/srtp.h +++ b/third_party/srtp/include/srtp.h @@ -50,15 +50,10 @@ extern "C" { #endif -#ifdef _MSC_VER -# ifdef WIN64 -# pragma pack(8) -# else -# pragma pack(4) -# endif -#endif - -#include "crypto_kernel.h" +#include <stdint.h> +#include "crypto.h" +#include "crypto_types.h" +#include "err.h" /** * @defgroup SRTP Secure RTP @@ -84,7 +79,7 @@ extern "C" { * SRTP_MAX_TAG_LEN is the maximum tag length supported by libSRTP */ -#define SRTP_MAX_TAG_LEN 12 +#define SRTP_MAX_TAG_LEN 16 /** * SRTP_MAX_TRAILER_LEN is the maximum length of the SRTP trailer @@ -96,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 @@ -176,6 +183,18 @@ typedef struct { } ssrc_t; +/** + * @brief points to an EKT policy + */ +typedef struct ekt_policy_ctx_t *ekt_policy_t; + + +/** + * @brief points to EKT stream data + */ +typedef struct ekt_stream_ctx_t *ekt_stream_t; + + /** * @brief represents the policy for an SRTP session. * @@ -213,6 +232,16 @@ typedef struct srtp_policy_t { crypto_policy_t rtcp; /**< SRTCP crypto policy. */ unsigned char *key; /**< Pointer to the SRTP master key for * this stream. */ + ekt_policy_t ekt; /**< Pointer to the EKT policy structure + * for this stream (if any) */ + unsigned long window_size; /**< The window size to use for replay + * protection. */ + int allow_repeat_tx; /**< Whether retransmissions of + * packets with the same sequence number + * are allowed. (Note that such repeated + * transmissions must have the same RTP + * payload, or a severe security weakness + * is introduced!) */ struct srtp_policy_t *next; /**< Pointer to next stream policy. */ } srtp_policy_t; @@ -262,14 +291,13 @@ err_status_t srtp_init(void); /** - * @brief srtp_deinit() deinitializes the srtp library. + * @brief srtp_shutdown() de-initializes the srtp library. * - * @warning This function @b must be called on quitting application or - * after srtp is no longer used. + * @warning No srtp functions may be called after calling this function. */ err_status_t -srtp_deinit(void); +srtp_shutdown(void); /** * @brief srtp_protect() is the Secure RTP sender-side packet processing @@ -291,6 +319,11 @@ srtp_deinit(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 @@ -329,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 @@ -363,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 @@ -478,8 +511,8 @@ crypto_policy_set_rtcp_default(crypto_policy_t *p); * * The function crypto_policy_set_aes_cm_128_hmac_sha1_80() is a * synonym for crypto_policy_set_rtp_default(). It conforms to the - * naming convention used in - * http://www.ietf.org/internet-drafts/draft-ietf-mmusic-sdescriptions-12.txt + * naming convention used in RFC 4568 (SDP Security Descriptions for + * Media Streams). * * @return void. * @@ -496,8 +529,8 @@ crypto_policy_set_rtcp_default(crypto_policy_t *p); * * The function call crypto_policy_set_aes_cm_128_hmac_sha1_32(&p) * sets the crypto_policy_t at location p to use policy - * AES_CM_128_HMAC_SHA1_32 as defined in - * draft-ietf-mmusic-sdescriptions-12.txt. This policy uses AES-128 + * 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 @@ -582,6 +615,242 @@ crypto_policy_set_aes_cm_128_null_auth(crypto_policy_t *p); void crypto_policy_set_null_cipher_hmac_sha1_80(crypto_policy_t *p); + +/** + * @brief 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. + * + * @param p is a pointer to the policy structure to be set + * + * The function call crypto_policy_set_aes_cm_256_hmac_sha1_80(&p) + * sets the crypto_policy_t at location p to use policy + * AES_CM_256_HMAC_SHA1_80 as defined in + * draft-ietf-avt-srtp-big-aes-03.txt. 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 crypto_policy_t datatype. + * + * @return void. + * + */ + +void crypto_policy_set_aes_cm_256_hmac_sha1_80(crypto_policy_t *p); + + +/** + * @brief crypto_policy_set_aes_cm_256_hmac_sha1_32() sets a crypto + * policy structure to a short-authentication tag policy using AES-256 + * encryption. + * + * @param p is a pointer to the policy structure to be set + * + * The function call crypto_policy_set_aes_cm_256_hmac_sha1_32(&p) + * sets the crypto_policy_t at location p to use policy + * AES_CM_256_HMAC_SHA1_32 as defined in + * draft-ietf-avt-srtp-big-aes-03.txt. 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 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). + * + * @return void. + * + */ + +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 * context. @@ -746,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 @@ -813,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 @@ -914,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 */ @@ -922,10 +1259,6 @@ srtp_install_event_handler(srtp_event_handler_func_t func); #define SRTCP_E_BYTE_BIT 0x80 #define SRTCP_INDEX_MASK 0x7fffffff -#ifdef _MSC_VER -#pragma pack() -#endif - #ifdef __cplusplus } #endif |