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_shutdown() de-initializes the srtp library. 280 * 281 * @warning No srtp functions may be called after calling this function. 282 */ 283 284 err_status_t 285 srtp_shutdown(void); 286 287 /** 288 * @brief srtp_protect() is the Secure RTP sender-side packet processing 289 * function. 290 * 291 * The function call srtp_protect(ctx, rtp_hdr, len_ptr) applies SRTP 292 * protection to the RTP packet rtp_hdr (which has length *len_ptr) using 293 * the SRTP context ctx. If err_status_ok is returned, then rtp_hdr 294 * points to the resulting SRTP packet and *len_ptr is the number of 295 * octets in that packet; otherwise, no assumptions should be made 296 * about the value of either data elements. 297 * 298 * The sequence numbers of the RTP packets presented to this function 299 * need not be consecutive, but they @b must be out of order by less 300 * than 2^15 = 32,768 packets. 301 * 302 * @warning This function assumes that it can write the authentication 303 * tag into the location in memory immediately following the RTP 304 * packet, and assumes that the RTP packet is aligned on a 32-bit 305 * boundary. 306 * 307 * @param ctx is the SRTP context to use in processing the packet. 308 * 309 * @param rtp_hdr is a pointer to the RTP packet (before the call); after 310 * the function returns, it points to the srtp packet. 311 * 312 * @param len_ptr is a pointer to the length in octets of the complete 313 * RTP packet (header and body) before the function call, and of the 314 * complete SRTP packet after the call, if err_status_ok was returned. 315 * Otherwise, the value of the data to which it points is undefined. 316 * 317 * @return 318 * - err_status_ok no problems 319 * - err_status_replay_fail rtp sequence number was non-increasing 320 * - @e other failure in cryptographic mechanisms 321 */ 322 323 err_status_t 324 srtp_protect(srtp_t ctx, void *rtp_hdr, int *len_ptr); 325 326 /** 327 * @brief srtp_unprotect() is the Secure RTP receiver-side packet 328 * processing function. 329 * 330 * The function call srtp_unprotect(ctx, srtp_hdr, len_ptr) verifies 331 * the Secure RTP protection of the SRTP packet pointed to by srtp_hdr 332 * (which has length *len_ptr), using the SRTP context ctx. If 333 * err_status_ok is returned, then srtp_hdr points to the resulting 334 * RTP packet and *len_ptr is the number of octets in that packet; 335 * otherwise, no assumptions should be made about the value of either 336 * data elements. 337 * 338 * The sequence numbers of the RTP packets presented to this function 339 * need not be consecutive, but they @b must be out of order by less 340 * than 2^15 = 32,768 packets. 341 * 342 * @warning This function assumes that the SRTP packet is aligned on a 343 * 32-bit boundary. 344 * 345 * @param ctx is a pointer to the srtp_t which applies to the 346 * particular packet. 347 * 348 * @param srtp_hdr is a pointer to the header of the SRTP packet 349 * (before the call). after the function returns, it points to the 350 * rtp packet if err_status_ok was returned; otherwise, the value of 351 * the data to which it points is undefined. 352 * 353 * @param len_ptr is a pointer to the length in octets of the complete 354 * srtp packet (header and body) before the function call, and of the 355 * complete rtp packet after the call, if err_status_ok was returned. 356 * Otherwise, the value of the data to which it points is undefined. 357 * 358 * @return 359 * - err_status_ok if the RTP packet is valid. 360 * - err_status_auth_fail if the SRTP packet failed the message 361 * authentication check. 362 * - err_status_replay_fail if the SRTP packet is a replay (e.g. packet has 363 * already been processed and accepted). 364 * - [other] if there has been an error in the cryptographic mechanisms. 365 * 366 */ 367 368 err_status_t 369 srtp_unprotect(srtp_t ctx, void *srtp_hdr, int *len_ptr); 370 371 372 /** 373 * @brief srtp_create() allocates and initializes an SRTP session. 374 375 * The function call srtp_create(session, policy, key) allocates and 376 * initializes an SRTP session context, applying the given policy and 377 * key. 378 * 379 * @param session is the SRTP session to which the policy is to be added. 380 * 381 * @param policy is the srtp_policy_t struct that describes the policy 382 * for the session. The struct may be a single element, or it may be 383 * the head of a list, in which case each element of the list is 384 * processed. It may also be NULL, in which case streams should be added 385 * later using srtp_add_stream(). The final element of the list @b must 386 * have its `next' field set to NULL. 387 * 388 * @return 389 * - err_status_ok if creation succeded. 390 * - err_status_alloc_fail if allocation failed. 391 * - err_status_init_fail if initialization failed. 392 */ 393 394 err_status_t 395 srtp_create(srtp_t *session, const srtp_policy_t *policy); 396 397 398 /** 399 * @brief srtp_add_stream() allocates and initializes an SRTP stream 400 * within a given SRTP session. 401 * 402 * The function call srtp_add_stream(session, policy) allocates and 403 * initializes a new SRTP stream within a given, previously created 404 * session, applying the policy given as the other argument to that 405 * stream. 406 * 407 * @return values: 408 * - err_status_ok if stream creation succeded. 409 * - err_status_alloc_fail if stream allocation failed 410 * - err_status_init_fail if stream initialization failed. 411 */ 412 413 err_status_t 414 srtp_add_stream(srtp_t session, 415 const srtp_policy_t *policy); 416 417 418 /** 419 * @brief srtp_remove_stream() deallocates an SRTP stream. 420 * 421 * The function call srtp_remove_stream(session, ssrc) removes 422 * the SRTP stream with the SSRC value ssrc from the SRTP session 423 * context given by the argument session. 424 * 425 * @param session is the SRTP session from which the stream 426 * will be removed. 427 * 428 * @param ssrc is the SSRC value of the stream to be removed. 429 * 430 * @warning Wildcard SSRC values cannot be removed from a 431 * session. 432 * 433 * @return 434 * - err_status_ok if the stream deallocation succeded. 435 * - [other] otherwise. 436 * 437 */ 438 439 err_status_t 440 srtp_remove_stream(srtp_t session, unsigned int ssrc); 441 442 /** 443 * @brief crypto_policy_set_rtp_default() sets a crypto policy 444 * structure to the SRTP default policy for RTP protection. 445 * 446 * @param p is a pointer to the policy structure to be set 447 * 448 * The function call crypto_policy_set_rtp_default(&p) sets the 449 * crypto_policy_t at location p to the SRTP default policy for RTP 450 * protection, as defined in the specification. This function is a 451 * convenience that helps to avoid dealing directly with the policy 452 * data structure. You are encouraged to initialize policy elements 453 * with this function call. Doing so may allow your code to be 454 * forward compatible with later versions of libSRTP that include more 455 * elements in the crypto_policy_t datatype. 456 * 457 * @return void. 458 * 459 */ 460 461 void 462 crypto_policy_set_rtp_default(crypto_policy_t *p); 463 464 /** 465 * @brief crypto_policy_set_rtcp_default() sets a crypto policy 466 * structure to the SRTP default policy for RTCP protection. 467 * 468 * @param p is a pointer to the policy structure to be set 469 * 470 * The function call crypto_policy_set_rtcp_default(&p) sets the 471 * crypto_policy_t at location p to the SRTP default policy for RTCP 472 * protection, as defined in the specification. This function is a 473 * convenience that helps to avoid dealing directly with the policy 474 * data structure. You are encouraged to initialize policy elements 475 * with this function call. Doing so may allow your code to be 476 * forward compatible with later versions of libSRTP that include more 477 * elements in the crypto_policy_t datatype. 478 * 479 * @return void. 480 * 481 */ 482 483 void 484 crypto_policy_set_rtcp_default(crypto_policy_t *p); 485 486 /** 487 * @brief crypto_policy_set_aes_cm_128_hmac_sha1_80() sets a crypto 488 * policy structure to the SRTP default policy for RTP protection. 489 * 490 * @param p is a pointer to the policy structure to be set 491 * 492 * The function crypto_policy_set_aes_cm_128_hmac_sha1_80() is a 493 * synonym for crypto_policy_set_rtp_default(). It conforms to the 494 * naming convention used in RFC 4568 (SDP Security Descriptions for 495 * Media Streams). 496 * 497 * @return void. 498 * 499 */ 500 501 #define crypto_policy_set_aes_cm_128_hmac_sha1_80(p) crypto_policy_set_rtp_default(p) 502 503 504 /** 505 * @brief crypto_policy_set_aes_cm_128_hmac_sha1_32() sets a crypto 506 * policy structure to a short-authentication tag policy 507 * 508 * @param p is a pointer to the policy structure to be set 509 * 510 * The function call crypto_policy_set_aes_cm_128_hmac_sha1_32(&p) 511 * sets the crypto_policy_t at location p to use policy 512 * AES_CM_128_HMAC_SHA1_32 as defined in RFC 4568. 513 * This policy uses AES-128 514 * Counter Mode encryption and HMAC-SHA1 authentication, with an 515 * authentication tag that is only 32 bits long. This length is 516 * considered adequate only for protecting audio and video media that 517 * use a stateless playback function. See Section 7.5 of RFC 3711 518 * (http://www.ietf.org/rfc/rfc3711.txt). 519 * 520 * This function is a convenience that helps to avoid dealing directly 521 * with the policy data structure. You are encouraged to initialize 522 * policy elements with this function call. Doing so may allow your 523 * code to be forward compatible with later versions of libSRTP that 524 * include more elements in the crypto_policy_t datatype. 525 * 526 * @warning This crypto policy is intended for use in SRTP, but not in 527 * SRTCP. It is recommended that a policy that uses longer 528 * authentication tags be used for SRTCP. See Section 7.5 of RFC 3711 529 * (http://www.ietf.org/rfc/rfc3711.txt). 530 * 531 * @return void. 532 * 533 */ 534 535 void 536 crypto_policy_set_aes_cm_128_hmac_sha1_32(crypto_policy_t *p); 537 538 539 540 /** 541 * @brief crypto_policy_set_aes_cm_128_null_auth() sets a crypto 542 * policy structure to an encryption-only policy 543 * 544 * @param p is a pointer to the policy structure to be set 545 * 546 * The function call crypto_policy_set_aes_cm_128_null_auth(&p) sets 547 * the crypto_policy_t at location p to use the SRTP default cipher 548 * (AES-128 Counter Mode), but to use no authentication method. This 549 * policy is NOT RECOMMENDED unless it is unavoidable; see Section 7.5 550 * of RFC 3711 (http://www.ietf.org/rfc/rfc3711.txt). 551 * 552 * This function is a convenience that helps to avoid dealing directly 553 * with the policy data structure. You are encouraged to initialize 554 * policy elements with this function call. Doing so may allow your 555 * code to be forward compatible with later versions of libSRTP that 556 * include more elements in the crypto_policy_t datatype. 557 * 558 * @warning This policy is NOT RECOMMENDED for SRTP unless it is 559 * unavoidable, and it is NOT RECOMMENDED at all for SRTCP; see 560 * Section 7.5 of RFC 3711 (http://www.ietf.org/rfc/rfc3711.txt). 561 * 562 * @return void. 563 * 564 */ 565 566 void 567 crypto_policy_set_aes_cm_128_null_auth(crypto_policy_t *p); 568 569 570 /** 571 * @brief crypto_policy_set_null_cipher_hmac_sha1_80() sets a crypto 572 * policy structure to an authentication-only policy 573 * 574 * @param p is a pointer to the policy structure to be set 575 * 576 * The function call crypto_policy_set_null_cipher_hmac_sha1_80(&p) 577 * sets the crypto_policy_t at location p to use HMAC-SHA1 with an 80 578 * bit authentication tag to provide message authentication, but to 579 * use no encryption. This policy is NOT RECOMMENDED for SRTP unless 580 * there is a requirement to forego encryption. 581 * 582 * This function is a convenience that helps to avoid dealing directly 583 * with the policy data structure. You are encouraged to initialize 584 * policy elements with this function call. Doing so may allow your 585 * code to be forward compatible with later versions of libSRTP that 586 * include more elements in the crypto_policy_t datatype. 587 * 588 * @warning This policy is NOT RECOMMENDED for SRTP unless there is a 589 * requirement to forego encryption. 590 * 591 * @return void. 592 * 593 */ 594 595 void 596 crypto_policy_set_null_cipher_hmac_sha1_80(crypto_policy_t *p); 597 598 599 /** 600 * @brief crypto_policy_set_aes_cm_256_hmac_sha1_80() sets a crypto 601 * policy structure to a encryption and authentication policy using AES-256 602 * for RTP protection. 603 * 604 * @param p is a pointer to the policy structure to be set 605 * 606 * The function call crypto_policy_set_aes_cm_256_hmac_sha1_80(&p) 607 * sets the crypto_policy_t at location p to use policy 608 * AES_CM_256_HMAC_SHA1_80 as defined in 609 * draft-ietf-avt-srtp-big-aes-03.txt. This policy uses AES-256 610 * Counter Mode encryption and HMAC-SHA1 authentication, with an 80 bit 611 * authentication tag. 612 * 613 * This function is a convenience that helps to avoid dealing directly 614 * with the policy data structure. You are encouraged to initialize 615 * policy elements with this function call. Doing so may allow your 616 * code to be forward compatible with later versions of libSRTP that 617 * include more elements in the crypto_policy_t datatype. 618 * 619 * @return void. 620 * 621 */ 622 623 void crypto_policy_set_aes_cm_256_hmac_sha1_80(crypto_policy_t *p); 624 625 626 /** 627 * @brief crypto_policy_set_aes_cm_256_hmac_sha1_32() sets a crypto 628 * policy structure to a short-authentication tag policy using AES-256 629 * encryption. 630 * 631 * @param p is a pointer to the policy structure to be set 632 * 633 * The function call crypto_policy_set_aes_cm_256_hmac_sha1_32(&p) 634 * sets the crypto_policy_t at location p to use policy 635 * AES_CM_256_HMAC_SHA1_32 as defined in 636 * draft-ietf-avt-srtp-big-aes-03.txt. This policy uses AES-256 637 * Counter Mode encryption and HMAC-SHA1 authentication, with an 638 * authentication tag that is only 32 bits long. This length is 639 * considered adequate only for protecting audio and video media that 640 * use a stateless playback function. See Section 7.5 of RFC 3711 641 * (http://www.ietf.org/rfc/rfc3711.txt). 642 * 643 * This function is a convenience that helps to avoid dealing directly 644 * with the policy data structure. You are encouraged to initialize 645 * policy elements with this function call. Doing so may allow your 646 * code to be forward compatible with later versions of libSRTP that 647 * include more elements in the crypto_policy_t datatype. 648 * 649 * @warning This crypto policy is intended for use in SRTP, but not in 650 * SRTCP. It is recommended that a policy that uses longer 651 * authentication tags be used for SRTCP. See Section 7.5 of RFC 3711 652 * (http://www.ietf.org/rfc/rfc3711.txt). 653 * 654 * @return void. 655 * 656 */ 657 658 void 659 crypto_policy_set_aes_cm_256_hmac_sha1_32(crypto_policy_t *p); 660 661 662 /** 663 * @brief srtp_dealloc() deallocates storage for an SRTP session 664 * context. 665 * 666 * The function call srtp_dealloc(s) deallocates storage for the 667 * SRTP session context s. This function should be called no more 668 * than one time for each of the contexts allocated by the function 669 * srtp_create(). 670 * 671 * @param s is the srtp_t for the session to be deallocated. 672 * 673 * @return 674 * - err_status_ok if there no problems. 675 * - err_status_dealloc_fail a memory deallocation failure occured. 676 */ 677 678 err_status_t 679 srtp_dealloc(srtp_t s); 680 681 682 /* 683 * @brief identifies a particular SRTP profile 684 * 685 * An srtp_profile_t enumeration is used to identify a particular SRTP 686 * profile (that is, a set of algorithms and parameters). These 687 * profiles are defined in the DTLS-SRTP draft. 688 */ 689 690 typedef enum { 691 srtp_profile_reserved = 0, 692 srtp_profile_aes128_cm_sha1_80 = 1, 693 srtp_profile_aes128_cm_sha1_32 = 2, 694 srtp_profile_aes256_cm_sha1_80 = 3, 695 srtp_profile_aes256_cm_sha1_32 = 4, 696 srtp_profile_null_sha1_80 = 5, 697 srtp_profile_null_sha1_32 = 6, 698 } srtp_profile_t; 699 700 701 /** 702 * @brief crypto_policy_set_from_profile_for_rtp() sets a crypto policy 703 * structure to the appropriate value for RTP based on an srtp_profile_t 704 * 705 * @param p is a pointer to the policy structure to be set 706 * 707 * The function call crypto_policy_set_rtp_default(&policy, profile) 708 * sets the crypto_policy_t at location policy to the policy for RTP 709 * protection, as defined by the srtp_profile_t profile. 710 * 711 * This function is a convenience that helps to avoid dealing directly 712 * with the policy data structure. You are encouraged to initialize 713 * policy elements with this function call. Doing so may allow your 714 * code to be forward compatible with later versions of libSRTP that 715 * include more elements in the crypto_policy_t datatype. 716 * 717 * @return values 718 * - err_status_ok no problems were encountered 719 * - err_status_bad_param the profile is not supported 720 * 721 */ 722 err_status_t 723 crypto_policy_set_from_profile_for_rtp(crypto_policy_t *policy, 724 srtp_profile_t profile); 725 726 727 728 729 /** 730 * @brief crypto_policy_set_from_profile_for_rtcp() sets a crypto policy 731 * structure to the appropriate value for RTCP based on an srtp_profile_t 732 * 733 * @param p is a pointer to the policy structure to be set 734 * 735 * The function call crypto_policy_set_rtcp_default(&policy, profile) 736 * sets the crypto_policy_t at location policy to the policy for RTCP 737 * protection, as defined by the srtp_profile_t profile. 738 * 739 * This function is a convenience that helps to avoid dealing directly 740 * with the policy data structure. You are encouraged to initialize 741 * policy elements with this function call. Doing so may allow your 742 * code to be forward compatible with later versions of libSRTP that 743 * include more elements in the crypto_policy_t datatype. 744 * 745 * @return values 746 * - err_status_ok no problems were encountered 747 * - err_status_bad_param the profile is not supported 748 * 749 */ 750 err_status_t 751 crypto_policy_set_from_profile_for_rtcp(crypto_policy_t *policy, 752 srtp_profile_t profile); 753 754 /** 755 * @brief returns the master key length for a given SRTP profile 756 */ 757 unsigned int 758 srtp_profile_get_master_key_length(srtp_profile_t profile); 759 760 761 /** 762 * @brief returns the master salt length for a given SRTP profile 763 */ 764 unsigned int 765 srtp_profile_get_master_salt_length(srtp_profile_t profile); 766 767 /** 768 * @brief appends the salt to the key 769 * 770 * The function call append_salt_to_key(k, klen, s, slen) 771 * copies the string s to the location at klen bytes following 772 * the location k. 773 * 774 * @warning There must be at least bytes_in_salt + bytes_in_key bytes 775 * available at the location pointed to by key. 776 * 777 */ 778 779 void 780 append_salt_to_key(unsigned char *key, unsigned int bytes_in_key, 781 unsigned char *salt, unsigned int bytes_in_salt); 782 783 784 785 /** 786 * @} 787 */ 788 789 790 791 /** 792 * @defgroup SRTCP Secure RTCP 793 * @ingroup SRTP 794 * 795 * @brief Secure RTCP functions are used to protect RTCP traffic. 796 * 797 * RTCP is the control protocol for RTP. libSRTP protects RTCP 798 * traffic in much the same way as it does RTP traffic. The function 799 * srtp_protect_rtcp() applies cryptographic protections to outbound 800 * RTCP packets, and srtp_unprotect_rtcp() verifies the protections on 801 * inbound RTCP packets. 802 * 803 * A note on the naming convention: srtp_protect_rtcp() has an srtp_t 804 * as its first argument, and thus has `srtp_' as its prefix. The 805 * trailing `_rtcp' indicates the protocol on which it acts. 806 * 807 * @{ 808 */ 809 810 /** 811 * @brief srtp_protect_rtcp() is the Secure RTCP sender-side packet 812 * processing function. 813 * 814 * The function call srtp_protect_rtcp(ctx, rtp_hdr, len_ptr) applies 815 * SRTCP protection to the RTCP packet rtcp_hdr (which has length 816 * *len_ptr) using the SRTP session context ctx. If err_status_ok is 817 * returned, then rtp_hdr points to the resulting SRTCP packet and 818 * *len_ptr is the number of octets in that packet; otherwise, no 819 * assumptions should be made about the value of either data elements. 820 * 821 * @warning This function assumes that it can write the authentication 822 * tag into the location in memory immediately following the RTCP 823 * packet, and assumes that the RTCP packet is aligned on a 32-bit 824 * boundary. 825 * 826 * @param ctx is the SRTP context to use in processing the packet. 827 * 828 * @param rtcp_hdr is a pointer to the RTCP packet (before the call); after 829 * the function returns, it points to the srtp packet. 830 * 831 * @param pkt_octet_len is a pointer to the length in octets of the 832 * complete RTCP packet (header and body) before the function call, 833 * and of the complete SRTCP packet after the call, if err_status_ok 834 * was returned. Otherwise, the value of the data to which it points 835 * is undefined. 836 * 837 * @return 838 * - err_status_ok if there were no problems. 839 * - [other] if there was a failure in 840 * the cryptographic mechanisms. 841 */ 842 843 844 err_status_t 845 srtp_protect_rtcp(srtp_t ctx, void *rtcp_hdr, int *pkt_octet_len); 846 847 /** 848 * @brief srtp_unprotect_rtcp() is the Secure RTCP receiver-side packet 849 * processing function. 850 * 851 * The function call srtp_unprotect_rtcp(ctx, srtp_hdr, len_ptr) 852 * verifies the Secure RTCP protection of the SRTCP packet pointed to 853 * by srtcp_hdr (which has length *len_ptr), using the SRTP session 854 * context ctx. If err_status_ok is returned, then srtcp_hdr points 855 * to the resulting RTCP packet and *len_ptr is the number of octets 856 * in that packet; otherwise, no assumptions should be made about the 857 * value of either data elements. 858 * 859 * @warning This function assumes that the SRTCP packet is aligned on a 860 * 32-bit boundary. 861 * 862 * @param ctx is a pointer to the srtp_t which applies to the 863 * particular packet. 864 * 865 * @param srtcp_hdr is a pointer to the header of the SRTCP packet 866 * (before the call). After the function returns, it points to the 867 * rtp packet if err_status_ok was returned; otherwise, the value of 868 * the data to which it points is undefined. 869 * 870 * @param pkt_octet_len is a pointer to the length in octets of the 871 * complete SRTCP packet (header and body) before the function call, 872 * and of the complete rtp packet after the call, if err_status_ok was 873 * returned. Otherwise, the value of the data to which it points is 874 * undefined. 875 * 876 * @return 877 * - err_status_ok if the RTCP packet is valid. 878 * - err_status_auth_fail if the SRTCP packet failed the message 879 * authentication check. 880 * - err_status_replay_fail if the SRTCP packet is a replay (e.g. has 881 * already been processed and accepted). 882 * - [other] if there has been an error in the cryptographic mechanisms. 883 * 884 */ 885 886 err_status_t 887 srtp_unprotect_rtcp(srtp_t ctx, void *srtcp_hdr, int *pkt_octet_len); 888 889 /** 890 * @} 891 */ 892 893 /** 894 * @defgroup SRTPevents SRTP events and callbacks 895 * @ingroup SRTP 896 * 897 * @brief libSRTP can use a user-provided callback function to 898 * handle events. 899 * 900 * 901 * libSRTP allows a user to provide a callback function to handle 902 * events that need to be dealt with outside of the data plane (see 903 * the enum srtp_event_t for a description of these events). Dealing 904 * with these events is not a strict necessity; they are not 905 * security-critical, but the application may suffer if they are not 906 * handled. The function srtp_set_event_handler() is used to provide 907 * the callback function. 908 * 909 * A default event handler that merely reports on the events as they 910 * happen is included. It is also possible to set the event handler 911 * function to NULL, in which case all events will just be silently 912 * ignored. 913 * 914 * @{ 915 */ 916 917 /** 918 * @brief srtp_event_t defines events that need to be handled 919 * 920 * The enum srtp_event_t defines events that need to be handled 921 * outside the `data plane', such as SSRC collisions and 922 * key expirations. 923 * 924 * When a key expires or the maximum number of packets has been 925 * reached, an SRTP stream will enter an `expired' state in which no 926 * more packets can be protected or unprotected. When this happens, 927 * it is likely that you will want to either deallocate the stream 928 * (using srtp_stream_dealloc()), and possibly allocate a new one. 929 * 930 * When an SRTP stream expires, the other streams in the same session 931 * are unaffected, unless key sharing is used by that stream. In the 932 * latter case, all of the streams in the session will expire. 933 */ 934 935 typedef enum { 936 event_ssrc_collision, /**< 937 * An SSRC collision occured. 938 */ 939 event_key_soft_limit, /**< An SRTP stream reached the soft key 940 * usage limit and will expire soon. 941 */ 942 event_key_hard_limit, /**< An SRTP stream reached the hard 943 * key usage limit and has expired. 944 */ 945 event_packet_index_limit /**< An SRTP stream reached the hard 946 * packet limit (2^48 packets). 947 */ 948 } srtp_event_t; 949 950 /** 951 * @brief srtp_event_data_t is the structure passed as a callback to 952 * the event handler function 953 * 954 * The struct srtp_event_data_t holds the data passed to the event 955 * handler function. 956 */ 957 958 typedef struct srtp_event_data_t { 959 srtp_t session; /**< The session in which the event happend. */ 960 srtp_stream_t stream; /**< The stream in which the event happend. */ 961 srtp_event_t event; /**< An enum indicating the type of event. */ 962 } srtp_event_data_t; 963 964 /** 965 * @brief srtp_event_handler_func_t is the function prototype for 966 * the event handler. 967 * 968 * The typedef srtp_event_handler_func_t is the prototype for the 969 * event handler function. It has as its only argument an 970 * srtp_event_data_t which describes the event that needs to be handled. 971 * There can only be a single, global handler for all events in 972 * libSRTP. 973 */ 974 975 typedef void (srtp_event_handler_func_t)(srtp_event_data_t *data); 976 977 /** 978 * @brief sets the event handler to the function supplied by the caller. 979 * 980 * The function call srtp_install_event_handler(func) sets the event 981 * handler function to the value func. The value NULL is acceptable 982 * as an argument; in this case, events will be ignored rather than 983 * handled. 984 * 985 * @param func is a pointer to a fuction that takes an srtp_event_data_t 986 * pointer as an argument and returns void. This function 987 * will be used by libSRTP to handle events. 988 */ 989 990 err_status_t 991 srtp_install_event_handler(srtp_event_handler_func_t func); 992 993 /** 994 * @} 995 */ 996 /* in host order, so outside the #if */ 997 #define SRTCP_E_BIT 0x80000000 998 /* for byte-access */ 999 #define SRTCP_E_BYTE_BIT 0x80 1000 #define SRTCP_INDEX_MASK 0x7fffffff 1001 1002 #ifdef __cplusplus 1003 } 1004 #endif 1005 1006 #endif /* SRTP_H */ 1007
