| OLD | NEW |
|---|
| (Empty) |
| 1 /* | |
| 2 * srtp.h | |
| 3 * | |
| 4 * interface to libsrtp | |
| 5 * | |
| 6 * David A. McGrew | |
| 7 * Cisco Systems, Inc. | |
| 8 */ | |
| 9 /* | |
| 10 * | |
| 11 * Copyright (c) 2001-2006, Cisco Systems, Inc. | |
| 12 * All rights reserved. | |
| 13 * | |
| 14 * Redistribution and use in source and binary forms, with or without | |
| 15 * modification, are permitted provided that the following conditions | |
| 16 * are met: | |
| 17 * | |
| 18 * Redistributions of source code must retain the above copyright | |
| 19 * notice, this list of conditions and the following disclaimer. | |
| 20 * | |
| 21 * Redistributions in binary form must reproduce the above | |
| 22 * copyright notice, this list of conditions and the following | |
| 23 * disclaimer in the documentation and/or other materials provided | |
| 24 * with the distribution. | |
| 25 * | |
| 26 * Neither the name of the Cisco Systems, Inc. nor the names of its | |
| 27 * contributors may be used to endorse or promote products derived | |
| 28 * from this software without specific prior written permission. | |
| 29 * | |
| 30 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS | |
| 31 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT | |
| 32 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS | |
| 33 * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE | |
| 34 * COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, | |
| 35 * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES | |
| 36 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR | |
| 37 * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | |
| 38 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, | |
| 39 * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) | |
| 40 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED | |
| 41 * OF THE POSSIBILITY OF SUCH DAMAGE. | |
| 42 * | |
| 43 */ | |
| 44 | |
| 45 | |
| 46 #ifndef SRTP_H | |
| 47 #define SRTP_H | |
| 48 | |
| 49 #ifdef __cplusplus | |
| 50 extern "C" { | |
| 51 #endif | |
| 52 | |
| 53 #include <stdint.h> | |
| 54 #include "crypto.h" | |
| 55 #include "crypto_types.h" | |
| 56 #include "err.h" | |
| 57 | |
| 58 /* | |
| 59 * Compatibility shim for v1->v2 transition. | |
| 60 */ | |
| 61 | |
| 62 #define srtp_crypto_policy_set_aes_cm_128_hmac_sha1_32 \ | |
| 63 crypto_policy_set_aes_cm_128_hmac_sha1_32 | |
| 64 #define srtp_crypto_policy_set_aes_cm_128_hmac_sha1_80 \ | |
| 65 crypto_policy_set_aes_cm_128_hmac_sha1_80 | |
| 66 #define srtp_crypto_policy_set_aes_gcm_128_16_auth \ | |
| 67 crypto_policy_set_aes_gcm_128_16_auth | |
| 68 #define srtp_crypto_policy_set_aes_gcm_256_16_auth \ | |
| 69 crypto_policy_set_aes_gcm_256_16_auth | |
| 70 | |
| 71 #define srtp_ssrc_type_t ssrc_type_t | |
| 72 | |
| 73 /** | |
| 74 * @defgroup SRTP Secure RTP | |
| 75 * | |
| 76 * @brief libSRTP provides functions for protecting RTP and RTCP. See | |
| 77 * Section @ref Overview for an introduction to the use of the library. | |
| 78 * | |
| 79 * @{ | |
| 80 */ | |
| 81 | |
| 82 /* | |
| 83 * SRTP_MASTER_KEY_LEN is the nominal master key length supported by libSRTP | |
| 84 */ | |
| 85 | |
| 86 #define SRTP_MASTER_KEY_LEN 30 | |
| 87 | |
| 88 /* | |
| 89 * SRTP_MAX_KEY_LEN is the maximum key length supported by libSRTP | |
| 90 */ | |
| 91 #define SRTP_MAX_KEY_LEN 64 | |
| 92 | |
| 93 /* | |
| 94 * SRTP_MAX_TAG_LEN is the maximum tag length supported by libSRTP | |
| 95 */ | |
| 96 | |
| 97 #define SRTP_MAX_TAG_LEN 16 | |
| 98 | |
| 99 /** | |
| 100 * SRTP_MAX_TRAILER_LEN is the maximum length of the SRTP trailer | |
| 101 * (authentication tag and MKI) supported by libSRTP. This value is | |
| 102 * the maximum number of octets that will be added to an RTP packet by | |
| 103 * srtp_protect(). | |
| 104 * | |
| 105 * @brief the maximum number of octets added by srtp_protect(). | |
| 106 */ | |
| 107 #define SRTP_MAX_TRAILER_LEN SRTP_MAX_TAG_LEN | |
| 108 | |
| 109 /* | |
| 110 * SRTP_AEAD_SALT_LEN is the length of the SALT values used with | |
| 111 * GCM mode. GCM mode requires an IV. The SALT value is used | |
| 112 * as part of the IV formation logic applied to each RTP packet. | |
| 113 */ | |
| 114 #define SRTP_AEAD_SALT_LEN 12 | |
| 115 #define AES_128_GCM_KEYSIZE_WSALT SRTP_AEAD_SALT_LEN + 16 | |
| 116 #define AES_192_GCM_KEYSIZE_WSALT SRTP_AEAD_SALT_LEN + 24 | |
| 117 #define AES_256_GCM_KEYSIZE_WSALT SRTP_AEAD_SALT_LEN + 32 | |
| 118 | |
| 119 | |
| 120 | |
| 121 /* | |
| 122 * nota bene: since libSRTP doesn't support the use of the MKI, the | |
| 123 * SRTP_MAX_TRAILER_LEN value is just the maximum tag length | |
| 124 */ | |
| 125 | |
| 126 /** | |
| 127 * @brief sec_serv_t describes a set of security services. | |
| 128 * | |
| 129 * A sec_serv_t enumeration is used to describe the particular | |
| 130 * security services that will be applied by a particular crypto | |
| 131 * policy (or other mechanism). | |
| 132 */ | |
| 133 | |
| 134 typedef enum { | |
| 135 sec_serv_none = 0, /**< no services */ | |
| 136 sec_serv_conf = 1, /**< confidentiality */ | |
| 137 sec_serv_auth = 2, /**< authentication */ | |
| 138 sec_serv_conf_and_auth = 3 /**< confidentiality and authentication */ | |
| 139 } sec_serv_t; | |
| 140 | |
| 141 /** | |
| 142 * @brief crypto_policy_t describes a particular crypto policy that | |
| 143 * can be applied to an SRTP stream. | |
| 144 * | |
| 145 * A crypto_policy_t describes a particular cryptographic policy that | |
| 146 * can be applied to an SRTP or SRTCP stream. An SRTP session policy | |
| 147 * consists of a list of these policies, one for each SRTP stream | |
| 148 * in the session. | |
| 149 */ | |
| 150 | |
| 151 typedef struct crypto_policy_t { | |
| 152 cipher_type_id_t cipher_type; /**< An integer representing | |
| 153 * the type of cipher. */ | |
| 154 int cipher_key_len; /**< The length of the cipher key | |
| 155 * in octets. */ | |
| 156 auth_type_id_t auth_type; /**< An integer representing the | |
| 157 * authentication function. */ | |
| 158 int auth_key_len; /**< The length of the authentication | |
| 159 * function key in octets. */ | |
| 160 int auth_tag_len; /**< The length of the authentication | |
| 161 * tag in octets. */ | |
| 162 sec_serv_t sec_serv; /**< The flag indicating the security | |
| 163 * services to be applied. */ | |
| 164 } crypto_policy_t; | |
| 165 | |
| 166 | |
| 167 /** | |
| 168 * @brief ssrc_type_t describes the type of an SSRC. | |
| 169 * | |
| 170 * An ssrc_type_t enumeration is used to indicate a type of SSRC. See | |
| 171 * @ref srtp_policy_t for more informataion. | |
| 172 */ | |
| 173 | |
| 174 typedef enum { | |
| 175 ssrc_undefined = 0, /**< Indicates an undefined SSRC type. */ | |
| 176 ssrc_specific = 1, /**< Indicates a specific SSRC value */ | |
| 177 ssrc_any_inbound = 2, /**< Indicates any inbound SSRC value | |
| 178 (i.e. a value that is used in the | |
| 179 function srtp_unprotect()) */ | |
| 180 ssrc_any_outbound = 3 /**< Indicates any outbound SSRC value | |
| 181 (i.e. a value that is used in the | |
| 182 function srtp_protect()) */ | |
| 183 } ssrc_type_t; | |
| 184 | |
| 185 /** | |
| 186 * @brief An ssrc_t represents a particular SSRC value, or a `wildcard' SSRC. | |
| 187 * | |
| 188 * An ssrc_t represents a particular SSRC value (if its type is | |
| 189 * ssrc_specific), or a wildcard SSRC value that will match all | |
| 190 * outbound SSRCs (if its type is ssrc_any_outbound) or all inbound | |
| 191 * SSRCs (if its type is ssrc_any_inbound). | |
| 192 * | |
| 193 */ | |
| 194 | |
| 195 typedef struct { | |
| 196 ssrc_type_t type; /**< The type of this particular SSRC */ | |
| 197 unsigned int value; /**< The value of this SSRC, if it is not a wildcard */ | |
| 198 } ssrc_t; | |
| 199 | |
| 200 | |
| 201 /** | |
| 202 * @brief points to an EKT policy | |
| 203 */ | |
| 204 typedef struct ekt_policy_ctx_t *ekt_policy_t; | |
| 205 | |
| 206 | |
| 207 /** | |
| 208 * @brief points to EKT stream data | |
| 209 */ | |
| 210 typedef struct ekt_stream_ctx_t *ekt_stream_t; | |
| 211 | |
| 212 | |
| 213 /** | |
| 214 * @brief represents the policy for an SRTP session. | |
| 215 * | |
| 216 * A single srtp_policy_t struct represents the policy for a single | |
| 217 * SRTP stream, and a linked list of these elements represents the | |
| 218 * policy for an entire SRTP session. Each element contains the SRTP | |
| 219 * and SRTCP crypto policies for that stream, a pointer to the SRTP | |
| 220 * master key for that stream, the SSRC describing that stream, or a | |
| 221 * flag indicating a `wildcard' SSRC value, and a `next' field that | |
| 222 * holds a pointer to the next element in the list of policy elements, | |
| 223 * or NULL if it is the last element. | |
| 224 * | |
| 225 * The wildcard value SSRC_ANY_INBOUND matches any SSRC from an | |
| 226 * inbound stream that for which there is no explicit SSRC entry in | |
| 227 * another policy element. Similarly, the value SSRC_ANY_OUTBOUND | |
| 228 * will matches any SSRC from an outbound stream that does not appear | |
| 229 * in another policy element. Note that wildcard SSRCs &b cannot be | |
| 230 * used to match both inbound and outbound traffic. This restriction | |
| 231 * is intentional, and it allows libSRTP to ensure that no security | |
| 232 * lapses result from accidental re-use of SSRC values during key | |
| 233 * sharing. | |
| 234 * | |
| 235 * | |
| 236 * @warning The final element of the list @b must have its `next' pointer | |
| 237 * set to NULL. | |
| 238 */ | |
| 239 | |
| 240 typedef struct srtp_policy_t { | |
| 241 ssrc_t ssrc; /**< The SSRC value of stream, or the | |
| 242 * flags SSRC_ANY_INBOUND or | |
| 243 * SSRC_ANY_OUTBOUND if key sharing | |
| 244 * is used for this policy element. | |
| 245 */ | |
| 246 crypto_policy_t rtp; /**< SRTP crypto policy. */ | |
| 247 crypto_policy_t rtcp; /**< SRTCP crypto policy. */ | |
| 248 unsigned char *key; /**< Pointer to the SRTP master key for | |
| 249 * this stream. */ | |
| 250 ekt_policy_t ekt; /**< Pointer to the EKT policy structure | |
| 251 * for this stream (if any) */ | |
| 252 unsigned long window_size; /**< The window size to use for replay | |
| 253 * protection. */ | |
| 254 int allow_repeat_tx; /**< Whether retransmissions of | |
| 255 * packets with the same sequence number | |
| 256 * are allowed. (Note that such repeated | |
| 257 * transmissions must have the same RTP | |
| 258 * payload, or a severe security weakness | |
| 259 * is introduced!) */ | |
| 260 int *enc_xtn_hdr; /**< List of header ids to encrypt. */ | |
| 261 int enc_xtn_hdr_count; /**< Number of entries in list of header ids. */ | |
| 262 struct srtp_policy_t *next; /**< Pointer to next stream policy. */ | |
| 263 } srtp_policy_t; | |
| 264 | |
| 265 | |
| 266 | |
| 267 | |
| 268 /** | |
| 269 * @brief An srtp_t points to an SRTP session structure. | |
| 270 * | |
| 271 * The typedef srtp_t is a pointer to a structure that represents | |
| 272 * an SRTP session. This datatype is intentially opaque in | |
| 273 * order to separate the interface from the implementation. | |
| 274 * | |
| 275 * An SRTP session consists of all of the traffic sent to the RTP and | |
| 276 * RTCP destination transport addresses, using the RTP/SAVP (Secure | |
| 277 * Audio/Video Profile). A session can be viewed as a set of SRTP | |
| 278 * streams, each of which originates with a different participant. | |
| 279 */ | |
| 280 | |
| 281 typedef struct srtp_ctx_t *srtp_t; | |
| 282 | |
| 283 | |
| 284 /** | |
| 285 * @brief An srtp_stream_t points to an SRTP stream structure. | |
| 286 * | |
| 287 * The typedef srtp_stream_t is a pointer to a structure that | |
| 288 * represents an SRTP stream. This datatype is intentionally | |
| 289 * opaque in order to separate the interface from the implementation. | |
| 290 * | |
| 291 * An SRTP stream consists of all of the traffic sent to an SRTP | |
| 292 * session by a single participant. A session can be viewed as | |
| 293 * a set of streams. | |
| 294 * | |
| 295 */ | |
| 296 typedef struct srtp_stream_ctx_t *srtp_stream_t; | |
| 297 | |
| 298 | |
| 299 | |
| 300 /** | |
| 301 * @brief srtp_init() initializes the srtp library. | |
| 302 * | |
| 303 * @warning This function @b must be called before any other srtp | |
| 304 * functions. | |
| 305 */ | |
| 306 | |
| 307 err_status_t | |
| 308 srtp_init(void); | |
| 309 | |
| 310 /** | |
| 311 * @brief srtp_shutdown() de-initializes the srtp library. | |
| 312 * | |
| 313 * @warning No srtp functions may be called after calling this function. | |
| 314 */ | |
| 315 | |
| 316 err_status_t | |
| 317 srtp_shutdown(void); | |
| 318 | |
| 319 /** | |
| 320 * @brief srtp_protect() is the Secure RTP sender-side packet processing | |
| 321 * function. | |
| 322 * | |
| 323 * The function call srtp_protect(ctx, rtp_hdr, len_ptr) applies SRTP | |
| 324 * protection to the RTP packet rtp_hdr (which has length *len_ptr) using | |
| 325 * the SRTP context ctx. If err_status_ok is returned, then rtp_hdr | |
| 326 * points to the resulting SRTP packet and *len_ptr is the number of | |
| 327 * octets in that packet; otherwise, no assumptions should be made | |
| 328 * about the value of either data elements. | |
| 329 * | |
| 330 * The sequence numbers of the RTP packets presented to this function | |
| 331 * need not be consecutive, but they @b must be out of order by less | |
| 332 * than 2^15 = 32,768 packets. | |
| 333 * | |
| 334 * @warning This function assumes that it can write the authentication | |
| 335 * tag into the location in memory immediately following the RTP | |
| 336 * packet, and assumes that the RTP packet is aligned on a 32-bit | |
| 337 * boundary. | |
| 338 * | |
| 339 * @warning This function assumes that it can write SRTP_MAX_TRAILER_LEN | |
| 340 * into the location in memory immediately following the RTP packet. | |
| 341 * Callers MUST ensure that this much writable memory is available in | |
| 342 * the buffer that holds the RTP packet. | |
| 343 * | |
| 344 * @param ctx is the SRTP context to use in processing the packet. | |
| 345 * | |
| 346 * @param rtp_hdr is a pointer to the RTP packet (before the call); after | |
| 347 * the function returns, it points to the srtp packet. | |
| 348 * | |
| 349 * @param len_ptr is a pointer to the length in octets of the complete | |
| 350 * RTP packet (header and body) before the function call, and of the | |
| 351 * complete SRTP packet after the call, if err_status_ok was returned. | |
| 352 * Otherwise, the value of the data to which it points is undefined. | |
| 353 * | |
| 354 * @return | |
| 355 * - err_status_ok no problems | |
| 356 * - err_status_replay_fail rtp sequence number was non-increasing | |
| 357 * - @e other failure in cryptographic mechanisms | |
| 358 */ | |
| 359 | |
| 360 err_status_t | |
| 361 srtp_protect(srtp_t ctx, void *rtp_hdr, int *len_ptr); | |
| 362 | |
| 363 /** | |
| 364 * @brief srtp_unprotect() is the Secure RTP receiver-side packet | |
| 365 * processing function. | |
| 366 * | |
| 367 * The function call srtp_unprotect(ctx, srtp_hdr, len_ptr) verifies | |
| 368 * the Secure RTP protection of the SRTP packet pointed to by srtp_hdr | |
| 369 * (which has length *len_ptr), using the SRTP context ctx. If | |
| 370 * err_status_ok is returned, then srtp_hdr points to the resulting | |
| 371 * RTP packet and *len_ptr is the number of octets in that packet; | |
| 372 * otherwise, no assumptions should be made about the value of either | |
| 373 * data elements. | |
| 374 * | |
| 375 * The sequence numbers of the RTP packets presented to this function | |
| 376 * need not be consecutive, but they @b must be out of order by less | |
| 377 * than 2^15 = 32,768 packets. | |
| 378 * | |
| 379 * @warning This function assumes that the SRTP packet is aligned on a | |
| 380 * 32-bit boundary. | |
| 381 * | |
| 382 * @param ctx is the SRTP session which applies to the particular packet. | |
| 383 * | |
| 384 * @param srtp_hdr is a pointer to the header of the SRTP packet | |
| 385 * (before the call). after the function returns, it points to the | |
| 386 * rtp packet if err_status_ok was returned; otherwise, the value of | |
| 387 * the data to which it points is undefined. | |
| 388 * | |
| 389 * @param len_ptr is a pointer to the length in octets of the complete | |
| 390 * srtp packet (header and body) before the function call, and of the | |
| 391 * complete rtp packet after the call, if err_status_ok was returned. | |
| 392 * Otherwise, the value of the data to which it points is undefined. | |
| 393 * | |
| 394 * @return | |
| 395 * - err_status_ok if the RTP packet is valid. | |
| 396 * - err_status_auth_fail if the SRTP packet failed the message | |
| 397 * authentication check. | |
| 398 * - err_status_replay_fail if the SRTP packet is a replay (e.g. packet has | |
| 399 * already been processed and accepted). | |
| 400 * - [other] if there has been an error in the cryptographic mechanisms. | |
| 401 * | |
| 402 */ | |
| 403 | |
| 404 err_status_t | |
| 405 srtp_unprotect(srtp_t ctx, void *srtp_hdr, int *len_ptr); | |
| 406 | |
| 407 | |
| 408 /** | |
| 409 * @brief srtp_create() allocates and initializes an SRTP session. | |
| 410 | |
| 411 * The function call srtp_create(session, policy, key) allocates and | |
| 412 * initializes an SRTP session context, applying the given policy and | |
| 413 * key. | |
| 414 * | |
| 415 * @param session is a pointer to the SRTP session to which the policy is | |
| 416 * to be added. | |
| 417 * | |
| 418 * @param policy is the srtp_policy_t struct that describes the policy | |
| 419 * for the session. The struct may be a single element, or it may be | |
| 420 * the head of a list, in which case each element of the list is | |
| 421 * processed. It may also be NULL, in which case streams should be added | |
| 422 * later using srtp_add_stream(). The final element of the list @b must | |
| 423 * have its `next' field set to NULL. | |
| 424 * | |
| 425 * @return | |
| 426 * - err_status_ok if creation succeded. | |
| 427 * - err_status_alloc_fail if allocation failed. | |
| 428 * - err_status_init_fail if initialization failed. | |
| 429 */ | |
| 430 | |
| 431 err_status_t | |
| 432 srtp_create(srtp_t *session, const srtp_policy_t *policy); | |
| 433 | |
| 434 | |
| 435 /** | |
| 436 * @brief srtp_add_stream() allocates and initializes an SRTP stream | |
| 437 * within a given SRTP session. | |
| 438 * | |
| 439 * The function call srtp_add_stream(session, policy) allocates and | |
| 440 * initializes a new SRTP stream within a given, previously created | |
| 441 * session, applying the policy given as the other argument to that | |
| 442 * stream. | |
| 443 * | |
| 444 * @return values: | |
| 445 * - err_status_ok if stream creation succeded. | |
| 446 * - err_status_alloc_fail if stream allocation failed | |
| 447 * - err_status_init_fail if stream initialization failed. | |
| 448 */ | |
| 449 | |
| 450 err_status_t | |
| 451 srtp_add_stream(srtp_t session, | |
| 452 const srtp_policy_t *policy); | |
| 453 | |
| 454 | |
| 455 /** | |
| 456 * @brief srtp_remove_stream() deallocates an SRTP stream. | |
| 457 * | |
| 458 * The function call srtp_remove_stream(session, ssrc) removes | |
| 459 * the SRTP stream with the SSRC value ssrc from the SRTP session | |
| 460 * context given by the argument session. | |
| 461 * | |
| 462 * @param session is the SRTP session from which the stream | |
| 463 * will be removed. | |
| 464 * | |
| 465 * @param ssrc is the SSRC value of the stream to be removed. | |
| 466 * | |
| 467 * @warning Wildcard SSRC values cannot be removed from a | |
| 468 * session. | |
| 469 * | |
| 470 * @return | |
| 471 * - err_status_ok if the stream deallocation succeded. | |
| 472 * - [other] otherwise. | |
| 473 * | |
| 474 */ | |
| 475 | |
| 476 err_status_t | |
| 477 srtp_remove_stream(srtp_t session, unsigned int ssrc); | |
| 478 | |
| 479 /** | |
| 480 * @brief crypto_policy_set_rtp_default() sets a crypto policy | |
| 481 * structure to the SRTP default policy for RTP protection. | |
| 482 * | |
| 483 * @param p is a pointer to the policy structure to be set | |
| 484 * | |
| 485 * The function call crypto_policy_set_rtp_default(&p) sets the | |
| 486 * crypto_policy_t at location p to the SRTP default policy for RTP | |
| 487 * protection, as defined in the specification. This function is a | |
| 488 * convenience that helps to avoid dealing directly with the policy | |
| 489 * data structure. You are encouraged to initialize policy elements | |
| 490 * with this function call. Doing so may allow your code to be | |
| 491 * forward compatible with later versions of libSRTP that include more | |
| 492 * elements in the crypto_policy_t datatype. | |
| 493 * | |
| 494 * @return void. | |
| 495 * | |
| 496 */ | |
| 497 | |
| 498 void | |
| 499 crypto_policy_set_rtp_default(crypto_policy_t *p); | |
| 500 | |
| 501 /** | |
| 502 * @brief crypto_policy_set_rtcp_default() sets a crypto policy | |
| 503 * structure to the SRTP default policy for RTCP protection. | |
| 504 * | |
| 505 * @param p is a pointer to the policy structure to be set | |
| 506 * | |
| 507 * The function call crypto_policy_set_rtcp_default(&p) sets the | |
| 508 * crypto_policy_t at location p to the SRTP default policy for RTCP | |
| 509 * protection, as defined in the specification. This function is a | |
| 510 * convenience that helps to avoid dealing directly with the policy | |
| 511 * data structure. You are encouraged to initialize policy elements | |
| 512 * with this function call. Doing so may allow your code to be | |
| 513 * forward compatible with later versions of libSRTP that include more | |
| 514 * elements in the crypto_policy_t datatype. | |
| 515 * | |
| 516 * @return void. | |
| 517 * | |
| 518 */ | |
| 519 | |
| 520 void | |
| 521 crypto_policy_set_rtcp_default(crypto_policy_t *p); | |
| 522 | |
| 523 /** | |
| 524 * @brief crypto_policy_set_aes_cm_128_hmac_sha1_80() sets a crypto | |
| 525 * policy structure to the SRTP default policy for RTP protection. | |
| 526 * | |
| 527 * @param p is a pointer to the policy structure to be set | |
| 528 * | |
| 529 * The function crypto_policy_set_aes_cm_128_hmac_sha1_80() is a | |
| 530 * synonym for crypto_policy_set_rtp_default(). It conforms to the | |
| 531 * naming convention used in RFC 4568 (SDP Security Descriptions for | |
| 532 * Media Streams). | |
| 533 * | |
| 534 * @return void. | |
| 535 * | |
| 536 */ | |
| 537 | |
| 538 #define crypto_policy_set_aes_cm_128_hmac_sha1_80(p) crypto_policy_set_rtp_defau
lt(p) | |
| 539 | |
| 540 | |
| 541 /** | |
| 542 * @brief crypto_policy_set_aes_cm_128_hmac_sha1_32() sets a crypto | |
| 543 * policy structure to a short-authentication tag policy | |
| 544 * | |
| 545 * @param p is a pointer to the policy structure to be set | |
| 546 * | |
| 547 * The function call crypto_policy_set_aes_cm_128_hmac_sha1_32(&p) | |
| 548 * sets the crypto_policy_t at location p to use policy | |
| 549 * AES_CM_128_HMAC_SHA1_32 as defined in RFC 4568. | |
| 550 * This policy uses AES-128 | |
| 551 * Counter Mode encryption and HMAC-SHA1 authentication, with an | |
| 552 * authentication tag that is only 32 bits long. This length is | |
| 553 * considered adequate only for protecting audio and video media that | |
| 554 * use a stateless playback function. See Section 7.5 of RFC 3711 | |
| 555 * (http://www.ietf.org/rfc/rfc3711.txt). | |
| 556 * | |
| 557 * This function is a convenience that helps to avoid dealing directly | |
| 558 * with the policy data structure. You are encouraged to initialize | |
| 559 * policy elements with this function call. Doing so may allow your | |
| 560 * code to be forward compatible with later versions of libSRTP that | |
| 561 * include more elements in the crypto_policy_t datatype. | |
| 562 * | |
| 563 * @warning This crypto policy is intended for use in SRTP, but not in | |
| 564 * SRTCP. It is recommended that a policy that uses longer | |
| 565 * authentication tags be used for SRTCP. See Section 7.5 of RFC 3711 | |
| 566 * (http://www.ietf.org/rfc/rfc3711.txt). | |
| 567 * | |
| 568 * @return void. | |
| 569 * | |
| 570 */ | |
| 571 | |
| 572 void | |
| 573 crypto_policy_set_aes_cm_128_hmac_sha1_32(crypto_policy_t *p); | |
| 574 | |
| 575 | |
| 576 | |
| 577 /** | |
| 578 * @brief crypto_policy_set_aes_cm_128_null_auth() sets a crypto | |
| 579 * policy structure to an encryption-only policy | |
| 580 * | |
| 581 * @param p is a pointer to the policy structure to be set | |
| 582 * | |
| 583 * The function call crypto_policy_set_aes_cm_128_null_auth(&p) sets | |
| 584 * the crypto_policy_t at location p to use the SRTP default cipher | |
| 585 * (AES-128 Counter Mode), but to use no authentication method. This | |
| 586 * policy is NOT RECOMMENDED unless it is unavoidable; see Section 7.5 | |
| 587 * of RFC 3711 (http://www.ietf.org/rfc/rfc3711.txt). | |
| 588 * | |
| 589 * This function is a convenience that helps to avoid dealing directly | |
| 590 * with the policy data structure. You are encouraged to initialize | |
| 591 * policy elements with this function call. Doing so may allow your | |
| 592 * code to be forward compatible with later versions of libSRTP that | |
| 593 * include more elements in the crypto_policy_t datatype. | |
| 594 * | |
| 595 * @warning This policy is NOT RECOMMENDED for SRTP unless it is | |
| 596 * unavoidable, and it is NOT RECOMMENDED at all for SRTCP; see | |
| 597 * Section 7.5 of RFC 3711 (http://www.ietf.org/rfc/rfc3711.txt). | |
| 598 * | |
| 599 * @return void. | |
| 600 * | |
| 601 */ | |
| 602 | |
| 603 void | |
| 604 crypto_policy_set_aes_cm_128_null_auth(crypto_policy_t *p); | |
| 605 | |
| 606 | |
| 607 /** | |
| 608 * @brief crypto_policy_set_null_cipher_hmac_sha1_80() sets a crypto | |
| 609 * policy structure to an authentication-only policy | |
| 610 * | |
| 611 * @param p is a pointer to the policy structure to be set | |
| 612 * | |
| 613 * The function call crypto_policy_set_null_cipher_hmac_sha1_80(&p) | |
| 614 * sets the crypto_policy_t at location p to use HMAC-SHA1 with an 80 | |
| 615 * bit authentication tag to provide message authentication, but to | |
| 616 * use no encryption. This policy is NOT RECOMMENDED for SRTP unless | |
| 617 * there is a requirement to forego encryption. | |
| 618 * | |
| 619 * This function is a convenience that helps to avoid dealing directly | |
| 620 * with the policy data structure. You are encouraged to initialize | |
| 621 * policy elements with this function call. Doing so may allow your | |
| 622 * code to be forward compatible with later versions of libSRTP that | |
| 623 * include more elements in the crypto_policy_t datatype. | |
| 624 * | |
| 625 * @warning This policy is NOT RECOMMENDED for SRTP unless there is a | |
| 626 * requirement to forego encryption. | |
| 627 * | |
| 628 * @return void. | |
| 629 * | |
| 630 */ | |
| 631 | |
| 632 void | |
| 633 crypto_policy_set_null_cipher_hmac_sha1_80(crypto_policy_t *p); | |
| 634 | |
| 635 | |
| 636 /** | |
| 637 * @brief crypto_policy_set_aes_cm_256_hmac_sha1_80() sets a crypto | |
| 638 * policy structure to a encryption and authentication policy using AES-256 | |
| 639 * for RTP protection. | |
| 640 * | |
| 641 * @param p is a pointer to the policy structure to be set | |
| 642 * | |
| 643 * The function call crypto_policy_set_aes_cm_256_hmac_sha1_80(&p) | |
| 644 * sets the crypto_policy_t at location p to use policy | |
| 645 * AES_CM_256_HMAC_SHA1_80 as defined in | |
| 646 * draft-ietf-avt-srtp-big-aes-03.txt. This policy uses AES-256 | |
| 647 * Counter Mode encryption and HMAC-SHA1 authentication, with an 80 bit | |
| 648 * authentication tag. | |
| 649 * | |
| 650 * This function is a convenience that helps to avoid dealing directly | |
| 651 * with the policy data structure. You are encouraged to initialize | |
| 652 * policy elements with this function call. Doing so may allow your | |
| 653 * code to be forward compatible with later versions of libSRTP that | |
| 654 * include more elements in the crypto_policy_t datatype. | |
| 655 * | |
| 656 * @return void. | |
| 657 * | |
| 658 */ | |
| 659 | |
| 660 void crypto_policy_set_aes_cm_256_hmac_sha1_80(crypto_policy_t *p); | |
| 661 | |
| 662 | |
| 663 /** | |
| 664 * @brief crypto_policy_set_aes_cm_256_hmac_sha1_32() sets a crypto | |
| 665 * policy structure to a short-authentication tag policy using AES-256 | |
| 666 * encryption. | |
| 667 * | |
| 668 * @param p is a pointer to the policy structure to be set | |
| 669 * | |
| 670 * The function call crypto_policy_set_aes_cm_256_hmac_sha1_32(&p) | |
| 671 * sets the crypto_policy_t at location p to use policy | |
| 672 * AES_CM_256_HMAC_SHA1_32 as defined in | |
| 673 * draft-ietf-avt-srtp-big-aes-03.txt. This policy uses AES-256 | |
| 674 * Counter Mode encryption and HMAC-SHA1 authentication, with an | |
| 675 * authentication tag that is only 32 bits long. This length is | |
| 676 * considered adequate only for protecting audio and video media that | |
| 677 * use a stateless playback function. See Section 7.5 of RFC 3711 | |
| 678 * (http://www.ietf.org/rfc/rfc3711.txt). | |
| 679 * | |
| 680 * This function is a convenience that helps to avoid dealing directly | |
| 681 * with the policy data structure. You are encouraged to initialize | |
| 682 * policy elements with this function call. Doing so may allow your | |
| 683 * code to be forward compatible with later versions of libSRTP that | |
| 684 * include more elements in the crypto_policy_t datatype. | |
| 685 * | |
| 686 * @warning This crypto policy is intended for use in SRTP, but not in | |
| 687 * SRTCP. It is recommended that a policy that uses longer | |
| 688 * authentication tags be used for SRTCP. See Section 7.5 of RFC 3711 | |
| 689 * (http://www.ietf.org/rfc/rfc3711.txt). | |
| 690 * | |
| 691 * @return void. | |
| 692 * | |
| 693 */ | |
| 694 | |
| 695 void | |
| 696 crypto_policy_set_aes_cm_256_hmac_sha1_32(crypto_policy_t *p); | |
| 697 | |
| 698 /** | |
| 699 * @brief crypto_policy_set_aes_cm_256_null_auth() sets a crypto | |
| 700 * policy structure to an encryption-only policy | |
| 701 * | |
| 702 * @param p is a pointer to the policy structure to be set | |
| 703 * | |
| 704 * The function call crypto_policy_set_aes_cm_256_null_auth(&p) sets | |
| 705 * the crypto_policy_t at location p to use the SRTP default cipher | |
| 706 * (AES-256 Counter Mode), but to use no authentication method. This | |
| 707 * policy is NOT RECOMMENDED unless it is unavoidable; see Section 7.5 | |
| 708 * of RFC 3711 (http://www.ietf.org/rfc/rfc3711.txt). | |
| 709 * | |
| 710 * This function is a convenience that helps to avoid dealing directly | |
| 711 * with the policy data structure. You are encouraged to initialize | |
| 712 * policy elements with this function call. Doing so may allow your | |
| 713 * code to be forward compatible with later versions of libSRTP that | |
| 714 * include more elements in the crypto_policy_t datatype. | |
| 715 * | |
| 716 * @warning This policy is NOT RECOMMENDED for SRTP unless it is | |
| 717 * unavoidable, and it is NOT RECOMMENDED at all for SRTCP; see | |
| 718 * Section 7.5 of RFC 3711 (http://www.ietf.org/rfc/rfc3711.txt). | |
| 719 * | |
| 720 * @return void. | |
| 721 * | |
| 722 */ | |
| 723 void | |
| 724 crypto_policy_set_aes_cm_256_null_auth(crypto_policy_t *p); | |
| 725 | |
| 726 /** | |
| 727 * @brief crypto_policy_set_aes_gcm_128_8_auth() sets a crypto | |
| 728 * policy structure to an AEAD encryption policy. | |
| 729 * | |
| 730 * @param p is a pointer to the policy structure to be set | |
| 731 * | |
| 732 * The function call crypto_policy_set_aes_gcm_128_8_auth(&p) sets | |
| 733 * the crypto_policy_t at location p to use the SRTP default cipher | |
| 734 * (AES-128 Galois Counter Mode) with 8 octet auth tag. This | |
| 735 * policy applies confidentiality and authentication to both the | |
| 736 * RTP and RTCP packets. | |
| 737 * | |
| 738 * This function is a convenience that helps to avoid dealing directly | |
| 739 * with the policy data structure. You are encouraged to initialize | |
| 740 * policy elements with this function call. Doing so may allow your | |
| 741 * code to be forward compatible with later versions of libSRTP that | |
| 742 * include more elements in the crypto_policy_t datatype. | |
| 743 * | |
| 744 * @return void. | |
| 745 * | |
| 746 */ | |
| 747 void | |
| 748 crypto_policy_set_aes_gcm_128_8_auth(crypto_policy_t *p); | |
| 749 | |
| 750 /** | |
| 751 * @brief crypto_policy_set_aes_gcm_256_8_auth() sets a crypto | |
| 752 * policy structure to an AEAD encryption policy | |
| 753 * | |
| 754 * @param p is a pointer to the policy structure to be set | |
| 755 * | |
| 756 * The function call crypto_policy_set_aes_gcm_256_8_auth(&p) sets | |
| 757 * the crypto_policy_t at location p to use the SRTP default cipher | |
| 758 * (AES-256 Galois Counter Mode) with 8 octet auth tag. This | |
| 759 * policy applies confidentiality and authentication to both the | |
| 760 * RTP and RTCP packets. | |
| 761 * | |
| 762 * This function is a convenience that helps to avoid dealing directly | |
| 763 * with the policy data structure. You are encouraged to initialize | |
| 764 * policy elements with this function call. Doing so may allow your | |
| 765 * code to be forward compatible with later versions of libSRTP that | |
| 766 * include more elements in the crypto_policy_t datatype. | |
| 767 * | |
| 768 * @return void. | |
| 769 * | |
| 770 */ | |
| 771 void | |
| 772 crypto_policy_set_aes_gcm_256_8_auth(crypto_policy_t *p); | |
| 773 | |
| 774 /** | |
| 775 * @brief crypto_policy_set_aes_gcm_128_8_only_auth() sets a crypto | |
| 776 * policy structure to an AEAD authentication-only policy | |
| 777 * | |
| 778 * @param p is a pointer to the policy structure to be set | |
| 779 * | |
| 780 * The function call crypto_policy_set_aes_gcm_128_8_only_auth(&p) sets | |
| 781 * the crypto_policy_t at location p to use the SRTP default cipher | |
| 782 * (AES-128 Galois Counter Mode) with 8 octet auth tag. This policy | |
| 783 * applies confidentiality and authentication to the RTP packets, | |
| 784 * but only authentication to the RTCP packets. | |
| 785 * | |
| 786 * This function is a convenience that helps to avoid dealing directly | |
| 787 * with the policy data structure. You are encouraged to initialize | |
| 788 * policy elements with this function call. Doing so may allow your | |
| 789 * code to be forward compatible with later versions of libSRTP that | |
| 790 * include more elements in the crypto_policy_t datatype. | |
| 791 * | |
| 792 * @return void. | |
| 793 * | |
| 794 */ | |
| 795 void | |
| 796 crypto_policy_set_aes_gcm_128_8_only_auth(crypto_policy_t *p); | |
| 797 | |
| 798 /** | |
| 799 * @brief crypto_policy_set_aes_gcm_256_8_only_auth() sets a crypto | |
| 800 * policy structure to an AEAD authentication-only policy | |
| 801 * | |
| 802 * @param p is a pointer to the policy structure to be set | |
| 803 * | |
| 804 * The function call crypto_policy_set_aes_gcm_256_8_only_auth(&p) sets | |
| 805 * the crypto_policy_t at location p to use the SRTP default cipher | |
| 806 * (AES-256 Galois Counter Mode) with 8 octet auth tag. This policy | |
| 807 * applies confidentiality and authentication to the RTP packets, | |
| 808 * but only authentication to the RTCP packets. | |
| 809 * | |
| 810 * This function is a convenience that helps to avoid dealing directly | |
| 811 * with the policy data structure. You are encouraged to initialize | |
| 812 * policy elements with this function call. Doing so may allow your | |
| 813 * code to be forward compatible with later versions of libSRTP that | |
| 814 * include more elements in the crypto_policy_t datatype. | |
| 815 * | |
| 816 * @return void. | |
| 817 * | |
| 818 */ | |
| 819 void | |
| 820 crypto_policy_set_aes_gcm_256_8_only_auth(crypto_policy_t *p); | |
| 821 | |
| 822 /** | |
| 823 * @brief crypto_policy_set_aes_gcm_128_16_auth() sets a crypto | |
| 824 * policy structure to an AEAD encryption policy. | |
| 825 * | |
| 826 * @param p is a pointer to the policy structure to be set | |
| 827 * | |
| 828 * The function call crypto_policy_set_aes_gcm_128_16_auth(&p) sets | |
| 829 * the crypto_policy_t at location p to use the SRTP default cipher | |
| 830 * (AES-128 Galois Counter Mode) with 16 octet auth tag. This | |
| 831 * policy applies confidentiality and authentication to both the | |
| 832 * RTP and RTCP packets. | |
| 833 * | |
| 834 * This function is a convenience that helps to avoid dealing directly | |
| 835 * with the policy data structure. You are encouraged to initialize | |
| 836 * policy elements with this function call. Doing so may allow your | |
| 837 * code to be forward compatible with later versions of libSRTP that | |
| 838 * include more elements in the crypto_policy_t datatype. | |
| 839 * | |
| 840 * @return void. | |
| 841 * | |
| 842 */ | |
| 843 void | |
| 844 crypto_policy_set_aes_gcm_128_16_auth(crypto_policy_t *p); | |
| 845 | |
| 846 /** | |
| 847 * @brief crypto_policy_set_aes_gcm_256_16_auth() sets a crypto | |
| 848 * policy structure to an AEAD encryption policy | |
| 849 * | |
| 850 * @param p is a pointer to the policy structure to be set | |
| 851 * | |
| 852 * The function call crypto_policy_set_aes_gcm_256_16_auth(&p) sets | |
| 853 * the crypto_policy_t at location p to use the SRTP default cipher | |
| 854 * (AES-256 Galois Counter Mode) with 16 octet auth tag. This | |
| 855 * policy applies confidentiality and authentication to both the | |
| 856 * RTP and RTCP packets. | |
| 857 * | |
| 858 * This function is a convenience that helps to avoid dealing directly | |
| 859 * with the policy data structure. You are encouraged to initialize | |
| 860 * policy elements with this function call. Doing so may allow your | |
| 861 * code to be forward compatible with later versions of libSRTP that | |
| 862 * include more elements in the crypto_policy_t datatype. | |
| 863 * | |
| 864 * @return void. | |
| 865 * | |
| 866 */ | |
| 867 void | |
| 868 crypto_policy_set_aes_gcm_256_16_auth(crypto_policy_t *p); | |
| 869 | |
| 870 | |
| 871 /** | |
| 872 * @brief srtp_dealloc() deallocates storage for an SRTP session | |
| 873 * context. | |
| 874 * | |
| 875 * The function call srtp_dealloc(s) deallocates storage for the | |
| 876 * SRTP session context s. This function should be called no more | |
| 877 * than one time for each of the contexts allocated by the function | |
| 878 * srtp_create(). | |
| 879 * | |
| 880 * @param s is the srtp_t for the session to be deallocated. | |
| 881 * | |
| 882 * @return | |
| 883 * - err_status_ok if there no problems. | |
| 884 * - err_status_dealloc_fail a memory deallocation failure occured. | |
| 885 */ | |
| 886 | |
| 887 err_status_t | |
| 888 srtp_dealloc(srtp_t s); | |
| 889 | |
| 890 | |
| 891 /* | |
| 892 * @brief identifies a particular SRTP profile | |
| 893 * | |
| 894 * An srtp_profile_t enumeration is used to identify a particular SRTP | |
| 895 * profile (that is, a set of algorithms and parameters). These | |
| 896 * profiles are defined in the DTLS-SRTP draft. | |
| 897 */ | |
| 898 | |
| 899 typedef enum { | |
| 900 srtp_profile_reserved = 0, | |
| 901 srtp_profile_aes128_cm_sha1_80 = 1, | |
| 902 srtp_profile_aes128_cm_sha1_32 = 2, | |
| 903 srtp_profile_aes256_cm_sha1_80 = 3, | |
| 904 srtp_profile_aes256_cm_sha1_32 = 4, | |
| 905 srtp_profile_null_sha1_80 = 5, | |
| 906 srtp_profile_null_sha1_32 = 6, | |
| 907 } srtp_profile_t; | |
| 908 | |
| 909 | |
| 910 /** | |
| 911 * @brief crypto_policy_set_from_profile_for_rtp() sets a crypto policy | |
| 912 * structure to the appropriate value for RTP based on an srtp_profile_t | |
| 913 * | |
| 914 * @param p is a pointer to the policy structure to be set | |
| 915 * | |
| 916 * The function call crypto_policy_set_rtp_default(&policy, profile) | |
| 917 * sets the crypto_policy_t at location policy to the policy for RTP | |
| 918 * protection, as defined by the srtp_profile_t profile. | |
| 919 * | |
| 920 * This function is a convenience that helps to avoid dealing directly | |
| 921 * with the policy data structure. You are encouraged to initialize | |
| 922 * policy elements with this function call. Doing so may allow your | |
| 923 * code to be forward compatible with later versions of libSRTP that | |
| 924 * include more elements in the crypto_policy_t datatype. | |
| 925 * | |
| 926 * @return values | |
| 927 * - err_status_ok no problems were encountered | |
| 928 * - err_status_bad_param the profile is not supported | |
| 929 * | |
| 930 */ | |
| 931 err_status_t | |
| 932 crypto_policy_set_from_profile_for_rtp(crypto_policy_t *policy, | |
| 933 srtp_profile_t profile); | |
| 934 | |
| 935 | |
| 936 | |
| 937 | |
| 938 /** | |
| 939 * @brief crypto_policy_set_from_profile_for_rtcp() sets a crypto policy | |
| 940 * structure to the appropriate value for RTCP based on an srtp_profile_t | |
| 941 * | |
| 942 * @param p is a pointer to the policy structure to be set | |
| 943 * | |
| 944 * The function call crypto_policy_set_rtcp_default(&policy, profile) | |
| 945 * sets the crypto_policy_t at location policy to the policy for RTCP | |
| 946 * protection, as defined by the srtp_profile_t profile. | |
| 947 * | |
| 948 * This function is a convenience that helps to avoid dealing directly | |
| 949 * with the policy data structure. You are encouraged to initialize | |
| 950 * policy elements with this function call. Doing so may allow your | |
| 951 * code to be forward compatible with later versions of libSRTP that | |
| 952 * include more elements in the crypto_policy_t datatype. | |
| 953 * | |
| 954 * @return values | |
| 955 * - err_status_ok no problems were encountered | |
| 956 * - err_status_bad_param the profile is not supported | |
| 957 * | |
| 958 */ | |
| 959 err_status_t | |
| 960 crypto_policy_set_from_profile_for_rtcp(crypto_policy_t *policy, | |
| 961 srtp_profile_t profile); | |
| 962 | |
| 963 /** | |
| 964 * @brief returns the master key length for a given SRTP profile | |
| 965 */ | |
| 966 unsigned int | |
| 967 srtp_profile_get_master_key_length(srtp_profile_t profile); | |
| 968 | |
| 969 | |
| 970 /** | |
| 971 * @brief returns the master salt length for a given SRTP profile | |
| 972 */ | |
| 973 unsigned int | |
| 974 srtp_profile_get_master_salt_length(srtp_profile_t profile); | |
| 975 | |
| 976 /** | |
| 977 * @brief appends the salt to the key | |
| 978 * | |
| 979 * The function call append_salt_to_key(k, klen, s, slen) | |
| 980 * copies the string s to the location at klen bytes following | |
| 981 * the location k. | |
| 982 * | |
| 983 * @warning There must be at least bytes_in_salt + bytes_in_key bytes | |
| 984 * available at the location pointed to by key. | |
| 985 * | |
| 986 */ | |
| 987 | |
| 988 void | |
| 989 append_salt_to_key(unsigned char *key, unsigned int bytes_in_key, | |
| 990 unsigned char *salt, unsigned int bytes_in_salt); | |
| 991 | |
| 992 | |
| 993 | |
| 994 /** | |
| 995 * @} | |
| 996 */ | |
| 997 | |
| 998 | |
| 999 | |
| 1000 /** | |
| 1001 * @defgroup SRTCP Secure RTCP | |
| 1002 * @ingroup SRTP | |
| 1003 * | |
| 1004 * @brief Secure RTCP functions are used to protect RTCP traffic. | |
| 1005 * | |
| 1006 * RTCP is the control protocol for RTP. libSRTP protects RTCP | |
| 1007 * traffic in much the same way as it does RTP traffic. The function | |
| 1008 * srtp_protect_rtcp() applies cryptographic protections to outbound | |
| 1009 * RTCP packets, and srtp_unprotect_rtcp() verifies the protections on | |
| 1010 * inbound RTCP packets. | |
| 1011 * | |
| 1012 * A note on the naming convention: srtp_protect_rtcp() has an srtp_t | |
| 1013 * as its first argument, and thus has `srtp_' as its prefix. The | |
| 1014 * trailing `_rtcp' indicates the protocol on which it acts. | |
| 1015 * | |
| 1016 * @{ | |
| 1017 */ | |
| 1018 | |
| 1019 /** | |
| 1020 * @brief srtp_protect_rtcp() is the Secure RTCP sender-side packet | |
| 1021 * processing function. | |
| 1022 * | |
| 1023 * The function call srtp_protect_rtcp(ctx, rtp_hdr, len_ptr) applies | |
| 1024 * SRTCP protection to the RTCP packet rtcp_hdr (which has length | |
| 1025 * *len_ptr) using the SRTP session context ctx. If err_status_ok is | |
| 1026 * returned, then rtp_hdr points to the resulting SRTCP packet and | |
| 1027 * *len_ptr is the number of octets in that packet; otherwise, no | |
| 1028 * assumptions should be made about the value of either data elements. | |
| 1029 * | |
| 1030 * @warning This function assumes that it can write the authentication | |
| 1031 * tag into the location in memory immediately following the RTCP | |
| 1032 * packet, and assumes that the RTCP packet is aligned on a 32-bit | |
| 1033 * boundary. | |
| 1034 * | |
| 1035 * @warning This function assumes that it can write SRTP_MAX_TRAILER_LEN+4 | |
| 1036 * into the location in memory immediately following the RTCP packet. | |
| 1037 * Callers MUST ensure that this much writable memory is available in | |
| 1038 * the buffer that holds the RTCP packet. | |
| 1039 * | |
| 1040 * @param ctx is the SRTP context to use in processing the packet. | |
| 1041 * | |
| 1042 * @param rtcp_hdr is a pointer to the RTCP packet (before the call); after | |
| 1043 * the function returns, it points to the srtp packet. | |
| 1044 * | |
| 1045 * @param pkt_octet_len is a pointer to the length in octets of the | |
| 1046 * complete RTCP packet (header and body) before the function call, | |
| 1047 * and of the complete SRTCP packet after the call, if err_status_ok | |
| 1048 * was returned. Otherwise, the value of the data to which it points | |
| 1049 * is undefined. | |
| 1050 * | |
| 1051 * @return | |
| 1052 * - err_status_ok if there were no problems. | |
| 1053 * - [other] if there was a failure in | |
| 1054 * the cryptographic mechanisms. | |
| 1055 */ | |
| 1056 | |
| 1057 | |
| 1058 err_status_t | |
| 1059 srtp_protect_rtcp(srtp_t ctx, void *rtcp_hdr, int *pkt_octet_len); | |
| 1060 | |
| 1061 /** | |
| 1062 * @brief srtp_unprotect_rtcp() is the Secure RTCP receiver-side packet | |
| 1063 * processing function. | |
| 1064 * | |
| 1065 * The function call srtp_unprotect_rtcp(ctx, srtp_hdr, len_ptr) | |
| 1066 * verifies the Secure RTCP protection of the SRTCP packet pointed to | |
| 1067 * by srtcp_hdr (which has length *len_ptr), using the SRTP session | |
| 1068 * context ctx. If err_status_ok is returned, then srtcp_hdr points | |
| 1069 * to the resulting RTCP packet and *len_ptr is the number of octets | |
| 1070 * in that packet; otherwise, no assumptions should be made about the | |
| 1071 * value of either data elements. | |
| 1072 * | |
| 1073 * @warning This function assumes that the SRTCP packet is aligned on a | |
| 1074 * 32-bit boundary. | |
| 1075 * | |
| 1076 * @param ctx is a pointer to the srtp_t which applies to the | |
| 1077 * particular packet. | |
| 1078 * | |
| 1079 * @param srtcp_hdr is a pointer to the header of the SRTCP packet | |
| 1080 * (before the call). After the function returns, it points to the | |
| 1081 * rtp packet if err_status_ok was returned; otherwise, the value of | |
| 1082 * the data to which it points is undefined. | |
| 1083 * | |
| 1084 * @param pkt_octet_len is a pointer to the length in octets of the | |
| 1085 * complete SRTCP packet (header and body) before the function call, | |
| 1086 * and of the complete rtp packet after the call, if err_status_ok was | |
| 1087 * returned. Otherwise, the value of the data to which it points is | |
| 1088 * undefined. | |
| 1089 * | |
| 1090 * @return | |
| 1091 * - err_status_ok if the RTCP packet is valid. | |
| 1092 * - err_status_auth_fail if the SRTCP packet failed the message | |
| 1093 * authentication check. | |
| 1094 * - err_status_replay_fail if the SRTCP packet is a replay (e.g. has | |
| 1095 * already been processed and accepted). | |
| 1096 * - [other] if there has been an error in the cryptographic mechanisms. | |
| 1097 * | |
| 1098 */ | |
| 1099 | |
| 1100 err_status_t | |
| 1101 srtp_unprotect_rtcp(srtp_t ctx, void *srtcp_hdr, int *pkt_octet_len); | |
| 1102 | |
| 1103 /** | |
| 1104 * @} | |
| 1105 */ | |
| 1106 | |
| 1107 | |
| 1108 /** | |
| 1109 * @defgroup User data associated to a SRTP session. | |
| 1110 * @ingroup SRTP | |
| 1111 * | |
| 1112 * @brief Store custom user data within a SRTP session. | |
| 1113 * | |
| 1114 * @{ | |
| 1115 */ | |
| 1116 | |
| 1117 /** | |
| 1118 * @brief srtp_set_user_data() stores the given pointer into the SRTP | |
| 1119 * session for later retrieval. | |
| 1120 * | |
| 1121 * @param ctx is the srtp_t context in which the given data pointer is | |
| 1122 * stored. | |
| 1123 * | |
| 1124 * @param data is a pointer to the custom information (struct, function, | |
| 1125 * etc) associated with the SRTP session. | |
| 1126 * | |
| 1127 * @return void. | |
| 1128 * | |
| 1129 */ | |
| 1130 | |
| 1131 void | |
| 1132 srtp_set_user_data(srtp_t ctx, void *data); | |
| 1133 | |
| 1134 /** | |
| 1135 * @brief srtp_get_user_data() retrieves the pointer to the custom data | |
| 1136 * previously stored with srtp_set_user_data(). | |
| 1137 * | |
| 1138 * This function is mostly useful for retrieving data associated to a | |
| 1139 * SRTP session when an event fires. The user can then get such a custom | |
| 1140 * data by calling this function with the session field of the | |
| 1141 * srtp_event_data_t struct as argument. | |
| 1142 * | |
| 1143 * @param ctx is the srtp_t context in which the given data pointer was | |
| 1144 * stored. | |
| 1145 * | |
| 1146 * @return void* pointer to the user data. | |
| 1147 * | |
| 1148 */ | |
| 1149 | |
| 1150 void* | |
| 1151 srtp_get_user_data(srtp_t ctx); | |
| 1152 | |
| 1153 /** | |
| 1154 * @} | |
| 1155 */ | |
| 1156 | |
| 1157 | |
| 1158 /** | |
| 1159 * @defgroup SRTPevents SRTP events and callbacks | |
| 1160 * @ingroup SRTP | |
| 1161 * | |
| 1162 * @brief libSRTP can use a user-provided callback function to | |
| 1163 * handle events. | |
| 1164 * | |
| 1165 * | |
| 1166 * libSRTP allows a user to provide a callback function to handle | |
| 1167 * events that need to be dealt with outside of the data plane (see | |
| 1168 * the enum srtp_event_t for a description of these events). Dealing | |
| 1169 * with these events is not a strict necessity; they are not | |
| 1170 * security-critical, but the application may suffer if they are not | |
| 1171 * handled. The function srtp_set_event_handler() is used to provide | |
| 1172 * the callback function. | |
| 1173 * | |
| 1174 * A default event handler that merely reports on the events as they | |
| 1175 * happen is included. It is also possible to set the event handler | |
| 1176 * function to NULL, in which case all events will just be silently | |
| 1177 * ignored. | |
| 1178 * | |
| 1179 * @{ | |
| 1180 */ | |
| 1181 | |
| 1182 /** | |
| 1183 * @brief srtp_event_t defines events that need to be handled | |
| 1184 * | |
| 1185 * The enum srtp_event_t defines events that need to be handled | |
| 1186 * outside the `data plane', such as SSRC collisions and | |
| 1187 * key expirations. | |
| 1188 * | |
| 1189 * When a key expires or the maximum number of packets has been | |
| 1190 * reached, an SRTP stream will enter an `expired' state in which no | |
| 1191 * more packets can be protected or unprotected. When this happens, | |
| 1192 * it is likely that you will want to either deallocate the stream | |
| 1193 * (using srtp_stream_dealloc()), and possibly allocate a new one. | |
| 1194 * | |
| 1195 * When an SRTP stream expires, the other streams in the same session | |
| 1196 * are unaffected, unless key sharing is used by that stream. In the | |
| 1197 * latter case, all of the streams in the session will expire. | |
| 1198 */ | |
| 1199 | |
| 1200 typedef enum { | |
| 1201 event_ssrc_collision, /**< | |
| 1202 * An SSRC collision occured. | |
| 1203 */ | |
| 1204 event_key_soft_limit, /**< An SRTP stream reached the soft key | |
| 1205 * usage limit and will expire soon. | |
| 1206 */ | |
| 1207 event_key_hard_limit, /**< An SRTP stream reached the hard | |
| 1208 * key usage limit and has expired. | |
| 1209 */ | |
| 1210 event_packet_index_limit /**< An SRTP stream reached the hard | |
| 1211 * packet limit (2^48 packets). | |
| 1212 */ | |
| 1213 } srtp_event_t; | |
| 1214 | |
| 1215 /** | |
| 1216 * @brief srtp_event_data_t is the structure passed as a callback to | |
| 1217 * the event handler function | |
| 1218 * | |
| 1219 * The struct srtp_event_data_t holds the data passed to the event | |
| 1220 * handler function. | |
| 1221 */ | |
| 1222 | |
| 1223 typedef struct srtp_event_data_t { | |
| 1224 srtp_t session; /**< The session in which the event happend. */ | |
| 1225 srtp_stream_t stream; /**< The stream in which the event happend. */ | |
| 1226 srtp_event_t event; /**< An enum indicating the type of event. */ | |
| 1227 } srtp_event_data_t; | |
| 1228 | |
| 1229 /** | |
| 1230 * @brief srtp_event_handler_func_t is the function prototype for | |
| 1231 * the event handler. | |
| 1232 * | |
| 1233 * The typedef srtp_event_handler_func_t is the prototype for the | |
| 1234 * event handler function. It has as its only argument an | |
| 1235 * srtp_event_data_t which describes the event that needs to be handled. | |
| 1236 * There can only be a single, global handler for all events in | |
| 1237 * libSRTP. | |
| 1238 */ | |
| 1239 | |
| 1240 typedef void (srtp_event_handler_func_t)(srtp_event_data_t *data); | |
| 1241 | |
| 1242 /** | |
| 1243 * @brief sets the event handler to the function supplied by the caller. | |
| 1244 * | |
| 1245 * The function call srtp_install_event_handler(func) sets the event | |
| 1246 * handler function to the value func. The value NULL is acceptable | |
| 1247 * as an argument; in this case, events will be ignored rather than | |
| 1248 * handled. | |
| 1249 * | |
| 1250 * @param func is a pointer to a fuction that takes an srtp_event_data_t | |
| 1251 * pointer as an argument and returns void. This function | |
| 1252 * will be used by libSRTP to handle events. | |
| 1253 */ | |
| 1254 | |
| 1255 err_status_t | |
| 1256 srtp_install_event_handler(srtp_event_handler_func_t func); | |
| 1257 | |
| 1258 /** | |
| 1259 * @brief Returns the version string of the library. | |
| 1260 * | |
| 1261 */ | |
| 1262 const char *srtp_get_version_string(void); | |
| 1263 | |
| 1264 /** | |
| 1265 * @brief Returns the numeric representation of the library version. | |
| 1266 * | |
| 1267 */ | |
| 1268 unsigned int srtp_get_version(void); | |
| 1269 | |
| 1270 /** | |
| 1271 * @} | |
| 1272 */ | |
| 1273 /* in host order, so outside the #if */ | |
| 1274 #define SRTCP_E_BIT 0x80000000 | |
| 1275 /* for byte-access */ | |
| 1276 #define SRTCP_E_BYTE_BIT 0x80 | |
| 1277 #define SRTCP_INDEX_MASK 0x7fffffff | |
| 1278 | |
| 1279 #ifdef __cplusplus | |
| 1280 } | |
| 1281 #endif | |
| 1282 | |
| 1283 #endif /* SRTP_H */ | |
| OLD | NEW |
|---|
Chromium Code Reviews
Issue 2344973002:
Update libsrtp to version 2.0 (Closed)
