1386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari/* 2386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * srtp.h 3386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 4386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * interface to libsrtp 5386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 6386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * David A. McGrew 7386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * Cisco Systems, Inc. 8386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari */ 9386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari/* 10386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 11386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * Copyright (c) 2001-2006, Cisco Systems, Inc. 12386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * All rights reserved. 13386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 14386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * Redistribution and use in source and binary forms, with or without 15386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * modification, are permitted provided that the following conditions 16386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * are met: 17386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 18386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * Redistributions of source code must retain the above copyright 19386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * notice, this list of conditions and the following disclaimer. 20386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 21386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * Redistributions in binary form must reproduce the above 22386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * copyright notice, this list of conditions and the following 23386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * disclaimer in the documentation and/or other materials provided 24386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * with the distribution. 25386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 26386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * Neither the name of the Cisco Systems, Inc. nor the names of its 27386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * contributors may be used to endorse or promote products derived 28386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * from this software without specific prior written permission. 29386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 30386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 31386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 32386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS 33386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE 34386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, 35386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 36386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 37386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 38386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 39386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 40386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 41386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * OF THE POSSIBILITY OF SUCH DAMAGE. 42386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 43386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari */ 44386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari 45386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari 46386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari#ifndef SRTP_H 47386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari#define SRTP_H 48386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari 49386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari#ifdef __cplusplus 50386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagariextern "C" { 51386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari#endif 52386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari 53386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari#include "crypto_kernel.h" 54386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari 55386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari/** 56386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * @defgroup SRTP Secure RTP 57386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 58386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * @brief libSRTP provides functions for protecting RTP and RTCP. See 59386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * Section @ref Overview for an introduction to the use of the library. 60386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 61386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * @{ 62386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari */ 63386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari 64386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari/* 65386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * SRTP_MASTER_KEY_LEN is the nominal master key length supported by libSRTP 66386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari */ 67386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari 68386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari#define SRTP_MASTER_KEY_LEN 30 69386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari 70386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari/* 71386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * SRTP_MAX_KEY_LEN is the maximum key length supported by libSRTP 72386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari */ 73386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari#define SRTP_MAX_KEY_LEN 64 74386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari 75386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari/* 76386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * SRTP_MAX_TAG_LEN is the maximum tag length supported by libSRTP 77386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari */ 78386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari 79386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari#define SRTP_MAX_TAG_LEN 12 80386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari 81386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari/** 82386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * SRTP_MAX_TRAILER_LEN is the maximum length of the SRTP trailer 83386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * (authentication tag and MKI) supported by libSRTP. This value is 84386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * the maximum number of octets that will be added to an RTP packet by 85386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * srtp_protect(). 86386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 87386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * @brief the maximum number of octets added by srtp_protect(). 88386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari */ 89386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari#define SRTP_MAX_TRAILER_LEN SRTP_MAX_TAG_LEN 90386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari 91386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari/* 92386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * nota bene: since libSRTP doesn't support the use of the MKI, the 93386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * SRTP_MAX_TRAILER_LEN value is just the maximum tag length 94386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari */ 95386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari 96386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari/** 97386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * @brief sec_serv_t describes a set of security services. 98386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 99386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * A sec_serv_t enumeration is used to describe the particular 100386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * security services that will be applied by a particular crypto 101386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * policy (or other mechanism). 102386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari */ 103386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari 104386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagaritypedef enum { 105386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari sec_serv_none = 0, /**< no services */ 106386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari sec_serv_conf = 1, /**< confidentiality */ 107386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari sec_serv_auth = 2, /**< authentication */ 108386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari sec_serv_conf_and_auth = 3 /**< confidentiality and authentication */ 109386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari} sec_serv_t; 110386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari 111386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari/** 112386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * @brief crypto_policy_t describes a particular crypto policy that 113386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * can be applied to an SRTP stream. 114386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 115386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * A crypto_policy_t describes a particular cryptographic policy that 116386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * can be applied to an SRTP or SRTCP stream. An SRTP session policy 117386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * consists of a list of these policies, one for each SRTP stream 118386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * in the session. 119386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari */ 120386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari 121386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagaritypedef struct crypto_policy_t { 122386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari cipher_type_id_t cipher_type; /**< An integer representing 123386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * the type of cipher. */ 124386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari int cipher_key_len; /**< The length of the cipher key 125386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * in octets. */ 126386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari auth_type_id_t auth_type; /**< An integer representing the 127386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * authentication function. */ 128386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari int auth_key_len; /**< The length of the authentication 129386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * function key in octets. */ 130386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari int auth_tag_len; /**< The length of the authentication 131386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * tag in octets. */ 132386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari sec_serv_t sec_serv; /**< The flag indicating the security 133386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * services to be applied. */ 134386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari} crypto_policy_t; 135386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari 136386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari 137386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari/** 138386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * @brief ssrc_type_t describes the type of an SSRC. 139386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 140386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * An ssrc_type_t enumeration is used to indicate a type of SSRC. See 141386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * @ref srtp_policy_t for more informataion. 142386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari */ 143386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari 144386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagaritypedef enum { 145386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari ssrc_undefined = 0, /**< Indicates an undefined SSRC type. */ 146386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari ssrc_specific = 1, /**< Indicates a specific SSRC value */ 147386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari ssrc_any_inbound = 2, /**< Indicates any inbound SSRC value 148386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari (i.e. a value that is used in the 149386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari function srtp_unprotect()) */ 150386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari ssrc_any_outbound = 3 /**< Indicates any outbound SSRC value 151386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari (i.e. a value that is used in the 152386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari function srtp_protect()) */ 153386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari} ssrc_type_t; 154386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari 155386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari/** 156386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * @brief An ssrc_t represents a particular SSRC value, or a `wildcard' SSRC. 157386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 158386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * An ssrc_t represents a particular SSRC value (if its type is 159386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * ssrc_specific), or a wildcard SSRC value that will match all 160386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * outbound SSRCs (if its type is ssrc_any_outbound) or all inbound 161386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * SSRCs (if its type is ssrc_any_inbound). 162386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 163386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari */ 164386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari 165386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagaritypedef struct { 166386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari ssrc_type_t type; /**< The type of this particular SSRC */ 167386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari unsigned int value; /**< The value of this SSRC, if it is not a wildcard */ 168386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari} ssrc_t; 169386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari 170386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari 171386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari/** 172386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * @brief points to an EKT policy 173386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari */ 174386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagaritypedef struct ekt_policy_ctx_t *ekt_policy_t; 175386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari 176386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari 177386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari/** 178386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * @brief points to EKT stream data 179386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari */ 180386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagaritypedef struct ekt_stream_ctx_t *ekt_stream_t; 181386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari 182386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari 183386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari/** 184386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * @brief represents the policy for an SRTP session. 185386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 186386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * A single srtp_policy_t struct represents the policy for a single 187386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * SRTP stream, and a linked list of these elements represents the 188386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * policy for an entire SRTP session. Each element contains the SRTP 189386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * and SRTCP crypto policies for that stream, a pointer to the SRTP 190386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * master key for that stream, the SSRC describing that stream, or a 191386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * flag indicating a `wildcard' SSRC value, and a `next' field that 192386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * holds a pointer to the next element in the list of policy elements, 193386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * or NULL if it is the last element. 194386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 195386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * The wildcard value SSRC_ANY_INBOUND matches any SSRC from an 196386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * inbound stream that for which there is no explicit SSRC entry in 197386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * another policy element. Similarly, the value SSRC_ANY_OUTBOUND 198386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * will matches any SSRC from an outbound stream that does not appear 199386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * in another policy element. Note that wildcard SSRCs &b cannot be 200386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * used to match both inbound and outbound traffic. This restriction 201386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * is intentional, and it allows libSRTP to ensure that no security 202386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * lapses result from accidental re-use of SSRC values during key 203386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * sharing. 204386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 205386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 206386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * @warning The final element of the list @b must have its `next' pointer 207386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * set to NULL. 208386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari */ 209386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari 210386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagaritypedef struct srtp_policy_t { 211386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari ssrc_t ssrc; /**< The SSRC value of stream, or the 212386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * flags SSRC_ANY_INBOUND or 213386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * SSRC_ANY_OUTBOUND if key sharing 214386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * is used for this policy element. 215386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari */ 216386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari crypto_policy_t rtp; /**< SRTP crypto policy. */ 217386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari crypto_policy_t rtcp; /**< SRTCP crypto policy. */ 218386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari unsigned char *key; /**< Pointer to the SRTP master key for 219386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * this stream. */ 220386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari ekt_policy_t ekt; /**< Pointer to the EKT policy structure 221386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * for this stream (if any) */ 222386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari unsigned long window_size; /**< The window size to use for replay 223386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * protection. */ 224386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari int allow_repeat_tx; /**< Whether retransmissions of 225386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * packets with the same sequence number 226386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * are allowed. (Note that such repeated 227386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * transmissions must have the same RTP 228386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * payload, or a severe security weakness 229386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * is introduced!) */ 230386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari struct srtp_policy_t *next; /**< Pointer to next stream policy. */ 231386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari} srtp_policy_t; 232386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari 233386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari 234386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari 235386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari 236386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari/** 237386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * @brief An srtp_t points to an SRTP session structure. 238386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 239386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * The typedef srtp_t is a pointer to a structure that represents 240386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * an SRTP session. This datatype is intentially opaque in 241386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * order to separate the interface from the implementation. 242386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 243386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * An SRTP session consists of all of the traffic sent to the RTP and 244386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * RTCP destination transport addresses, using the RTP/SAVP (Secure 245386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * Audio/Video Profile). A session can be viewed as a set of SRTP 246386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * streams, each of which originates with a different participant. 247386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari */ 248386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari 249386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagaritypedef struct srtp_ctx_t *srtp_t; 250386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari 251386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari 252386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari/** 253386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * @brief An srtp_stream_t points to an SRTP stream structure. 254386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 255386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * The typedef srtp_stream_t is a pointer to a structure that 256386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * represents an SRTP stream. This datatype is intentionally 257386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * opaque in order to separate the interface from the implementation. 258386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 259386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * An SRTP stream consists of all of the traffic sent to an SRTP 260386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * session by a single participant. A session can be viewed as 261386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * a set of streams. 262386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 263386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari */ 264386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagaritypedef struct srtp_stream_ctx_t *srtp_stream_t; 265386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari 266386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari 267386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari 268386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari/** 269386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * @brief srtp_init() initializes the srtp library. 270386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 271386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * @warning This function @b must be called before any other srtp 272386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * functions. 273386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari */ 274386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari 275386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagarierr_status_t 276386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagarisrtp_init(void); 277386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari 278386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari/** 279386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * @brief srtp_protect() is the Secure RTP sender-side packet processing 280386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * function. 281386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 282386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * The function call srtp_protect(ctx, rtp_hdr, len_ptr) applies SRTP 283386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * protection to the RTP packet rtp_hdr (which has length *len_ptr) using 284386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * the SRTP context ctx. If err_status_ok is returned, then rtp_hdr 285386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * points to the resulting SRTP packet and *len_ptr is the number of 286386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * octets in that packet; otherwise, no assumptions should be made 287386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * about the value of either data elements. 288386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 289386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * The sequence numbers of the RTP packets presented to this function 290386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * need not be consecutive, but they @b must be out of order by less 291386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * than 2^15 = 32,768 packets. 292386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 293386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * @warning This function assumes that it can write the authentication 294386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * tag into the location in memory immediately following the RTP 295386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * packet, and assumes that the RTP packet is aligned on a 32-bit 296386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * boundary. 297386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 298386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * @param ctx is the SRTP context to use in processing the packet. 299386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 300386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * @param rtp_hdr is a pointer to the RTP packet (before the call); after 301386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * the function returns, it points to the srtp packet. 302386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 303386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * @param len_ptr is a pointer to the length in octets of the complete 304386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * RTP packet (header and body) before the function call, and of the 305386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * complete SRTP packet after the call, if err_status_ok was returned. 306386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * Otherwise, the value of the data to which it points is undefined. 307386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 308386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * @return 309386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * - err_status_ok no problems 310386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * - err_status_replay_fail rtp sequence number was non-increasing 311386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * - @e other failure in cryptographic mechanisms 312386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari */ 313386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari 314386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagarierr_status_t 315386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagarisrtp_protect(srtp_t ctx, void *rtp_hdr, int *len_ptr); 316386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari 317386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari/** 318386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * @brief srtp_unprotect() is the Secure RTP receiver-side packet 319386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * processing function. 320386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 321386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * The function call srtp_unprotect(ctx, srtp_hdr, len_ptr) verifies 322386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * the Secure RTP protection of the SRTP packet pointed to by srtp_hdr 323386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * (which has length *len_ptr), using the SRTP context ctx. If 324386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * err_status_ok is returned, then srtp_hdr points to the resulting 325386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * RTP packet and *len_ptr is the number of octets in that packet; 326386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * otherwise, no assumptions should be made about the value of either 327386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * data elements. 328386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 329386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * The sequence numbers of the RTP packets presented to this function 330386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * need not be consecutive, but they @b must be out of order by less 331386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * than 2^15 = 32,768 packets. 332386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 333386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * @warning This function assumes that the SRTP packet is aligned on a 334386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 32-bit boundary. 335386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 336386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * @param ctx is a pointer to the srtp_t which applies to the 337386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * particular packet. 338386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 339386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * @param srtp_hdr is a pointer to the header of the SRTP packet 340386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * (before the call). after the function returns, it points to the 341386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * rtp packet if err_status_ok was returned; otherwise, the value of 342386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * the data to which it points is undefined. 343386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 344386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * @param len_ptr is a pointer to the length in octets of the complete 345386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * srtp packet (header and body) before the function call, and of the 346386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * complete rtp packet after the call, if err_status_ok was returned. 347386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * Otherwise, the value of the data to which it points is undefined. 348386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 349386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * @return 350386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * - err_status_ok if the RTP packet is valid. 351386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * - err_status_auth_fail if the SRTP packet failed the message 352386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * authentication check. 353386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * - err_status_replay_fail if the SRTP packet is a replay (e.g. packet has 354386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * already been processed and accepted). 355386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * - [other] if there has been an error in the cryptographic mechanisms. 356386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 357386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari */ 358386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari 359386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagarierr_status_t 360386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagarisrtp_unprotect(srtp_t ctx, void *srtp_hdr, int *len_ptr); 361386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari 362386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari 363386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari/** 364386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * @brief srtp_create() allocates and initializes an SRTP session. 365386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari 366386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * The function call srtp_create(session, policy, key) allocates and 367386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * initializes an SRTP session context, applying the given policy and 368386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * key. 369386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 370386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * @param session is the SRTP session to which the policy is to be added. 371386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 372386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * @param policy is the srtp_policy_t struct that describes the policy 373386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * for the session. The struct may be a single element, or it may be 374386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * the head of a list, in which case each element of the list is 375386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * processed. It may also be NULL, in which case streams should be added 376386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * later using srtp_add_stream(). The final element of the list @b must 377386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * have its `next' field set to NULL. 378386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 379386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * @return 380386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * - err_status_ok if creation succeded. 381386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * - err_status_alloc_fail if allocation failed. 382386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * - err_status_init_fail if initialization failed. 383386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari */ 384386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari 385386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagarierr_status_t 386386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagarisrtp_create(srtp_t *session, const srtp_policy_t *policy); 387386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari 388386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari 389386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari/** 390386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * @brief srtp_add_stream() allocates and initializes an SRTP stream 391386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * within a given SRTP session. 392386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 393386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * The function call srtp_add_stream(session, policy) allocates and 394386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * initializes a new SRTP stream within a given, previously created 395386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * session, applying the policy given as the other argument to that 396386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * stream. 397386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 398386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * @return values: 399386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * - err_status_ok if stream creation succeded. 400386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * - err_status_alloc_fail if stream allocation failed 401386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * - err_status_init_fail if stream initialization failed. 402386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari */ 403386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari 404386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagarierr_status_t 405386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagarisrtp_add_stream(srtp_t session, 406386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari const srtp_policy_t *policy); 407386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari 408386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari 409386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari/** 410386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * @brief srtp_remove_stream() deallocates an SRTP stream. 411386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 412386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * The function call srtp_remove_stream(session, ssrc) removes 413386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * the SRTP stream with the SSRC value ssrc from the SRTP session 414386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * context given by the argument session. 415386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 416386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * @param session is the SRTP session from which the stream 417386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * will be removed. 418386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 419386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * @param ssrc is the SSRC value of the stream to be removed. 420386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 421386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * @warning Wildcard SSRC values cannot be removed from a 422386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * session. 423386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 424386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * @return 425386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * - err_status_ok if the stream deallocation succeded. 426386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * - [other] otherwise. 427386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 428386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari */ 429386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari 430386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagarierr_status_t 431386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagarisrtp_remove_stream(srtp_t session, unsigned int ssrc); 432386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari 433386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari/** 434386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * @brief crypto_policy_set_rtp_default() sets a crypto policy 435386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * structure to the SRTP default policy for RTP protection. 436386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 437386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * @param p is a pointer to the policy structure to be set 438386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 439386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * The function call crypto_policy_set_rtp_default(&p) sets the 440386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * crypto_policy_t at location p to the SRTP default policy for RTP 441386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * protection, as defined in the specification. This function is a 442386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * convenience that helps to avoid dealing directly with the policy 443386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * data structure. You are encouraged to initialize policy elements 444386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * with this function call. Doing so may allow your code to be 445386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * forward compatible with later versions of libSRTP that include more 446386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * elements in the crypto_policy_t datatype. 447386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 448386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * @return void. 449386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 450386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari */ 451386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari 452386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagarivoid 453386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagaricrypto_policy_set_rtp_default(crypto_policy_t *p); 454386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari 455386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari/** 456386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * @brief crypto_policy_set_rtcp_default() sets a crypto policy 457386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * structure to the SRTP default policy for RTCP protection. 458386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 459386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * @param p is a pointer to the policy structure to be set 460386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 461386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * The function call crypto_policy_set_rtcp_default(&p) sets the 462386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * crypto_policy_t at location p to the SRTP default policy for RTCP 463386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * protection, as defined in the specification. This function is a 464386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * convenience that helps to avoid dealing directly with the policy 465386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * data structure. You are encouraged to initialize policy elements 466386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * with this function call. Doing so may allow your code to be 467386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * forward compatible with later versions of libSRTP that include more 468386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * elements in the crypto_policy_t datatype. 469386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 470386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * @return void. 471386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 472386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari */ 473386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari 474386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagarivoid 475386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagaricrypto_policy_set_rtcp_default(crypto_policy_t *p); 476386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari 477386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari/** 478386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * @brief crypto_policy_set_aes_cm_128_hmac_sha1_80() sets a crypto 479386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * policy structure to the SRTP default policy for RTP protection. 480386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 481386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * @param p is a pointer to the policy structure to be set 482386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 483386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * The function crypto_policy_set_aes_cm_128_hmac_sha1_80() is a 484386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * synonym for crypto_policy_set_rtp_default(). It conforms to the 485386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * naming convention used in 486386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * http://www.ietf.org/internet-drafts/draft-ietf-mmusic-sdescriptions-12.txt 487386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 488386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * @return void. 489386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 490386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari */ 491386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari 492386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari#define crypto_policy_set_aes_cm_128_hmac_sha1_80(p) crypto_policy_set_rtp_default(p) 493386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari 494386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari 495386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari/** 496386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * @brief crypto_policy_set_aes_cm_128_hmac_sha1_32() sets a crypto 497386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * policy structure to a short-authentication tag policy 498386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 499386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * @param p is a pointer to the policy structure to be set 500386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 501386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * The function call crypto_policy_set_aes_cm_128_hmac_sha1_32(&p) 502386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * sets the crypto_policy_t at location p to use policy 503386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * AES_CM_128_HMAC_SHA1_32 as defined in 504386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * draft-ietf-mmusic-sdescriptions-12.txt. This policy uses AES-128 505386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * Counter Mode encryption and HMAC-SHA1 authentication, with an 506386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * authentication tag that is only 32 bits long. This length is 507386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * considered adequate only for protecting audio and video media that 508386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * use a stateless playback function. See Section 7.5 of RFC 3711 509386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * (http://www.ietf.org/rfc/rfc3711.txt). 510386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 511386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * This function is a convenience that helps to avoid dealing directly 512386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * with the policy data structure. You are encouraged to initialize 513386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * policy elements with this function call. Doing so may allow your 514386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * code to be forward compatible with later versions of libSRTP that 515386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * include more elements in the crypto_policy_t datatype. 516386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 517386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * @warning This crypto policy is intended for use in SRTP, but not in 518386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * SRTCP. It is recommended that a policy that uses longer 519386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * authentication tags be used for SRTCP. See Section 7.5 of RFC 3711 520386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * (http://www.ietf.org/rfc/rfc3711.txt). 521386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 522386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * @return void. 523386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 524386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari */ 525386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari 526386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagarivoid 527386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagaricrypto_policy_set_aes_cm_128_hmac_sha1_32(crypto_policy_t *p); 528386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari 529386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari 530386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari 531386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari/** 532386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * @brief crypto_policy_set_aes_cm_128_null_auth() sets a crypto 533386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * policy structure to an encryption-only policy 534386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 535386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * @param p is a pointer to the policy structure to be set 536386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 537386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * The function call crypto_policy_set_aes_cm_128_null_auth(&p) sets 538386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * the crypto_policy_t at location p to use the SRTP default cipher 539386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * (AES-128 Counter Mode), but to use no authentication method. This 540386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * policy is NOT RECOMMENDED unless it is unavoidable; see Section 7.5 541386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * of RFC 3711 (http://www.ietf.org/rfc/rfc3711.txt). 542386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 543386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * This function is a convenience that helps to avoid dealing directly 544386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * with the policy data structure. You are encouraged to initialize 545386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * policy elements with this function call. Doing so may allow your 546386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * code to be forward compatible with later versions of libSRTP that 547386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * include more elements in the crypto_policy_t datatype. 548386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 549386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * @warning This policy is NOT RECOMMENDED for SRTP unless it is 550386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * unavoidable, and it is NOT RECOMMENDED at all for SRTCP; see 551386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * Section 7.5 of RFC 3711 (http://www.ietf.org/rfc/rfc3711.txt). 552386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 553386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * @return void. 554386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 555386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari */ 556386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari 557386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagarivoid 558386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagaricrypto_policy_set_aes_cm_128_null_auth(crypto_policy_t *p); 559386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari 560386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari 561386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari/** 562386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * @brief crypto_policy_set_null_cipher_hmac_sha1_80() sets a crypto 563386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * policy structure to an authentication-only policy 564386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 565386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * @param p is a pointer to the policy structure to be set 566386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 567386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * The function call crypto_policy_set_null_cipher_hmac_sha1_80(&p) 568386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * sets the crypto_policy_t at location p to use HMAC-SHA1 with an 80 569386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * bit authentication tag to provide message authentication, but to 570386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * use no encryption. This policy is NOT RECOMMENDED for SRTP unless 571386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * there is a requirement to forego encryption. 572386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 573386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * This function is a convenience that helps to avoid dealing directly 574386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * with the policy data structure. You are encouraged to initialize 575386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * policy elements with this function call. Doing so may allow your 576386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * code to be forward compatible with later versions of libSRTP that 577386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * include more elements in the crypto_policy_t datatype. 578386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 579386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * @warning This policy is NOT RECOMMENDED for SRTP unless there is a 580386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * requirement to forego encryption. 581386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 582386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * @return void. 583386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 584386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari */ 585386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari 586386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagarivoid 587386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagaricrypto_policy_set_null_cipher_hmac_sha1_80(crypto_policy_t *p); 588386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari 589386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari/** 590386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * @brief srtp_dealloc() deallocates storage for an SRTP session 591386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * context. 592386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 593386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * The function call srtp_dealloc(s) deallocates storage for the 594386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * SRTP session context s. This function should be called no more 595386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * than one time for each of the contexts allocated by the function 596386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * srtp_create(). 597386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 598386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * @param s is the srtp_t for the session to be deallocated. 599386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 600386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * @return 601386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * - err_status_ok if there no problems. 602386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * - err_status_dealloc_fail a memory deallocation failure occured. 603386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari */ 604386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari 605386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagarierr_status_t 606386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagarisrtp_dealloc(srtp_t s); 607386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari 608386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari 609386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari/* 610386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * @brief identifies a particular SRTP profile 611386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 612386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * An srtp_profile_t enumeration is used to identify a particular SRTP 613386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * profile (that is, a set of algorithms and parameters). These 614386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * profiles are defined in the DTLS-SRTP draft. 615386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari */ 616386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari 617386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagaritypedef enum { 618386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari srtp_profile_reserved = 0, 619386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari srtp_profile_aes128_cm_sha1_80 = 1, 620386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari srtp_profile_aes128_cm_sha1_32 = 2, 621386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari srtp_profile_aes256_cm_sha1_80 = 3, 622386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari srtp_profile_aes256_cm_sha1_32 = 4, 623386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari srtp_profile_null_sha1_80 = 5, 624386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari srtp_profile_null_sha1_32 = 6, 625386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari} srtp_profile_t; 626386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari 627386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari 628386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari/** 629386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * @brief crypto_policy_set_from_profile_for_rtp() sets a crypto policy 630386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * structure to the appropriate value for RTP based on an srtp_profile_t 631386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 632386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * @param p is a pointer to the policy structure to be set 633386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 634386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * The function call crypto_policy_set_rtp_default(&policy, profile) 635386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * sets the crypto_policy_t at location policy to the policy for RTP 636386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * protection, as defined by the srtp_profile_t profile. 637386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 638386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * This function is a convenience that helps to avoid dealing directly 639386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * with the policy data structure. You are encouraged to initialize 640386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * policy elements with this function call. Doing so may allow your 641386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * code to be forward compatible with later versions of libSRTP that 642386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * include more elements in the crypto_policy_t datatype. 643386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 644386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * @return values 645386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * - err_status_ok no problems were encountered 646386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * - err_status_bad_param the profile is not supported 647386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 648386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari */ 649386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagarierr_status_t 650386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagaricrypto_policy_set_from_profile_for_rtp(crypto_policy_t *policy, 651386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari srtp_profile_t profile); 652386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari 653386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari 654386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari 655386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari 656386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari/** 657386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * @brief crypto_policy_set_from_profile_for_rtcp() sets a crypto policy 658386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * structure to the appropriate value for RTCP based on an srtp_profile_t 659386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 660386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * @param p is a pointer to the policy structure to be set 661386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 662386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * The function call crypto_policy_set_rtcp_default(&policy, profile) 663386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * sets the crypto_policy_t at location policy to the policy for RTCP 664386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * protection, as defined by the srtp_profile_t profile. 665386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 666386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * This function is a convenience that helps to avoid dealing directly 667386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * with the policy data structure. You are encouraged to initialize 668386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * policy elements with this function call. Doing so may allow your 669386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * code to be forward compatible with later versions of libSRTP that 670386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * include more elements in the crypto_policy_t datatype. 671386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 672386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * @return values 673386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * - err_status_ok no problems were encountered 674386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * - err_status_bad_param the profile is not supported 675386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 676386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari */ 677386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagarierr_status_t 678386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagaricrypto_policy_set_from_profile_for_rtcp(crypto_policy_t *policy, 679386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari srtp_profile_t profile); 680386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari 681386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari/** 682386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * @brief returns the master key length for a given SRTP profile 683386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari */ 684386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagariunsigned int 685386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagarisrtp_profile_get_master_key_length(srtp_profile_t profile); 686386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari 687386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari 688386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari/** 689386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * @brief returns the master salt length for a given SRTP profile 690386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari */ 691386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagariunsigned int 692386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagarisrtp_profile_get_master_salt_length(srtp_profile_t profile); 693386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari 694386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari/** 695386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * @brief appends the salt to the key 696386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 697386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * The function call append_salt_to_key(k, klen, s, slen) 698386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * copies the string s to the location at klen bytes following 699386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * the location k. 700386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 701386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * @warning There must be at least bytes_in_salt + bytes_in_key bytes 702386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * available at the location pointed to by key. 703386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 704386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari */ 705386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari 706386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagarivoid 707386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagariappend_salt_to_key(unsigned char *key, unsigned int bytes_in_key, 708386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari unsigned char *salt, unsigned int bytes_in_salt); 709386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari 710386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari 711386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari 712386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari/** 713386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * @} 714386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari */ 715386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari 716386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari 717386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari 718386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari/** 719386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * @defgroup SRTCP Secure RTCP 720386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * @ingroup SRTP 721386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 722386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * @brief Secure RTCP functions are used to protect RTCP traffic. 723386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 724386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * RTCP is the control protocol for RTP. libSRTP protects RTCP 725386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * traffic in much the same way as it does RTP traffic. The function 726386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * srtp_protect_rtcp() applies cryptographic protections to outbound 727386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * RTCP packets, and srtp_unprotect_rtcp() verifies the protections on 728386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * inbound RTCP packets. 729386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 730386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * A note on the naming convention: srtp_protect_rtcp() has an srtp_t 731386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * as its first argument, and thus has `srtp_' as its prefix. The 732386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * trailing `_rtcp' indicates the protocol on which it acts. 733386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 734386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * @{ 735386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari */ 736386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari 737386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari/** 738386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * @brief srtp_protect_rtcp() is the Secure RTCP sender-side packet 739386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * processing function. 740386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 741386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * The function call srtp_protect_rtcp(ctx, rtp_hdr, len_ptr) applies 742386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * SRTCP protection to the RTCP packet rtcp_hdr (which has length 743386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * *len_ptr) using the SRTP session context ctx. If err_status_ok is 744386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * returned, then rtp_hdr points to the resulting SRTCP packet and 745386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * *len_ptr is the number of octets in that packet; otherwise, no 746386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * assumptions should be made about the value of either data elements. 747386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 748386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * @warning This function assumes that it can write the authentication 749386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * tag into the location in memory immediately following the RTCP 750386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * packet, and assumes that the RTCP packet is aligned on a 32-bit 751386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * boundary. 752386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 753386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * @param ctx is the SRTP context to use in processing the packet. 754386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 755386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * @param rtcp_hdr is a pointer to the RTCP packet (before the call); after 756386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * the function returns, it points to the srtp packet. 757386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 758386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * @param pkt_octet_len is a pointer to the length in octets of the 759386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * complete RTCP packet (header and body) before the function call, 760386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * and of the complete SRTCP packet after the call, if err_status_ok 761386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * was returned. Otherwise, the value of the data to which it points 762386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * is undefined. 763386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 764386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * @return 765386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * - err_status_ok if there were no problems. 766386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * - [other] if there was a failure in 767386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * the cryptographic mechanisms. 768386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari */ 769386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari 770386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari 771386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagarierr_status_t 772386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagarisrtp_protect_rtcp(srtp_t ctx, void *rtcp_hdr, int *pkt_octet_len); 773386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari 774386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari/** 775386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * @brief srtp_unprotect_rtcp() is the Secure RTCP receiver-side packet 776386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * processing function. 777386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 778386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * The function call srtp_unprotect_rtcp(ctx, srtp_hdr, len_ptr) 779386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * verifies the Secure RTCP protection of the SRTCP packet pointed to 780386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * by srtcp_hdr (which has length *len_ptr), using the SRTP session 781386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * context ctx. If err_status_ok is returned, then srtcp_hdr points 782386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * to the resulting RTCP packet and *len_ptr is the number of octets 783386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * in that packet; otherwise, no assumptions should be made about the 784386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * value of either data elements. 785386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 786386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * @warning This function assumes that the SRTCP packet is aligned on a 787386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 32-bit boundary. 788386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 789386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * @param ctx is a pointer to the srtp_t which applies to the 790386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * particular packet. 791386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 792386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * @param srtcp_hdr is a pointer to the header of the SRTCP packet 793386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * (before the call). After the function returns, it points to the 794386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * rtp packet if err_status_ok was returned; otherwise, the value of 795386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * the data to which it points is undefined. 796386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 797386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * @param pkt_octet_len is a pointer to the length in octets of the 798386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * complete SRTCP packet (header and body) before the function call, 799386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * and of the complete rtp packet after the call, if err_status_ok was 800386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * returned. Otherwise, the value of the data to which it points is 801386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * undefined. 802386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 803386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * @return 804386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * - err_status_ok if the RTCP packet is valid. 805386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * - err_status_auth_fail if the SRTCP packet failed the message 806386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * authentication check. 807386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * - err_status_replay_fail if the SRTCP packet is a replay (e.g. has 808386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * already been processed and accepted). 809386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * - [other] if there has been an error in the cryptographic mechanisms. 810386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 811386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari */ 812386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari 813386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagarierr_status_t 814386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagarisrtp_unprotect_rtcp(srtp_t ctx, void *srtcp_hdr, int *pkt_octet_len); 815386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari 816386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari/** 817386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * @} 818386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari */ 819386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari 820386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari/** 821386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * @defgroup SRTPevents SRTP events and callbacks 822386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * @ingroup SRTP 823386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 824386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * @brief libSRTP can use a user-provided callback function to 825386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * handle events. 826386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 827386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 828386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * libSRTP allows a user to provide a callback function to handle 829386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * events that need to be dealt with outside of the data plane (see 830386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * the enum srtp_event_t for a description of these events). Dealing 831386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * with these events is not a strict necessity; they are not 832386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * security-critical, but the application may suffer if they are not 833386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * handled. The function srtp_set_event_handler() is used to provide 834386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * the callback function. 835386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 836386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * A default event handler that merely reports on the events as they 837386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * happen is included. It is also possible to set the event handler 838386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * function to NULL, in which case all events will just be silently 839386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * ignored. 840386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 841386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * @{ 842386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari */ 843386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari 844386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari/** 845386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * @brief srtp_event_t defines events that need to be handled 846386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 847386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * The enum srtp_event_t defines events that need to be handled 848386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * outside the `data plane', such as SSRC collisions and 849386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * key expirations. 850386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 851386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * When a key expires or the maximum number of packets has been 852386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * reached, an SRTP stream will enter an `expired' state in which no 853386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * more packets can be protected or unprotected. When this happens, 854386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * it is likely that you will want to either deallocate the stream 855386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * (using srtp_stream_dealloc()), and possibly allocate a new one. 856386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 857386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * When an SRTP stream expires, the other streams in the same session 858386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * are unaffected, unless key sharing is used by that stream. In the 859386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * latter case, all of the streams in the session will expire. 860386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari */ 861386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari 862386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagaritypedef enum { 863386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari event_ssrc_collision, /**< 864386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * An SSRC collision occured. 865386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari */ 866386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari event_key_soft_limit, /**< An SRTP stream reached the soft key 867386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * usage limit and will expire soon. 868386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari */ 869386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari event_key_hard_limit, /**< An SRTP stream reached the hard 870386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * key usage limit and has expired. 871386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari */ 872386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari event_packet_index_limit /**< An SRTP stream reached the hard 873386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * packet limit (2^48 packets). 874386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari */ 875386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari} srtp_event_t; 876386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari 877386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari/** 878386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * @brief srtp_event_data_t is the structure passed as a callback to 879386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * the event handler function 880386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 881386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * The struct srtp_event_data_t holds the data passed to the event 882386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * handler function. 883386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari */ 884386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari 885386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagaritypedef struct srtp_event_data_t { 886386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari srtp_t session; /**< The session in which the event happend. */ 887386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari srtp_stream_t stream; /**< The stream in which the event happend. */ 888386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari srtp_event_t event; /**< An enum indicating the type of event. */ 889386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari} srtp_event_data_t; 890386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari 891386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari/** 892386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * @brief srtp_event_handler_func_t is the function prototype for 893386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * the event handler. 894386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 895386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * The typedef srtp_event_handler_func_t is the prototype for the 896386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * event handler function. It has as its only argument an 897386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * srtp_event_data_t which describes the event that needs to be handled. 898386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * There can only be a single, global handler for all events in 899386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * libSRTP. 900386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari */ 901386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari 902386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagaritypedef void (srtp_event_handler_func_t)(srtp_event_data_t *data); 903386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari 904386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari/** 905386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * @brief sets the event handler to the function supplied by the caller. 906386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 907386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * The function call srtp_install_event_handler(func) sets the event 908386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * handler function to the value func. The value NULL is acceptable 909386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * as an argument; in this case, events will be ignored rather than 910386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * handled. 911386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * 912386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * @param func is a pointer to a fuction that takes an srtp_event_data_t 913386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * pointer as an argument and returns void. This function 914386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * will be used by libSRTP to handle events. 915386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari */ 916386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari 917386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagarierr_status_t 918386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagarisrtp_install_event_handler(srtp_event_handler_func_t func); 919386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari 920386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari/** 921386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari * @} 922386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari */ 923386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari/* in host order, so outside the #if */ 924386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari#define SRTCP_E_BIT 0x80000000 925386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari/* for byte-access */ 926386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari#define SRTCP_E_BYTE_BIT 0x80 927386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari#define SRTCP_INDEX_MASK 0x7fffffff 928386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari 929386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari#ifdef __cplusplus 930386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari} 931386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari#endif 932386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari 933386ce4d9144fc190797f4e43a31aeaf76ca2e373Param Reddappagari#endif /* SRTP_H */ 934