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 "crypto_kernel.h" 54 55 /** 56 * @defgroup SRTP Secure RTP 57 * 58 * @brief libSRTP provides functions for protecting RTP and RTCP. See 59 * Section @ref Overview for an introduction to the use of the library. 60 * 61 * @{ 62 */ 63 64 /* 65 * SRTP_MASTER_KEY_LEN is the nominal master key length supported by libSRTP 66 */ 67 68 #define SRTP_MASTER_KEY_LEN 30 69 70 /* 71 * SRTP_MAX_KEY_LEN is the maximum key length supported by libSRTP 72 */ 73 #define SRTP_MAX_KEY_LEN 64 74 75 /* 76 * SRTP_MAX_TAG_LEN is the maximum tag length supported by libSRTP 77 */ 78 79 #define SRTP_MAX_TAG_LEN 12 80 81 /** 82 * SRTP_MAX_TRAILER_LEN is the maximum length of the SRTP trailer 83 * (authentication tag and MKI) supported by libSRTP. This value is 84 * the maximum number of octets that will be added to an RTP packet by 85 * srtp_protect(). 86 * 87 * @brief the maximum number of octets added by srtp_protect(). 88 */ 89 #define SRTP_MAX_TRAILER_LEN SRTP_MAX_TAG_LEN 90 91 /* 92 * nota bene: since libSRTP doesn't support the use of the MKI, the 93 * SRTP_MAX_TRAILER_LEN value is just the maximum tag length 94 */ 95 96 /** 97 * @brief sec_serv_t describes a set of security services. 98 * 99 * A sec_serv_t enumeration is used to describe the particular 100 * security services that will be applied by a particular crypto 101 * policy (or other mechanism). 102 */ 103 104 typedef enum { 105 sec_serv_none = 0, /**< no services */ 106 sec_serv_conf = 1, /**< confidentiality */ 107 sec_serv_auth = 2, /**< authentication */ 108 sec_serv_conf_and_auth = 3 /**< confidentiality and authentication */ 109 } sec_serv_t; 110 111 /** 112 * @brief crypto_policy_t describes a particular crypto policy that 113 * can be applied to an SRTP stream. 114 * 115 * A crypto_policy_t describes a particular cryptographic policy that 116 * can be applied to an SRTP or SRTCP stream. An SRTP session policy 117 * consists of a list of these policies, one for each SRTP stream 118 * in the session. 119 */ 120 121 typedef struct crypto_policy_t { 122 cipher_type_id_t cipher_type; /**< An integer representing 123 * the type of cipher. */ 124 int cipher_key_len; /**< The length of the cipher key 125 * in octets. */ 126 auth_type_id_t auth_type; /**< An integer representing the 127 * authentication function. */ 128 int auth_key_len; /**< The length of the authentication 129 * function key in octets. */ 130 int auth_tag_len; /**< The length of the authentication 131 * tag in octets. */ 132 sec_serv_t sec_serv; /**< The flag indicating the security 133 * services to be applied. */ 134 } crypto_policy_t; 135 136 137 /** 138 * @brief ssrc_type_t describes the type of an SSRC. 139 * 140 * An ssrc_type_t enumeration is used to indicate a type of SSRC. See 141 * @ref srtp_policy_t for more informataion. 142 */ 143 144 typedef enum { 145 ssrc_undefined = 0, /**< Indicates an undefined SSRC type. */ 146 ssrc_specific = 1, /**< Indicates a specific SSRC value */ 147 ssrc_any_inbound = 2, /**< Indicates any inbound SSRC value 148 (i.e. a value that is used in the 149 function srtp_unprotect()) */ 150 ssrc_any_outbound = 3 /**< Indicates any outbound SSRC value 151 (i.e. a value that is used in the 152 function srtp_protect()) */ 153 } ssrc_type_t; 154 155 /** 156 * @brief An ssrc_t represents a particular SSRC value, or a `wildcard' SSRC. 157 * 158 * An ssrc_t represents a particular SSRC value (if its type is 159 * ssrc_specific), or a wildcard SSRC value that will match all 160 * outbound SSRCs (if its type is ssrc_any_outbound) or all inbound 161 * SSRCs (if its type is ssrc_any_inbound). 162 * 163 */ 164 165 typedef struct { 166 ssrc_type_t type; /**< The type of this particular SSRC */ 167 unsigned int value; /**< The value of this SSRC, if it is not a wildcard */ 168 } ssrc_t; 169 170 171 /** 172 * @brief points to an EKT policy 173 */ 174 typedef struct ekt_policy_ctx_t *ekt_policy_t; 175 176 177 /** 178 * @brief points to EKT stream data 179 */ 180 typedef struct ekt_stream_ctx_t *ekt_stream_t; 181 182 183 /** 184 * @brief represents the policy for an SRTP session. 185 * 186 * A single srtp_policy_t struct represents the policy for a single 187 * SRTP stream, and a linked list of these elements represents the 188 * policy for an entire SRTP session. Each element contains the SRTP 189 * and SRTCP crypto policies for that stream, a pointer to the SRTP 190 * master key for that stream, the SSRC describing that stream, or a 191 * flag indicating a `wildcard' SSRC value, and a `next' field that 192 * holds a pointer to the next element in the list of policy elements, 193 * or NULL if it is the last element. 194 * 195 * The wildcard value SSRC_ANY_INBOUND matches any SSRC from an 196 * inbound stream that for which there is no explicit SSRC entry in 197 * another policy element. Similarly, the value SSRC_ANY_OUTBOUND 198 * will matches any SSRC from an outbound stream that does not appear 199 * in another policy element. Note that wildcard SSRCs &b cannot be 200 * used to match both inbound and outbound traffic. This restriction 201 * is intentional, and it allows libSRTP to ensure that no security 202 * lapses result from accidental re-use of SSRC values during key 203 * sharing. 204 * 205 * 206 * @warning The final element of the list @b must have its `next' pointer 207 * set to NULL. 208 */ 209 210 typedef struct srtp_policy_t { 211 ssrc_t ssrc; /**< The SSRC value of stream, or the 212 * flags SSRC_ANY_INBOUND or 213 * SSRC_ANY_OUTBOUND if key sharing 214 * is used for this policy element. 215 */ 216 crypto_policy_t rtp; /**< SRTP crypto policy. */ 217 crypto_policy_t rtcp; /**< SRTCP crypto policy. */ 218 unsigned char *key; /**< Pointer to the SRTP master key for 219 * this stream. */ 220 ekt_policy_t ekt; /**< Pointer to the EKT policy structure 221 * for this stream (if any) */ 222 unsigned long window_size; /**< The window size to use for replay 223 * protection. */ 224 int allow_repeat_tx; /**< Whether retransmissions of 225 * packets with the same sequence number 226 * are allowed. (Note that such repeated 227 * transmissions must have the same RTP 228 * payload, or a severe security weakness 229 * is introduced!) */ 230 struct srtp_policy_t *next; /**< Pointer to next stream policy. */ 231 } srtp_policy_t; 232 233 234 235 236 /** 237 * @brief An srtp_t points to an SRTP session structure. 238 * 239 * The typedef srtp_t is a pointer to a structure that represents 240 * an SRTP session. This datatype is intentially opaque in 241 * order to separate the interface from the implementation. 242 * 243 * An SRTP session consists of all of the traffic sent to the RTP and 244 * RTCP destination transport addresses, using the RTP/SAVP (Secure 245 * Audio/Video Profile). A session can be viewed as a set of SRTP 246 * streams, each of which originates with a different participant. 247 */ 248 249 typedef struct srtp_ctx_t *srtp_t; 250 251 252 /** 253 * @brief An srtp_stream_t points to an SRTP stream structure. 254 * 255 * The typedef srtp_stream_t is a pointer to a structure that 256 * represents an SRTP stream. This datatype is intentionally 257 * opaque in order to separate the interface from the implementation. 258 * 259 * An SRTP stream consists of all of the traffic sent to an SRTP 260 * session by a single participant. A session can be viewed as 261 * a set of streams. 262 * 263 */ 264 typedef struct srtp_stream_ctx_t *srtp_stream_t; 265 266 267 268 /** 269 * @brief srtp_init() initializes the srtp library. 270 * 271 * @warning This function @b must be called before any other srtp 272 * functions. 273 */ 274 275 err_status_t 276 srtp_init(void); 277 278 /** 279 * @brief srtp_protect() is the Secure RTP sender-side packet processing 280 * function. 281 * 282 * The function call srtp_protect(ctx, rtp_hdr, len_ptr) applies SRTP 283 * protection to the RTP packet rtp_hdr (which has length *len_ptr) using 284 * the SRTP context ctx. If err_status_ok is returned, then rtp_hdr 285 * points to the resulting SRTP packet and *len_ptr is the number of 286 * octets in that packet; otherwise, no assumptions should be made 287 * about the value of either data elements. 288 * 289 * The sequence numbers of the RTP packets presented to this function 290 * need not be consecutive, but they @b must be out of order by less 291 * than 2^15 = 32,768 packets. 292 * 293 * @warning This function assumes that it can write the authentication 294 * tag into the location in memory immediately following the RTP 295 * packet, and assumes that the RTP packet is aligned on a 32-bit 296 * boundary. 297 * 298 * @param ctx is the SRTP context to use in processing the packet. 299 * 300 * @param rtp_hdr is a pointer to the RTP packet (before the call); after 301 * the function returns, it points to the srtp packet. 302 * 303 * @param len_ptr is a pointer to the length in octets of the complete 304 * RTP packet (header and body) before the function call, and of the 305 * complete SRTP packet after the call, if err_status_ok was returned. 306 * Otherwise, the value of the data to which it points is undefined. 307 * 308 * @return 309 * - err_status_ok no problems 310 * - err_status_replay_fail rtp sequence number was non-increasing 311 * - @e other failure in cryptographic mechanisms 312 */ 313 314 err_status_t 315 srtp_protect(srtp_t ctx, void *rtp_hdr, int *len_ptr); 316 317 /** 318 * @brief srtp_unprotect() is the Secure RTP receiver-side packet 319 * processing function. 320 * 321 * The function call srtp_unprotect(ctx, srtp_hdr, len_ptr) verifies 322 * the Secure RTP protection of the SRTP packet pointed to by srtp_hdr 323 * (which has length *len_ptr), using the SRTP context ctx. If 324 * err_status_ok is returned, then srtp_hdr points to the resulting 325 * RTP packet and *len_ptr is the number of octets in that packet; 326 * otherwise, no assumptions should be made about the value of either 327 * data elements. 328 * 329 * The sequence numbers of the RTP packets presented to this function 330 * need not be consecutive, but they @b must be out of order by less 331 * than 2^15 = 32,768 packets. 332 * 333 * @warning This function assumes that the SRTP packet is aligned on a 334 * 32-bit boundary. 335 * 336 * @param ctx is a pointer to the srtp_t which applies to the 337 * particular packet. 338 * 339 * @param srtp_hdr is a pointer to the header of the SRTP packet 340 * (before the call). after the function returns, it points to the 341 * rtp packet if err_status_ok was returned; otherwise, the value of 342 * the data to which it points is undefined. 343 * 344 * @param len_ptr is a pointer to the length in octets of the complete 345 * srtp packet (header and body) before the function call, and of the 346 * complete rtp packet after the call, if err_status_ok was returned. 347 * Otherwise, the value of the data to which it points is undefined. 348 * 349 * @return 350 * - err_status_ok if the RTP packet is valid. 351 * - err_status_auth_fail if the SRTP packet failed the message 352 * authentication check. 353 * - err_status_replay_fail if the SRTP packet is a replay (e.g. packet has 354 * already been processed and accepted). 355 * - [other] if there has been an error in the cryptographic mechanisms. 356 * 357 */ 358 359 err_status_t 360 srtp_unprotect(srtp_t ctx, void *srtp_hdr, int *len_ptr); 361 362 363 /** 364 * @brief srtp_create() allocates and initializes an SRTP session. 365 366 * The function call srtp_create(session, policy, key) allocates and 367 * initializes an SRTP session context, applying the given policy and 368 * key. 369 * 370 * @param session is the SRTP session to which the policy is to be added. 371 * 372 * @param policy is the srtp_policy_t struct that describes the policy 373 * for the session. The struct may be a single element, or it may be 374 * the head of a list, in which case each element of the list is 375 * processed. It may also be NULL, in which case streams should be added 376 * later using srtp_add_stream(). The final element of the list @b must 377 * have its `next' field set to NULL. 378 * 379 * @return 380 * - err_status_ok if creation succeded. 381 * - err_status_alloc_fail if allocation failed. 382 * - err_status_init_fail if initialization failed. 383 */ 384 385 err_status_t 386 srtp_create(srtp_t *session, const srtp_policy_t *policy); 387 388 389 /** 390 * @brief srtp_add_stream() allocates and initializes an SRTP stream 391 * within a given SRTP session. 392 * 393 * The function call srtp_add_stream(session, policy) allocates and 394 * initializes a new SRTP stream within a given, previously created 395 * session, applying the policy given as the other argument to that 396 * stream. 397 * 398 * @return values: 399 * - err_status_ok if stream creation succeded. 400 * - err_status_alloc_fail if stream allocation failed 401 * - err_status_init_fail if stream initialization failed. 402 */ 403 404 err_status_t 405 srtp_add_stream(srtp_t session, 406 const srtp_policy_t *policy); 407 408 409 /** 410 * @brief srtp_remove_stream() deallocates an SRTP stream. 411 * 412 * The function call srtp_remove_stream(session, ssrc) removes 413 * the SRTP stream with the SSRC value ssrc from the SRTP session 414 * context given by the argument session. 415 * 416 * @param session is the SRTP session from which the stream 417 * will be removed. 418 * 419 * @param ssrc is the SSRC value of the stream to be removed. 420 * 421 * @warning Wildcard SSRC values cannot be removed from a 422 * session. 423 * 424 * @return 425 * - err_status_ok if the stream deallocation succeded. 426 * - [other] otherwise. 427 * 428 */ 429 430 err_status_t 431 srtp_remove_stream(srtp_t session, unsigned int ssrc); 432 433 /** 434 * @brief crypto_policy_set_rtp_default() sets a crypto policy 435 * structure to the SRTP default policy for RTP protection. 436 * 437 * @param p is a pointer to the policy structure to be set 438 * 439 * The function call crypto_policy_set_rtp_default(&p) sets the 440 * crypto_policy_t at location p to the SRTP default policy for RTP 441 * protection, as defined in the specification. This function is a 442 * convenience that helps to avoid dealing directly with the policy 443 * data structure. You are encouraged to initialize policy elements 444 * with this function call. Doing so may allow your code to be 445 * forward compatible with later versions of libSRTP that include more 446 * elements in the crypto_policy_t datatype. 447 * 448 * @return void. 449 * 450 */ 451 452 void 453 crypto_policy_set_rtp_default(crypto_policy_t *p); 454 455 /** 456 * @brief crypto_policy_set_rtcp_default() sets a crypto policy 457 * structure to the SRTP default policy for RTCP protection. 458 * 459 * @param p is a pointer to the policy structure to be set 460 * 461 * The function call crypto_policy_set_rtcp_default(&p) sets the 462 * crypto_policy_t at location p to the SRTP default policy for RTCP 463 * protection, as defined in the specification. This function is a 464 * convenience that helps to avoid dealing directly with the policy 465 * data structure. You are encouraged to initialize policy elements 466 * with this function call. Doing so may allow your code to be 467 * forward compatible with later versions of libSRTP that include more 468 * elements in the crypto_policy_t datatype. 469 * 470 * @return void. 471 * 472 */ 473 474 void 475 crypto_policy_set_rtcp_default(crypto_policy_t *p); 476 477 /** 478 * @brief crypto_policy_set_aes_cm_128_hmac_sha1_80() sets a crypto 479 * policy structure to the SRTP default policy for RTP protection. 480 * 481 * @param p is a pointer to the policy structure to be set 482 * 483 * The function crypto_policy_set_aes_cm_128_hmac_sha1_80() is a 484 * synonym for crypto_policy_set_rtp_default(). It conforms to the 485 * naming convention used in 486 * http://www.ietf.org/internet-drafts/draft-ietf-mmusic-sdescriptions-12.txt 487 * 488 * @return void. 489 * 490 */ 491 492 #define crypto_policy_set_aes_cm_128_hmac_sha1_80(p) crypto_policy_set_rtp_default(p) 493 494 495 /** 496 * @brief crypto_policy_set_aes_cm_128_hmac_sha1_32() sets a crypto 497 * policy structure to a short-authentication tag policy 498 * 499 * @param p is a pointer to the policy structure to be set 500 * 501 * The function call crypto_policy_set_aes_cm_128_hmac_sha1_32(&p) 502 * sets the crypto_policy_t at location p to use policy 503 * AES_CM_128_HMAC_SHA1_32 as defined in 504 * draft-ietf-mmusic-sdescriptions-12.txt. This policy uses AES-128 505 * Counter Mode encryption and HMAC-SHA1 authentication, with an 506 * authentication tag that is only 32 bits long. This length is 507 * considered adequate only for protecting audio and video media that 508 * use a stateless playback function. See Section 7.5 of RFC 3711 509 * (http://www.ietf.org/rfc/rfc3711.txt). 510 * 511 * This function is a convenience that helps to avoid dealing directly 512 * with the policy data structure. You are encouraged to initialize 513 * policy elements with this function call. Doing so may allow your 514 * code to be forward compatible with later versions of libSRTP that 515 * include more elements in the crypto_policy_t datatype. 516 * 517 * @warning This crypto policy is intended for use in SRTP, but not in 518 * SRTCP. It is recommended that a policy that uses longer 519 * authentication tags be used for SRTCP. See Section 7.5 of RFC 3711 520 * (http://www.ietf.org/rfc/rfc3711.txt). 521 * 522 * @return void. 523 * 524 */ 525 526 void 527 crypto_policy_set_aes_cm_128_hmac_sha1_32(crypto_policy_t *p); 528 529 530 531 /** 532 * @brief crypto_policy_set_aes_cm_128_null_auth() sets a crypto 533 * policy structure to an encryption-only policy 534 * 535 * @param p is a pointer to the policy structure to be set 536 * 537 * The function call crypto_policy_set_aes_cm_128_null_auth(&p) sets 538 * the crypto_policy_t at location p to use the SRTP default cipher 539 * (AES-128 Counter Mode), but to use no authentication method. This 540 * policy is NOT RECOMMENDED unless it is unavoidable; see Section 7.5 541 * of RFC 3711 (http://www.ietf.org/rfc/rfc3711.txt). 542 * 543 * This function is a convenience that helps to avoid dealing directly 544 * with the policy data structure. You are encouraged to initialize 545 * policy elements with this function call. Doing so may allow your 546 * code to be forward compatible with later versions of libSRTP that 547 * include more elements in the crypto_policy_t datatype. 548 * 549 * @warning This policy is NOT RECOMMENDED for SRTP unless it is 550 * unavoidable, and it is NOT RECOMMENDED at all for SRTCP; see 551 * Section 7.5 of RFC 3711 (http://www.ietf.org/rfc/rfc3711.txt). 552 * 553 * @return void. 554 * 555 */ 556 557 void 558 crypto_policy_set_aes_cm_128_null_auth(crypto_policy_t *p); 559 560 561 /** 562 * @brief crypto_policy_set_null_cipher_hmac_sha1_80() sets a crypto 563 * policy structure to an authentication-only policy 564 * 565 * @param p is a pointer to the policy structure to be set 566 * 567 * The function call crypto_policy_set_null_cipher_hmac_sha1_80(&p) 568 * sets the crypto_policy_t at location p to use HMAC-SHA1 with an 80 569 * bit authentication tag to provide message authentication, but to 570 * use no encryption. This policy is NOT RECOMMENDED for SRTP unless 571 * there is a requirement to forego encryption. 572 * 573 * This function is a convenience that helps to avoid dealing directly 574 * with the policy data structure. You are encouraged to initialize 575 * policy elements with this function call. Doing so may allow your 576 * code to be forward compatible with later versions of libSRTP that 577 * include more elements in the crypto_policy_t datatype. 578 * 579 * @warning This policy is NOT RECOMMENDED for SRTP unless there is a 580 * requirement to forego encryption. 581 * 582 * @return void. 583 * 584 */ 585 586 void 587 crypto_policy_set_null_cipher_hmac_sha1_80(crypto_policy_t *p); 588 589 /** 590 * @brief srtp_dealloc() deallocates storage for an SRTP session 591 * context. 592 * 593 * The function call srtp_dealloc(s) deallocates storage for the 594 * SRTP session context s. This function should be called no more 595 * than one time for each of the contexts allocated by the function 596 * srtp_create(). 597 * 598 * @param s is the srtp_t for the session to be deallocated. 599 * 600 * @return 601 * - err_status_ok if there no problems. 602 * - err_status_dealloc_fail a memory deallocation failure occured. 603 */ 604 605 err_status_t 606 srtp_dealloc(srtp_t s); 607 608 609 /* 610 * @brief identifies a particular SRTP profile 611 * 612 * An srtp_profile_t enumeration is used to identify a particular SRTP 613 * profile (that is, a set of algorithms and parameters). These 614 * profiles are defined in the DTLS-SRTP draft. 615 */ 616 617 typedef enum { 618 srtp_profile_reserved = 0, 619 srtp_profile_aes128_cm_sha1_80 = 1, 620 srtp_profile_aes128_cm_sha1_32 = 2, 621 srtp_profile_aes256_cm_sha1_80 = 3, 622 srtp_profile_aes256_cm_sha1_32 = 4, 623 srtp_profile_null_sha1_80 = 5, 624 srtp_profile_null_sha1_32 = 6, 625 } srtp_profile_t; 626 627 628 /** 629 * @brief crypto_policy_set_from_profile_for_rtp() sets a crypto policy 630 * structure to the appropriate value for RTP based on an srtp_profile_t 631 * 632 * @param p is a pointer to the policy structure to be set 633 * 634 * The function call crypto_policy_set_rtp_default(&policy, profile) 635 * sets the crypto_policy_t at location policy to the policy for RTP 636 * protection, as defined by the srtp_profile_t profile. 637 * 638 * This function is a convenience that helps to avoid dealing directly 639 * with the policy data structure. You are encouraged to initialize 640 * policy elements with this function call. Doing so may allow your 641 * code to be forward compatible with later versions of libSRTP that 642 * include more elements in the crypto_policy_t datatype. 643 * 644 * @return values 645 * - err_status_ok no problems were encountered 646 * - err_status_bad_param the profile is not supported 647 * 648 */ 649 err_status_t 650 crypto_policy_set_from_profile_for_rtp(crypto_policy_t *policy, 651 srtp_profile_t profile); 652 653 654 655 656 /** 657 * @brief crypto_policy_set_from_profile_for_rtcp() sets a crypto policy 658 * structure to the appropriate value for RTCP based on an srtp_profile_t 659 * 660 * @param p is a pointer to the policy structure to be set 661 * 662 * The function call crypto_policy_set_rtcp_default(&policy, profile) 663 * sets the crypto_policy_t at location policy to the policy for RTCP 664 * protection, as defined by the srtp_profile_t profile. 665 * 666 * This function is a convenience that helps to avoid dealing directly 667 * with the policy data structure. You are encouraged to initialize 668 * policy elements with this function call. Doing so may allow your 669 * code to be forward compatible with later versions of libSRTP that 670 * include more elements in the crypto_policy_t datatype. 671 * 672 * @return values 673 * - err_status_ok no problems were encountered 674 * - err_status_bad_param the profile is not supported 675 * 676 */ 677 err_status_t 678 crypto_policy_set_from_profile_for_rtcp(crypto_policy_t *policy, 679 srtp_profile_t profile); 680 681 /** 682 * @brief returns the master key length for a given SRTP profile 683 */ 684 unsigned int 685 srtp_profile_get_master_key_length(srtp_profile_t profile); 686 687 688 /** 689 * @brief returns the master salt length for a given SRTP profile 690 */ 691 unsigned int 692 srtp_profile_get_master_salt_length(srtp_profile_t profile); 693 694 /** 695 * @brief appends the salt to the key 696 * 697 * The function call append_salt_to_key(k, klen, s, slen) 698 * copies the string s to the location at klen bytes following 699 * the location k. 700 * 701 * @warning There must be at least bytes_in_salt + bytes_in_key bytes 702 * available at the location pointed to by key. 703 * 704 */ 705 706 void 707 append_salt_to_key(unsigned char *key, unsigned int bytes_in_key, 708 unsigned char *salt, unsigned int bytes_in_salt); 709 710 711 712 /** 713 * @} 714 */ 715 716 717 718 /** 719 * @defgroup SRTCP Secure RTCP 720 * @ingroup SRTP 721 * 722 * @brief Secure RTCP functions are used to protect RTCP traffic. 723 * 724 * RTCP is the control protocol for RTP. libSRTP protects RTCP 725 * traffic in much the same way as it does RTP traffic. The function 726 * srtp_protect_rtcp() applies cryptographic protections to outbound 727 * RTCP packets, and srtp_unprotect_rtcp() verifies the protections on 728 * inbound RTCP packets. 729 * 730 * A note on the naming convention: srtp_protect_rtcp() has an srtp_t 731 * as its first argument, and thus has `srtp_' as its prefix. The 732 * trailing `_rtcp' indicates the protocol on which it acts. 733 * 734 * @{ 735 */ 736 737 /** 738 * @brief srtp_protect_rtcp() is the Secure RTCP sender-side packet 739 * processing function. 740 * 741 * The function call srtp_protect_rtcp(ctx, rtp_hdr, len_ptr) applies 742 * SRTCP protection to the RTCP packet rtcp_hdr (which has length 743 * *len_ptr) using the SRTP session context ctx. If err_status_ok is 744 * returned, then rtp_hdr points to the resulting SRTCP packet and 745 * *len_ptr is the number of octets in that packet; otherwise, no 746 * assumptions should be made about the value of either data elements. 747 * 748 * @warning This function assumes that it can write the authentication 749 * tag into the location in memory immediately following the RTCP 750 * packet, and assumes that the RTCP packet is aligned on a 32-bit 751 * boundary. 752 * 753 * @param ctx is the SRTP context to use in processing the packet. 754 * 755 * @param rtcp_hdr is a pointer to the RTCP packet (before the call); after 756 * the function returns, it points to the srtp packet. 757 * 758 * @param pkt_octet_len is a pointer to the length in octets of the 759 * complete RTCP packet (header and body) before the function call, 760 * and of the complete SRTCP packet after the call, if err_status_ok 761 * was returned. Otherwise, the value of the data to which it points 762 * is undefined. 763 * 764 * @return 765 * - err_status_ok if there were no problems. 766 * - [other] if there was a failure in 767 * the cryptographic mechanisms. 768 */ 769 770 771 err_status_t 772 srtp_protect_rtcp(srtp_t ctx, void *rtcp_hdr, int *pkt_octet_len); 773 774 /** 775 * @brief srtp_unprotect_rtcp() is the Secure RTCP receiver-side packet 776 * processing function. 777 * 778 * The function call srtp_unprotect_rtcp(ctx, srtp_hdr, len_ptr) 779 * verifies the Secure RTCP protection of the SRTCP packet pointed to 780 * by srtcp_hdr (which has length *len_ptr), using the SRTP session 781 * context ctx. If err_status_ok is returned, then srtcp_hdr points 782 * to the resulting RTCP packet and *len_ptr is the number of octets 783 * in that packet; otherwise, no assumptions should be made about the 784 * value of either data elements. 785 * 786 * @warning This function assumes that the SRTCP packet is aligned on a 787 * 32-bit boundary. 788 * 789 * @param ctx is a pointer to the srtp_t which applies to the 790 * particular packet. 791 * 792 * @param srtcp_hdr is a pointer to the header of the SRTCP packet 793 * (before the call). After the function returns, it points to the 794 * rtp packet if err_status_ok was returned; otherwise, the value of 795 * the data to which it points is undefined. 796 * 797 * @param pkt_octet_len is a pointer to the length in octets of the 798 * complete SRTCP packet (header and body) before the function call, 799 * and of the complete rtp packet after the call, if err_status_ok was 800 * returned. Otherwise, the value of the data to which it points is 801 * undefined. 802 * 803 * @return 804 * - err_status_ok if the RTCP packet is valid. 805 * - err_status_auth_fail if the SRTCP packet failed the message 806 * authentication check. 807 * - err_status_replay_fail if the SRTCP packet is a replay (e.g. has 808 * already been processed and accepted). 809 * - [other] if there has been an error in the cryptographic mechanisms. 810 * 811 */ 812 813 err_status_t 814 srtp_unprotect_rtcp(srtp_t ctx, void *srtcp_hdr, int *pkt_octet_len); 815 816 /** 817 * @} 818 */ 819 820 /** 821 * @defgroup SRTPevents SRTP events and callbacks 822 * @ingroup SRTP 823 * 824 * @brief libSRTP can use a user-provided callback function to 825 * handle events. 826 * 827 * 828 * libSRTP allows a user to provide a callback function to handle 829 * events that need to be dealt with outside of the data plane (see 830 * the enum srtp_event_t for a description of these events). Dealing 831 * with these events is not a strict necessity; they are not 832 * security-critical, but the application may suffer if they are not 833 * handled. The function srtp_set_event_handler() is used to provide 834 * the callback function. 835 * 836 * A default event handler that merely reports on the events as they 837 * happen is included. It is also possible to set the event handler 838 * function to NULL, in which case all events will just be silently 839 * ignored. 840 * 841 * @{ 842 */ 843 844 /** 845 * @brief srtp_event_t defines events that need to be handled 846 * 847 * The enum srtp_event_t defines events that need to be handled 848 * outside the `data plane', such as SSRC collisions and 849 * key expirations. 850 * 851 * When a key expires or the maximum number of packets has been 852 * reached, an SRTP stream will enter an `expired' state in which no 853 * more packets can be protected or unprotected. When this happens, 854 * it is likely that you will want to either deallocate the stream 855 * (using srtp_stream_dealloc()), and possibly allocate a new one. 856 * 857 * When an SRTP stream expires, the other streams in the same session 858 * are unaffected, unless key sharing is used by that stream. In the 859 * latter case, all of the streams in the session will expire. 860 */ 861 862 typedef enum { 863 event_ssrc_collision, /**< 864 * An SSRC collision occured. 865 */ 866 event_key_soft_limit, /**< An SRTP stream reached the soft key 867 * usage limit and will expire soon. 868 */ 869 event_key_hard_limit, /**< An SRTP stream reached the hard 870 * key usage limit and has expired. 871 */ 872 event_packet_index_limit /**< An SRTP stream reached the hard 873 * packet limit (2^48 packets). 874 */ 875 } srtp_event_t; 876 877 /** 878 * @brief srtp_event_data_t is the structure passed as a callback to 879 * the event handler function 880 * 881 * The struct srtp_event_data_t holds the data passed to the event 882 * handler function. 883 */ 884 885 typedef struct srtp_event_data_t { 886 srtp_t session; /**< The session in which the event happend. */ 887 srtp_stream_t stream; /**< The stream in which the event happend. */ 888 srtp_event_t event; /**< An enum indicating the type of event. */ 889 } srtp_event_data_t; 890 891 /** 892 * @brief srtp_event_handler_func_t is the function prototype for 893 * the event handler. 894 * 895 * The typedef srtp_event_handler_func_t is the prototype for the 896 * event handler function. It has as its only argument an 897 * srtp_event_data_t which describes the event that needs to be handled. 898 * There can only be a single, global handler for all events in 899 * libSRTP. 900 */ 901 902 typedef void (srtp_event_handler_func_t)(srtp_event_data_t *data); 903 904 /** 905 * @brief sets the event handler to the function supplied by the caller. 906 * 907 * The function call srtp_install_event_handler(func) sets the event 908 * handler function to the value func. The value NULL is acceptable 909 * as an argument; in this case, events will be ignored rather than 910 * handled. 911 * 912 * @param func is a pointer to a fuction that takes an srtp_event_data_t 913 * pointer as an argument and returns void. This function 914 * will be used by libSRTP to handle events. 915 */ 916 917 err_status_t 918 srtp_install_event_handler(srtp_event_handler_func_t func); 919 920 /** 921 * @} 922 */ 923 /* in host order, so outside the #if */ 924 #define SRTCP_E_BIT 0x80000000 925 /* for byte-access */ 926 #define SRTCP_E_BYTE_BIT 0x80 927 #define SRTCP_INDEX_MASK 0x7fffffff 928 929 #ifdef __cplusplus 930 } 931 #endif 932 933 #endif /* SRTP_H */ 934