srtp.h 69.9 KB
Newer Older
Cullen Jennings's avatar
Cullen Jennings committed
1 2 3 4 5 6 7 8 9
/*
 * srtp.h
 *
 * interface to libsrtp
 *
 * David A. McGrew
 * Cisco Systems, Inc.
 */
/*
10
 *
Geir Istad's avatar
Geir Istad committed
11
 * Copyright (c) 2001-2017, Cisco Systems, Inc.
Cullen Jennings's avatar
Cullen Jennings committed
12
 * All rights reserved.
13
 *
Cullen Jennings's avatar
Cullen Jennings committed
14 15 16
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
17
 *
Cullen Jennings's avatar
Cullen Jennings committed
18 19
 *   Redistributions of source code must retain the above copyright
 *   notice, this list of conditions and the following disclaimer.
20
 *
Cullen Jennings's avatar
Cullen Jennings committed
21 22 23 24
 *   Redistributions in binary form must reproduce the above
 *   copyright notice, this list of conditions and the following
 *   disclaimer in the documentation and/or other materials provided
 *   with the distribution.
25
 *
Cullen Jennings's avatar
Cullen Jennings committed
26 27 28
 *   Neither the name of the Cisco Systems, Inc. nor the names of its
 *   contributors may be used to endorse or promote products derived
 *   from this software without specific prior written permission.
29
 *
Cullen Jennings's avatar
Cullen Jennings committed
30 31 32 33 34 35 36 37 38 39 40 41 42 43 44
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
 * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
 * COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
 * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
 * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
 * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 * OF THE POSSIBILITY OF SUCH DAMAGE.
 *
 */

45 46
#ifndef SRTP_SRTP_H
#define SRTP_SRTP_H
Cullen Jennings's avatar
Cullen Jennings committed
47

48 49
#include <stdint.h>

