11 * Copyright (c) 2001-2017, Cisco Systems, Inc.
12 * All rights reserved.
14 * Redistribution and use in source and binary forms, with or without
15 * modification, are permitted provided that the following conditions
18 * Redistributions of source code must retain the above copyright
19 * notice, this list of conditions and the following disclaimer.
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.
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.
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.
55 * @defgroup SRTP Secure RTP
57 * @brief libSRTP provides functions for protecting RTP and RTCP. See
58 * Section @ref Overview for an introduction to the use of the library.
64 * SRTP_MASTER_KEY_LEN is the nominal master key length supported by libSRTP
67 #define SRTP_MASTER_KEY_LEN 30
70 * SRTP_MAX_KEY_LEN is the maximum key length supported by libSRTP
72 #define SRTP_MAX_KEY_LEN 64
75 * SRTP_MAX_TAG_LEN is the maximum tag length supported by libSRTP
78 #define SRTP_MAX_TAG_LEN 16
81 * SRTP_MAX_MKI_LEN is the maximum size the MKI could be which is
84 #define SRTP_MAX_MKI_LEN 128
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
92 * @brief the maximum number of octets added by srtp_protect().
94 #define SRTP_MAX_TRAILER_LEN (SRTP_MAX_TAG_LEN + SRTP_MAX_MKI_LEN)
97 * SRTP_MAX_NUM_MASTER_KEYS is the maximum number of Master keys for
98 * MKI supported by libSRTP.
101 #define SRTP_MAX_NUM_MASTER_KEYS 16
103 #define SRTP_SALT_LEN 14
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.
110 #define SRTP_AEAD_SALT_LEN 12
112 #define SRTP_AES_128_KEY_LEN 16
113 #define SRTP_AES_192_KEY_LEN 24
114 #define SRTP_AES_256_KEY_LEN 32
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)
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)
128 * @brief A srtp_cipher_type_id_t is an identifier for a particular cipher
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
139 typedef uint32_t srtp_cipher_type_id_t;
142 * @brief An srtp_auth_type_id_t is an identifier for a particular
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
152 * @ingroup Authentication
154 typedef uint32_t srtp_auth_type_id_t;
157 * @brief srtp_err_status_t defines error codes.
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
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 */
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 */
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 */
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 */
195 srtp_err_status_pkt_idx_old = 26, /**< packet index is too old to */
197 srtp_err_status_pkt_idx_adv = 27 /**< packet index advanced, reset */
201 typedef struct srtp_ctx_t_ srtp_ctx_t;
204 * @brief srtp_sec_serv_t describes a set of security services.
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).
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 */
218 * @brief srtp_crypto_policy_t describes a particular crypto policy that
219 * can be applied to an SRTP stream.
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
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 */
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;
242 * @brief srtp_ssrc_type_t describes the type of an SSRC.
244 * An srtp_ssrc_type_t enumeration is used to indicate a type of SSRC. See
245 * @ref srtp_policy_t for more informataion.
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()) */
259 * @brief An srtp_ssrc_t represents a particular SSRC value, or a `wildcard'
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).
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 */
274 * @brief points to an EKT policy
276 typedef struct srtp_ekt_policy_ctx_t *srtp_ekt_policy_t;
279 * @brief points to EKT stream data
281 typedef struct srtp_ekt_stream_ctx_t *srtp_ekt_stream_t;
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.
289 typedef struct srtp_master_key_t {
291 unsigned char *mki_id;
292 unsigned int mki_size;
296 * @brief represents the policy for an SRTP session.
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.
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
317 * @warning The final element of the list @b must have its `next' pointer
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 */
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 */
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 */
346 struct srtp_policy_t *next; /**< Pointer to next stream policy. */
350 * @brief An srtp_t points to an SRTP session structure.
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.
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.
361 typedef srtp_ctx_t *srtp_t;
364 * @brief srtp_init() initializes the srtp library.
366 * @warning This function @b must be called before any other srtp
369 srtp_err_status_t srtp_init(void);
372 * @brief srtp_shutdown() de-initializes the srtp library.
374 * @warning No srtp functions may be called after calling this function.
376 srtp_err_status_t srtp_shutdown(void);
379 * @brief srtp_protect() is the Secure RTP sender-side packet processing
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.
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.
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
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.
403 * @param ctx is the SRTP context to use in processing the packet.
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.
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.
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
418 srtp_err_status_t srtp_protect(srtp_t ctx, void *rtp_hdr, int *len_ptr);
421 * @brief srtp_protect_mki() is the Secure RTP sender-side packet processing
422 * function that can utilize MKI.
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.
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.
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
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.
445 * @param ctx is the SRTP context to use in processing the packet.
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.
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.
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
458 * use the session keys identified by the mki_index
460 * @param mki_index integer value specifying which set of session keys should be
461 * used if use_mki is set to true.
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
468 srtp_err_status_t srtp_protect_mki(srtp_ctx_t *ctx,
471 unsigned int use_mki,
472 unsigned int mki_index);
475 * @brief srtp_unprotect() is the Secure RTP receiver-side packet
476 * processing function.
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
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.
490 * @warning This function assumes that the SRTP packet is aligned on a
493 * @param ctx is the SRTP session which applies to the particular packet.
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.
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.
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.
514 srtp_err_status_t srtp_unprotect(srtp_t ctx, void *srtp_hdr, int *len_ptr);
517 * @brief srtp_unprotect_mki() is the Secure RTP receiver-side packet
518 * processing function that checks for MKI.
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
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.
532 * @warning This function assumes that the SRTP packet is aligned on a
535 * @param ctx is the SRTP session which applies to the particular packet.
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.
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.
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
550 * use the session keys identified by the mki_index
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.
562 srtp_err_status_t srtp_unprotect_mki(srtp_t ctx,
565 unsigned int use_mki);
568 * @brief srtp_create() allocates and initializes an SRTP session.
570 * The function call srtp_create(session, policy) allocates and
571 * initializes an SRTP session context, applying the given policy.
573 * @param session is a pointer to the SRTP session to which the policy is
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.
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.
588 srtp_err_status_t srtp_create(srtp_t *session, const srtp_policy_t *policy);
591 * @brief srtp_add_stream() allocates and initializes an SRTP stream
592 * within a given SRTP session.
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
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.
604 srtp_err_status_t srtp_add_stream(srtp_t session, const srtp_policy_t *policy);
607 * @brief srtp_remove_stream() deallocates an SRTP stream.
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.
613 * @param session is the SRTP session from which the stream
616 * @param ssrc is the SSRC value of the stream to be removed
617 * in network byte order.
619 * @warning Wildcard SSRC values cannot be removed from a
623 * - srtp_err_status_ok if the stream deallocation succeded.
624 * - [other] otherwise.
627 srtp_err_status_t srtp_remove_stream(srtp_t session, unsigned int ssrc);
630 * @brief srtp_update() udpates all streams in the session.
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
637 * @param session is the SRTP session that contains the streams
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.
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.
653 srtp_err_status_t srtp_update(srtp_t session, const srtp_policy_t *policy);
656 * @brief srtp_update_stream() udpates a SRTP stream.
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
663 * @param session is the SRTP session that contains the streams
666 * @param policy is the srtp_policy_t struct that describes the policy
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.
676 srtp_err_status_t srtp_update_stream(srtp_t session,
677 const srtp_policy_t *policy);
680 * @brief srtp_crypto_policy_set_rtp_default() sets a crypto policy
681 * structure to the SRTP default policy for RTP protection.
683 * @param p is a pointer to the policy structure to be set
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.
697 void srtp_crypto_policy_set_rtp_default(srtp_crypto_policy_t *p);
700 * @brief srtp_crypto_policy_set_rtcp_default() sets a crypto policy
701 * structure to the SRTP default policy for RTCP protection.
703 * @param p is a pointer to the policy structure to be set
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.
717 void srtp_crypto_policy_set_rtcp_default(srtp_crypto_policy_t *p);
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.
723 * @param p is a pointer to the policy structure to be set
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
733 #define srtp_crypto_policy_set_aes_cm_128_hmac_sha1_80(p) \
734 srtp_crypto_policy_set_rtp_default(p)
737 * @brief srtp_crypto_policy_set_aes_cm_128_hmac_sha1_32() sets a crypto
738 * policy structure to a short-authentication tag policy
740 * @param p is a pointer to the policy structure to be set
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).
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.
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).
766 void srtp_crypto_policy_set_aes_cm_128_hmac_sha1_32(srtp_crypto_policy_t *p);
769 * @brief srtp_crypto_policy_set_aes_cm_128_null_auth() sets a crypto
770 * policy structure to an encryption-only policy
772 * @param p is a pointer to the policy structure to be set
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).
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.
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).
793 void srtp_crypto_policy_set_aes_cm_128_null_auth(srtp_crypto_policy_t *p);
796 * @brief srtp_crypto_policy_set_null_cipher_hmac_sha1_80() sets a crypto
797 * policy structure to an authentication-only policy
799 * @param p is a pointer to the policy structure to be set
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.
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.
813 * @warning This policy is NOT RECOMMENDED for SRTP unless there is a
814 * requirement to forego encryption.
819 void srtp_crypto_policy_set_null_cipher_hmac_sha1_80(srtp_crypto_policy_t *p);
822 * @brief srtp_crypto_policy_set_null_cipher_hmac_null() sets a crypto
823 * policy structure to use no encryption or authentication.
825 * @param p is a pointer to the policy structure to be set
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
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.
838 * @warning This policy is NOT RECOMMENDED for SRTP unless there is a
839 * requirement to forego encryption and authentication.
844 void srtp_crypto_policy_set_null_cipher_hmac_null(srtp_crypto_policy_t *p);
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.
851 * @param p is a pointer to the policy structure to be set
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.
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.
868 void srtp_crypto_policy_set_aes_cm_256_hmac_sha1_80(srtp_crypto_policy_t *p);
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
875 * @param p is a pointer to the policy structure to be set
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).
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.
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).
900 void srtp_crypto_policy_set_aes_cm_256_hmac_sha1_32(srtp_crypto_policy_t *p);
903 * @brief srtp_crypto_policy_set_aes_cm_256_null_auth() sets a crypto
904 * policy structure to an encryption-only policy
906 * @param p is a pointer to the policy structure to be set
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).
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.
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).
927 void srtp_crypto_policy_set_aes_cm_256_null_auth(srtp_crypto_policy_t *p);
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.
934 * @param p is a pointer to the policy structure to be set
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.
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.
951 void srtp_crypto_policy_set_aes_cm_192_hmac_sha1_80(srtp_crypto_policy_t *p);
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
958 * @param p is a pointer to the policy structure to be set
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).
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.
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).
983 void srtp_crypto_policy_set_aes_cm_192_hmac_sha1_32(srtp_crypto_policy_t *p);
986 * @brief srtp_crypto_policy_set_aes_cm_192_null_auth() sets a crypto
987 * policy structure to an encryption-only policy
989 * @param p is a pointer to the policy structure to be set
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).
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.
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).
1010 void srtp_crypto_policy_set_aes_cm_192_null_auth(srtp_crypto_policy_t *p);
1013 * @brief srtp_crypto_policy_set_aes_gcm_128_8_auth() sets a crypto
1014 * policy structure to an AEAD encryption policy.
1016 * @param p is a pointer to the policy structure to be set
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.
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.
1033 void srtp_crypto_policy_set_aes_gcm_128_8_auth(srtp_crypto_policy_t *p);
1036 * @brief srtp_crypto_policy_set_aes_gcm_256_8_auth() sets a crypto
1037 * policy structure to an AEAD encryption policy
1039 * @param p is a pointer to the policy structure to be set
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.
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.
1056 void srtp_crypto_policy_set_aes_gcm_256_8_auth(srtp_crypto_policy_t *p);
1059 * @brief srtp_crypto_policy_set_aes_gcm_128_8_only_auth() sets a crypto
1060 * policy structure to an AEAD authentication-only policy
1062 * @param p is a pointer to the policy structure to be set
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.
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.
1079 void srtp_crypto_policy_set_aes_gcm_128_8_only_auth(srtp_crypto_policy_t *p);
1082 * @brief srtp_crypto_policy_set_aes_gcm_256_8_only_auth() sets a crypto
1083 * policy structure to an AEAD authentication-only policy
1085 * @param p is a pointer to the policy structure to be set
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.
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.
1102 void srtp_crypto_policy_set_aes_gcm_256_8_only_auth(srtp_crypto_policy_t *p);
1105 * @brief srtp_crypto_policy_set_aes_gcm_128_16_auth() sets a crypto
1106 * policy structure to an AEAD encryption policy.
1108 * @param p is a pointer to the policy structure to be set
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.
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.
1125 void srtp_crypto_policy_set_aes_gcm_128_16_auth(srtp_crypto_policy_t *p);
1128 * @brief srtp_crypto_policy_set_aes_gcm_256_16_auth() sets a crypto
1129 * policy structure to an AEAD encryption policy
1131 * @param p is a pointer to the policy structure to be set
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.
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.
1148 void srtp_crypto_policy_set_aes_gcm_256_16_auth(srtp_crypto_policy_t *p);
1151 * @brief srtp_dealloc() deallocates storage for an SRTP session
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
1159 * @param s is the srtp_t for the session to be deallocated.
1162 * - srtp_err_status_ok if there no problems.
1163 * - srtp_err_status_dealloc_fail a memory deallocation failure occured.
1165 srtp_err_status_t srtp_dealloc(srtp_t s);
1168 * @brief identifies a particular SRTP profile
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
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,
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
1189 * @param policy is a pointer to the policy structure to be set
1191 * @param profile is an enumeration for the policy to be set
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.
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.
1204 * - srtp_err_status_ok no problems were encountered
1205 * - srtp_err_status_bad_param the profile is not supported
1208 srtp_err_status_t srtp_crypto_policy_set_from_profile_for_rtp(
1209 srtp_crypto_policy_t *policy,
1210 srtp_profile_t profile);
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
1216 * @param policy is a pointer to the policy structure to be set
1218 * @param profile is an enumeration for the policy to be set
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.
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.
1231 * - srtp_err_status_ok no problems were encountered
1232 * - srtp_err_status_bad_param the profile is not supported
1235 srtp_err_status_t srtp_crypto_policy_set_from_profile_for_rtcp(
1236 srtp_crypto_policy_t *policy,
1237 srtp_profile_t profile);
1240 * @brief returns the master key length for a given SRTP profile
1242 unsigned int srtp_profile_get_master_key_length(srtp_profile_t profile);
1245 * @brief returns the master salt length for a given SRTP profile
1247 unsigned int srtp_profile_get_master_salt_length(srtp_profile_t profile);
1250 * @brief appends the salt to the key
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
1256 * @warning There must be at least bytes_in_salt + bytes_in_key bytes
1257 * available at the location pointed to by key.
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);
1270 * @defgroup SRTCP Secure RTCP
1273 * @brief Secure RTCP functions are used to protect RTCP traffic.
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.
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.
1289 * @brief srtp_protect_rtcp() is the Secure RTCP sender-side packet
1290 * processing function.
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.
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
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.
1309 * @param ctx is the SRTP context to use in processing the packet.
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.
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
1321 * - srtp_err_status_ok if there were no problems.
1322 * - [other] if there was a failure in
1323 * the cryptographic mechanisms.
1325 srtp_err_status_t srtp_protect_rtcp(srtp_t ctx,
1327 int *pkt_octet_len);
1330 * @brief srtp_protect_rtcp_mki() is the Secure RTCP sender-side packet
1331 * processing function that can utilize mki.
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.
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
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.
1350 * @param ctx is the SRTP context to use in processing the packet.
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.
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
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
1364 * use the session keys identified by the mki_index
1366 * @param mki_index integer value specifying which set of session kesy should be
1367 * used if use_mki is set to true.
1370 * - srtp_err_status_ok if there were no problems.
1371 * - [other] if there was a failure in
1372 * the cryptographic mechanisms.
1374 srtp_err_status_t srtp_protect_rtcp_mki(srtp_t ctx,
1377 unsigned int use_mki,
1378 unsigned int mki_index);
1381 * @brief srtp_unprotect_rtcp() is the Secure RTCP receiver-side packet
1382 * processing function.
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.
1392 * @warning This function assumes that the SRTCP packet is aligned on a
1395 * @param ctx is a pointer to the srtp_t which applies to the
1396 * particular packet.
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.
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
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.
1418 srtp_err_status_t srtp_unprotect_rtcp(srtp_t ctx,
1420 int *pkt_octet_len);
1423 * @brief srtp_unprotect_rtcp() is the Secure RTCP receiver-side packet
1424 * processing function.
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.
1434 * @warning This function assumes that the SRTCP packet is aligned on a
1437 * @param ctx is a pointer to the srtp_t which applies to the
1438 * particular packet.
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.
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
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
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
1463 * - [other] if there has been an error in the
1464 * cryptographic mechanisms.
1467 srtp_err_status_t srtp_unprotect_rtcp_mki(srtp_t ctx,
1470 unsigned int use_mki);
1477 * @defgroup User data associated to a SRTP session.
1480 * @brief Store custom user data within a SRTP session.
1486 * @brief srtp_set_user_data() stores the given pointer into the SRTP
1487 * session for later retrieval.
1489 * @param ctx is the srtp_t context in which the given data pointer is
1492 * @param data is a pointer to the custom information (struct, function,
1493 * etc) associated with the SRTP session.
1498 void srtp_set_user_data(srtp_t ctx, void *data);
1501 * @brief srtp_get_user_data() retrieves the pointer to the custom data
1502 * previously stored with srtp_set_user_data().
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.
1509 * @param ctx is the srtp_t context in which the given data pointer was
1512 * @return void* pointer to the user data.
1515 void *srtp_get_user_data(srtp_t ctx);
1522 * @defgroup SRTPevents SRTP events and callbacks
1525 * @brief libSRTP can use a user-provided callback function to
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.
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
1546 * @brief srtp_event_t defines events that need to be handled
1548 * The enum srtp_event_t defines events that need to be handled
1549 * outside the `data plane', such as SSRC collisions and
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.
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.
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). */
1573 * @brief srtp_event_data_t is the structure passed as a callback to
1574 * the event handler function
1576 * The struct srtp_event_data_t holds the data passed to the event
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;
1587 * @brief srtp_event_handler_func_t is the function prototype for
1588 * the event handler.
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
1596 typedef void(srtp_event_handler_func_t)(srtp_event_data_t *data);
1599 * @brief sets the event handler to the function supplied by the caller.
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
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.
1610 srtp_err_status_t srtp_install_event_handler(srtp_event_handler_func_t func);
1613 * @brief Returns the version string of the library.
1616 const char *srtp_get_version_string(void);
1619 * @brief Returns the numeric representation of the library version.
1622 unsigned int srtp_get_version(void);
1625 * @brief srtp_set_debug_module(mod_name, v)
1627 * sets dynamic debugging to the value v (0 for off, 1 for on) for the
1628 * debug module with the name mod_name
1630 * returns err_status_ok on success, err_status_fail otherwise
1632 srtp_err_status_t srtp_set_debug_module(const char *mod_name, int v);
1635 * @brief srtp_list_debug_modules() outputs a list of debugging modules
1638 srtp_err_status_t srtp_list_debug_modules(void);
1641 * @brief srtp_log_level_t defines log levels.
1643 * The enumeration srtp_log_level_t defines log levels reported
1644 * in the srtp_log_handler_func_t.
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 */
1655 * @brief srtp_log_handler_func_t is the function prototype for
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
1664 typedef void(srtp_log_handler_func_t)(srtp_log_level_t level,
1669 * @brief sets the log handler to the function supplied by the caller.
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.
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
1682 srtp_err_status_t srtp_install_log_handler(srtp_log_handler_func_t func,
1686 * @brief srtp_get_protect_trailer_length(session, use_mki, mki_index, length)
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
1692 * returns err_status_ok on success, err_status_bad_mki if the MKI index is
1696 srtp_err_status_t srtp_get_protect_trailer_length(srtp_t session,
1702 * @brief srtp_get_protect_rtcp_trailer_length(session, use_mki, mki_index,
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
1709 * returns err_status_ok on success, err_status_bad_mki if the MKI index is
1713 srtp_err_status_t srtp_get_protect_rtcp_trailer_length(srtp_t session,
1719 * @brief srtp_set_stream_roc(session, ssrc, roc)
1721 * Set the roll-over-counter on a session for a given SSRC
1723 * returns err_status_ok on success, srtp_err_status_bad_param if there is no
1727 srtp_err_status_t srtp_set_stream_roc(srtp_t session,
1732 * @brief srtp_get_stream_roc(session, ssrc, roc)
1734 * Get the roll-over-counter on a session for a given SSRC
1736 * returns err_status_ok on success, srtp_err_status_bad_param if there is no
1740 srtp_err_status_t srtp_get_stream_roc(srtp_t session,
1748 /* in host order, so outside the #if */
1749 #define SRTCP_E_BIT 0x80000000
1751 /* for byte-access */
1752 #define SRTCP_E_BYTE_BIT 0x80
1753 #define SRTCP_INDEX_MASK 0x7fffffff
1759 #endif /* SRTP_SRTP_H */