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-2017, 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 #ifndef SRTP_SRTP_H 46 #define SRTP_SRTP_H 47 48 #include <stdint.h> 49 50 #ifdef __cplusplus 51 extern "C" { 52 #endif 53 54 /** 55 * @defgroup SRTP Secure RTP 56 * 57 * @brief libSRTP provides functions for protecting RTP and RTCP. See 58 * Section @ref Overview for an introduction to the use of the library. 59 * 60 * @{ 61 */ 62 63 /* 64 * SRTP_MASTER_KEY_LEN is the nominal master key length supported by libSRTP 65 */ 66 67 #define SRTP_MASTER_KEY_LEN 30 68 69 /* 70 * SRTP_MAX_KEY_LEN is the maximum key length supported by libSRTP 71 */ 72 #define SRTP_MAX_KEY_LEN 64 73 74 /* 75 * SRTP_MAX_TAG_LEN is the maximum tag length supported by libSRTP 76 */ 77 78 #define SRTP_MAX_TAG_LEN 16 79 80 /** 81 * SRTP_MAX_MKI_LEN is the maximum size the MKI could be which is 82 * 128 bytes 83 */ 84 #define SRTP_MAX_MKI_LEN 128 85 86 /** 87 * SRTP_MAX_TRAILER_LEN is the maximum length of the SRTP trailer 88 * (authentication tag and MKI) supported by libSRTP. This value is 89 * the maixmum number of octets that will be added to an RTP packet by 90 * srtp_protect(). 91 * 92 * @brief the maximum number of octets added by srtp_protect(). 93 */ 94 #define SRTP_MAX_TRAILER_LEN (SRTP_MAX_TAG_LEN + SRTP_MAX_MKI_LEN) 95 96 /** 97 * SRTP_MAX_NUM_MASTER_KEYS is the maximum number of Master keys for 98 * MKI supported by libSRTP. 99 * 100 */ 101 #define SRTP_MAX_NUM_MASTER_KEYS 16 102 103 #define SRTP_SALT_LEN 14 104 105 /* 106 * SRTP_AEAD_SALT_LEN is the length of the SALT values used with 107 * GCM mode. GCM mode requires an IV. The SALT value is used 108 * as part of the IV formation logic applied to each RTP packet. 109 */ 110 #define SRTP_AEAD_SALT_LEN 12 111 112 #define SRTP_AES_128_KEY_LEN 16 113 #define SRTP_AES_192_KEY_LEN 24 114 #define SRTP_AES_256_KEY_LEN 32 115 116 #define SRTP_AES_ICM_128_KEY_LEN_WSALT (SRTP_SALT_LEN + SRTP_AES_128_KEY_LEN) 117 #define SRTP_AES_ICM_192_KEY_LEN_WSALT (SRTP_SALT_LEN + SRTP_AES_192_KEY_LEN) 118 #define SRTP_AES_ICM_256_KEY_LEN_WSALT (SRTP_SALT_LEN + SRTP_AES_256_KEY_LEN) 119 120 #define SRTP_AES_GCM_128_KEY_LEN_WSALT \ 121 (SRTP_AEAD_SALT_LEN + SRTP_AES_128_KEY_LEN) 122 #define SRTP_AES_GCM_192_KEY_LEN_WSALT \ 123 (SRTP_AEAD_SALT_LEN + SRTP_AES_192_KEY_LEN) 124 #define SRTP_AES_GCM_256_KEY_LEN_WSALT \ 125 (SRTP_AEAD_SALT_LEN + SRTP_AES_256_KEY_LEN) 126 127 /** 128 * @brief A srtp_cipher_type_id_t is an identifier for a particular cipher 129 * type. 130 * 131 * A srtp_cipher_type_id_t is an integer that represents a particular 132 * cipher type, e.g. the Advanced Encryption Standard (AES). A 133 * SRTP_NULL_CIPHER is avaliable; this cipher leaves the data unchanged, 134 * and can be selected to indicate that no encryption is to take 135 * place. 136 * 137 * @ingroup Ciphers 138 */ 139 typedef uint32_t srtp_cipher_type_id_t; 140 141 /** 142 * @brief An srtp_auth_type_id_t is an identifier for a particular 143 * authentication 144 * function. 145 * 146 * An srtp_auth_type_id_t is an integer that represents a particular 147 * authentication function type, e.g. HMAC-SHA1. A SRTP_NULL_AUTH is 148 * avaliable; this authentication function performs no computation, 149 * and can be selected to indicate that no authentication is to take 150 * place. 151 * 152 * @ingroup Authentication 153 */ 154 typedef uint32_t srtp_auth_type_id_t; 155 156 /** 157 * @brief srtp_err_status_t defines error codes. 158 * 159 * The enumeration srtp_err_status_t defines error codes. Note that the 160 * value of srtp_err_status_ok is equal to zero, which can simplify error 161 * checking somewhat. 162 * 163 */ 164 typedef enum { 165 srtp_err_status_ok = 0, /**< nothing to report */ 166 srtp_err_status_fail = 1, /**< unspecified failure */ 167 srtp_err_status_bad_param = 2, /**< unsupported parameter */ 168 srtp_err_status_alloc_fail = 3, /**< couldn't allocate memory */ 169 srtp_err_status_dealloc_fail = 4, /**< couldn't deallocate properly */ 170 srtp_err_status_init_fail = 5, /**< couldn't initialize */ 171 srtp_err_status_terminus = 6, /**< can't process as much data as */ 172 /**< requested */ 173 srtp_err_status_auth_fail = 7, /**< authentication failure */ 174 srtp_err_status_cipher_fail = 8, /**< cipher failure */ 175 srtp_err_status_replay_fail = 9, /**< replay check failed (bad index) */ 176 srtp_err_status_replay_old = 10, /**< replay check failed (index too */ 177 /**< old) */ 178 srtp_err_status_algo_fail = 11, /**< algorithm failed test routine */ 179 srtp_err_status_no_such_op = 12, /**< unsupported operation */ 180 srtp_err_status_no_ctx = 13, /**< no appropriate context found */ 181 srtp_err_status_cant_check = 14, /**< unable to perform desired */ 182 /**< validation */ 183 srtp_err_status_key_expired = 15, /**< can't use key any more */ 184 srtp_err_status_socket_err = 16, /**< error in use of socket */ 185 srtp_err_status_signal_err = 17, /**< error in use POSIX signals */ 186 srtp_err_status_nonce_bad = 18, /**< nonce check failed */ 187 srtp_err_status_read_fail = 19, /**< couldn't read data */ 188 srtp_err_status_write_fail = 20, /**< couldn't write data */ 189 srtp_err_status_parse_err = 21, /**< error parsing data */ 190 srtp_err_status_encode_err = 22, /**< error encoding data */ 191 srtp_err_status_semaphore_err = 23, /**< error while using semaphores */ 192 srtp_err_status_pfkey_err = 24, /**< error while using pfkey */ 193 srtp_err_status_bad_mki = 25, /**< error MKI present in packet is */ 194 /**< invalid */ 195 srtp_err_status_pkt_idx_old = 26, /**< packet index is too old to */ 196 /**< consider */ 197 srtp_err_status_pkt_idx_adv = 27 /**< packet index advanced, reset */ 198 /**< needed */ 199 } srtp_err_status_t; 200 201 typedef struct srtp_ctx_t_ srtp_ctx_t; 202 203 /** 204 * @brief srtp_sec_serv_t describes a set of security services. 205 * 206 * A srtp_sec_serv_t enumeration is used to describe the particular 207 * security services that will be applied by a particular crypto 208 * policy (or other mechanism). 209 */ 210 typedef enum { 211 sec_serv_none = 0, /**< no services */ 212 sec_serv_conf = 1, /**< confidentiality */ 213 sec_serv_auth = 2, /**< authentication */ 214 sec_serv_conf_and_auth = 3 /**< confidentiality and authentication */ 215 } srtp_sec_serv_t; 216 217 /** 218 * @brief srtp_crypto_policy_t describes a particular crypto policy that 219 * can be applied to an SRTP stream. 220 * 221 * A srtp_crypto_policy_t describes a particular cryptographic policy that 222 * can be applied to an SRTP or SRTCP stream. An SRTP session policy 223 * consists of a list of these policies, one for each SRTP stream 224 * in the session. 225 */ 226 typedef struct srtp_crypto_policy_t { 227 srtp_cipher_type_id_t cipher_type; /**< An integer representing */ 228 /**< the type of cipher. */ 229 int cipher_key_len; /**< The length of the cipher key */ 230 /**< in octets. */ 231 srtp_auth_type_id_t auth_type; /**< An integer representing the */ 232 /**< authentication function. */ 233 int auth_key_len; /**< The length of the authentication */ 234 /**< function key in octets. */ 235 int auth_tag_len; /**< The length of the authentication */ 236 /**< tag in octets. */ 237 srtp_sec_serv_t sec_serv; /**< The flag indicating the security */ 238 /**< services to be applied. */ 239 } srtp_crypto_policy_t; 240 241 /** 242 * @brief srtp_ssrc_type_t describes the type of an SSRC. 243 * 244 * An srtp_ssrc_type_t enumeration is used to indicate a type of SSRC. See 245 * @ref srtp_policy_t for more informataion. 246 */ 247 typedef enum { 248 ssrc_undefined = 0, /**< Indicates an undefined SSRC type. */ 249 ssrc_specific = 1, /**< Indicates a specific SSRC value */ 250 ssrc_any_inbound = 2, /**< Indicates any inbound SSRC value */ 251 /**< (i.e. a value that is used in the */ 252 /**< function srtp_unprotect()) */ 253 ssrc_any_outbound = 3 /**< Indicates any outbound SSRC value */ 254 /**< (i.e. a value that is used in the */ 255 /**< function srtp_protect()) */ 256 } srtp_ssrc_type_t; 257 258 /** 259 * @brief An srtp_ssrc_t represents a particular SSRC value, or a `wildcard' 260 * SSRC. 261 * 262 * An srtp_ssrc_t represents a particular SSRC value (if its type is 263 * ssrc_specific), or a wildcard SSRC value that will match all 264 * outbound SSRCs (if its type is ssrc_any_outbound) or all inbound 265 * SSRCs (if its type is ssrc_any_inbound). 266 */ 267 typedef struct { 268 srtp_ssrc_type_t type; /**< The type of this particular SSRC */ 269 unsigned int value; /**< The value of this SSRC, if it is not a */ 270 /**< wildcard */ 271 } srtp_ssrc_t; 272 273 /** 274 * @brief points to an EKT policy 275 */ 276 typedef struct srtp_ekt_policy_ctx_t *srtp_ekt_policy_t; 277 278 /** 279 * @brief points to EKT stream data 280 */ 281 typedef struct srtp_ekt_stream_ctx_t *srtp_ekt_stream_t; 282 283 /** 284 * @brief srtp_master_key_t represents a master key. There will 285 * be a Master Key Index and the Master Key associated with the 286 * Master Key Index. Need to also keep track of the Master Key 287 * Index Size to correctly read it from a packet. 288 */ 289 typedef struct srtp_master_key_t { 290 unsigned char *key; 291 unsigned char *mki_id; 292 unsigned int mki_size; 293 } srtp_master_key_t; 294 295 /** 296 * @brief represents the policy for an SRTP session. 297 * 298 * A single srtp_policy_t struct represents the policy for a single 299 * SRTP stream, and a linked list of these elements represents the 300 * policy for an entire SRTP session. Each element contains the SRTP 301 * and SRTCP crypto policies for that stream, a pointer to the SRTP 302 * master key for that stream, the SSRC describing that stream, or a 303 * flag indicating a `wildcard' SSRC value, and a `next' field that 304 * holds a pointer to the next element in the list of policy elements, 305 * or NULL if it is the last element. 306 * 307 * The wildcard value SSRC_ANY_INBOUND matches any SSRC from an 308 * inbound stream that for which there is no explicit SSRC entry in 309 * another policy element. Similarly, the value SSRC_ANY_OUTBOUND 310 * will matches any SSRC from an outbound stream that does not appear 311 * in another policy element. Note that wildcard SSRCs &b cannot be 312 * used to match both inbound and outbound traffic. This restriction 313 * is intentional, and it allows libSRTP to ensure that no security 314 * lapses result from accidental re-use of SSRC values during key 315 * sharing. 316 * 317 * @warning The final element of the list @b must have its `next' pointer 318 * set to NULL. 319 */ 320 321 typedef struct srtp_policy_t { 322 srtp_ssrc_t ssrc; /**< The SSRC value of stream, or the */ 323 /**< flags SSRC_ANY_INBOUND or */ 324 /**< SSRC_ANY_OUTBOUND if key sharing */ 325 /**< is used for this policy element. */ 326 srtp_crypto_policy_t rtp; /**< SRTP crypto policy. */ 327 srtp_crypto_policy_t rtcp; /**< SRTCP crypto policy. */ 328 unsigned char *key; /**< Pointer to the SRTP master key for */ 329 /**< this stream. */ 330 srtp_master_key_t **keys; /** Array of Master Key structures */ 331 unsigned long num_master_keys; /** Number of master keys */ 332 srtp_ekt_policy_t ekt; /**< Pointer to the EKT policy structure */ 333 /**< for this stream (if any) */ 334 unsigned long window_size; /**< The window size to use for replay */ 335 /**< protection. */ 336 int allow_repeat_tx; /**< Whether retransmissions of */ 337 /**< packets with the same sequence */ 338 /**< number are allowed. */ 339 /**< (Note that such repeated */ 340 /**< transmissions must have the same */ 341 /**< RTP payload, or a severe security */ 342 /**< weakness is introduced!) */ 343 int *enc_xtn_hdr; /**< List of header ids to encrypt. */ 344 int enc_xtn_hdr_count; /**< Number of entries in list of header */ 345 /**< ids. */ 346 struct srtp_policy_t *next; /**< Pointer to next stream policy. */ 347 } srtp_policy_t; 348 349 /** 350 * @brief An srtp_t points to an SRTP session structure. 351 * 352 * The typedef srtp_t is a pointer to a structure that represents 353 * an SRTP session. This datatype is intentially opaque in 354 * order to separate the interface from the implementation. 355 * 356 * An SRTP session consists of all of the traffic sent to the RTP and 357 * RTCP destination transport addresses, using the RTP/SAVP (Secure 358 * Audio/Video Profile). A session can be viewed as a set of SRTP 359 * streams, each of which originates with a different participant. 360 */ 361 typedef srtp_ctx_t *srtp_t; 362 363 /** 364 * @brief srtp_init() initializes the srtp library. 365 * 366 * @warning This function @b must be called before any other srtp 367 * functions. 368 */ 369 srtp_err_status_t srtp_init(void); 370 371 /** 372 * @brief srtp_shutdown() de-initializes the srtp library. 373 * 374 * @warning No srtp functions may be called after calling this function. 375 */ 376 srtp_err_status_t srtp_shutdown(void); 377 378 /** 379 * @brief srtp_protect() is the Secure RTP sender-side packet processing 380 * function. 381 * 382 * The function call srtp_protect(ctx, rtp_hdr, len_ptr) applies SRTP 383 * protection to the RTP packet rtp_hdr (which has length *len_ptr) using 384 * the SRTP context ctx. If srtp_err_status_ok is returned, then rtp_hdr 385 * points to the resulting SRTP packet and *len_ptr is the number of 386 * octets in that packet; otherwise, no assumptions should be made 387 * about the value of either data elements. 388 * 389 * The sequence numbers of the RTP packets presented to this function 390 * need not be consecutive, but they @b must be out of order by less 391 * than 2^15 = 32,768 packets. 392 * 393 * @warning This function assumes that it can write the authentication 394 * tag into the location in memory immediately following the RTP 395 * packet, and assumes that the RTP packet is aligned on a 32-bit 396 * boundary. 397 * 398 * @warning This function assumes that it can write SRTP_MAX_TRAILER_LEN 399 * into the location in memory immediately following the RTP packet. 400 * Callers MUST ensure that this much writable memory is available in 401 * the buffer that holds the RTP packet. 402 * 403 * @param ctx is the SRTP context to use in processing the packet. 404 * 405 * @param rtp_hdr is a pointer to the RTP packet (before the call); after 406 * the function returns, it points to the srtp packet. 407 * 408 * @param len_ptr is a pointer to the length in octets of the complete 409 * RTP packet (header and body) before the function call, and of the 410 * complete SRTP packet after the call, if srtp_err_status_ok was returned. 411 * Otherwise, the value of the data to which it points is undefined. 412 * 413 * @return 414 * - srtp_err_status_ok no problems 415 * - srtp_err_status_replay_fail rtp sequence number was non-increasing 416 * - @e other failure in cryptographic mechanisms 417 */ 418 srtp_err_status_t srtp_protect(srtp_t ctx, void *rtp_hdr, int *len_ptr); 419 420 /** 421 * @brief srtp_protect_mki() is the Secure RTP sender-side packet processing 422 * function that can utilize MKI. 423 * 424 * The function call srtp_protect(ctx, rtp_hdr, len_ptr) applies SRTP 425 * protection to the RTP packet rtp_hdr (which has length *len_ptr) using 426 * the SRTP context ctx. If srtp_err_status_ok is returned, then rtp_hdr 427 * points to the resulting SRTP packet and *len_ptr is the number of 428 * octets in that packet; otherwise, no assumptions should be made 429 * about the value of either data elements. 430 * 431 * The sequence numbers of the RTP packets presented to this function 432 * need not be consecutive, but they @b must be out of order by less 433 * than 2^15 = 32,768 packets. 434 * 435 * @warning This function assumes that it can write the authentication 436 * tag into the location in memory immediately following the RTP 437 * packet, and assumes that the RTP packet is aligned on a 32-bit 438 * boundary. 439 * 440 * @warning This function assumes that it can write SRTP_MAX_TRAILER_LEN 441 * into the location in memory immediately following the RTP packet. 442 * Callers MUST ensure that this much writable memory is available in 443 * the buffer that holds the RTP packet. 444 * 445 * @param ctx is the SRTP context to use in processing the packet. 446 * 447 * @param rtp_hdr is a pointer to the RTP packet (before the call); after 448 * the function returns, it points to the srtp packet. 449 * 450 * @param pkt_octet_len is a pointer to the length in octets of the complete 451 * RTP packet (header and body) before the function call, and of the 452 * complete SRTP packet after the call, if srtp_err_status_ok was returned. 453 * Otherwise, the value of the data to which it points is undefined. 454 * 455 * @param use_mki is a boolean to tell the system if mki is being used. If 456 * set to false then will use the first set of session keys. If set to true 457 * will 458 * use the session keys identified by the mki_index 459 * 460 * @param mki_index integer value specifying which set of session keys should be 461 * used if use_mki is set to true. 462 * 463 * @return 464 * - srtp_err_status_ok no problems 465 * - srtp_err_status_replay_fail rtp sequence number was non-increasing 466 * - @e other failure in cryptographic mechanisms 467 */ 468 srtp_err_status_t srtp_protect_mki(srtp_ctx_t *ctx, 469 void *rtp_hdr, 470 int *pkt_octet_len, 471 unsigned int use_mki, 472 unsigned int mki_index); 473 474 /** 475 * @brief srtp_unprotect() is the Secure RTP receiver-side packet 476 * processing function. 477 * 478 * The function call srtp_unprotect(ctx, srtp_hdr, len_ptr) verifies 479 * the Secure RTP protection of the SRTP packet pointed to by srtp_hdr 480 * (which has length *len_ptr), using the SRTP context ctx. If 481 * srtp_err_status_ok is returned, then srtp_hdr points to the resulting 482 * RTP packet and *len_ptr is the number of octets in that packet; 483 * otherwise, no assumptions should be made about the value of either 484 * data elements. 485 * 486 * The sequence numbers of the RTP packets presented to this function 487 * need not be consecutive, but they @b must be out of order by less 488 * than 2^15 = 32,768 packets. 489 * 490 * @warning This function assumes that the SRTP packet is aligned on a 491 * 32-bit boundary. 492 * 493 * @param ctx is the SRTP session which applies to the particular packet. 494 * 495 * @param srtp_hdr is a pointer to the header of the SRTP packet 496 * (before the call). after the function returns, it points to the 497 * rtp packet if srtp_err_status_ok was returned; otherwise, the value of 498 * the data to which it points is undefined. 499 * 500 * @param len_ptr is a pointer to the length in octets of the complete 501 * srtp packet (header and body) before the function call, and of the 502 * complete rtp packet after the call, if srtp_err_status_ok was returned. 503 * Otherwise, the value of the data to which it points is undefined. 504 * 505 * @return 506 * - srtp_err_status_ok if the RTP packet is valid. 507 * - srtp_err_status_auth_fail if the SRTP packet failed the message 508 * authentication check. 509 * - srtp_err_status_replay_fail if the SRTP packet is a replay (e.g. packet 510 * has already been processed and accepted). 511 * - [other] if there has been an error in the cryptographic mechanisms. 512 * 513 */ 514 srtp_err_status_t srtp_unprotect(srtp_t ctx, void *srtp_hdr, int *len_ptr); 515 516 /** 517 * @brief srtp_unprotect_mki() is the Secure RTP receiver-side packet 518 * processing function that checks for MKI. 519 * 520 * The function call srtp_unprotect(ctx, srtp_hdr, len_ptr) verifies 521 * the Secure RTP protection of the SRTP packet pointed to by srtp_hdr 522 * (which has length *len_ptr), using the SRTP context ctx. If 523 * srtp_err_status_ok is returned, then srtp_hdr points to the resulting 524 * RTP packet and *len_ptr is the number of octets in that packet; 525 * otherwise, no assumptions should be made about the value of either 526 * data elements. 527 * 528 * The sequence numbers of the RTP packets presented to this function 529 * need not be consecutive, but they @b must be out of order by less 530 * than 2^15 = 32,768 packets. 531 * 532 * @warning This function assumes that the SRTP packet is aligned on a 533 * 32-bit boundary. 534 * 535 * @param ctx is the SRTP session which applies to the particular packet. 536 * 537 * @param srtp_hdr is a pointer to the header of the SRTP packet 538 * (before the call). after the function returns, it points to the 539 * rtp packet if srtp_err_status_ok was returned; otherwise, the value of 540 * the data to which it points is undefined. 541 * 542 * @param len_ptr is a pointer to the length in octets of the complete 543 * srtp packet (header and body) before the function call, and of the 544 * complete rtp packet after the call, if srtp_err_status_ok was returned. 545 * Otherwise, the value of the data to which it points is undefined. 546 * 547 * @param use_mki is a boolean to tell the system if mki is being used. If 548 * set to false then will use the first set of session keys. If set to true 549 * will 550 * use the session keys identified by the mki_index 551 * 552 * @return 553 * - srtp_err_status_ok if the RTP packet is valid. 554 * - srtp_err_status_auth_fail if the SRTP packet failed the message 555 * authentication check. 556 * - srtp_err_status_replay_fail if the SRTP packet is a replay (e.g. packet 557 * has already been processed and accepted). 558 * - srtp_err_status_bad_mki if the MKI in the packet is not a known MKI id 559 * - [other] if there has been an error in the cryptographic mechanisms. 560 * 561 */ 562 srtp_err_status_t srtp_unprotect_mki(srtp_t ctx, 563 void *srtp_hdr, 564 int *len_ptr, 565 unsigned int use_mki); 566 567 /** 568 * @brief srtp_create() allocates and initializes an SRTP session. 569 570 * The function call srtp_create(session, policy) allocates and 571 * initializes an SRTP session context, applying the given policy. 572 * 573 * @param session is a pointer to the SRTP session to which the policy is 574 * to be added. 575 * 576 * @param policy is the srtp_policy_t struct that describes the policy 577 * for the session. The struct may be a single element, or it may be 578 * the head of a list, in which case each element of the list is 579 * processed. It may also be NULL, in which case streams should be added 580 * later using srtp_add_stream(). The final element of the list @b must 581 * have its `next' field set to NULL. 582 * 583 * @return 584 * - srtp_err_status_ok if creation succeded. 585 * - srtp_err_status_alloc_fail if allocation failed. 586 * - srtp_err_status_init_fail if initialization failed. 587 */ 588 srtp_err_status_t srtp_create(srtp_t *session, const srtp_policy_t *policy); 589 590 /** 591 * @brief srtp_add_stream() allocates and initializes an SRTP stream 592 * within a given SRTP session. 593 * 594 * The function call srtp_add_stream(session, policy) allocates and 595 * initializes a new SRTP stream within a given, previously created 596 * session, applying the policy given as the other argument to that 597 * stream. 598 * 599 * @return values: 600 * - srtp_err_status_ok if stream creation succeded. 601 * - srtp_err_status_alloc_fail if stream allocation failed 602 * - srtp_err_status_init_fail if stream initialization failed. 603 */ 604 srtp_err_status_t srtp_add_stream(srtp_t session, const srtp_policy_t *policy); 605 606 /** 607 * @brief srtp_remove_stream() deallocates an SRTP stream. 608 * 609 * The function call srtp_remove_stream(session, ssrc) removes 610 * the SRTP stream with the SSRC value ssrc from the SRTP session 611 * context given by the argument session. 612 * 613 * @param session is the SRTP session from which the stream 614 * will be removed. 615 * 616 * @param ssrc is the SSRC value of the stream to be removed 617 * in network byte order. 618 * 619 * @warning Wildcard SSRC values cannot be removed from a 620 * session. 621 * 622 * @return 623 * - srtp_err_status_ok if the stream deallocation succeded. 624 * - [other] otherwise. 625 * 626 */ 627 srtp_err_status_t srtp_remove_stream(srtp_t session, unsigned int ssrc); 628 629 /** 630 * @brief srtp_update() udpates all streams in the session. 631 * 632 * The function call srtp_update(session, policy) updates 633 * all the streams in the session applying the given policy 634 * and key. The exsisting ROC value of all streams will be 635 * preserved. 636 * 637 * @param session is the SRTP session that contains the streams 638 * to be updated. 639 * 640 * @param policy is the srtp_policy_t struct that describes the policy 641 * for the session. The struct may be a single element, or it may be 642 * the head of a list, in which case each element of the list is 643 * processed. The final element of the list @b must 644 * have its `next' field set to NULL. 645 * 646 * @return 647 * - srtp_err_status_ok if stream creation succeded. 648 * - srtp_err_status_alloc_fail if stream allocation failed 649 * - srtp_err_status_init_fail if stream initialization failed. 650 * - [other] otherwise. 651 * 652 */ 653 srtp_err_status_t srtp_update(srtp_t session, const srtp_policy_t *policy); 654 655 /** 656 * @brief srtp_update_stream() udpates a SRTP stream. 657 * 658 * The function call srtp_update_stream(session, policy) updates 659 * the stream(s) in the session that match applying the given 660 * policy and key. The exsisting ROC value of all stream(s) will 661 * be preserved. 662 * 663 * @param session is the SRTP session that contains the streams 664 * to be updated. 665 * 666 * @param policy is the srtp_policy_t struct that describes the policy 667 * for the session. 668 * 669 * @return 670 * - srtp_err_status_ok if stream creation succeded. 671 * - srtp_err_status_alloc_fail if stream allocation failed 672 * - srtp_err_status_init_fail if stream initialization failed. 673 * - [other] otherwise. 674 * 675 */ 676 srtp_err_status_t srtp_update_stream(srtp_t session, 677 const srtp_policy_t *policy); 678 679 /** 680 * @brief srtp_crypto_policy_set_rtp_default() sets a crypto policy 681 * structure to the SRTP default policy for RTP protection. 682 * 683 * @param p is a pointer to the policy structure to be set 684 * 685 * The function call srtp_crypto_policy_set_rtp_default(&p) sets the 686 * srtp_crypto_policy_t at location p to the SRTP default policy for RTP 687 * protection, as defined in the specification. This function is a 688 * convenience that helps to avoid dealing directly with the policy 689 * data structure. You are encouraged to initialize policy elements 690 * with this function call. Doing so may allow your code to be 691 * forward compatible with later versions of libSRTP that include more 692 * elements in the srtp_crypto_policy_t datatype. 693 * 694 * @return void. 695 * 696 */ 697 void srtp_crypto_policy_set_rtp_default(srtp_crypto_policy_t *p); 698 699 /** 700 * @brief srtp_crypto_policy_set_rtcp_default() sets a crypto policy 701 * structure to the SRTP default policy for RTCP protection. 702 * 703 * @param p is a pointer to the policy structure to be set 704 * 705 * The function call srtp_crypto_policy_set_rtcp_default(&p) sets the 706 * srtp_crypto_policy_t at location p to the SRTP default policy for RTCP 707 * protection, as defined in the specification. This function is a 708 * convenience that helps to avoid dealing directly with the policy 709 * data structure. You are encouraged to initialize policy elements 710 * with this function call. Doing so may allow your code to be 711 * forward compatible with later versions of libSRTP that include more 712 * elements in the srtp_crypto_policy_t datatype. 713 * 714 * @return void. 715 * 716 */ 717 void srtp_crypto_policy_set_rtcp_default(srtp_crypto_policy_t *p); 718 719 /** 720 * @brief srtp_crypto_policy_set_aes_cm_128_hmac_sha1_80() sets a crypto 721 * policy structure to the SRTP default policy for RTP protection. 722 * 723 * @param p is a pointer to the policy structure to be set 724 * 725 * The function srtp_crypto_policy_set_aes_cm_128_hmac_sha1_80() is a 726 * synonym for srtp_crypto_policy_set_rtp_default(). It conforms to the 727 * naming convention used in RFC 4568 (SDP Security Descriptions for 728 * Media Streams). 729 * 730 * @return void. 731 * 732 */ 733 #define srtp_crypto_policy_set_aes_cm_128_hmac_sha1_80(p) \ 734 srtp_crypto_policy_set_rtp_default(p) 735 736 /** 737 * @brief srtp_crypto_policy_set_aes_cm_128_hmac_sha1_32() sets a crypto 738 * policy structure to a short-authentication tag policy 739 * 740 * @param p is a pointer to the policy structure to be set 741 * 742 * The function call srtp_crypto_policy_set_aes_cm_128_hmac_sha1_32(&p) 743 * sets the srtp_crypto_policy_t at location p to use policy 744 * AES_CM_128_HMAC_SHA1_32 as defined in RFC 4568. 745 * This policy uses AES-128 746 * Counter Mode encryption and HMAC-SHA1 authentication, with an 747 * authentication tag that is only 32 bits long. This length is 748 * considered adequate only for protecting audio and video media that 749 * use a stateless playback function. See Section 7.5 of RFC 3711 750 * (http://www.ietf.org/rfc/rfc3711.txt). 751 * 752 * This function is a convenience that helps to avoid dealing directly 753 * with the policy data structure. You are encouraged to initialize 754 * policy elements with this function call. Doing so may allow your 755 * code to be forward compatible with later versions of libSRTP that 756 * include more elements in the srtp_crypto_policy_t datatype. 757 * 758 * @warning This crypto policy is intended for use in SRTP, but not in 759 * SRTCP. It is recommended that a policy that uses longer 760 * authentication tags be used for SRTCP. See Section 7.5 of RFC 3711 761 * (http://www.ietf.org/rfc/rfc3711.txt). 762 * 763 * @return void. 764 * 765 */ 766 void srtp_crypto_policy_set_aes_cm_128_hmac_sha1_32(srtp_crypto_policy_t *p); 767 768 /** 769 * @brief srtp_crypto_policy_set_aes_cm_128_null_auth() sets a crypto 770 * policy structure to an encryption-only policy 771 * 772 * @param p is a pointer to the policy structure to be set 773 * 774 * The function call srtp_crypto_policy_set_aes_cm_128_null_auth(&p) sets 775 * the srtp_crypto_policy_t at location p to use the SRTP default cipher 776 * (AES-128 Counter Mode), but to use no authentication method. This 777 * policy is NOT RECOMMENDED unless it is unavoidable; see Section 7.5 778 * of RFC 3711 (http://www.ietf.org/rfc/rfc3711.txt). 779 * 780 * This function is a convenience that helps to avoid dealing directly 781 * with the policy data structure. You are encouraged to initialize 782 * policy elements with this function call. Doing so may allow your 783 * code to be forward compatible with later versions of libSRTP that 784 * include more elements in the srtp_crypto_policy_t datatype. 785 * 786 * @warning This policy is NOT RECOMMENDED for SRTP unless it is 787 * unavoidable, and it is NOT RECOMMENDED at all for SRTCP; see 788 * Section 7.5 of RFC 3711 (http://www.ietf.org/rfc/rfc3711.txt). 789 * 790 * @return void. 791 * 792 */ 793 void srtp_crypto_policy_set_aes_cm_128_null_auth(srtp_crypto_policy_t *p); 794 795 /** 796 * @brief srtp_crypto_policy_set_null_cipher_hmac_sha1_80() sets a crypto 797 * policy structure to an authentication-only policy 798 * 799 * @param p is a pointer to the policy structure to be set 800 * 801 * The function call srtp_crypto_policy_set_null_cipher_hmac_sha1_80(&p) 802 * sets the srtp_crypto_policy_t at location p to use HMAC-SHA1 with an 80 803 * bit authentication tag to provide message authentication, but to 804 * use no encryption. This policy is NOT RECOMMENDED for SRTP unless 805 * there is a requirement to forego encryption. 806 * 807 * This function is a convenience that helps to avoid dealing directly 808 * with the policy data structure. You are encouraged to initialize 809 * policy elements with this function call. Doing so may allow your 810 * code to be forward compatible with later versions of libSRTP that 811 * include more elements in the srtp_crypto_policy_t datatype. 812 * 813 * @warning This policy is NOT RECOMMENDED for SRTP unless there is a 814 * requirement to forego encryption. 815 * 816 * @return void. 817 * 818 */ 819 void srtp_crypto_policy_set_null_cipher_hmac_sha1_80(srtp_crypto_policy_t *p); 820 821 /** 822 * @brief srtp_crypto_policy_set_null_cipher_hmac_null() sets a crypto 823 * policy structure to use no encryption or authentication. 824 * 825 * @param p is a pointer to the policy structure to be set 826 * 827 * The function call srtp_crypto_policy_set_null_cipher_hmac_null(&p) 828 * sets the srtp_crypto_policy_t at location p to use no encryption and 829 * no authentication. This policy should only be used for testing and 830 * troubleshootingl. 831 * 832 * This function is a convenience that helps to avoid dealing directly 833 * with the policy data structure. You are encouraged to initialize 834 * policy elements with this function call. Doing so may allow your 835 * code to be forward compatible with later versions of libSRTP that 836 * include more elements in the srtp_crypto_policy_t datatype. 837 * 838 * @warning This policy is NOT RECOMMENDED for SRTP unless there is a 839 * requirement to forego encryption and authentication. 840 * 841 * @return void. 842 * 843 */ 844 void srtp_crypto_policy_set_null_cipher_hmac_null(srtp_crypto_policy_t *p); 845 846 /** 847 * @brief srtp_crypto_policy_set_aes_cm_256_hmac_sha1_80() sets a crypto 848 * policy structure to a encryption and authentication policy using AES-256 849 * for RTP protection. 850 * 851 * @param p is a pointer to the policy structure to be set 852 * 853 * The function call srtp_crypto_policy_set_aes_cm_256_hmac_sha1_80(&p) 854 * sets the srtp_crypto_policy_t at location p to use policy 855 * AES_CM_256_HMAC_SHA1_80 as defined in RFC 6188. This policy uses AES-256 856 * Counter Mode encryption and HMAC-SHA1 authentication, with an 80 bit 857 * authentication tag. 858 * 859 * This function is a convenience that helps to avoid dealing directly 860 * with the policy data structure. You are encouraged to initialize 861 * policy elements with this function call. Doing so may allow your 862 * code to be forward compatible with later versions of libSRTP that 863 * include more elements in the srtp_crypto_policy_t datatype. 864 * 865 * @return void. 866 * 867 */ 868 void srtp_crypto_policy_set_aes_cm_256_hmac_sha1_80(srtp_crypto_policy_t *p); 869 870 /** 871 * @brief srtp_crypto_policy_set_aes_cm_256_hmac_sha1_32() sets a crypto 872 * policy structure to a short-authentication tag policy using AES-256 873 * encryption. 874 * 875 * @param p is a pointer to the policy structure to be set 876 * 877 * The function call srtp_crypto_policy_set_aes_cm_256_hmac_sha1_32(&p) 878 * sets the srtp_crypto_policy_t at location p to use policy 879 * AES_CM_256_HMAC_SHA1_32 as defined in RFC 6188. This policy uses AES-256 880 * Counter Mode encryption and HMAC-SHA1 authentication, with an 881 * authentication tag that is only 32 bits long. This length is 882 * considered adequate only for protecting audio and video media that 883 * use a stateless playback function. See Section 7.5 of RFC 3711 884 * (http://www.ietf.org/rfc/rfc3711.txt). 885 * 886 * This function is a convenience that helps to avoid dealing directly 887 * with the policy data structure. You are encouraged to initialize 888 * policy elements with this function call. Doing so may allow your 889 * code to be forward compatible with later versions of libSRTP that 890 * include more elements in the srtp_crypto_policy_t datatype. 891 * 892 * @warning This crypto policy is intended for use in SRTP, but not in 893 * SRTCP. It is recommended that a policy that uses longer 894 * authentication tags be used for SRTCP. See Section 7.5 of RFC 3711 895 * (http://www.ietf.org/rfc/rfc3711.txt). 896 * 897 * @return void. 898 * 899 */ 900 void srtp_crypto_policy_set_aes_cm_256_hmac_sha1_32(srtp_crypto_policy_t *p); 901 902 /** 903 * @brief srtp_crypto_policy_set_aes_cm_256_null_auth() sets a crypto 904 * policy structure to an encryption-only policy 905 * 906 * @param p is a pointer to the policy structure to be set 907 * 908 * The function call srtp_crypto_policy_set_aes_cm_256_null_auth(&p) sets 909 * the srtp_crypto_policy_t at location p to use the SRTP default cipher 910 * (AES-256 Counter Mode), but to use no authentication method. This 911 * policy is NOT RECOMMENDED unless it is unavoidable; see Section 7.5 912 * of RFC 3711 (http://www.ietf.org/rfc/rfc3711.txt). 913 * 914 * This function is a convenience that helps to avoid dealing directly 915 * with the policy data structure. You are encouraged to initialize 916 * policy elements with this function call. Doing so may allow your 917 * code to be forward compatible with later versions of libSRTP that 918 * include more elements in the srtp_crypto_policy_t datatype. 919 * 920 * @warning This policy is NOT RECOMMENDED for SRTP unless it is 921 * unavoidable, and it is NOT RECOMMENDED at all for SRTCP; see 922 * Section 7.5 of RFC 3711 (http://www.ietf.org/rfc/rfc3711.txt). 923 * 924 * @return void. 925 * 926 */ 927 void srtp_crypto_policy_set_aes_cm_256_null_auth(srtp_crypto_policy_t *p); 928 929 /** 930 * @brief srtp_crypto_policy_set_aes_cm_192_hmac_sha1_80() sets a crypto 931 * policy structure to a encryption and authentication policy using AES-192 932 * for RTP protection. 933 * 934 * @param p is a pointer to the policy structure to be set 935 * 936 * The function call srtp_crypto_policy_set_aes_cm_192_hmac_sha1_80(&p) 937 * sets the srtp_crypto_policy_t at location p to use policy 938 * AES_CM_192_HMAC_SHA1_80 as defined in RFC 6188. This policy uses AES-192 939 * Counter Mode encryption and HMAC-SHA1 authentication, with an 80 bit 940 * authentication tag. 941 * 942 * This function is a convenience that helps to avoid dealing directly 943 * with the policy data structure. You are encouraged to initialize 944 * policy elements with this function call. Doing so may allow your 945 * code to be forward compatible with later versions of libSRTP that 946 * include more elements in the srtp_crypto_policy_t datatype. 947 * 948 * @return void. 949 * 950 */ 951 void srtp_crypto_policy_set_aes_cm_192_hmac_sha1_80(srtp_crypto_policy_t *p); 952 953 /** 954 * @brief srtp_crypto_policy_set_aes_cm_192_hmac_sha1_32() sets a crypto 955 * policy structure to a short-authentication tag policy using AES-192 956 * encryption. 957 * 958 * @param p is a pointer to the policy structure to be set 959 * 960 * The function call srtp_crypto_policy_set_aes_cm_192_hmac_sha1_32(&p) 961 * sets the srtp_crypto_policy_t at location p to use policy 962 * AES_CM_192_HMAC_SHA1_32 as defined in RFC 6188. This policy uses AES-192 963 * Counter Mode encryption and HMAC-SHA1 authentication, with an 964 * authentication tag that is only 32 bits long. This length is 965 * considered adequate only for protecting audio and video media that 966 * use a stateless playback function. See Section 7.5 of RFC 3711 967 * (http://www.ietf.org/rfc/rfc3711.txt). 968 * 969 * This function is a convenience that helps to avoid dealing directly 970 * with the policy data structure. You are encouraged to initialize 971 * policy elements with this function call. Doing so may allow your 972 * code to be forward compatible with later versions of libSRTP that 973 * include more elements in the srtp_crypto_policy_t datatype. 974 * 975 * @warning This crypto policy is intended for use in SRTP, but not in 976 * SRTCP. It is recommended that a policy that uses longer 977 * authentication tags be used for SRTCP. See Section 7.5 of RFC 3711 978 * (http://www.ietf.org/rfc/rfc3711.txt). 979 * 980 * @return void. 981 * 982 */ 983 void srtp_crypto_policy_set_aes_cm_192_hmac_sha1_32(srtp_crypto_policy_t *p); 984 985 /** 986 * @brief srtp_crypto_policy_set_aes_cm_192_null_auth() sets a crypto 987 * policy structure to an encryption-only policy 988 * 989 * @param p is a pointer to the policy structure to be set 990 * 991 * The function call srtp_crypto_policy_set_aes_cm_192_null_auth(&p) sets 992 * the srtp_crypto_policy_t at location p to use the SRTP default cipher 993 * (AES-192 Counter Mode), but to use no authentication method. This 994 * policy is NOT RECOMMENDED unless it is unavoidable; see Section 7.5 995 * of RFC 3711 (http://www.ietf.org/rfc/rfc3711.txt). 996 * 997 * This function is a convenience that helps to avoid dealing directly 998 * with the policy data structure. You are encouraged to initialize 999 * policy elements with this function call. Doing so may allow your 1000 * code to be forward compatible with later versions of libSRTP that 1001 * include more elements in the srtp_crypto_policy_t datatype. 1002 * 1003 * @warning This policy is NOT RECOMMENDED for SRTP unless it is 1004 * unavoidable, and it is NOT RECOMMENDED at all for SRTCP; see 1005 * Section 7.5 of RFC 3711 (http://www.ietf.org/rfc/rfc3711.txt). 1006 * 1007 * @return void. 1008 * 1009 */ 1010 void srtp_crypto_policy_set_aes_cm_192_null_auth(srtp_crypto_policy_t *p); 1011 1012 /** 1013 * @brief srtp_crypto_policy_set_aes_gcm_128_8_auth() sets a crypto 1014 * policy structure to an AEAD encryption policy. 1015 * 1016 * @param p is a pointer to the policy structure to be set 1017 * 1018 * The function call srtp_crypto_policy_set_aes_gcm_128_8_auth(&p) sets 1019 * the srtp_crypto_policy_t at location p to use the SRTP default cipher 1020 * (AES-128 Galois Counter Mode) with 8 octet auth tag. This 1021 * policy applies confidentiality and authentication to both the 1022 * RTP and RTCP packets. 1023 * 1024 * This function is a convenience that helps to avoid dealing directly 1025 * with the policy data structure. You are encouraged to initialize 1026 * policy elements with this function call. Doing so may allow your 1027 * code to be forward compatible with later versions of libSRTP that 1028 * include more elements in the srtp_crypto_policy_t datatype. 1029 * 1030 * @return void. 1031 * 1032 */ 1033 void srtp_crypto_policy_set_aes_gcm_128_8_auth(srtp_crypto_policy_t *p); 1034 1035 /** 1036 * @brief srtp_crypto_policy_set_aes_gcm_256_8_auth() sets a crypto 1037 * policy structure to an AEAD encryption policy 1038 * 1039 * @param p is a pointer to the policy structure to be set 1040 * 1041 * The function call srtp_crypto_policy_set_aes_gcm_256_8_auth(&p) sets 1042 * the srtp_crypto_policy_t at location p to use the SRTP default cipher 1043 * (AES-256 Galois Counter Mode) with 8 octet auth tag. This 1044 * policy applies confidentiality and authentication to both the 1045 * RTP and RTCP packets. 1046 * 1047 * This function is a convenience that helps to avoid dealing directly 1048 * with the policy data structure. You are encouraged to initialize 1049 * policy elements with this function call. Doing so may allow your 1050 * code to be forward compatible with later versions of libSRTP that 1051 * include more elements in the srtp_crypto_policy_t datatype. 1052 * 1053 * @return void. 1054 * 1055 */ 1056 void srtp_crypto_policy_set_aes_gcm_256_8_auth(srtp_crypto_policy_t *p); 1057 1058 /** 1059 * @brief srtp_crypto_policy_set_aes_gcm_128_8_only_auth() sets a crypto 1060 * policy structure to an AEAD authentication-only policy 1061 * 1062 * @param p is a pointer to the policy structure to be set 1063 * 1064 * The function call srtp_crypto_policy_set_aes_gcm_128_8_only_auth(&p) sets 1065 * the srtp_crypto_policy_t at location p to use the SRTP default cipher 1066 * (AES-128 Galois Counter Mode) with 8 octet auth tag. This policy 1067 * applies confidentiality and authentication to the RTP packets, 1068 * but only authentication to the RTCP packets. 1069 * 1070 * This function is a convenience that helps to avoid dealing directly 1071 * with the policy data structure. You are encouraged to initialize 1072 * policy elements with this function call. Doing so may allow your 1073 * code to be forward compatible with later versions of libSRTP that 1074 * include more elements in the srtp_crypto_policy_t datatype. 1075 * 1076 * @return void. 1077 * 1078 */ 1079 void srtp_crypto_policy_set_aes_gcm_128_8_only_auth(srtp_crypto_policy_t *p); 1080 1081 /** 1082 * @brief srtp_crypto_policy_set_aes_gcm_256_8_only_auth() sets a crypto 1083 * policy structure to an AEAD authentication-only policy 1084 * 1085 * @param p is a pointer to the policy structure to be set 1086 * 1087 * The function call srtp_crypto_policy_set_aes_gcm_256_8_only_auth(&p) sets 1088 * the srtp_crypto_policy_t at location p to use the SRTP default cipher 1089 * (AES-256 Galois Counter Mode) with 8 octet auth tag. This policy 1090 * applies confidentiality and authentication to the RTP packets, 1091 * but only authentication to the RTCP packets. 1092 * 1093 * This function is a convenience that helps to avoid dealing directly 1094 * with the policy data structure. You are encouraged to initialize 1095 * policy elements with this function call. Doing so may allow your 1096 * code to be forward compatible with later versions of libSRTP that 1097 * include more elements in the srtp_crypto_policy_t datatype. 1098 * 1099 * @return void. 1100 * 1101 */ 1102 void srtp_crypto_policy_set_aes_gcm_256_8_only_auth(srtp_crypto_policy_t *p); 1103 1104 /** 1105 * @brief srtp_crypto_policy_set_aes_gcm_128_16_auth() sets a crypto 1106 * policy structure to an AEAD encryption policy. 1107 * 1108 * @param p is a pointer to the policy structure to be set 1109 * 1110 * The function call srtp_crypto_policy_set_aes_gcm_128_16_auth(&p) sets 1111 * the srtp_crypto_policy_t at location p to use the SRTP default cipher 1112 * (AES-128 Galois Counter Mode) with 16 octet auth tag. This 1113 * policy applies confidentiality and authentication to both the 1114 * RTP and RTCP packets. 1115 * 1116 * This function is a convenience that helps to avoid dealing directly 1117 * with the policy data structure. You are encouraged to initialize 1118 * policy elements with this function call. Doing so may allow your 1119 * code to be forward compatible with later versions of libSRTP that 1120 * include more elements in the srtp_crypto_policy_t datatype. 1121 * 1122 * @return void. 1123 * 1124 */ 1125 void srtp_crypto_policy_set_aes_gcm_128_16_auth(srtp_crypto_policy_t *p); 1126 1127 /** 1128 * @brief srtp_crypto_policy_set_aes_gcm_256_16_auth() sets a crypto 1129 * policy structure to an AEAD encryption policy 1130 * 1131 * @param p is a pointer to the policy structure to be set 1132 * 1133 * The function call srtp_crypto_policy_set_aes_gcm_256_16_auth(&p) sets 1134 * the srtp_crypto_policy_t at location p to use the SRTP default cipher 1135 * (AES-256 Galois Counter Mode) with 16 octet auth tag. This 1136 * policy applies confidentiality and authentication to both the 1137 * RTP and RTCP packets. 1138 * 1139 * This function is a convenience that helps to avoid dealing directly 1140 * with the policy data structure. You are encouraged to initialize 1141 * policy elements with this function call. Doing so may allow your 1142 * code to be forward compatible with later versions of libSRTP that 1143 * include more elements in the srtp_crypto_policy_t datatype. 1144 * 1145 * @return void. 1146 * 1147 */ 1148 void srtp_crypto_policy_set_aes_gcm_256_16_auth(srtp_crypto_policy_t *p); 1149 1150 /** 1151 * @brief srtp_dealloc() deallocates storage for an SRTP session 1152 * context. 1153 * 1154 * The function call srtp_dealloc(s) deallocates storage for the 1155 * SRTP session context s. This function should be called no more 1156 * than one time for each of the contexts allocated by the function 1157 * srtp_create(). 1158 * 1159 * @param s is the srtp_t for the session to be deallocated. 1160 * 1161 * @return 1162 * - srtp_err_status_ok if there no problems. 1163 * - srtp_err_status_dealloc_fail a memory deallocation failure occured. 1164 */ 1165 srtp_err_status_t srtp_dealloc(srtp_t s); 1166 1167 /* 1168 * @brief identifies a particular SRTP profile 1169 * 1170 * An srtp_profile_t enumeration is used to identify a particular SRTP 1171 * profile (that is, a set of algorithms and parameters). These profiles 1172 * are defined for DTLS-SRTP: 1173 * https://www.iana.org/assignments/srtp-protection/srtp-protection.xhtml 1174 */ 1175 typedef enum { 1176 srtp_profile_reserved = 0, 1177 srtp_profile_aes128_cm_sha1_80 = 1, 1178 srtp_profile_aes128_cm_sha1_32 = 2, 1179 srtp_profile_null_sha1_80 = 5, 1180 srtp_profile_null_sha1_32 = 6, 1181 srtp_profile_aead_aes_128_gcm = 7, 1182 srtp_profile_aead_aes_256_gcm = 8, 1183 } srtp_profile_t; 1184 1185 /** 1186 * @brief srtp_crypto_policy_set_from_profile_for_rtp() sets a crypto policy 1187 * structure to the appropriate value for RTP based on an srtp_profile_t 1188 * 1189 * @param policy is a pointer to the policy structure to be set 1190 * 1191 * @param profile is an enumeration for the policy to be set 1192 * 1193 * The function call srtp_crypto_policy_set_rtp_default(&policy, profile) 1194 * sets the srtp_crypto_policy_t at location policy to the policy for RTP 1195 * protection, as defined by the srtp_profile_t profile. 1196 * 1197 * This function is a convenience that helps to avoid dealing directly 1198 * with the policy data structure. You are encouraged to initialize 1199 * policy elements with this function call. Doing so may allow your 1200 * code to be forward compatible with later versions of libSRTP that 1201 * include more elements in the srtp_crypto_policy_t datatype. 1202 * 1203 * @return values 1204 * - srtp_err_status_ok no problems were encountered 1205 * - srtp_err_status_bad_param the profile is not supported 1206 * 1207 */ 1208 srtp_err_status_t srtp_crypto_policy_set_from_profile_for_rtp( 1209 srtp_crypto_policy_t *policy, 1210 srtp_profile_t profile); 1211 1212 /** 1213 * @brief srtp_crypto_policy_set_from_profile_for_rtcp() sets a crypto policy 1214 * structure to the appropriate value for RTCP based on an srtp_profile_t 1215 * 1216 * @param policy is a pointer to the policy structure to be set 1217 * 1218 * @param profile is an enumeration for the policy to be set 1219 * 1220 * The function call srtp_crypto_policy_set_rtcp_default(&policy, profile) 1221 * sets the srtp_crypto_policy_t at location policy to the policy for RTCP 1222 * protection, as defined by the srtp_profile_t profile. 1223 * 1224 * This function is a convenience that helps to avoid dealing directly 1225 * with the policy data structure. You are encouraged to initialize 1226 * policy elements with this function call. Doing so may allow your 1227 * code to be forward compatible with later versions of libSRTP that 1228 * include more elements in the srtp_crypto_policy_t datatype. 1229 * 1230 * @return values 1231 * - srtp_err_status_ok no problems were encountered 1232 * - srtp_err_status_bad_param the profile is not supported 1233 * 1234 */ 1235 srtp_err_status_t srtp_crypto_policy_set_from_profile_for_rtcp( 1236 srtp_crypto_policy_t *policy, 1237 srtp_profile_t profile); 1238 1239 /** 1240 * @brief returns the master key length for a given SRTP profile 1241 */ 1242 unsigned int srtp_profile_get_master_key_length(srtp_profile_t profile); 1243 1244 /** 1245 * @brief returns the master salt length for a given SRTP profile 1246 */ 1247 unsigned int srtp_profile_get_master_salt_length(srtp_profile_t profile); 1248 1249 /** 1250 * @brief appends the salt to the key 1251 * 1252 * The function call srtp_append_salt_to_key(k, klen, s, slen) 1253 * copies the string s to the location at klen bytes following 1254 * the location k. 1255 * 1256 * @warning There must be at least bytes_in_salt + bytes_in_key bytes 1257 * available at the location pointed to by key. 1258 * 1259 */ 1260 void srtp_append_salt_to_key(unsigned char *key, 1261 unsigned int bytes_in_key, 1262 unsigned char *salt, 1263 unsigned int bytes_in_salt); 1264 1265 /** 1266 * @} 1267 */ 1268 1269 /** 1270 * @defgroup SRTCP Secure RTCP 1271 * @ingroup SRTP 1272 * 1273 * @brief Secure RTCP functions are used to protect RTCP traffic. 1274 * 1275 * RTCP is the control protocol for RTP. libSRTP protects RTCP 1276 * traffic in much the same way as it does RTP traffic. The function 1277 * srtp_protect_rtcp() applies cryptographic protections to outbound 1278 * RTCP packets, and srtp_unprotect_rtcp() verifies the protections on 1279 * inbound RTCP packets. 1280 * 1281 * A note on the naming convention: srtp_protect_rtcp() has an srtp_t 1282 * as its first argument, and thus has `srtp_' as its prefix. The 1283 * trailing `_rtcp' indicates the protocol on which it acts. 1284 * 1285 * @{ 1286 */ 1287 1288 /** 1289 * @brief srtp_protect_rtcp() is the Secure RTCP sender-side packet 1290 * processing function. 1291 * 1292 * The function call srtp_protect_rtcp(ctx, rtp_hdr, len_ptr) applies 1293 * SRTCP protection to the RTCP packet rtcp_hdr (which has length 1294 * *len_ptr) using the SRTP session context ctx. If srtp_err_status_ok is 1295 * returned, then rtp_hdr points to the resulting SRTCP packet and 1296 * *len_ptr is the number of octets in that packet; otherwise, no 1297 * assumptions should be made about the value of either data elements. 1298 * 1299 * @warning This function assumes that it can write the authentication 1300 * tag into the location in memory immediately following the RTCP 1301 * packet, and assumes that the RTCP packet is aligned on a 32-bit 1302 * boundary. 1303 * 1304 * @warning This function assumes that it can write SRTP_MAX_TRAILER_LEN+4 1305 * into the location in memory immediately following the RTCP packet. 1306 * Callers MUST ensure that this much writable memory is available in 1307 * the buffer that holds the RTCP packet. 1308 * 1309 * @param ctx is the SRTP context to use in processing the packet. 1310 * 1311 * @param rtcp_hdr is a pointer to the RTCP packet (before the call); after 1312 * the function returns, it points to the srtp packet. 1313 * 1314 * @param pkt_octet_len is a pointer to the length in octets of the 1315 * complete RTCP packet (header and body) before the function call, 1316 * and of the complete SRTCP packet after the call, if srtp_err_status_ok 1317 * was returned. Otherwise, the value of the data to which it points 1318 * is undefined. 1319 * 1320 * @return 1321 * - srtp_err_status_ok if there were no problems. 1322 * - [other] if there was a failure in 1323 * the cryptographic mechanisms. 1324 */ 1325 srtp_err_status_t srtp_protect_rtcp(srtp_t ctx, 1326 void *rtcp_hdr, 1327 int *pkt_octet_len); 1328 1329 /** 1330 * @brief srtp_protect_rtcp_mki() is the Secure RTCP sender-side packet 1331 * processing function that can utilize mki. 1332 * 1333 * The function call srtp_protect_rtcp(ctx, rtp_hdr, len_ptr) applies 1334 * SRTCP protection to the RTCP packet rtcp_hdr (which has length 1335 * *len_ptr) using the SRTP session context ctx. If srtp_err_status_ok is 1336 * returned, then rtp_hdr points to the resulting SRTCP packet and 1337 * *len_ptr is the number of octets in that packet; otherwise, no 1338 * assumptions should be made about the value of either data elements. 1339 * 1340 * @warning This function assumes that it can write the authentication 1341 * tag into the location in memory immediately following the RTCP 1342 * packet, and assumes that the RTCP packet is aligned on a 32-bit 1343 * boundary. 1344 * 1345 * @warning This function assumes that it can write SRTP_MAX_TRAILER_LEN+4 1346 * into the location in memory immediately following the RTCP packet. 1347 * Callers MUST ensure that this much writable memory is available in 1348 * the buffer that holds the RTCP packet. 1349 * 1350 * @param ctx is the SRTP context to use in processing the packet. 1351 * 1352 * @param rtcp_hdr is a pointer to the RTCP packet (before the call); after 1353 * the function returns, it points to the srtp packet. 1354 * 1355 * @param pkt_octet_len is a pointer to the length in octets of the 1356 * complete RTCP packet (header and body) before the function call, 1357 * and of the complete SRTCP packet after the call, if srtp_err_status_ok 1358 * was returned. Otherwise, the value of the data to which it points 1359 * is undefined. 1360 * 1361 * @param use_mki is a boolean to tell the system if mki is being used. If 1362 * set to false then will use the first set of session keys. If set to true 1363 * will 1364 * use the session keys identified by the mki_index 1365 * 1366 * @param mki_index integer value specifying which set of session kesy should be 1367 * used if use_mki is set to true. 1368 * 1369 * @return 1370 * - srtp_err_status_ok if there were no problems. 1371 * - [other] if there was a failure in 1372 * the cryptographic mechanisms. 1373 */ 1374 srtp_err_status_t srtp_protect_rtcp_mki(srtp_t ctx, 1375 void *rtcp_hdr, 1376 int *pkt_octet_len, 1377 unsigned int use_mki, 1378 unsigned int mki_index); 1379 1380 /** 1381 * @brief srtp_unprotect_rtcp() is the Secure RTCP receiver-side packet 1382 * processing function. 1383 * 1384 * The function call srtp_unprotect_rtcp(ctx, srtp_hdr, len_ptr) 1385 * verifies the Secure RTCP protection of the SRTCP packet pointed to 1386 * by srtcp_hdr (which has length *len_ptr), using the SRTP session 1387 * context ctx. If srtp_err_status_ok is returned, then srtcp_hdr points 1388 * to the resulting RTCP packet and *len_ptr is the number of octets 1389 * in that packet; otherwise, no assumptions should be made about the 1390 * value of either data elements. 1391 * 1392 * @warning This function assumes that the SRTCP packet is aligned on a 1393 * 32-bit boundary. 1394 * 1395 * @param ctx is a pointer to the srtp_t which applies to the 1396 * particular packet. 1397 * 1398 * @param srtcp_hdr is a pointer to the header of the SRTCP packet 1399 * (before the call). After the function returns, it points to the 1400 * rtp packet if srtp_err_status_ok was returned; otherwise, the value of 1401 * the data to which it points is undefined. 1402 * 1403 * @param pkt_octet_len is a pointer to the length in octets of the 1404 * complete SRTCP packet (header and body) before the function call, 1405 * and of the complete rtp packet after the call, if srtp_err_status_ok was 1406 * returned. Otherwise, the value of the data to which it points is 1407 * undefined. 1408 * 1409 * @return 1410 * - srtp_err_status_ok if the RTCP packet is valid. 1411 * - srtp_err_status_auth_fail if the SRTCP packet failed the message 1412 * authentication check. 1413 * - srtp_err_status_replay_fail if the SRTCP packet is a replay (e.g. has 1414 * already been processed and accepted). 1415 * - [other] if there has been an error in the cryptographic mechanisms. 1416 * 1417 */ 1418 srtp_err_status_t srtp_unprotect_rtcp(srtp_t ctx, 1419 void *srtcp_hdr, 1420 int *pkt_octet_len); 1421 1422 /** 1423 * @brief srtp_unprotect_rtcp() is the Secure RTCP receiver-side packet 1424 * processing function. 1425 * 1426 * The function call srtp_unprotect_rtcp(ctx, srtp_hdr, len_ptr) 1427 * verifies the Secure RTCP protection of the SRTCP packet pointed to 1428 * by srtcp_hdr (which has length *len_ptr), using the SRTP session 1429 * context ctx. If srtp_err_status_ok is returned, then srtcp_hdr points 1430 * to the resulting RTCP packet and *len_ptr is the number of octets 1431 * in that packet; otherwise, no assumptions should be made about the 1432 * value of either data elements. 1433 * 1434 * @warning This function assumes that the SRTCP packet is aligned on a 1435 * 32-bit boundary. 1436 * 1437 * @param ctx is a pointer to the srtp_t which applies to the 1438 * particular packet. 1439 * 1440 * @param srtcp_hdr is a pointer to the header of the SRTCP packet 1441 * (before the call). After the function returns, it points to the 1442 * rtp packet if srtp_err_status_ok was returned; otherwise, the value of 1443 * the data to which it points is undefined. 1444 * 1445 * @param pkt_octet_len is a pointer to the length in octets of the 1446 * complete SRTCP packet (header and body) before the function call, 1447 * and of the complete rtp packet after the call, if srtp_err_status_ok was 1448 * returned. Otherwise, the value of the data to which it points is 1449 * undefined. 1450 * 1451 * @param use_mki is a boolean to tell the system if mki is being used. If 1452 * set to false then will use the first set of session keys. If set to true 1453 * will use the session keys identified by the mki_index 1454 * 1455 * @return 1456 * - srtp_err_status_ok if the RTCP packet is valid. 1457 * - srtp_err_status_auth_fail if the SRTCP packet failed the message 1458 * authentication check. 1459 * - srtp_err_status_replay_fail if the SRTCP packet is a replay (e.g. has 1460 * already been processed and accepted). 1461 * - srtp_err_status_bad_mki if the MKI in the packet is not a known MKI 1462 * id 1463 * - [other] if there has been an error in the 1464 * cryptographic mechanisms. 1465 * 1466 */ 1467 srtp_err_status_t srtp_unprotect_rtcp_mki(srtp_t ctx, 1468 void *srtcp_hdr, 1469 int *pkt_octet_len, 1470 unsigned int use_mki); 1471 1472 /** 1473 * @} 1474 */ 1475 1476 /** 1477 * @defgroup User data associated to a SRTP session. 1478 * @ingroup SRTP 1479 * 1480 * @brief Store custom user data within a SRTP session. 1481 * 1482 * @{ 1483 */ 1484 1485 /** 1486 * @brief srtp_set_user_data() stores the given pointer into the SRTP 1487 * session for later retrieval. 1488 * 1489 * @param ctx is the srtp_t context in which the given data pointer is 1490 * stored. 1491 * 1492 * @param data is a pointer to the custom information (struct, function, 1493 * etc) associated with the SRTP session. 1494 * 1495 * @return void. 1496 * 1497 */ 1498 void srtp_set_user_data(srtp_t ctx, void *data); 1499 1500 /** 1501 * @brief srtp_get_user_data() retrieves the pointer to the custom data 1502 * previously stored with srtp_set_user_data(). 1503 * 1504 * This function is mostly useful for retrieving data associated to a 1505 * SRTP session when an event fires. The user can then get such a custom 1506 * data by calling this function with the session field of the 1507 * srtp_event_data_t struct as argument. 1508 * 1509 * @param ctx is the srtp_t context in which the given data pointer was 1510 * stored. 1511 * 1512 * @return void* pointer to the user data. 1513 * 1514 */ 1515 void *srtp_get_user_data(srtp_t ctx); 1516 1517 /** 1518 * @} 1519 */ 1520 1521 /** 1522 * @defgroup SRTPevents SRTP events and callbacks 1523 * @ingroup SRTP 1524 * 1525 * @brief libSRTP can use a user-provided callback function to 1526 * handle events. 1527 * 1528 * 1529 * libSRTP allows a user to provide a callback function to handle 1530 * events that need to be dealt with outside of the data plane (see 1531 * the enum srtp_event_t for a description of these events). Dealing 1532 * with these events is not a strict necessity; they are not 1533 * security-critical, but the application may suffer if they are not 1534 * handled. The function srtp_set_event_handler() is used to provide 1535 * the callback function. 1536 * 1537 * A default event handler that merely reports on the events as they 1538 * happen is included. It is also possible to set the event handler 1539 * function to NULL, in which case all events will just be silently 1540 * ignored. 1541 * 1542 * @{ 1543 */ 1544 1545 /** 1546 * @brief srtp_event_t defines events that need to be handled 1547 * 1548 * The enum srtp_event_t defines events that need to be handled 1549 * outside the `data plane', such as SSRC collisions and 1550 * key expirations. 1551 * 1552 * When a key expires or the maximum number of packets has been 1553 * reached, an SRTP stream will enter an `expired' state in which no 1554 * more packets can be protected or unprotected. When this happens, 1555 * it is likely that you will want to either deallocate the stream 1556 * (using srtp_remove_stream()), and possibly allocate a new one. 1557 * 1558 * When an SRTP stream expires, the other streams in the same session 1559 * are unaffected, unless key sharing is used by that stream. In the 1560 * latter case, all of the streams in the session will expire. 1561 */ 1562 typedef enum { 1563 event_ssrc_collision, /**< An SSRC collision occured. */ 1564 event_key_soft_limit, /**< An SRTP stream reached the soft key */ 1565 /**< usage limit and will expire soon. */ 1566 event_key_hard_limit, /**< An SRTP stream reached the hard */ 1567 /**< key usage limit and has expired. */ 1568 event_packet_index_limit /**< An SRTP stream reached the hard */ 1569 /**< packet limit (2^48 packets). */ 1570 } srtp_event_t; 1571 1572 /** 1573 * @brief srtp_event_data_t is the structure passed as a callback to 1574 * the event handler function 1575 * 1576 * The struct srtp_event_data_t holds the data passed to the event 1577 * handler function. 1578 */ 1579 typedef struct srtp_event_data_t { 1580 srtp_t session; /**< The session in which the event happend. */ 1581 uint32_t ssrc; /**< The ssrc in host order of the stream in which */ 1582 /**< the event happend */ 1583 srtp_event_t event; /**< An enum indicating the type of event. */ 1584 } srtp_event_data_t; 1585 1586 /** 1587 * @brief srtp_event_handler_func_t is the function prototype for 1588 * the event handler. 1589 * 1590 * The typedef srtp_event_handler_func_t is the prototype for the 1591 * event handler function. It has as its only argument an 1592 * srtp_event_data_t which describes the event that needs to be handled. 1593 * There can only be a single, global handler for all events in 1594 * libSRTP. 1595 */ 1596 typedef void(srtp_event_handler_func_t)(srtp_event_data_t *data); 1597 1598 /** 1599 * @brief sets the event handler to the function supplied by the caller. 1600 * 1601 * The function call srtp_install_event_handler(func) sets the event 1602 * handler function to the value func. The value NULL is acceptable 1603 * as an argument; in this case, events will be ignored rather than 1604 * handled. 1605 * 1606 * @param func is a pointer to a fuction that takes an srtp_event_data_t 1607 * pointer as an argument and returns void. This function 1608 * will be used by libSRTP to handle events. 1609 */ 1610 srtp_err_status_t srtp_install_event_handler(srtp_event_handler_func_t func); 1611 1612 /** 1613 * @brief Returns the version string of the library. 1614 * 1615 */ 1616 const char *srtp_get_version_string(void); 1617 1618 /** 1619 * @brief Returns the numeric representation of the library version. 1620 * 1621 */ 1622 unsigned int srtp_get_version(void); 1623 1624 /** 1625 * @brief srtp_set_debug_module(mod_name, v) 1626 * 1627 * sets dynamic debugging to the value v (0 for off, 1 for on) for the 1628 * debug module with the name mod_name 1629 * 1630 * returns err_status_ok on success, err_status_fail otherwise 1631 */ 1632 srtp_err_status_t srtp_set_debug_module(const char *mod_name, int v); 1633 1634 /** 1635 * @brief srtp_list_debug_modules() outputs a list of debugging modules 1636 * 1637 */ 1638 srtp_err_status_t srtp_list_debug_modules(void); 1639 1640 /** 1641 * @brief srtp_log_level_t defines log levels. 1642 * 1643 * The enumeration srtp_log_level_t defines log levels reported 1644 * in the srtp_log_handler_func_t. 1645 * 1646 */ 1647 typedef enum { 1648 srtp_log_level_error, /**< log level is reporting an error message */ 1649 srtp_log_level_warning, /**< log level is reporting a warning message */ 1650 srtp_log_level_info, /**< log level is reporting an info message */ 1651 srtp_log_level_debug /**< log level is reporting a debug message */ 1652 } srtp_log_level_t; 1653 1654 /** 1655 * @brief srtp_log_handler_func_t is the function prototype for 1656 * the log handler. 1657 * 1658 * The typedef srtp_event_handler_func_t is the prototype for the 1659 * event handler function. It has as srtp_log_level_t, log 1660 * message and data as arguments. 1661 * There can only be a single, global handler for all log messages in 1662 * libSRTP. 1663 */ 1664 typedef void(srtp_log_handler_func_t)(srtp_log_level_t level, 1665 const char *msg, 1666 void *data); 1667 1668 /** 1669 * @brief sets the log handler to the function supplied by the caller. 1670 * 1671 * The function call srtp_install_log_handler(func) sets the log 1672 * handler function to the value func. The value NULL is acceptable 1673 * as an argument; in this case, log messages will be ignored. 1674 * This function can be called before srtp_init() inorder to capture 1675 * any logging during start up. 1676 * 1677 * @param func is a pointer to a fuction of type srtp_log_handler_func_t. 1678 * This function will be used by libSRTP to output log messages. 1679 * @param data is a user pointer that will be returned as the data argument in 1680 * func. 1681 */ 1682 srtp_err_status_t srtp_install_log_handler(srtp_log_handler_func_t func, 1683 void *data); 1684 1685 /** 1686 * @brief srtp_get_protect_trailer_length(session, use_mki, mki_index, length) 1687 * 1688 * Determines the length of the amount of data Lib SRTP will add to the 1689 * packet during the protect process. The length is returned in the length 1690 * parameter 1691 * 1692 * returns err_status_ok on success, err_status_bad_mki if the MKI index is 1693 * invalid 1694 * 1695 */ 1696 srtp_err_status_t srtp_get_protect_trailer_length(srtp_t session, 1697 uint32_t use_mki, 1698 uint32_t mki_index, 1699 uint32_t *length); 1700 1701 /** 1702 * @brief srtp_get_protect_rtcp_trailer_length(session, use_mki, mki_index, 1703 * length) 1704 * 1705 * Determines the length of the amount of data Lib SRTP will add to the 1706 * packet during the protect process. The length is returned in the length 1707 * parameter 1708 * 1709 * returns err_status_ok on success, err_status_bad_mki if the MKI index is 1710 * invalid 1711 * 1712 */ 1713 srtp_err_status_t srtp_get_protect_rtcp_trailer_length(srtp_t session, 1714 uint32_t use_mki, 1715 uint32_t mki_index, 1716 uint32_t *length); 1717 1718 /** 1719 * @brief srtp_set_stream_roc(session, ssrc, roc) 1720 * 1721 * Set the roll-over-counter on a session for a given SSRC 1722 * 1723 * returns err_status_ok on success, srtp_err_status_bad_param if there is no 1724 * stream found 1725 * 1726 */ 1727 srtp_err_status_t srtp_set_stream_roc(srtp_t session, 1728 uint32_t ssrc, 1729 uint32_t roc); 1730 1731 /** 1732 * @brief srtp_get_stream_roc(session, ssrc, roc) 1733 * 1734 * Get the roll-over-counter on a session for a given SSRC 1735 * 1736 * returns err_status_ok on success, srtp_err_status_bad_param if there is no 1737 * stream found 1738 * 1739 */ 1740 srtp_err_status_t srtp_get_stream_roc(srtp_t session, 1741 uint32_t ssrc, 1742 uint32_t *roc); 1743 1744 /** 1745 * @} 1746 */ 1747 1748 /* in host order, so outside the #if */ 1749 #define SRTCP_E_BIT 0x80000000 1750 1751 /* for byte-access */ 1752 #define SRTCP_E_BYTE_BIT 0x80 1753 #define SRTCP_INDEX_MASK 0x7fffffff 1754 1755 #ifdef __cplusplus 1756 } 1757 #endif 1758 1759 #endif /* SRTP_SRTP_H */ 1760