50 51 52 53
#ifdef __cplusplus
extern "C" {
#endif

Cullen Jennings's avatar
Cullen Jennings committed
54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71
/**
 * @defgroup SRTP Secure RTP
 *
 * @brief libSRTP provides functions for protecting RTP and RTCP.  See
 * Section @ref Overview for an introduction to the use of the library.
 *
 * @{
 */

/*
 * SRTP_MASTER_KEY_LEN is the nominal master key length supported by libSRTP
 */

#define SRTP_MASTER_KEY_LEN 30

/*
 * SRTP_MAX_KEY_LEN is the maximum key length supported by libSRTP
 */
72
#define SRTP_MAX_KEY_LEN 64
Cullen Jennings's avatar
Cullen Jennings committed
73 74 75 76 77

/*
 * SRTP_MAX_TAG_LEN is the maximum tag length supported by libSRTP
 */

78
#define SRTP_MAX_TAG_LEN 16
Cullen Jennings's avatar
Cullen Jennings committed
79

80 81 82 83 84 85
/**
 * SRTP_MAX_MKI_LEN is the maximum size the MKI could be which is
 * 128 bytes
 */
#define SRTP_MAX_MKI_LEN 128

Cullen Jennings's avatar
Cullen Jennings committed
86 87 88
/**
 * SRTP_MAX_TRAILER_LEN is the maximum length of the SRTP trailer
 * (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
Cullen Jennings's avatar
Cullen Jennings committed
90 91 92 93
 * srtp_protect().
 *
 * @brief the maximum number of octets added by srtp_protect().
 */
94
#define SRTP_MAX_TRAILER_LEN (SRTP_MAX_TAG_LEN + SRTP_MAX_MKI_LEN)
Cullen Jennings's avatar
Cullen Jennings committed
95

Ryan Hooper's avatar
Ryan Hooper committed
96 97
/**
 * SRTP_MAX_NUM_MASTER_KEYS is the maximum number of Master keys for
98 99
 * MKI supported by libSRTP.
 *
Ryan Hooper's avatar
Ryan Hooper committed
100
 */
101
#define SRTP_MAX_NUM_MASTER_KEYS 16
Cullen Jennings's avatar
Cullen Jennings committed
102

103 104
#define SRTP_SALT_LEN 14

105
/*
106
 * SRTP_AEAD_SALT_LEN is the length of the SALT values used with
107 108 109
 * GCM mode.  GCM mode requires an IV.  The SALT value is used
 * as part of the IV formation logic applied to each RTP packet.
 */
110
#define SRTP_AEAD_SALT_LEN 12
111

112 113 114
#define SRTP_AES_128_KEY_LEN 16
#define SRTP_AES_192_KEY_LEN 24
#define SRTP_AES_256_KEY_LEN 32
115

116 117 118
#define SRTP_AES_ICM_128_KEY_LEN_WSALT (SRTP_SALT_LEN + SRTP_AES_128_KEY_LEN)
#define SRTP_AES_ICM_192_KEY_LEN_WSALT (SRTP_SALT_LEN + SRTP_AES_192_KEY_LEN)
#define SRTP_AES_ICM_256_KEY_LEN_WSALT (SRTP_SALT_LEN + SRTP_AES_256_KEY_LEN)
119

120 121 122 123 124 125
#define SRTP_AES_GCM_128_KEY_LEN_WSALT                                         \
    (SRTP_AEAD_SALT_LEN + SRTP_AES_128_KEY_LEN)
#define SRTP_AES_GCM_192_KEY_LEN_WSALT                                         \
    (SRTP_AEAD_SALT_LEN + SRTP_AES_192_KEY_LEN)
#define SRTP_AES_GCM_256_KEY_LEN_WSALT                                         \
    (SRTP_AEAD_SALT_LEN + SRTP_AES_256_KEY_LEN)
126

127
/**
128
 *  @brief A srtp_cipher_type_id_t is an identifier for a particular cipher
129 130
 *  type.
 *
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 135
 *  and can be selected to indicate that no encryption is to take
 *  place.
136
 *
137 138
 *  @ingroup Ciphers
 */
139
typedef uint32_t srtp_cipher_type_id_t;
140 141

/**
142 143
 *  @brief An srtp_auth_type_id_t is an identifier for a particular
 * authentication
144 145
 *   function.
 *
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 149 150
 *  avaliable; this authentication function performs no computation,
 *  and can be selected to indicate that no authentication is to take
 *  place.
151
 *
152 153
 *  @ingroup Authentication
 */
154
typedef uint32_t srtp_auth_type_id_t;
155

156
/**
157
 * @brief srtp_err_status_t defines error codes.
158
 *
159 160
 * The enumeration srtp_err_status_t defines error codes.  Note that the
 * value of srtp_err_status_ok is equal to zero, which can simplify error
161 162 163 164
 * checking somewhat.
 *
 */
typedef enum {
165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198
    srtp_err_status_ok = 0,             /**< nothing to report               */
    srtp_err_status_fail = 1,           /**< unspecified failure             */
    srtp_err_status_bad_param = 2,      /**< unsupported parameter           */
    srtp_err_status_alloc_fail = 3,     /**< couldn't allocate memory        */
    srtp_err_status_dealloc_fail = 4,   /**< couldn't deallocate properly    */
    srtp_err_status_init_fail = 5,      /**< couldn't initialize             */
    srtp_err_status_terminus = 6,       /**< can't process as much data as   */
                                        /**< requested                       */
    srtp_err_status_auth_fail = 7,      /**< authentication failure          */
    srtp_err_status_cipher_fail = 8,    /**< cipher failure                  */
    srtp_err_status_replay_fail = 9,    /**< replay check failed (bad index) */
    srtp_err_status_replay_old = 10,    /**< replay check failed (index too  */
                                        /**< old)                            */
    srtp_err_status_algo_fail = 11,     /**< algorithm failed test routine   */
    srtp_err_status_no_such_op = 12,    /**< unsupported operation           */
    srtp_err_status_no_ctx = 13,        /**< no appropriate context found    */
    srtp_err_status_cant_check = 14,    /**< unable to perform desired       */
                                        /**< validation                      */
    srtp_err_status_key_expired = 15,   /**< can't use key any more          */
    srtp_err_status_socket_err = 16,    /**< error in use of socket          */
    srtp_err_status_signal_err = 17,    /**< error in use POSIX signals      */
    srtp_err_status_nonce_bad = 18,     /**< nonce check failed              */
    srtp_err_status_read_fail = 19,     /**< couldn't read data              */
    srtp_err_status_write_fail = 20,    /**< couldn't write data             */
    srtp_err_status_parse_err = 21,     /**< error parsing data              */
    srtp_err_status_encode_err = 22,    /**< error encoding data             */
    srtp_err_status_semaphore_err = 23, /**< error while using semaphores    */
    srtp_err_status_pfkey_err = 24,     /**< error while using pfkey         */
    srtp_err_status_bad_mki = 25,       /**< error MKI present in packet is  */
                                        /**< invalid                         */
    srtp_err_status_pkt_idx_old = 26,   /**< packet index is too old to      */
                                        /**< consider                        */
    srtp_err_status_pkt_idx_adv = 27    /**< packet index advanced, reset    */
                                        /**< needed                          */
199
} srtp_err_status_t;
200 201

typedef struct srtp_ctx_t_ srtp_ctx_t;
202

Cullen Jennings's avatar
Cullen Jennings committed
203
/**
204
 * @brief srtp_sec_serv_t describes a set of security services.
Cullen Jennings's avatar
Cullen Jennings committed
205
 *
206
 * A srtp_sec_serv_t enumeration is used to describe the particular
Cullen Jennings's avatar
Cullen Jennings committed
207
 * security services that will be applied by a particular crypto
208
 * policy (or other mechanism).
Cullen Jennings's avatar
Cullen Jennings committed
209 210
 */
typedef enum {
211 212 213 214
    sec_serv_none = 0,         /**< no services                        */
    sec_serv_conf = 1,         /**< confidentiality                    */
    sec_serv_auth = 2,         /**< authentication                     */
    sec_serv_conf_and_auth = 3 /**< confidentiality and authentication */
215
} srtp_sec_serv_t;
Cullen Jennings's avatar
Cullen Jennings committed
216

217
/**
218
 * @brief srtp_crypto_policy_t describes a particular crypto policy that
Cullen Jennings's avatar
Cullen Jennings committed
219 220
 * can be applied to an SRTP stream.
 *
221
 * A srtp_crypto_policy_t describes a particular cryptographic policy that
Cullen Jennings's avatar
Cullen Jennings committed
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
Cullen Jennings's avatar
Cullen Jennings committed
224 225
 * in the session.
 */
226
typedef struct srtp_crypto_policy_t {
227 228 229 230 231 232 233 234 235 236 237 238
    srtp_cipher_type_id_t cipher_type; /**< An integer representing          */
                                       /**< the type of cipher.              */
    int cipher_key_len;                /**< The length of the cipher key     */
                                       /**< in octets.                       */
    srtp_auth_type_id_t auth_type;     /**< An integer representing the      */
                                       /**< authentication function.         */
    int auth_key_len;                  /**< The length of the authentication */
                                       /**< function key in octets.          */
    int auth_tag_len;                  /**< The length of the authentication */
                                       /**< tag in octets.                   */
    srtp_sec_serv_t sec_serv;          /**< The flag indicating the security */
                                       /**< services to be applied.          */
239
} srtp_crypto_policy_t;
Cullen Jennings's avatar
Cullen Jennings committed
240

241
/**
242
 * @brief srtp_ssrc_type_t describes the type of an SSRC.
243
 *
244
 * An srtp_ssrc_type_t enumeration is used to indicate a type of SSRC.  See
Cullen Jennings's avatar
Cullen Jennings committed
245 246
 * @ref srtp_policy_t for more informataion.
 */
247 248 249 250 251 252 253 254 255
typedef enum {
    ssrc_undefined = 0,   /**< Indicates an undefined SSRC type.    */
    ssrc_specific = 1,    /**< Indicates a specific SSRC value      */
    ssrc_any_inbound = 2, /**< Indicates any inbound SSRC value     */
                          /**< (i.e. a value that is used in the    */
                          /**< function srtp_unprotect())           */
    ssrc_any_outbound = 3 /**< Indicates any outbound SSRC value    */
                          /**< (i.e. a value that is used in the    */
                          /**< function srtp_protect())             */
256
} srtp_ssrc_type_t;
Cullen Jennings's avatar
Cullen Jennings committed
257 258

/**
259 260 261
 * @brief An srtp_ssrc_t represents a particular SSRC value, or a `wildcard'
 * SSRC.
 *
262
 * An srtp_ssrc_t represents a particular SSRC value (if its type is
Cullen Jennings's avatar
Cullen Jennings committed
263 264
 * ssrc_specific), or a wildcard SSRC value that will match all
 * outbound SSRCs (if its type is ssrc_any_outbound) or all inbound
265
 * SSRCs (if its type is ssrc_any_inbound).
Cullen Jennings's avatar
Cullen Jennings committed
266
 */
267 268 269 270
typedef struct {
    srtp_ssrc_type_t type; /**< The type of this particular SSRC */
    unsigned int value;    /**< The value of this SSRC, if it is not a */
                           /**< wildcard */
271
} srtp_ssrc_t;
Cullen Jennings's avatar
Cullen Jennings committed
272

David McGrew's avatar
David McGrew committed
273 274 275
/**
 * @brief points to an EKT policy
 */
276
typedef struct srtp_ekt_policy_ctx_t *srtp_ekt_policy_t;
David McGrew's avatar
David McGrew committed
277 278 279 280

/**
 * @brief points to EKT stream data
 */
281
typedef struct srtp_ekt_stream_ctx_t *srtp_ekt_stream_t;
David McGrew's avatar
David McGrew committed
282

Ryan Hooper's avatar
Ryan Hooper committed
283 284 285 286 287 288 289
/**
 * @brief srtp_master_key_t represents a master key.  There will
 * be a Master Key Index and the Master Key associated with the
 * Master Key Index.  Need to also keep track of the Master Key
 * Index Size to correctly read it from a packet.
 */
typedef struct srtp_master_key_t {
290 291 292
    unsigned char *key;
    unsigned char *mki_id;
    unsigned int mki_size;
Ryan Hooper's avatar
Ryan Hooper committed
293
} srtp_master_key_t;
David McGrew's avatar
David McGrew committed
294

295 296
/**
 * @brief represents the policy for an SRTP session.
Cullen Jennings's avatar
Cullen Jennings committed
297 298 299 300 301 302 303 304
 *
 * A single srtp_policy_t struct represents the policy for a single
 * SRTP stream, and a linked list of these elements represents the
 * policy for an entire SRTP session.  Each element contains the SRTP
 * and SRTCP crypto policies for that stream, a pointer to the SRTP
 * master key for that stream, the SSRC describing that stream, or a
 * flag indicating a `wildcard' SSRC value, and a `next' field that
 * holds a pointer to the next element in the list of policy elements,
305
 * or NULL if it is the last element.
Cullen Jennings's avatar
Cullen Jennings committed
306 307 308 309 310 311 312 313 314 315
 *
 * The wildcard value SSRC_ANY_INBOUND matches any SSRC from an
 * inbound stream that for which there is no explicit SSRC entry in
 * another policy element.  Similarly, the value SSRC_ANY_OUTBOUND
 * will matches any SSRC from an outbound stream that does not appear
 * in another policy element.  Note that wildcard SSRCs &b cannot be
 * used to match both inbound and outbound traffic.  This restriction
 * is intentional, and it allows libSRTP to ensure that no security
 * lapses result from accidental re-use of SSRC values during key
 * sharing.
316
 *
Cullen Jennings's avatar
Cullen Jennings committed
317 318 319 320 321
 * @warning The final element of the list @b must have its `next' pointer
 *          set to NULL.
 */

typedef struct srtp_policy_t {
322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346
    srtp_ssrc_t ssrc;              /**< The SSRC value of stream, or the    */
                                   /**< flags SSRC_ANY_INBOUND or           */
                                   /**< SSRC_ANY_OUTBOUND if key sharing    */
                                   /**< is used for this policy element.    */
    srtp_crypto_policy_t rtp;      /**< SRTP crypto policy.                 */
    srtp_crypto_policy_t rtcp;     /**< SRTCP crypto policy.                */
    unsigned char *key;            /**< Pointer to the SRTP master key for  */
                                   /**< this stream.                        */
    srtp_master_key_t **keys;      /** Array of Master Key structures       */
    unsigned long num_master_keys; /** Number of master keys                */
    srtp_ekt_policy_t ekt;         /**< Pointer to the EKT policy structure */
                                   /**< for this stream (if any)            */
    unsigned long window_size;     /**< The window size to use for replay   */
                                   /**< protection.                         */
    int allow_repeat_tx;           /**< Whether retransmissions of          */
                                   /**< packets with the same sequence      */
                                   /**< number are allowed.                 */
                                   /**< (Note that such repeated            */
                                   /**< transmissions must have the same    */
                                   /**< RTP payload, or a severe security   */
                                   /**< weakness is introduced!)            */
    int *enc_xtn_hdr;              /**< List of header ids to encrypt.      */
    int enc_xtn_hdr_count;         /**< Number of entries in list of header */
                                   /**<  ids.                               */
    struct srtp_policy_t *next;    /**< Pointer to next stream policy.      */
Cullen Jennings's avatar
Cullen Jennings committed
347 348 349 350 351 352
} srtp_policy_t;

/**
 * @brief An srtp_t points to an SRTP session structure.
 *
 * The typedef srtp_t is a pointer to a structure that represents
353
 * an SRTP session.  This datatype is intentially opaque in
Cullen Jennings's avatar
Cullen Jennings committed
354 355 356 357 358 359 360
 * order to separate the interface from the implementation.
 *
 * An SRTP session consists of all of the traffic sent to the RTP and
 * RTCP destination transport addresses, using the RTP/SAVP (Secure
 * Audio/Video Profile).  A session can be viewed as a set of SRTP
 * streams, each of which originates with a different participant.
 */
361
typedef srtp_ctx_t *srtp_t;
Cullen Jennings's avatar
Cullen Jennings committed
362 363

/**
364
 * @brief srtp_init() initializes the srtp library.
Cullen Jennings's avatar
Cullen Jennings committed
365 366 367 368
 *
 * @warning This function @b must be called before any other srtp
 * functions.
 */
369
srtp_err_status_t srtp_init(void);
Cullen Jennings's avatar
Cullen Jennings committed
370

371 372 373 374 375
/**
 * @brief srtp_shutdown() de-initializes the srtp library.
 *
 * @warning No srtp functions may be called after calling this function.
 */
376
srtp_err_status_t srtp_shutdown(void);
377

Cullen Jennings's avatar
Cullen Jennings committed
378 379 380
/**
 * @brief srtp_protect() is the Secure RTP sender-side packet processing
 * function.
381
 *
Cullen Jennings's avatar
Cullen Jennings committed
382 383
 * The function call srtp_protect(ctx, rtp_hdr, len_ptr) applies SRTP
 * 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
Cullen Jennings's avatar
Cullen Jennings committed
385 386 387
 * points to the resulting SRTP packet and *len_ptr is the number of
 * octets in that packet; otherwise, no assumptions should be made
 * about the value of either data elements.
388
 *
Cullen Jennings's avatar
Cullen Jennings committed
389 390 391 392 393 394 395 396 397
 * The sequence numbers of the RTP packets presented to this function
 * need not be consecutive, but they @b must be out of order by less
 * than 2^15 = 32,768 packets.
 *
 * @warning This function assumes that it can write the authentication
 * tag into the location in memory immediately following the RTP
 * packet, and assumes that the RTP packet is aligned on a 32-bit
 * boundary.
 *
398 399 400
 * @warning This function assumes that it can write SRTP_MAX_TRAILER_LEN
 * into the location in memory immediately following the RTP packet.
 * Callers MUST ensure that this much writable memory is available in
401
 * the buffer that holds the RTP packet.
402
 *
Cullen Jennings's avatar
Cullen Jennings committed
403 404 405 406 407 408 409
 * @param ctx is the SRTP context to use in processing the packet.
 *
 * @param rtp_hdr is a pointer to the RTP packet (before the call); after
 * the function returns, it points to the srtp packet.
 *
 * @param len_ptr is a pointer to the length in octets of the complete
 * 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.
Cullen Jennings's avatar
Cullen Jennings committed
411 412
 * Otherwise, the value of the data to which it points is undefined.
 *
413
 * @return
414 415
 *    - srtp_err_status_ok            no problems
 *    - srtp_err_status_replay_fail   rtp sequence number was non-increasing
Cullen Jennings's avatar
Cullen Jennings committed
416 417
 *    - @e other                 failure in cryptographic mechanisms
 */
418
srtp_err_status_t srtp_protect(srtp_t ctx, void *rtp_hdr, int *len_ptr);
Ryan Hooper's avatar
Ryan Hooper committed
419 420 421 422

/**
 * @brief srtp_protect_mki() is the Secure RTP sender-side packet processing
 * function that can utilize MKI.
423
 *
Ryan Hooper's avatar
Ryan Hooper committed
424 425 426 427 428 429
 * The function call srtp_protect(ctx, rtp_hdr, len_ptr) applies SRTP
 * protection to the RTP packet rtp_hdr (which has length *len_ptr) using
 * the SRTP context ctx.  If srtp_err_status_ok is returned, then rtp_hdr
 * points to the resulting SRTP packet and *len_ptr is the number of
 * octets in that packet; otherwise, no assumptions should be made
 * about the value of either data elements.
430
 *
Ryan Hooper's avatar
Ryan Hooper committed
431 432 433 434 435 436 437 438 439
 * The sequence numbers of the RTP packets presented to this function
 * need not be consecutive, but they @b must be out of order by less
 * than 2^15 = 32,768 packets.
 *
 * @warning This function assumes that it can write the authentication
 * tag into the location in memory immediately following the RTP
 * packet, and assumes that the RTP packet is aligned on a 32-bit
 * boundary.
 *
440 441 442
 * @warning This function assumes that it can write SRTP_MAX_TRAILER_LEN
 * into the location in memory immediately following the RTP packet.
 * Callers MUST ensure that this much writable memory is available in
Ryan Hooper's avatar
Ryan Hooper committed
443
 * the buffer that holds the RTP packet.
444
 *
Ryan Hooper's avatar
Ryan Hooper committed
445 446 447 448 449
 * @param ctx is the SRTP context to use in processing the packet.
 *
 * @param rtp_hdr is a pointer to the RTP packet (before the call); after
 * 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
Ryan Hooper's avatar
Ryan Hooper committed
451 452 453 454
 * RTP packet (header and body) before the function call, and of the
 * complete SRTP packet after the call, if srtp_err_status_ok was returned.
 * Otherwise, the value of the data to which it points is undefined.
 *
455 456 457
 * @param use_mki is a boolean to tell the system if mki is being used.  If
 * set to false then will use the first set of session keys.  If set to true
 * will
Ryan Hooper's avatar
Ryan Hooper committed
458 459
 * use the session keys identified by the mki_index
 *
Geir Istad's avatar
Geir Istad committed
460
 * @param mki_index integer value specifying which set of session keys should be
Ryan Hooper's avatar
Ryan Hooper committed
461 462
 * used if use_mki is set to true.
 *
463
 * @return
Ryan Hooper's avatar
Ryan Hooper committed
464 465 466 467
 *    - srtp_err_status_ok            no problems
 *    - srtp_err_status_replay_fail   rtp sequence number was non-increasing
 *    - @e other                 failure in cryptographic mechanisms
 */
468 469 470 471
srtp_err_status_t srtp_protect_mki(srtp_ctx_t *ctx,
                                   void *rtp_hdr,
                                   int *pkt_octet_len,
                                   unsigned int use_mki,
Geir Istad's avatar
Geir Istad committed
472 473
                                   unsigned int mki_index);

Cullen Jennings's avatar
Cullen Jennings committed
474 475 476 477 478 479 480
/**
 * @brief srtp_unprotect() is the Secure RTP receiver-side packet
 * processing function.
 *
 * The function call srtp_unprotect(ctx, srtp_hdr, len_ptr) verifies
 * the Secure RTP protection of the SRTP packet pointed to by srtp_hdr
 * (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
Cullen Jennings's avatar
Cullen Jennings committed
482 483
 * RTP packet and *len_ptr is the number of octets in that packet;
 * otherwise, no assumptions should be made about the value of either
484 485
 * data elements.
 *
Cullen Jennings's avatar
Cullen Jennings committed
486 487 488
 * The sequence numbers of the RTP packets presented to this function
 * need not be consecutive, but they @b must be out of order by less
 * than 2^15 = 32,768 packets.
489
 *
Cullen Jennings's avatar
Cullen Jennings committed
490 491 492
 * @warning This function assumes that the SRTP packet is aligned on a
 * 32-bit boundary.
 *
493
 * @param ctx is the SRTP session which applies to the particular packet.
Cullen Jennings's avatar
Cullen Jennings committed
494 495 496
 *
 * @param srtp_hdr is a pointer to the header of the SRTP packet
 * (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
Cullen Jennings's avatar
Cullen Jennings committed
498 499 500 501
 * the data to which it points is undefined.
 *
 * @param len_ptr is a pointer to the length in octets of the complete
 * 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.
Cullen Jennings's avatar
Cullen Jennings committed
503 504
 * Otherwise, the value of the data to which it points is undefined.
 *
505
 * @return
506
 *    - srtp_err_status_ok          if the RTP packet is valid.
507 508 509 510
 *    - srtp_err_status_auth_fail   if the SRTP packet failed the message
 *                                  authentication check.
 *    - srtp_err_status_replay_fail if the SRTP packet is a replay (e.g. packet
 *                                  has already been processed and accepted).
Cullen Jennings's avatar
Cullen Jennings committed
511 512 513
 *    - [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);
Cullen Jennings's avatar
Cullen Jennings committed
515

Ryan Hooper's avatar
Ryan Hooper committed
516 517 518 519 520 521 522 523 524 525
/**
 * @brief srtp_unprotect_mki() is the Secure RTP receiver-side packet
 * processing function that checks for MKI.
 *
 * The function call srtp_unprotect(ctx, srtp_hdr, len_ptr) verifies
 * the Secure RTP protection of the SRTP packet pointed to by srtp_hdr
 * (which has length *len_ptr), using the SRTP context ctx.  If
 * srtp_err_status_ok is returned, then srtp_hdr points to the resulting
 * RTP packet and *len_ptr is the number of octets in that packet;
 * otherwise, no assumptions should be made about the value of either
526 527
 * data elements.
 *
Ryan Hooper's avatar
Ryan Hooper committed
528 529 530
 * The sequence numbers of the RTP packets presented to this function
 * need not be consecutive, but they @b must be out of order by less
 * than 2^15 = 32,768 packets.
531
 *
Ryan Hooper's avatar
Ryan Hooper committed
532 533 534 535 536 537 538 539 540 541 542 543 544 545 546
 * @warning This function assumes that the SRTP packet is aligned on a
 * 32-bit boundary.
 *
 * @param ctx is the SRTP session which applies to the particular packet.
 *
 * @param srtp_hdr is a pointer to the header of the SRTP packet
 * (before the call).  after the function returns, it points to the
 * rtp packet if srtp_err_status_ok was returned; otherwise, the value of
 * the data to which it points is undefined.
 *
 * @param len_ptr is a pointer to the length in octets of the complete
 * srtp packet (header and body) before the function call, and of the
 * complete rtp packet after the call, if srtp_err_status_ok was returned.
 * 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 549
 * set to false then will use the first set of session keys.  If set to true
 * will
550 551
 * use the session keys identified by the mki_index
 *
552
 * @return
Ryan Hooper's avatar
Ryan Hooper committed
553
 *    - srtp_err_status_ok          if the RTP packet is valid.
554 555 556 557
 *    - srtp_err_status_auth_fail   if the SRTP packet failed the message
 *                                  authentication check.
 *    - srtp_err_status_replay_fail if the SRTP packet is a replay (e.g. packet
 *                                  has already been processed and accepted).
Ryan Hooper's avatar
Ryan Hooper committed
558 559 560 561
 *    - srtp_err_status_bad_mki if the MKI in the packet is not a known MKI id
 *    - [other]  if there has been an error in the cryptographic mechanisms.
 *
 */
562 563 564
srtp_err_status_t srtp_unprotect_mki(srtp_t ctx,
                                     void *srtp_hdr,
                                     int *len_ptr,
Geir Istad's avatar
Geir Istad committed
565
                                     unsigned int use_mki);
Cullen Jennings's avatar
Cullen Jennings committed
566 567 568 569

/**
 * @brief srtp_create() allocates and initializes an SRTP session.

jfigus's avatar
jfigus committed
570
 * The function call srtp_create(session, policy) allocates and
571
 * initializes an SRTP session context, applying the given policy.
Cullen Jennings's avatar
Cullen Jennings committed
572
 *
573 574
 * @param session is a pointer to the SRTP session to which the policy is
 * to be added.
575
 *
Cullen Jennings's avatar
Cullen Jennings committed
576 577 578
 * @param policy is the srtp_policy_t struct that describes the policy
 * for the session.  The struct may be a single element, or it may be
 * the head of a list, in which case each element of the list is
579 580 581
 * processed.  It may also be NULL, in which case streams should be added
 * later using srtp_add_stream().  The final element of the list @b must
 * have its `next' field set to NULL.
582
 *
Cullen Jennings's avatar
Cullen Jennings committed
583
 * @return
584 585 586
 *    - srtp_err_status_ok           if creation succeded.
 *    - srtp_err_status_alloc_fail   if allocation failed.
 *    - srtp_err_status_init_fail    if initialization failed.
Cullen Jennings's avatar
Cullen Jennings committed
587
 */
588
srtp_err_status_t srtp_create(srtp_t *session, const srtp_policy_t *policy);
Cullen Jennings's avatar
Cullen Jennings committed
589 590 591 592

/**
 * @brief srtp_add_stream() allocates and initializes an SRTP stream
 * within a given SRTP session.
593
 *
Cullen Jennings's avatar
Cullen Jennings committed
594 595 596 597 598 599
 * The function call srtp_add_stream(session, policy) allocates and
 * initializes a new SRTP stream within a given, previously created
 * session, applying the policy given as the other argument to that
 * stream.
 *
 * @return values:
600 601 602
 *    - srtp_err_status_ok           if stream creation succeded.
 *    - srtp_err_status_alloc_fail   if stream allocation failed
 *    - srtp_err_status_init_fail    if stream initialization failed.
Cullen Jennings's avatar
Cullen Jennings committed
603
 */
604
srtp_err_status_t srtp_add_stream(srtp_t session, const srtp_policy_t *policy);
Cullen Jennings's avatar
Cullen Jennings committed
605 606 607

/**
 * @brief srtp_remove_stream() deallocates an SRTP stream.
608
 *
Cullen Jennings's avatar
Cullen Jennings committed
609 610 611 612 613 614 615
 * The function call srtp_remove_stream(session, ssrc) removes
 * the SRTP stream with the SSRC value ssrc from the SRTP session
 * context given by the argument session.
 *
 * @param session is the SRTP session from which the stream
 *        will be removed.
 *
616 617
 * @param ssrc is the SSRC value of the stream to be removed
 *             in network byte order.
Cullen Jennings's avatar
Cullen Jennings committed
618 619 620
 *
 * @warning Wildcard SSRC values cannot be removed from a
 *          session.
621
 *
Cullen Jennings's avatar
Cullen Jennings committed
622
 * @return
623
 *    - srtp_err_status_ok     if the stream deallocation succeded.
Cullen Jennings's avatar
Cullen Jennings committed
624 625 626
 *    - [other]           otherwise.
 *
 */
627
srtp_err_status_t srtp_remove_stream(srtp_t session, unsigned int ssrc);
Cullen Jennings's avatar
Cullen Jennings committed
628

629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675
/**
 * @brief srtp_update() udpates all streams in the session.
 *
 * The function call srtp_update(session, policy) updates
 * all the streams in the session applying the given policy
 * and key. The exsisting ROC value of all streams will be
 * preserved.
 *
 * @param session is the SRTP session that contains the streams
 *        to be updated.
 *
 * @param policy is the srtp_policy_t struct that describes the policy
 * for the session.  The struct may be a single element, or it may be
 * the head of a list, in which case each element of the list is
 * processed. The final element of the list @b must
 * have its `next' field set to NULL.
 *
 * @return
 *    - srtp_err_status_ok           if stream creation succeded.
 *    - srtp_err_status_alloc_fail   if stream allocation failed
 *    - srtp_err_status_init_fail    if stream initialization failed.
 *    - [other]                 otherwise.
 *
 */
srtp_err_status_t srtp_update(srtp_t session, const srtp_policy_t *policy);

/**
 * @brief srtp_update_stream() udpates a SRTP stream.
 *
 * The function call srtp_update_stream(session, policy) updates
 * the stream(s) in the session that match applying the given
 * policy and key. The exsisting ROC value of all stream(s) will
 * be preserved.
 *
 * @param session is the SRTP session that contains the streams
 *        to be updated.
 *
 * @param policy is the srtp_policy_t struct that describes the policy
 * for the session.
 *
 * @return
 *    - srtp_err_status_ok           if stream creation succeded.
 *    - srtp_err_status_alloc_fail   if stream allocation failed
 *    - srtp_err_status_init_fail    if stream initialization failed.
 *    - [other]                      otherwise.
 *
 */
676 677
srtp_err_status_t srtp_update_stream(srtp_t session,
                                     const srtp_policy_t *policy);
678

Cullen Jennings's avatar
Cullen Jennings committed
679
/**
680
 * @brief srtp_crypto_policy_set_rtp_default() sets a crypto policy
Cullen Jennings's avatar
Cullen Jennings committed
681 682
 * structure to the SRTP default policy for RTP protection.
 *
683 684
 * @param p is a pointer to the policy structure to be set
 *
Cullen Jennings's avatar
Cullen Jennings committed
685 686 687 688 689 690 691 692
 * The function call crypto_policy_set_rtp_default(&p) sets the
 * crypto_policy_t at location p to the SRTP default policy for RTP
 * protection, as defined in the specification.  This function is a
 * convenience that helps to avoid dealing directly with the policy
 * data structure.  You are encouraged to initialize policy elements
 * with this function call.  Doing so may allow your code to be
 * forward compatible with later versions of libSRTP that include more
 * elements in the crypto_policy_t datatype.
693
 *
Cullen Jennings's avatar
Cullen Jennings committed
694
 * @return void.
695
 *
Cullen Jennings's avatar
Cullen Jennings committed
696
 */
697
void srtp_crypto_policy_set_rtp_default(srtp_crypto_policy_t *p);
Cullen Jennings's avatar
Cullen Jennings committed
698 699

/**
700
 * @brief srtp_crypto_policy_set_rtcp_default() sets a crypto policy
Cullen Jennings's avatar
Cullen Jennings committed
701 702
 * structure to the SRTP default policy for RTCP protection.
 *
703 704
 * @param p is a pointer to the policy structure to be set
 *
705 706
 * The function call srtp_crypto_policy_set_rtcp_default(&p) sets the
 * srtp_crypto_policy_t at location p to the SRTP default policy for RTCP
Cullen Jennings's avatar
Cullen Jennings committed
707 708 709 710 711
 * protection, as defined in the specification.  This function is a
 * convenience that helps to avoid dealing directly with the policy
 * data structure.  You are encouraged to initialize policy elements
 * with this function call.  Doing so may allow your code to be
 * forward compatible with later versions of libSRTP that include more
712
 * elements in the srtp_crypto_policy_t datatype.
713
 *
Cullen Jennings's avatar
Cullen Jennings committed
714
 * @return void.
715
 *
Cullen Jennings's avatar
Cullen Jennings committed
716
 */
717
void srtp_crypto_policy_set_rtcp_default(srtp_crypto_policy_t *p);
Cullen Jennings's avatar
Cullen Jennings committed
718

719
/**
720
 * @brief srtp_crypto_policy_set_aes_cm_128_hmac_sha1_80() sets a crypto
721 722
 * policy structure to the SRTP default policy for RTP protection.
 *
723 724
 * @param p is a pointer to the policy structure to be set
 *
725 726
 * The function srtp_crypto_policy_set_aes_cm_128_hmac_sha1_80() is a
 * synonym for srtp_crypto_policy_set_rtp_default().  It conforms to the
727 728
 * naming convention used in RFC 4568 (SDP Security Descriptions for
 * Media Streams).
729
 *
730
 * @return void.
731
 *
732
 */
733 734
#define srtp_crypto_policy_set_aes_cm_128_hmac_sha1_80(p)                      \
    srtp_crypto_policy_set_rtp_default(p)
735 736

/**
737
 * @brief srtp_crypto_policy_set_aes_cm_128_hmac_sha1_32() sets a crypto
738 739
 * policy structure to a short-authentication tag policy
 *
740 741
 * @param p is a pointer to the policy structure to be set
 *
742 743
 * The function call srtp_crypto_policy_set_aes_cm_128_hmac_sha1_32(&p)
 * sets the srtp_crypto_policy_t at location p to use policy
744 745
 * AES_CM_128_HMAC_SHA1_32 as defined in RFC 4568.
 * This policy uses AES-128
746 747 748 749 750
 * Counter Mode encryption and HMAC-SHA1 authentication, with an
 * authentication tag that is only 32 bits long.  This length is
 * considered adequate only for protecting audio and video media that
 * use a stateless playback function.  See Section 7.5 of RFC 3711
 * (http://www.ietf.org/rfc/rfc3711.txt).
751
 *
752 753 754 755
 * This function is a convenience that helps to avoid dealing directly
 * with the policy data structure.  You are encouraged to initialize
 * policy elements with this function call.  Doing so may allow your
 * code to be forward compatible with later versions of libSRTP that
756
 * include more elements in the srtp_crypto_policy_t datatype.
757 758 759 760 761 762 763
 *
 * @warning This crypto policy is intended for use in SRTP, but not in
 * SRTCP.  It is recommended that a policy that uses longer
 * authentication tags be used for SRTCP.  See Section 7.5 of RFC 3711
 * (http://www.ietf.org/rfc/rfc3711.txt).
 *
 * @return void.
764
 *
765
 */
766
void srtp_crypto_policy_set_aes_cm_128_hmac_sha1_32(srtp_crypto_policy_t *p);
767 768

/**
769
 * @brief srtp_crypto_policy_set_aes_cm_128_null_auth() sets a crypto
770 771
 * policy structure to an encryption-only policy
 *
772 773
 * @param p is a pointer to the policy structure to be set
 *
774 775
 * The function call srtp_crypto_policy_set_aes_cm_128_null_auth(&p) sets
 * the srtp_crypto_policy_t at location p to use the SRTP default cipher
776 777 778
 * (AES-128 Counter Mode), but to use no authentication method.  This
 * policy is NOT RECOMMENDED unless it is unavoidable; see Section 7.5
 * of RFC 3711 (http://www.ietf.org/rfc/rfc3711.txt).
779
 *
780 781 782 783
 * This function is a convenience that helps to avoid dealing directly
 * with the policy data structure.  You are encouraged to initialize
 * policy elements with this function call.  Doing so may allow your
 * code to be forward compatible with later versions of libSRTP that
784
 * include more elements in the srtp_crypto_policy_t datatype.
785 786 787 788 789 790
 *
 * @warning This policy is NOT RECOMMENDED for SRTP unless it is
 * unavoidable, and it is NOT RECOMMENDED at all for SRTCP; see
 * Section 7.5 of RFC 3711 (http://www.ietf.org/rfc/rfc3711.txt).
 *
 * @return void.
791
 *
792
 */
793
void srtp_crypto_policy_set_aes_cm_128_null_auth(srtp_crypto_policy_t *p);
794 795

/**
796
 * @brief srtp_crypto_policy_set_null_cipher_hmac_sha1_80() sets a crypto
797 798
 * policy structure to an authentication-only policy
 *
799 800
 * @param p is a pointer to the policy structure to be set
 *
801 802
 * The function call srtp_crypto_policy_set_null_cipher_hmac_sha1_80(&p)
 * sets the srtp_crypto_policy_t at location p to use HMAC-SHA1 with an 80
803 804
 * bit authentication tag to provide message authentication, but to
 * use no encryption.  This policy is NOT RECOMMENDED for SRTP unless
805 806
 * there is a requirement to forego encryption.
 *
807 808 809 810
 * This function is a convenience that helps to avoid dealing directly
 * with the policy data structure.  You are encouraged to initialize
 * policy elements with this function call.  Doing so may allow your
 * code to be forward compatible with later versions of libSRTP that
811
 * include more elements in the srtp_crypto_policy_t datatype.
812 813
 *
 * @warning This policy is NOT RECOMMENDED for SRTP unless there is a
814
 * requirement to forego encryption.
815 816
 *
 * @return void.
817
 *
818
 */
819
void srtp_crypto_policy_set_null_cipher_hmac_sha1_80(srtp_crypto_policy_t *p);
820

821 822
/**
 * @brief srtp_crypto_policy_set_null_cipher_hmac_null() sets a crypto
823 824 825
 * policy structure to use no encryption or authentication.
 *
 * @param p is a pointer to the policy structure to be set
826 827 828 829
 *
 * The function call srtp_crypto_policy_set_null_cipher_hmac_null(&p)
 * sets the srtp_crypto_policy_t at location p to use no encryption and
 * no authentication.  This policy should only be used for testing and
830 831
 * troubleshootingl.
 *
832 833 834 835 836 837 838
 * This function is a convenience that helps to avoid dealing directly
 * with the policy data structure.  You are encouraged to initialize
 * policy elements with this function call.  Doing so may allow your
 * code to be forward compatible with later versions of libSRTP that
 * include more elements in the srtp_crypto_policy_t datatype.
 *
 * @warning This policy is NOT RECOMMENDED for SRTP unless there is a
839
 * requirement to forego encryption and authentication.
840 841
 *
 * @return void.
842
 *
843 844 845
 */
void srtp_crypto_policy_set_null_cipher_hmac_null(srtp_crypto_policy_t *p);

Jonathan Lennox's avatar
Jonathan Lennox committed
846
/**
847
 * @brief srtp_crypto_policy_set_aes_cm_256_hmac_sha1_80() sets a crypto
848
 * policy structure to a encryption and authentication policy using AES-256
Jonathan Lennox's avatar
Jonathan Lennox committed
849 850
 * for RTP protection.
 *
851 852
 * @param p is a pointer to the policy structure to be set
 *
853 854
 * The function call srtp_crypto_policy_set_aes_cm_256_hmac_sha1_80(&p)
 * 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
Jonathan Lennox's avatar
Jonathan Lennox committed
856 857
 * Counter Mode encryption and HMAC-SHA1 authentication, with an 80 bit
 * authentication tag.
858
 *
Jonathan Lennox's avatar
Jonathan Lennox committed
859 860 861 862
 * This function is a convenience that helps to avoid dealing directly
 * with the policy data structure.  You are encouraged to initialize
 * policy elements with this function call.  Doing so may allow your
 * code to be forward compatible with later versions of libSRTP that
863
 * include more elements in the srtp_crypto_policy_t datatype.
Jonathan Lennox's avatar
Jonathan Lennox committed
864 865
 *
 * @return void.
866
 *
Jonathan Lennox's avatar
Jonathan Lennox committed
867
 */
868
void srtp_crypto_policy_set_aes_cm_256_hmac_sha1_80(srtp_crypto_policy_t *p);
Jonathan Lennox's avatar
Jonathan Lennox committed
869 870

/**
871
 * @brief srtp_crypto_policy_set_aes_cm_256_hmac_sha1_32() sets a crypto
Jonathan Lennox's avatar
Jonathan Lennox committed
872 873 874
 * policy structure to a short-authentication tag policy using AES-256
 * encryption.
 *
875 876
 * @param p is a pointer to the policy structure to be set
 *
877 878
 * The function call srtp_crypto_policy_set_aes_cm_256_hmac_sha1_32(&p)
 * 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
Jonathan Lennox's avatar
Jonathan Lennox committed
880 881 882 883 884
 * Counter Mode encryption and HMAC-SHA1 authentication, with an
 * authentication tag that is only 32 bits long.  This length is
 * considered adequate only for protecting audio and video media that
 * use a stateless playback function.  See Section 7.5 of RFC 3711
 * (http://www.ietf.org/rfc/rfc3711.txt).
885
 *
Jonathan Lennox's avatar
Jonathan Lennox committed
886 887 888 889
 * This function is a convenience that helps to avoid dealing directly
 * with the policy data structure.  You are encouraged to initialize
 * policy elements with this function call.  Doing so may allow your
 * code to be forward compatible with later versions of libSRTP that
890
 * include more elements in the srtp_crypto_policy_t datatype.
Jonathan Lennox's avatar
Jonathan Lennox committed
891 892 893 894 895 896 897
 *
 * @warning This crypto policy is intended for use in SRTP, but not in
 * SRTCP.  It is recommended that a policy that uses longer
 * authentication tags be used for SRTCP.  See Section 7.5 of RFC 3711
 * (http://www.ietf.org/rfc/rfc3711.txt).
 *
 * @return void.
898
 *
Jonathan Lennox's avatar
Jonathan Lennox committed
899
 */
900
void srtp_crypto_policy_set_aes_cm_256_hmac_sha1_32(srtp_crypto_policy_t *p);
Jonathan Lennox's avatar
Jonathan Lennox committed
901

902
/**
903
 * @brief srtp_crypto_policy_set_aes_cm_256_null_auth() sets a crypto
904 905 906 907
 * policy structure to an encryption-only policy
 *
 * @param p is a pointer to the policy structure to be set
 *
908 909
 * The function call srtp_crypto_policy_set_aes_cm_256_null_auth(&p) sets
 * the srtp_crypto_policy_t at location p to use the SRTP default cipher
910 911 912 913 914 915 916 917
 * (AES-256 Counter Mode), but to use no authentication method.  This
 * policy is NOT RECOMMENDED unless it is unavoidable; see Section 7.5
 * of RFC 3711 (http://www.ietf.org/rfc/rfc3711.txt).
 *
 * This function is a convenience that helps to avoid dealing directly
 * with the policy data structure.  You are encouraged to initialize
 * policy elements with this function call.  Doing so may allow your
 * code to be forward compatible with later versions of libSRTP that
918
 * include more elements in the srtp_crypto_policy_t datatype.
919 920 921 922 923 924 925 926
 *
 * @warning This policy is NOT RECOMMENDED for SRTP unless it is
 * unavoidable, and it is NOT RECOMMENDED at all for SRTCP; see
 * Section 7.5 of RFC 3711 (http://www.ietf.org/rfc/rfc3711.txt).
 *
 * @return void.
 *
 */
927
void srtp_crypto_policy_set_aes_cm_256_null_auth(srtp_crypto_policy_t *p);
928

929 930 931 932 933 934 935 936 937
/**
 * @brief srtp_crypto_policy_set_aes_cm_192_hmac_sha1_80() sets a crypto
 * policy structure to a encryption and authentication policy using AES-192
 * for RTP protection.
 *
 * @param p is a pointer to the policy structure to be set
 *
 * The function call srtp_crypto_policy_set_aes_cm_192_hmac_sha1_80(&p)
 * sets the 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 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961
 * Counter Mode encryption and HMAC-SHA1 authentication, with an 80 bit
 * authentication tag.
 *
 * This function is a convenience that helps to avoid dealing directly
 * with the policy data structure.  You are encouraged to initialize
 * policy elements with this function call.  Doing so may allow your
 * code to be forward compatible with later versions of libSRTP that
 * include more elements in the crypto_policy_t datatype.
 *
 * @return void.
 *
 */
void srtp_crypto_policy_set_aes_cm_192_hmac_sha1_80(srtp_crypto_policy_t *p);

/**
 * @brief srtp_crypto_policy_set_aes_cm_192_hmac_sha1_32() sets a crypto
 * policy structure to a short-authentication tag policy using AES-192
 * encryption.
 *
 * @param p is a pointer to the policy structure to be set
 *
 * The function call srtp_crypto_policy_set_aes_cm_192_hmac_sha1_32(&p)
 * sets the 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 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011
 * Counter Mode encryption and HMAC-SHA1 authentication, with an
 * authentication tag that is only 32 bits long.  This length is
 * considered adequate only for protecting audio and video media that
 * use a stateless playback function.  See Section 7.5 of RFC 3711
 * (http://www.ietf.org/rfc/rfc3711.txt).
 *
 * This function is a convenience that helps to avoid dealing directly
 * with the policy data structure.  You are encouraged to initialize
 * policy elements with this function call.  Doing so may allow your
 * code to be forward compatible with later versions of libSRTP that
 * include more elements in the crypto_policy_t datatype.
 *
 * @warning This crypto policy is intended for use in SRTP, but not in
 * SRTCP.  It is recommended that a policy that uses longer
 * authentication tags be used for SRTCP.  See Section 7.5 of RFC 3711
 * (http://www.ietf.org/rfc/rfc3711.txt).
 *
 * @return void.
 *
 */
void srtp_crypto_policy_set_aes_cm_192_hmac_sha1_32(srtp_crypto_policy_t *p);

/**
 * @brief srtp_crypto_policy_set_aes_cm_192_null_auth() sets a crypto
 * policy structure to an encryption-only policy
 *
 * @param p is a pointer to the policy structure to be set
 *
 * The function call srtp_crypto_policy_set_aes_cm_192_null_auth(&p) sets
 * the crypto_policy_t at location p to use the SRTP default cipher
 * (AES-192 Counter Mode), but to use no authentication method.  This
 * policy is NOT RECOMMENDED unless it is unavoidable; see Section 7.5
 * of RFC 3711 (http://www.ietf.org/rfc/rfc3711.txt).
 *
 * This function is a convenience that helps to avoid dealing directly
 * with the policy data structure.  You are encouraged to initialize
 * policy elements with this function call.  Doing so may allow your
 * code to be forward compatible with later versions of libSRTP that
 * include more elements in the crypto_policy_t datatype.
 *
 * @warning This policy is NOT RECOMMENDED for SRTP unless it is
 * unavoidable, and it is NOT RECOMMENDED at all for SRTCP; see
 * Section 7.5 of RFC 3711 (http://www.ietf.org/rfc/rfc3711.txt).
 *
 * @return void.
 *
 */
void srtp_crypto_policy_set_aes_cm_192_null_auth(srtp_crypto_policy_t *p);

1012
/**
1013
 * @brief srtp_crypto_policy_set_aes_gcm_128_8_auth() sets a crypto
1014 1015
 * policy structure to an AEAD encryption policy.
 *
1016 1017
 * @param p is a pointer to the policy structure to be set
 *
1018 1019
 * The function call srtp_crypto_policy_set_aes_gcm_128_8_auth(&p) sets
 * the srtp_crypto_policy_t at location p to use the SRTP default cipher
1020 1021 1022
 * (AES-128 Galois Counter Mode) with 8 octet auth tag.  This
 * policy applies confidentiality and authentication to both the
 * RTP and RTCP packets.
1023
 *
1024 1025 1026 1027
 * This function is a convenience that helps to avoid dealing directly
 * with the policy data structure.  You are encouraged to initialize
 * policy elements with this function call.  Doing so may allow your
 * code to be forward compatible with later versions of libSRTP that
1028
 * include more elements in the srtp_crypto_policy_t datatype.
1029 1030
 *
 * @return void.
1031
 *
1032
 */
1033
void srtp_crypto_policy_set_aes_gcm_128_8_auth(srtp_crypto_policy_t *p);
1034 1035

/**
1036
 * @brief srtp_crypto_policy_set_aes_gcm_256_8_auth() sets a crypto
1037 1038
 * policy structure to an AEAD encryption policy
 *
1039 1040
 * @param p is a pointer to the policy structure to be set
 *
1041 1042
 * The function call srtp_crypto_policy_set_aes_gcm_256_8_auth(&p) sets
 * 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 1045
 * policy applies confidentiality and authentication to both the
 * RTP and RTCP packets.
1046
 *
1047 1048 1049 1050
 * This function is a convenience that helps to avoid dealing directly
 * with the policy data structure.  You are encouraged to initialize
 * policy elements with this function call.  Doing so may allow your
 * code to be forward compatible with later versions of libSRTP that
1051
 * include more elements in the srtp_crypto_policy_t datatype.
1052 1053
 *
 * @return void.
1054
 *
1055
 */
1056
void srtp_crypto_policy_set_aes_gcm_256_8_auth(srtp_crypto_policy_t *p);
1057 1058

/**
1059
 * @brief srtp_crypto_policy_set_aes_gcm_128_8_only_auth() sets a crypto
1060 1061
 * policy structure to an AEAD authentication-only policy
 *
1062 1063
 * @param p is a pointer to the policy structure to be set
 *
1064 1065
 * The function call srtp_crypto_policy_set_aes_gcm_128_8_only_auth(&p) sets
 * the srtp_crypto_policy_t at location p to use the SRTP default cipher
1066 1067
 * (AES-128 Galois Counter Mode) with 8 octet auth tag.  This policy
 * applies confidentiality and authentication to the RTP packets,
1068
 * but only authentication to the RTCP packets.
1069
 *
1070 1071 1072 1073
 * This function is a convenience that helps to avoid dealing directly
 * with the policy data structure.  You are encouraged to initialize
 * policy elements with this function call.  Doing so may allow your
 * code to be forward compatible with later versions of libSRTP that
1074
 * include more elements in the srtp_crypto_policy_t datatype.
1075 1076
 *
 * @return void.
1077
 *
1078
 */
1079
void srtp_crypto_policy_set_aes_gcm_128_8_only_auth(srtp_crypto_policy_t *p);
1080 1081

/**
1082
 * @brief srtp_crypto_policy_set_aes_gcm_256_8_only_auth() sets a crypto
1083 1084
 * policy structure to an AEAD authentication-only policy
 *
1085 1086
 * @param p is a pointer to the policy structure to be set
 *
1087 1088
 * The function call srtp_crypto_policy_set_aes_gcm_256_8_only_auth(&p) sets
 * the srtp_crypto_policy_t at location p to use the SRTP default cipher
1089 1090
 * (AES-256 Galois Counter Mode) with 8 octet auth tag.  This policy
 * applies confidentiality and authentication to the RTP packets,
1091
 * but only authentication to the RTCP packets.
1092
 *
1093 1094 1095 1096
 * This function is a convenience that helps to avoid dealing directly
 * with the policy data structure.  You are encouraged to initialize
 * policy elements with this function call.  Doing so may allow your
 * code to be forward compatible with later versions of libSRTP that
1097
 * include more elements in the srtp_crypto_policy_t datatype.
1098 1099
 *
 * @return void.
1100
 *
1101
 */
1102
void srtp_crypto_policy_set_aes_gcm_256_8_only_auth(srtp_crypto_policy_t *p);
1103

1104
/**
1105
 * @brief srtp_crypto_policy_set_aes_gcm_128_16_auth() sets a crypto
1106 1107
 * policy structure to an AEAD encryption policy.
 *
1108 1109
 * @param p is a pointer to the policy structure to be set
 *
1110 1111
 * The function call srtp_crypto_policy_set_aes_gcm_128_16_auth(&p) sets
 * the srtp_crypto_policy_t at location p to use the SRTP default cipher
1112 1113 1114
 * (AES-128 Galois Counter Mode) with 16 octet auth tag.  This
 * policy applies confidentiality and authentication to both the
 * RTP and RTCP packets.
1115
 *
1116 1117 1118 1119
 * This function is a convenience that helps to avoid dealing directly
 * with the policy data structure.  You are encouraged to initialize
 * policy elements with this function call.  Doing so may allow your
 * code to be forward compatible with later versions of libSRTP that
1120
 * include more elements in the srtp_crypto_policy_t datatype.
1121 1122
 *
 * @return void.
1123
 *
1124
 */
1125
void srtp_crypto_policy_set_aes_gcm_128_16_auth(srtp_crypto_policy_t *p);
1126 1127

/**
1128
 * @brief srtp_crypto_policy_set_aes_gcm_256_16_auth() sets a crypto
1129 1130
 * policy structure to an AEAD encryption policy
 *
1131 1132
 * @param p is a pointer to the policy structure to be set
 *
1133 1134
 * The function call srtp_crypto_policy_set_aes_gcm_256_16_auth(&p) sets
 * 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 1137
 * policy applies confidentiality and authentication to both the
 * RTP and RTCP packets.
1138
 *
1139 1140 1141 1142
 * This function is a convenience that helps to avoid dealing directly
 * with the policy data structure.  You are encouraged to initialize
 * policy elements with this function call.  Doing so may allow your
 * code to be forward compatible with later versions of libSRTP that
1143
 * include more elements in the srtp_crypto_policy_t datatype.
1144 1145
 *
 * @return void.
1146
 *
1147
 */
1148
void srtp_crypto_policy_set_aes_gcm_256_16_auth(srtp_crypto_policy_t *p);
1149

Cullen Jennings's avatar
Cullen Jennings committed
1150 1151 1152
/**
 * @brief srtp_dealloc() deallocates storage for an SRTP session
 * context.
1153
 *
Cullen Jennings's avatar
Cullen Jennings committed
1154 1155 1156 1157 1158 1159 1160 1161
 * The function call srtp_dealloc(s) deallocates storage for the
 * SRTP session context s.  This function should be called no more
 * than one time for each of the contexts allocated by the function
 * srtp_create().
 *
 * @param s is the srtp_t for the session to be deallocated.
 *
 * @return
1162 1163
 *    - srtp_err_status_ok             if there no problems.
 *    - srtp_err_status_dealloc_fail   a memory deallocation failure occured.
Cullen Jennings's avatar
Cullen Jennings committed
1164
 */
1165
srtp_err_status_t srtp_dealloc(srtp_t s);
Cullen Jennings's avatar
Cullen Jennings committed
1166

1167
/*
1168
 * @brief identifies a particular SRTP profile
1169 1170
 *
 * An srtp_profile_t enumeration is used to identify a particular SRTP
1171 1172 1173
 * profile (that is, a set of algorithms and parameters). These profiles
 * are defined for DTLS-SRTP:
 * https://www.iana.org/assignments/srtp-protection/srtp-protection.xhtml
1174 1175
 */
typedef enum {
1176 1177 1178 1179 1180 1181 1182
    srtp_profile_reserved = 0,
    srtp_profile_aes128_cm_sha1_80 = 1,
    srtp_profile_aes128_cm_sha1_32 = 2,
    srtp_profile_null_sha1_80 = 5,
    srtp_profile_null_sha1_32 = 6,
    srtp_profile_aead_aes_128_gcm = 7,
    srtp_profile_aead_aes_256_gcm = 8,
1183 1184 1185
} srtp_profile_t;

/**
1186
 * @brief srtp_crypto_policy_set_from_profile_for_rtp() sets a crypto policy
1187 1188
 * structure to the appropriate value for RTP based on an srtp_profile_t
 *
1189 1190 1191 1192
 * @param policy is a pointer to the policy structure to be set
 *
 * @param profile is an enumeration for the policy to be set
 *
1193 1194
 * The function call srtp_crypto_policy_set_rtp_default(&policy, profile)
 * sets the srtp_crypto_policy_t at location policy to the policy for RTP
1195
 * protection, as defined by the srtp_profile_t profile.
1196
 *
1197 1198 1199 1200
 * This function is a convenience that helps to avoid dealing directly
 * with the policy data structure.  You are encouraged to initialize
 * policy elements with this function call.  Doing so may allow your
 * code to be forward compatible with later versions of libSRTP that
1201
 * include more elements in the srtp_crypto_policy_t datatype.
1202
 *
1203
 * @return values
1204
 *     - srtp_err_status_ok         no problems were encountered
1205
 *     - srtp_err_status_bad_param  the profile is not supported
1206
 *
1207
 */
1208 1209 1210
srtp_err_status_t srtp_crypto_policy_set_from_profile_for_rtp(
    srtp_crypto_policy_t *policy,
    srtp_profile_t profile);
1211 1212

/**
1213
 * @brief srtp_crypto_policy_set_from_profile_for_rtcp() sets a crypto policy
1214 1215
 * structure to the appropriate value for RTCP based on an srtp_profile_t
 *
1216 1217 1218 1219
 * @param policy is a pointer to the policy structure to be set
 *
 * @param profile is an enumeration for the policy to be set
 *
1220 1221
 * The function call srtp_crypto_policy_set_rtcp_default(&policy, profile)
 * sets the srtp_crypto_policy_t at location policy to the policy for RTCP
1222
 * protection, as defined by the srtp_profile_t profile.
1223
 *
1224 1225 1226 1227
 * This function is a convenience that helps to avoid dealing directly
 * with the policy data structure.  You are encouraged to initialize
 * policy elements with this function call.  Doing so may allow your
 * code to be forward compatible with later versions of libSRTP that
1228
 * include more elements in the srtp_crypto_policy_t datatype.
1229
 *
1230
 * @return values
1231
 *     - srtp_err_status_ok         no problems were encountered
1232 1233
 *     - srtp_err_status_bad_param  the profile is not supported
 *
1234
 */
1235 1236 1237
srtp_err_status_t srtp_crypto_policy_set_from_profile_for_rtcp(
    srtp_crypto_policy_t *policy,
    srtp_profile_t profile);
1238 1239 1240 1241

/**
 * @brief returns the master key length for a given SRTP profile
 */
1242
unsigned int srtp_profile_get_master_key_length(srtp_profile_t profile);
1243 1244 1245 1246

/**
 * @brief returns the master salt length for a given SRTP profile
 */
1247
unsigned int srtp_profile_get_master_salt_length(srtp_profile_t profile);
1248 1249 1250 1251

/**
 * @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
1254
 * the location k.
1255 1256 1257
 *
 * @warning There must be at least bytes_in_salt + bytes_in_key bytes
 *          available at the location pointed to by key.
1258
 *
1259
 */
1260 1261 1262 1263
void srtp_append_salt_to_key(unsigned char *key,
                             unsigned int bytes_in_key,
                             unsigned char *salt,
                             unsigned int bytes_in_salt);
Cullen Jennings's avatar
Cullen Jennings committed
1264 1265 1266 1267 1268 1269 1270

/**
 * @}
 */

/**
 * @defgroup SRTCP Secure RTCP
1271
 * @ingroup  SRTP
Cullen Jennings's avatar
Cullen Jennings committed
1272 1273 1274 1275 1276 1277 1278
 *
 * @brief Secure RTCP functions are used to protect RTCP traffic.
 *
 * RTCP is the control protocol for RTP.  libSRTP protects RTCP
 * traffic in much the same way as it does RTP traffic.  The function
 * srtp_protect_rtcp() applies cryptographic protections to outbound
 * RTCP packets, and srtp_unprotect_rtcp() verifies the protections on
1279
 * inbound RTCP packets.
Cullen Jennings's avatar
Cullen Jennings committed
1280 1281 1282
 *
 * A note on the naming convention: srtp_protect_rtcp() has an srtp_t
 * as its first argument, and thus has `srtp_' as its prefix.  The
1283 1284
 * trailing `_rtcp' indicates the protocol on which it acts.
 *
Cullen Jennings's avatar
Cullen Jennings committed
1285 1286 1287 1288 1289 1290
 * @{
 */

/**
 * @brief srtp_protect_rtcp() is the Secure RTCP sender-side packet
 * processing function.
1291
 *
Cullen Jennings's avatar
Cullen Jennings committed
1292 1293
 * The function call srtp_protect_rtcp(ctx, rtp_hdr, len_ptr) applies
 * 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
Cullen Jennings's avatar
Cullen Jennings committed
1295 1296 1297
 * returned, then rtp_hdr points to the resulting SRTCP packet and
 * *len_ptr is the number of octets in that packet; otherwise, no
 * assumptions should be made about the value of either data elements.
1298
 *
Cullen Jennings's avatar
Cullen Jennings committed
1299 1300 1301 1302 1303
 * @warning This function assumes that it can write the authentication
 * tag into the location in memory immediately following the RTCP
 * packet, and assumes that the RTCP packet is aligned on a 32-bit
 * boundary.
 *
1304 1305 1306
 * @warning This function assumes that it can write SRTP_MAX_TRAILER_LEN+4
 * into the location in memory immediately following the RTCP packet.
 * Callers MUST ensure that this much writable memory is available in
1307
 * the buffer that holds the RTCP packet.
1308
 *
Cullen Jennings's avatar
Cullen Jennings committed
1309 1310 1311 1312 1313 1314 1315
 * @param ctx is the SRTP context to use in processing the packet.
 *
 * @param rtcp_hdr is a pointer to the RTCP packet (before the call); after
 * the function returns, it points to the srtp packet.
 *
 * @param pkt_octet_len is a pointer to the length in octets of the
 * 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
Cullen Jennings's avatar
Cullen Jennings committed
1317 1318 1319
 * was returned.  Otherwise, the value of the data to which it points
 * is undefined.
 *
1320
 * @return
1321
 *    - srtp_err_status_ok            if there were no problems.
1322
 *    - [other]                  if there was a failure in
Cullen Jennings's avatar
Cullen Jennings committed
1323 1324
 *                               the cryptographic mechanisms.
 */
1325 1326 1327
srtp_err_status_t srtp_protect_rtcp(srtp_t ctx,
                                    void *rtcp_hdr,
                                    int *pkt_octet_len);
Ryan Hooper's avatar
Ryan Hooper committed
1328 1329 1330 1331

/**
 * @brief srtp_protect_rtcp_mki() is the Secure RTCP sender-side packet
 * processing function that can utilize mki.
1332
 *
Ryan Hooper's avatar
Ryan Hooper committed
1333 1334 1335 1336 1337 1338
 * The function call srtp_protect_rtcp(ctx, rtp_hdr, len_ptr) applies
 * SRTCP protection to the RTCP packet rtcp_hdr (which has length
 * *len_ptr) using the SRTP session context ctx.  If srtp_err_status_ok is
 * returned, then rtp_hdr points to the resulting SRTCP packet and
 * *len_ptr is the number of octets in that packet; otherwise, no
 * assumptions should be made about the value of either data elements.
1339
 *
Ryan Hooper's avatar
Ryan Hooper committed
1340 1341 1342 1343 1344
 * @warning This function assumes that it can write the authentication
 * tag into the location in memory immediately following the RTCP
 * packet, and assumes that the RTCP packet is aligned on a 32-bit
 * boundary.
 *
1345 1346 1347
 * @warning This function assumes that it can write SRTP_MAX_TRAILER_LEN+4
 * into the location in memory immediately following the RTCP packet.
 * Callers MUST ensure that this much writable memory is available in
Ryan Hooper's avatar
Ryan Hooper committed
1348
 * the buffer that holds the RTCP packet.
1349
 *
Ryan Hooper's avatar
Ryan Hooper committed
1350 1351 1352 1353 1354 1355 1356 1357 1358 1359 1360
 * @param ctx is the SRTP context to use in processing the packet.
 *
 * @param rtcp_hdr is a pointer to the RTCP packet (before the call); after
 * the function returns, it points to the srtp packet.
 *
 * @param pkt_octet_len is a pointer to the length in octets of the
 * complete RTCP packet (header and body) before the function call,
 * and of the complete SRTCP packet after the call, if srtp_err_status_ok
 * was returned.  Otherwise, the value of the data to which it points
 * is undefined.
 *
1361 1362 1363
 * @param use_mki is a boolean to tell the system if mki is being used.  If
 * set to false then will use the first set of session keys.  If set to true
 * will
Ryan Hooper's avatar
Ryan Hooper committed
1364 1365 1366 1367 1368
 * use the session keys identified by the mki_index
 *
 * @param mki_index integer value specifying which set of session kesy should be
 * used if use_mki is set to true.
 *
1369
 * @return
Ryan Hooper's avatar
Ryan Hooper committed
1370
 *    - srtp_err_status_ok            if there were no problems.
1371
 *    - [other]                  if there was a failure in
Ryan Hooper's avatar
Ryan Hooper committed
1372 1373
 *                               the cryptographic mechanisms.
 */
1374 1375 1376 1377 1378
srtp_err_status_t srtp_protect_rtcp_mki(srtp_t ctx,
                                        void *rtcp_hdr,
                                        int *pkt_octet_len,
                                        unsigned int use_mki,
                                        unsigned int mki_index);
Ryan Hooper's avatar
Ryan Hooper committed
1379

Cullen Jennings's avatar
Cullen Jennings committed
1380 1381 1382 1383 1384 1385 1386
/**
 * @brief srtp_unprotect_rtcp() is the Secure RTCP receiver-side packet
 * processing function.
 *
 * The function call srtp_unprotect_rtcp(ctx, srtp_hdr, len_ptr)
 * verifies the Secure RTCP protection of the SRTCP packet pointed to
 * 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
Cullen Jennings's avatar
Cullen Jennings committed
1388 1389 1390
 * to the resulting RTCP packet and *len_ptr is the number of octets
 * in that packet; otherwise, no assumptions should be made about the
 * value of either data elements.
1391
 *
Cullen Jennings's avatar
Cullen Jennings committed
1392 1393 1394 1395 1396 1397 1398 1399
 * @warning This function assumes that the SRTCP packet is aligned on a
 * 32-bit boundary.
 *
 * @param ctx is a pointer to the srtp_t which applies to the
 * particular packet.
 *
 * @param srtcp_hdr is a pointer to the header of the SRTCP packet
 * (before the call).  After the function returns, it points to the