1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/netwerk/srtp/src/include/srtp.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,1006 @@
1.4 +/*
1.5 + * srtp.h
1.6 + *
1.7 + * interface to libsrtp
1.8 + *
1.9 + * David A. McGrew
1.10 + * Cisco Systems, Inc.
1.11 + */
1.12 +/*
1.13 + *
1.14 + * Copyright (c) 2001-2006, Cisco Systems, Inc.
1.15 + * All rights reserved.
1.16 + *
1.17 + * Redistribution and use in source and binary forms, with or without
1.18 + * modification, are permitted provided that the following conditions
1.19 + * are met:
1.20 + *
1.21 + * Redistributions of source code must retain the above copyright
1.22 + * notice, this list of conditions and the following disclaimer.
1.23 + *
1.24 + * Redistributions in binary form must reproduce the above
1.25 + * copyright notice, this list of conditions and the following
1.26 + * disclaimer in the documentation and/or other materials provided
1.27 + * with the distribution.
1.28 + *
1.29 + * Neither the name of the Cisco Systems, Inc. nor the names of its
1.30 + * contributors may be used to endorse or promote products derived
1.31 + * from this software without specific prior written permission.
1.32 + *
1.33 + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
1.34 + * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
1.35 + * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
1.36 + * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
1.37 + * COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
1.38 + * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
1.39 + * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
1.40 + * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
1.41 + * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
1.42 + * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
1.43 + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
1.44 + * OF THE POSSIBILITY OF SUCH DAMAGE.
1.45 + *
1.46 + */
1.47 +
1.48 +
1.49 +#ifndef SRTP_H
1.50 +#define SRTP_H
1.51 +
1.52 +#ifdef __cplusplus
1.53 +extern "C" {
1.54 +#endif
1.55 +
1.56 +#include "crypto_kernel.h"
1.57 +
1.58 +/**
1.59 + * @defgroup SRTP Secure RTP
1.60 + *
1.61 + * @brief libSRTP provides functions for protecting RTP and RTCP. See
1.62 + * Section @ref Overview for an introduction to the use of the library.
1.63 + *
1.64 + * @{
1.65 + */
1.66 +
1.67 +/*
1.68 + * SRTP_MASTER_KEY_LEN is the nominal master key length supported by libSRTP
1.69 + */
1.70 +
1.71 +#define SRTP_MASTER_KEY_LEN 30
1.72 +
1.73 +/*
1.74 + * SRTP_MAX_KEY_LEN is the maximum key length supported by libSRTP
1.75 + */
1.76 +#define SRTP_MAX_KEY_LEN 64
1.77 +
1.78 +/*
1.79 + * SRTP_MAX_TAG_LEN is the maximum tag length supported by libSRTP
1.80 + */
1.81 +
1.82 +#define SRTP_MAX_TAG_LEN 12
1.83 +
1.84 +/**
1.85 + * SRTP_MAX_TRAILER_LEN is the maximum length of the SRTP trailer
1.86 + * (authentication tag and MKI) supported by libSRTP. This value is
1.87 + * the maximum number of octets that will be added to an RTP packet by
1.88 + * srtp_protect().
1.89 + *
1.90 + * @brief the maximum number of octets added by srtp_protect().
1.91 + */
1.92 +#define SRTP_MAX_TRAILER_LEN SRTP_MAX_TAG_LEN
1.93 +
1.94 +/*
1.95 + * nota bene: since libSRTP doesn't support the use of the MKI, the
1.96 + * SRTP_MAX_TRAILER_LEN value is just the maximum tag length
1.97 + */
1.98 +
1.99 +/**
1.100 + * @brief sec_serv_t describes a set of security services.
1.101 + *
1.102 + * A sec_serv_t enumeration is used to describe the particular
1.103 + * security services that will be applied by a particular crypto
1.104 + * policy (or other mechanism).
1.105 + */
1.106 +
1.107 +typedef enum {
1.108 + sec_serv_none = 0, /**< no services */
1.109 + sec_serv_conf = 1, /**< confidentiality */
1.110 + sec_serv_auth = 2, /**< authentication */
1.111 + sec_serv_conf_and_auth = 3 /**< confidentiality and authentication */
1.112 +} sec_serv_t;
1.113 +
1.114 +/**
1.115 + * @brief crypto_policy_t describes a particular crypto policy that
1.116 + * can be applied to an SRTP stream.
1.117 + *
1.118 + * A crypto_policy_t describes a particular cryptographic policy that
1.119 + * can be applied to an SRTP or SRTCP stream. An SRTP session policy
1.120 + * consists of a list of these policies, one for each SRTP stream
1.121 + * in the session.
1.122 + */
1.123 +
1.124 +typedef struct crypto_policy_t {
1.125 + cipher_type_id_t cipher_type; /**< An integer representing
1.126 + * the type of cipher. */
1.127 + int cipher_key_len; /**< The length of the cipher key
1.128 + * in octets. */
1.129 + auth_type_id_t auth_type; /**< An integer representing the
1.130 + * authentication function. */
1.131 + int auth_key_len; /**< The length of the authentication
1.132 + * function key in octets. */
1.133 + int auth_tag_len; /**< The length of the authentication
1.134 + * tag in octets. */
1.135 + sec_serv_t sec_serv; /**< The flag indicating the security
1.136 + * services to be applied. */
1.137 +} crypto_policy_t;
1.138 +
1.139 +
1.140 +/**
1.141 + * @brief ssrc_type_t describes the type of an SSRC.
1.142 + *
1.143 + * An ssrc_type_t enumeration is used to indicate a type of SSRC. See
1.144 + * @ref srtp_policy_t for more informataion.
1.145 + */
1.146 +
1.147 +typedef enum {
1.148 + ssrc_undefined = 0, /**< Indicates an undefined SSRC type. */
1.149 + ssrc_specific = 1, /**< Indicates a specific SSRC value */
1.150 + ssrc_any_inbound = 2, /**< Indicates any inbound SSRC value
1.151 + (i.e. a value that is used in the
1.152 + function srtp_unprotect()) */
1.153 + ssrc_any_outbound = 3 /**< Indicates any outbound SSRC value
1.154 + (i.e. a value that is used in the
1.155 + function srtp_protect()) */
1.156 +} ssrc_type_t;
1.157 +
1.158 +/**
1.159 + * @brief An ssrc_t represents a particular SSRC value, or a `wildcard' SSRC.
1.160 + *
1.161 + * An ssrc_t represents a particular SSRC value (if its type is
1.162 + * ssrc_specific), or a wildcard SSRC value that will match all
1.163 + * outbound SSRCs (if its type is ssrc_any_outbound) or all inbound
1.164 + * SSRCs (if its type is ssrc_any_inbound).
1.165 + *
1.166 + */
1.167 +
1.168 +typedef struct {
1.169 + ssrc_type_t type; /**< The type of this particular SSRC */
1.170 + unsigned int value; /**< The value of this SSRC, if it is not a wildcard */
1.171 +} ssrc_t;
1.172 +
1.173 +
1.174 +/**
1.175 + * @brief points to an EKT policy
1.176 + */
1.177 +typedef struct ekt_policy_ctx_t *ekt_policy_t;
1.178 +
1.179 +
1.180 +/**
1.181 + * @brief points to EKT stream data
1.182 + */
1.183 +typedef struct ekt_stream_ctx_t *ekt_stream_t;
1.184 +
1.185 +
1.186 +/**
1.187 + * @brief represents the policy for an SRTP session.
1.188 + *
1.189 + * A single srtp_policy_t struct represents the policy for a single
1.190 + * SRTP stream, and a linked list of these elements represents the
1.191 + * policy for an entire SRTP session. Each element contains the SRTP
1.192 + * and SRTCP crypto policies for that stream, a pointer to the SRTP
1.193 + * master key for that stream, the SSRC describing that stream, or a
1.194 + * flag indicating a `wildcard' SSRC value, and a `next' field that
1.195 + * holds a pointer to the next element in the list of policy elements,
1.196 + * or NULL if it is the last element.
1.197 + *
1.198 + * The wildcard value SSRC_ANY_INBOUND matches any SSRC from an
1.199 + * inbound stream that for which there is no explicit SSRC entry in
1.200 + * another policy element. Similarly, the value SSRC_ANY_OUTBOUND
1.201 + * will matches any SSRC from an outbound stream that does not appear
1.202 + * in another policy element. Note that wildcard SSRCs &b cannot be
1.203 + * used to match both inbound and outbound traffic. This restriction
1.204 + * is intentional, and it allows libSRTP to ensure that no security
1.205 + * lapses result from accidental re-use of SSRC values during key
1.206 + * sharing.
1.207 + *
1.208 + *
1.209 + * @warning The final element of the list @b must have its `next' pointer
1.210 + * set to NULL.
1.211 + */
1.212 +
1.213 +typedef struct srtp_policy_t {
1.214 + ssrc_t ssrc; /**< The SSRC value of stream, or the
1.215 + * flags SSRC_ANY_INBOUND or
1.216 + * SSRC_ANY_OUTBOUND if key sharing
1.217 + * is used for this policy element.
1.218 + */
1.219 + crypto_policy_t rtp; /**< SRTP crypto policy. */
1.220 + crypto_policy_t rtcp; /**< SRTCP crypto policy. */
1.221 + unsigned char *key; /**< Pointer to the SRTP master key for
1.222 + * this stream. */
1.223 + ekt_policy_t ekt; /**< Pointer to the EKT policy structure
1.224 + * for this stream (if any) */
1.225 + unsigned long window_size; /**< The window size to use for replay
1.226 + * protection. */
1.227 + int allow_repeat_tx; /**< Whether retransmissions of
1.228 + * packets with the same sequence number
1.229 + * are allowed. (Note that such repeated
1.230 + * transmissions must have the same RTP
1.231 + * payload, or a severe security weakness
1.232 + * is introduced!) */
1.233 + struct srtp_policy_t *next; /**< Pointer to next stream policy. */
1.234 +} srtp_policy_t;
1.235 +
1.236 +
1.237 +
1.238 +
1.239 +/**
1.240 + * @brief An srtp_t points to an SRTP session structure.
1.241 + *
1.242 + * The typedef srtp_t is a pointer to a structure that represents
1.243 + * an SRTP session. This datatype is intentially opaque in
1.244 + * order to separate the interface from the implementation.
1.245 + *
1.246 + * An SRTP session consists of all of the traffic sent to the RTP and
1.247 + * RTCP destination transport addresses, using the RTP/SAVP (Secure
1.248 + * Audio/Video Profile). A session can be viewed as a set of SRTP
1.249 + * streams, each of which originates with a different participant.
1.250 + */
1.251 +
1.252 +typedef struct srtp_ctx_t *srtp_t;
1.253 +
1.254 +
1.255 +/**
1.256 + * @brief An srtp_stream_t points to an SRTP stream structure.
1.257 + *
1.258 + * The typedef srtp_stream_t is a pointer to a structure that
1.259 + * represents an SRTP stream. This datatype is intentionally
1.260 + * opaque in order to separate the interface from the implementation.
1.261 + *
1.262 + * An SRTP stream consists of all of the traffic sent to an SRTP
1.263 + * session by a single participant. A session can be viewed as
1.264 + * a set of streams.
1.265 + *
1.266 + */
1.267 +typedef struct srtp_stream_ctx_t *srtp_stream_t;
1.268 +
1.269 +
1.270 +
1.271 +/**
1.272 + * @brief srtp_init() initializes the srtp library.
1.273 + *
1.274 + * @warning This function @b must be called before any other srtp
1.275 + * functions.
1.276 + */
1.277 +
1.278 +err_status_t
1.279 +srtp_init(void);
1.280 +
1.281 +/**
1.282 + * @brief srtp_shutdown() de-initializes the srtp library.
1.283 + *
1.284 + * @warning No srtp functions may be called after calling this function.
1.285 + */
1.286 +
1.287 +err_status_t
1.288 +srtp_shutdown(void);
1.289 +
1.290 +/**
1.291 + * @brief srtp_protect() is the Secure RTP sender-side packet processing
1.292 + * function.
1.293 + *
1.294 + * The function call srtp_protect(ctx, rtp_hdr, len_ptr) applies SRTP
1.295 + * protection to the RTP packet rtp_hdr (which has length *len_ptr) using
1.296 + * the SRTP context ctx. If err_status_ok is returned, then rtp_hdr
1.297 + * points to the resulting SRTP packet and *len_ptr is the number of
1.298 + * octets in that packet; otherwise, no assumptions should be made
1.299 + * about the value of either data elements.
1.300 + *
1.301 + * The sequence numbers of the RTP packets presented to this function
1.302 + * need not be consecutive, but they @b must be out of order by less
1.303 + * than 2^15 = 32,768 packets.
1.304 + *
1.305 + * @warning This function assumes that it can write the authentication
1.306 + * tag into the location in memory immediately following the RTP
1.307 + * packet, and assumes that the RTP packet is aligned on a 32-bit
1.308 + * boundary.
1.309 + *
1.310 + * @param ctx is the SRTP context to use in processing the packet.
1.311 + *
1.312 + * @param rtp_hdr is a pointer to the RTP packet (before the call); after
1.313 + * the function returns, it points to the srtp packet.
1.314 + *
1.315 + * @param len_ptr is a pointer to the length in octets of the complete
1.316 + * RTP packet (header and body) before the function call, and of the
1.317 + * complete SRTP packet after the call, if err_status_ok was returned.
1.318 + * Otherwise, the value of the data to which it points is undefined.
1.319 + *
1.320 + * @return
1.321 + * - err_status_ok no problems
1.322 + * - err_status_replay_fail rtp sequence number was non-increasing
1.323 + * - @e other failure in cryptographic mechanisms
1.324 + */
1.325 +
1.326 +err_status_t
1.327 +srtp_protect(srtp_t ctx, void *rtp_hdr, int *len_ptr);
1.328 +
1.329 +/**
1.330 + * @brief srtp_unprotect() is the Secure RTP receiver-side packet
1.331 + * processing function.
1.332 + *
1.333 + * The function call srtp_unprotect(ctx, srtp_hdr, len_ptr) verifies
1.334 + * the Secure RTP protection of the SRTP packet pointed to by srtp_hdr
1.335 + * (which has length *len_ptr), using the SRTP context ctx. If
1.336 + * err_status_ok is returned, then srtp_hdr points to the resulting
1.337 + * RTP packet and *len_ptr is the number of octets in that packet;
1.338 + * otherwise, no assumptions should be made about the value of either
1.339 + * data elements.
1.340 + *
1.341 + * The sequence numbers of the RTP packets presented to this function
1.342 + * need not be consecutive, but they @b must be out of order by less
1.343 + * than 2^15 = 32,768 packets.
1.344 + *
1.345 + * @warning This function assumes that the SRTP packet is aligned on a
1.346 + * 32-bit boundary.
1.347 + *
1.348 + * @param ctx is a pointer to the srtp_t which applies to the
1.349 + * particular packet.
1.350 + *
1.351 + * @param srtp_hdr is a pointer to the header of the SRTP packet
1.352 + * (before the call). after the function returns, it points to the
1.353 + * rtp packet if err_status_ok was returned; otherwise, the value of
1.354 + * the data to which it points is undefined.
1.355 + *
1.356 + * @param len_ptr is a pointer to the length in octets of the complete
1.357 + * srtp packet (header and body) before the function call, and of the
1.358 + * complete rtp packet after the call, if err_status_ok was returned.
1.359 + * Otherwise, the value of the data to which it points is undefined.
1.360 + *
1.361 + * @return
1.362 + * - err_status_ok if the RTP packet is valid.
1.363 + * - err_status_auth_fail if the SRTP packet failed the message
1.364 + * authentication check.
1.365 + * - err_status_replay_fail if the SRTP packet is a replay (e.g. packet has
1.366 + * already been processed and accepted).
1.367 + * - [other] if there has been an error in the cryptographic mechanisms.
1.368 + *
1.369 + */
1.370 +
1.371 +err_status_t
1.372 +srtp_unprotect(srtp_t ctx, void *srtp_hdr, int *len_ptr);
1.373 +
1.374 +
1.375 +/**
1.376 + * @brief srtp_create() allocates and initializes an SRTP session.
1.377 +
1.378 + * The function call srtp_create(session, policy, key) allocates and
1.379 + * initializes an SRTP session context, applying the given policy and
1.380 + * key.
1.381 + *
1.382 + * @param session is the SRTP session to which the policy is to be added.
1.383 + *
1.384 + * @param policy is the srtp_policy_t struct that describes the policy
1.385 + * for the session. The struct may be a single element, or it may be
1.386 + * the head of a list, in which case each element of the list is
1.387 + * processed. It may also be NULL, in which case streams should be added
1.388 + * later using srtp_add_stream(). The final element of the list @b must
1.389 + * have its `next' field set to NULL.
1.390 + *
1.391 + * @return
1.392 + * - err_status_ok if creation succeded.
1.393 + * - err_status_alloc_fail if allocation failed.
1.394 + * - err_status_init_fail if initialization failed.
1.395 + */
1.396 +
1.397 +err_status_t
1.398 +srtp_create(srtp_t *session, const srtp_policy_t *policy);
1.399 +
1.400 +
1.401 +/**
1.402 + * @brief srtp_add_stream() allocates and initializes an SRTP stream
1.403 + * within a given SRTP session.
1.404 + *
1.405 + * The function call srtp_add_stream(session, policy) allocates and
1.406 + * initializes a new SRTP stream within a given, previously created
1.407 + * session, applying the policy given as the other argument to that
1.408 + * stream.
1.409 + *
1.410 + * @return values:
1.411 + * - err_status_ok if stream creation succeded.
1.412 + * - err_status_alloc_fail if stream allocation failed
1.413 + * - err_status_init_fail if stream initialization failed.
1.414 + */
1.415 +
1.416 +err_status_t
1.417 +srtp_add_stream(srtp_t session,
1.418 + const srtp_policy_t *policy);
1.419 +
1.420 +
1.421 +/**
1.422 + * @brief srtp_remove_stream() deallocates an SRTP stream.
1.423 + *
1.424 + * The function call srtp_remove_stream(session, ssrc) removes
1.425 + * the SRTP stream with the SSRC value ssrc from the SRTP session
1.426 + * context given by the argument session.
1.427 + *
1.428 + * @param session is the SRTP session from which the stream
1.429 + * will be removed.
1.430 + *
1.431 + * @param ssrc is the SSRC value of the stream to be removed.
1.432 + *
1.433 + * @warning Wildcard SSRC values cannot be removed from a
1.434 + * session.
1.435 + *
1.436 + * @return
1.437 + * - err_status_ok if the stream deallocation succeded.
1.438 + * - [other] otherwise.
1.439 + *
1.440 + */
1.441 +
1.442 +err_status_t
1.443 +srtp_remove_stream(srtp_t session, unsigned int ssrc);
1.444 +
1.445 +/**
1.446 + * @brief crypto_policy_set_rtp_default() sets a crypto policy
1.447 + * structure to the SRTP default policy for RTP protection.
1.448 + *
1.449 + * @param p is a pointer to the policy structure to be set
1.450 + *
1.451 + * The function call crypto_policy_set_rtp_default(&p) sets the
1.452 + * crypto_policy_t at location p to the SRTP default policy for RTP
1.453 + * protection, as defined in the specification. This function is a
1.454 + * convenience that helps to avoid dealing directly with the policy
1.455 + * data structure. You are encouraged to initialize policy elements
1.456 + * with this function call. Doing so may allow your code to be
1.457 + * forward compatible with later versions of libSRTP that include more
1.458 + * elements in the crypto_policy_t datatype.
1.459 + *
1.460 + * @return void.
1.461 + *
1.462 + */
1.463 +
1.464 +void
1.465 +crypto_policy_set_rtp_default(crypto_policy_t *p);
1.466 +
1.467 +/**
1.468 + * @brief crypto_policy_set_rtcp_default() sets a crypto policy
1.469 + * structure to the SRTP default policy for RTCP protection.
1.470 + *
1.471 + * @param p is a pointer to the policy structure to be set
1.472 + *
1.473 + * The function call crypto_policy_set_rtcp_default(&p) sets the
1.474 + * crypto_policy_t at location p to the SRTP default policy for RTCP
1.475 + * protection, as defined in the specification. This function is a
1.476 + * convenience that helps to avoid dealing directly with the policy
1.477 + * data structure. You are encouraged to initialize policy elements
1.478 + * with this function call. Doing so may allow your code to be
1.479 + * forward compatible with later versions of libSRTP that include more
1.480 + * elements in the crypto_policy_t datatype.
1.481 + *
1.482 + * @return void.
1.483 + *
1.484 + */
1.485 +
1.486 +void
1.487 +crypto_policy_set_rtcp_default(crypto_policy_t *p);
1.488 +
1.489 +/**
1.490 + * @brief crypto_policy_set_aes_cm_128_hmac_sha1_80() sets a crypto
1.491 + * policy structure to the SRTP default policy for RTP protection.
1.492 + *
1.493 + * @param p is a pointer to the policy structure to be set
1.494 + *
1.495 + * The function crypto_policy_set_aes_cm_128_hmac_sha1_80() is a
1.496 + * synonym for crypto_policy_set_rtp_default(). It conforms to the
1.497 + * naming convention used in RFC 4568 (SDP Security Descriptions for
1.498 + * Media Streams).
1.499 + *
1.500 + * @return void.
1.501 + *
1.502 + */
1.503 +
1.504 +#define crypto_policy_set_aes_cm_128_hmac_sha1_80(p) crypto_policy_set_rtp_default(p)
1.505 +
1.506 +
1.507 +/**
1.508 + * @brief crypto_policy_set_aes_cm_128_hmac_sha1_32() sets a crypto
1.509 + * policy structure to a short-authentication tag policy
1.510 + *
1.511 + * @param p is a pointer to the policy structure to be set
1.512 + *
1.513 + * The function call crypto_policy_set_aes_cm_128_hmac_sha1_32(&p)
1.514 + * sets the crypto_policy_t at location p to use policy
1.515 + * AES_CM_128_HMAC_SHA1_32 as defined in RFC 4568.
1.516 + * This policy uses AES-128
1.517 + * Counter Mode encryption and HMAC-SHA1 authentication, with an
1.518 + * authentication tag that is only 32 bits long. This length is
1.519 + * considered adequate only for protecting audio and video media that
1.520 + * use a stateless playback function. See Section 7.5 of RFC 3711
1.521 + * (http://www.ietf.org/rfc/rfc3711.txt).
1.522 + *
1.523 + * This function is a convenience that helps to avoid dealing directly
1.524 + * with the policy data structure. You are encouraged to initialize
1.525 + * policy elements with this function call. Doing so may allow your
1.526 + * code to be forward compatible with later versions of libSRTP that
1.527 + * include more elements in the crypto_policy_t datatype.
1.528 + *
1.529 + * @warning This crypto policy is intended for use in SRTP, but not in
1.530 + * SRTCP. It is recommended that a policy that uses longer
1.531 + * authentication tags be used for SRTCP. See Section 7.5 of RFC 3711
1.532 + * (http://www.ietf.org/rfc/rfc3711.txt).
1.533 + *
1.534 + * @return void.
1.535 + *
1.536 + */
1.537 +
1.538 +void
1.539 +crypto_policy_set_aes_cm_128_hmac_sha1_32(crypto_policy_t *p);
1.540 +
1.541 +
1.542 +
1.543 +/**
1.544 + * @brief crypto_policy_set_aes_cm_128_null_auth() sets a crypto
1.545 + * policy structure to an encryption-only policy
1.546 + *
1.547 + * @param p is a pointer to the policy structure to be set
1.548 + *
1.549 + * The function call crypto_policy_set_aes_cm_128_null_auth(&p) sets
1.550 + * the crypto_policy_t at location p to use the SRTP default cipher
1.551 + * (AES-128 Counter Mode), but to use no authentication method. This
1.552 + * policy is NOT RECOMMENDED unless it is unavoidable; see Section 7.5
1.553 + * of RFC 3711 (http://www.ietf.org/rfc/rfc3711.txt).
1.554 + *
1.555 + * This function is a convenience that helps to avoid dealing directly
1.556 + * with the policy data structure. You are encouraged to initialize
1.557 + * policy elements with this function call. Doing so may allow your
1.558 + * code to be forward compatible with later versions of libSRTP that
1.559 + * include more elements in the crypto_policy_t datatype.
1.560 + *
1.561 + * @warning This policy is NOT RECOMMENDED for SRTP unless it is
1.562 + * unavoidable, and it is NOT RECOMMENDED at all for SRTCP; see
1.563 + * Section 7.5 of RFC 3711 (http://www.ietf.org/rfc/rfc3711.txt).
1.564 + *
1.565 + * @return void.
1.566 + *
1.567 + */
1.568 +
1.569 +void
1.570 +crypto_policy_set_aes_cm_128_null_auth(crypto_policy_t *p);
1.571 +
1.572 +
1.573 +/**
1.574 + * @brief crypto_policy_set_null_cipher_hmac_sha1_80() sets a crypto
1.575 + * policy structure to an authentication-only policy
1.576 + *
1.577 + * @param p is a pointer to the policy structure to be set
1.578 + *
1.579 + * The function call crypto_policy_set_null_cipher_hmac_sha1_80(&p)
1.580 + * sets the crypto_policy_t at location p to use HMAC-SHA1 with an 80
1.581 + * bit authentication tag to provide message authentication, but to
1.582 + * use no encryption. This policy is NOT RECOMMENDED for SRTP unless
1.583 + * there is a requirement to forego encryption.
1.584 + *
1.585 + * This function is a convenience that helps to avoid dealing directly
1.586 + * with the policy data structure. You are encouraged to initialize
1.587 + * policy elements with this function call. Doing so may allow your
1.588 + * code to be forward compatible with later versions of libSRTP that
1.589 + * include more elements in the crypto_policy_t datatype.
1.590 + *
1.591 + * @warning This policy is NOT RECOMMENDED for SRTP unless there is a
1.592 + * requirement to forego encryption.
1.593 + *
1.594 + * @return void.
1.595 + *
1.596 + */
1.597 +
1.598 +void
1.599 +crypto_policy_set_null_cipher_hmac_sha1_80(crypto_policy_t *p);
1.600 +
1.601 +
1.602 +/**
1.603 + * @brief crypto_policy_set_aes_cm_256_hmac_sha1_80() sets a crypto
1.604 + * policy structure to a encryption and authentication policy using AES-256
1.605 + * for RTP protection.
1.606 + *
1.607 + * @param p is a pointer to the policy structure to be set
1.608 + *
1.609 + * The function call crypto_policy_set_aes_cm_256_hmac_sha1_80(&p)
1.610 + * sets the crypto_policy_t at location p to use policy
1.611 + * AES_CM_256_HMAC_SHA1_80 as defined in
1.612 + * draft-ietf-avt-srtp-big-aes-03.txt. This policy uses AES-256
1.613 + * Counter Mode encryption and HMAC-SHA1 authentication, with an 80 bit
1.614 + * authentication tag.
1.615 + *
1.616 + * This function is a convenience that helps to avoid dealing directly
1.617 + * with the policy data structure. You are encouraged to initialize
1.618 + * policy elements with this function call. Doing so may allow your
1.619 + * code to be forward compatible with later versions of libSRTP that
1.620 + * include more elements in the crypto_policy_t datatype.
1.621 + *
1.622 + * @return void.
1.623 + *
1.624 + */
1.625 +
1.626 +void crypto_policy_set_aes_cm_256_hmac_sha1_80(crypto_policy_t *p);
1.627 +
1.628 +
1.629 +/**
1.630 + * @brief crypto_policy_set_aes_cm_256_hmac_sha1_32() sets a crypto
1.631 + * policy structure to a short-authentication tag policy using AES-256
1.632 + * encryption.
1.633 + *
1.634 + * @param p is a pointer to the policy structure to be set
1.635 + *
1.636 + * The function call crypto_policy_set_aes_cm_256_hmac_sha1_32(&p)
1.637 + * sets the crypto_policy_t at location p to use policy
1.638 + * AES_CM_256_HMAC_SHA1_32 as defined in
1.639 + * draft-ietf-avt-srtp-big-aes-03.txt. This policy uses AES-256
1.640 + * Counter Mode encryption and HMAC-SHA1 authentication, with an
1.641 + * authentication tag that is only 32 bits long. This length is
1.642 + * considered adequate only for protecting audio and video media that
1.643 + * use a stateless playback function. See Section 7.5 of RFC 3711
1.644 + * (http://www.ietf.org/rfc/rfc3711.txt).
1.645 + *
1.646 + * This function is a convenience that helps to avoid dealing directly
1.647 + * with the policy data structure. You are encouraged to initialize
1.648 + * policy elements with this function call. Doing so may allow your
1.649 + * code to be forward compatible with later versions of libSRTP that
1.650 + * include more elements in the crypto_policy_t datatype.
1.651 + *
1.652 + * @warning This crypto policy is intended for use in SRTP, but not in
1.653 + * SRTCP. It is recommended that a policy that uses longer
1.654 + * authentication tags be used for SRTCP. See Section 7.5 of RFC 3711
1.655 + * (http://www.ietf.org/rfc/rfc3711.txt).
1.656 + *
1.657 + * @return void.
1.658 + *
1.659 + */
1.660 +
1.661 +void
1.662 +crypto_policy_set_aes_cm_256_hmac_sha1_32(crypto_policy_t *p);
1.663 +
1.664 +
1.665 +/**
1.666 + * @brief srtp_dealloc() deallocates storage for an SRTP session
1.667 + * context.
1.668 + *
1.669 + * The function call srtp_dealloc(s) deallocates storage for the
1.670 + * SRTP session context s. This function should be called no more
1.671 + * than one time for each of the contexts allocated by the function
1.672 + * srtp_create().
1.673 + *
1.674 + * @param s is the srtp_t for the session to be deallocated.
1.675 + *
1.676 + * @return
1.677 + * - err_status_ok if there no problems.
1.678 + * - err_status_dealloc_fail a memory deallocation failure occured.
1.679 + */
1.680 +
1.681 +err_status_t
1.682 +srtp_dealloc(srtp_t s);
1.683 +
1.684 +
1.685 +/*
1.686 + * @brief identifies a particular SRTP profile
1.687 + *
1.688 + * An srtp_profile_t enumeration is used to identify a particular SRTP
1.689 + * profile (that is, a set of algorithms and parameters). These
1.690 + * profiles are defined in the DTLS-SRTP draft.
1.691 + */
1.692 +
1.693 +typedef enum {
1.694 + srtp_profile_reserved = 0,
1.695 + srtp_profile_aes128_cm_sha1_80 = 1,
1.696 + srtp_profile_aes128_cm_sha1_32 = 2,
1.697 + srtp_profile_aes256_cm_sha1_80 = 3,
1.698 + srtp_profile_aes256_cm_sha1_32 = 4,
1.699 + srtp_profile_null_sha1_80 = 5,
1.700 + srtp_profile_null_sha1_32 = 6,
1.701 +} srtp_profile_t;
1.702 +
1.703 +
1.704 +/**
1.705 + * @brief crypto_policy_set_from_profile_for_rtp() sets a crypto policy
1.706 + * structure to the appropriate value for RTP based on an srtp_profile_t
1.707 + *
1.708 + * @param p is a pointer to the policy structure to be set
1.709 + *
1.710 + * The function call crypto_policy_set_rtp_default(&policy, profile)
1.711 + * sets the crypto_policy_t at location policy to the policy for RTP
1.712 + * protection, as defined by the srtp_profile_t profile.
1.713 + *
1.714 + * This function is a convenience that helps to avoid dealing directly
1.715 + * with the policy data structure. You are encouraged to initialize
1.716 + * policy elements with this function call. Doing so may allow your
1.717 + * code to be forward compatible with later versions of libSRTP that
1.718 + * include more elements in the crypto_policy_t datatype.
1.719 + *
1.720 + * @return values
1.721 + * - err_status_ok no problems were encountered
1.722 + * - err_status_bad_param the profile is not supported
1.723 + *
1.724 + */
1.725 +err_status_t
1.726 +crypto_policy_set_from_profile_for_rtp(crypto_policy_t *policy,
1.727 + srtp_profile_t profile);
1.728 +
1.729 +
1.730 +
1.731 +
1.732 +/**
1.733 + * @brief crypto_policy_set_from_profile_for_rtcp() sets a crypto policy
1.734 + * structure to the appropriate value for RTCP based on an srtp_profile_t
1.735 + *
1.736 + * @param p is a pointer to the policy structure to be set
1.737 + *
1.738 + * The function call crypto_policy_set_rtcp_default(&policy, profile)
1.739 + * sets the crypto_policy_t at location policy to the policy for RTCP
1.740 + * protection, as defined by the srtp_profile_t profile.
1.741 + *
1.742 + * This function is a convenience that helps to avoid dealing directly
1.743 + * with the policy data structure. You are encouraged to initialize
1.744 + * policy elements with this function call. Doing so may allow your
1.745 + * code to be forward compatible with later versions of libSRTP that
1.746 + * include more elements in the crypto_policy_t datatype.
1.747 + *
1.748 + * @return values
1.749 + * - err_status_ok no problems were encountered
1.750 + * - err_status_bad_param the profile is not supported
1.751 + *
1.752 + */
1.753 +err_status_t
1.754 +crypto_policy_set_from_profile_for_rtcp(crypto_policy_t *policy,
1.755 + srtp_profile_t profile);
1.756 +
1.757 +/**
1.758 + * @brief returns the master key length for a given SRTP profile
1.759 + */
1.760 +unsigned int
1.761 +srtp_profile_get_master_key_length(srtp_profile_t profile);
1.762 +
1.763 +
1.764 +/**
1.765 + * @brief returns the master salt length for a given SRTP profile
1.766 + */
1.767 +unsigned int
1.768 +srtp_profile_get_master_salt_length(srtp_profile_t profile);
1.769 +
1.770 +/**
1.771 + * @brief appends the salt to the key
1.772 + *
1.773 + * The function call append_salt_to_key(k, klen, s, slen)
1.774 + * copies the string s to the location at klen bytes following
1.775 + * the location k.
1.776 + *
1.777 + * @warning There must be at least bytes_in_salt + bytes_in_key bytes
1.778 + * available at the location pointed to by key.
1.779 + *
1.780 + */
1.781 +
1.782 +void
1.783 +append_salt_to_key(unsigned char *key, unsigned int bytes_in_key,
1.784 + unsigned char *salt, unsigned int bytes_in_salt);
1.785 +
1.786 +
1.787 +
1.788 +/**
1.789 + * @}
1.790 + */
1.791 +
1.792 +
1.793 +
1.794 +/**
1.795 + * @defgroup SRTCP Secure RTCP
1.796 + * @ingroup SRTP
1.797 + *
1.798 + * @brief Secure RTCP functions are used to protect RTCP traffic.
1.799 + *
1.800 + * RTCP is the control protocol for RTP. libSRTP protects RTCP
1.801 + * traffic in much the same way as it does RTP traffic. The function
1.802 + * srtp_protect_rtcp() applies cryptographic protections to outbound
1.803 + * RTCP packets, and srtp_unprotect_rtcp() verifies the protections on
1.804 + * inbound RTCP packets.
1.805 + *
1.806 + * A note on the naming convention: srtp_protect_rtcp() has an srtp_t
1.807 + * as its first argument, and thus has `srtp_' as its prefix. The
1.808 + * trailing `_rtcp' indicates the protocol on which it acts.
1.809 + *
1.810 + * @{
1.811 + */
1.812 +
1.813 +/**
1.814 + * @brief srtp_protect_rtcp() is the Secure RTCP sender-side packet
1.815 + * processing function.
1.816 + *
1.817 + * The function call srtp_protect_rtcp(ctx, rtp_hdr, len_ptr) applies
1.818 + * SRTCP protection to the RTCP packet rtcp_hdr (which has length
1.819 + * *len_ptr) using the SRTP session context ctx. If err_status_ok is
1.820 + * returned, then rtp_hdr points to the resulting SRTCP packet and
1.821 + * *len_ptr is the number of octets in that packet; otherwise, no
1.822 + * assumptions should be made about the value of either data elements.
1.823 + *
1.824 + * @warning This function assumes that it can write the authentication
1.825 + * tag into the location in memory immediately following the RTCP
1.826 + * packet, and assumes that the RTCP packet is aligned on a 32-bit
1.827 + * boundary.
1.828 + *
1.829 + * @param ctx is the SRTP context to use in processing the packet.
1.830 + *
1.831 + * @param rtcp_hdr is a pointer to the RTCP packet (before the call); after
1.832 + * the function returns, it points to the srtp packet.
1.833 + *
1.834 + * @param pkt_octet_len is a pointer to the length in octets of the
1.835 + * complete RTCP packet (header and body) before the function call,
1.836 + * and of the complete SRTCP packet after the call, if err_status_ok
1.837 + * was returned. Otherwise, the value of the data to which it points
1.838 + * is undefined.
1.839 + *
1.840 + * @return
1.841 + * - err_status_ok if there were no problems.
1.842 + * - [other] if there was a failure in
1.843 + * the cryptographic mechanisms.
1.844 + */
1.845 +
1.846 +
1.847 +err_status_t
1.848 +srtp_protect_rtcp(srtp_t ctx, void *rtcp_hdr, int *pkt_octet_len);
1.849 +
1.850 +/**
1.851 + * @brief srtp_unprotect_rtcp() is the Secure RTCP receiver-side packet
1.852 + * processing function.
1.853 + *
1.854 + * The function call srtp_unprotect_rtcp(ctx, srtp_hdr, len_ptr)
1.855 + * verifies the Secure RTCP protection of the SRTCP packet pointed to
1.856 + * by srtcp_hdr (which has length *len_ptr), using the SRTP session
1.857 + * context ctx. If err_status_ok is returned, then srtcp_hdr points
1.858 + * to the resulting RTCP packet and *len_ptr is the number of octets
1.859 + * in that packet; otherwise, no assumptions should be made about the
1.860 + * value of either data elements.
1.861 + *
1.862 + * @warning This function assumes that the SRTCP packet is aligned on a
1.863 + * 32-bit boundary.
1.864 + *
1.865 + * @param ctx is a pointer to the srtp_t which applies to the
1.866 + * particular packet.
1.867 + *
1.868 + * @param srtcp_hdr is a pointer to the header of the SRTCP packet
1.869 + * (before the call). After the function returns, it points to the
1.870 + * rtp packet if err_status_ok was returned; otherwise, the value of
1.871 + * the data to which it points is undefined.
1.872 + *
1.873 + * @param pkt_octet_len is a pointer to the length in octets of the
1.874 + * complete SRTCP packet (header and body) before the function call,
1.875 + * and of the complete rtp packet after the call, if err_status_ok was
1.876 + * returned. Otherwise, the value of the data to which it points is
1.877 + * undefined.
1.878 + *
1.879 + * @return
1.880 + * - err_status_ok if the RTCP packet is valid.
1.881 + * - err_status_auth_fail if the SRTCP packet failed the message
1.882 + * authentication check.
1.883 + * - err_status_replay_fail if the SRTCP packet is a replay (e.g. has
1.884 + * already been processed and accepted).
1.885 + * - [other] if there has been an error in the cryptographic mechanisms.
1.886 + *
1.887 + */
1.888 +
1.889 +err_status_t
1.890 +srtp_unprotect_rtcp(srtp_t ctx, void *srtcp_hdr, int *pkt_octet_len);
1.891 +
1.892 +/**
1.893 + * @}
1.894 + */
1.895 +
1.896 +/**
1.897 + * @defgroup SRTPevents SRTP events and callbacks
1.898 + * @ingroup SRTP
1.899 + *
1.900 + * @brief libSRTP can use a user-provided callback function to
1.901 + * handle events.
1.902 + *
1.903 + *
1.904 + * libSRTP allows a user to provide a callback function to handle
1.905 + * events that need to be dealt with outside of the data plane (see
1.906 + * the enum srtp_event_t for a description of these events). Dealing
1.907 + * with these events is not a strict necessity; they are not
1.908 + * security-critical, but the application may suffer if they are not
1.909 + * handled. The function srtp_set_event_handler() is used to provide
1.910 + * the callback function.
1.911 + *
1.912 + * A default event handler that merely reports on the events as they
1.913 + * happen is included. It is also possible to set the event handler
1.914 + * function to NULL, in which case all events will just be silently
1.915 + * ignored.
1.916 + *
1.917 + * @{
1.918 + */
1.919 +
1.920 +/**
1.921 + * @brief srtp_event_t defines events that need to be handled
1.922 + *
1.923 + * The enum srtp_event_t defines events that need to be handled
1.924 + * outside the `data plane', such as SSRC collisions and
1.925 + * key expirations.
1.926 + *
1.927 + * When a key expires or the maximum number of packets has been
1.928 + * reached, an SRTP stream will enter an `expired' state in which no
1.929 + * more packets can be protected or unprotected. When this happens,
1.930 + * it is likely that you will want to either deallocate the stream
1.931 + * (using srtp_stream_dealloc()), and possibly allocate a new one.
1.932 + *
1.933 + * When an SRTP stream expires, the other streams in the same session
1.934 + * are unaffected, unless key sharing is used by that stream. In the
1.935 + * latter case, all of the streams in the session will expire.
1.936 + */
1.937 +
1.938 +typedef enum {
1.939 + event_ssrc_collision, /**<
1.940 + * An SSRC collision occured.
1.941 + */
1.942 + event_key_soft_limit, /**< An SRTP stream reached the soft key
1.943 + * usage limit and will expire soon.
1.944 + */
1.945 + event_key_hard_limit, /**< An SRTP stream reached the hard
1.946 + * key usage limit and has expired.
1.947 + */
1.948 + event_packet_index_limit /**< An SRTP stream reached the hard
1.949 + * packet limit (2^48 packets).
1.950 + */
1.951 +} srtp_event_t;
1.952 +
1.953 +/**
1.954 + * @brief srtp_event_data_t is the structure passed as a callback to
1.955 + * the event handler function
1.956 + *
1.957 + * The struct srtp_event_data_t holds the data passed to the event
1.958 + * handler function.
1.959 + */
1.960 +
1.961 +typedef struct srtp_event_data_t {
1.962 + srtp_t session; /**< The session in which the event happend. */
1.963 + srtp_stream_t stream; /**< The stream in which the event happend. */
1.964 + srtp_event_t event; /**< An enum indicating the type of event. */
1.965 +} srtp_event_data_t;
1.966 +
1.967 +/**
1.968 + * @brief srtp_event_handler_func_t is the function prototype for
1.969 + * the event handler.
1.970 + *
1.971 + * The typedef srtp_event_handler_func_t is the prototype for the
1.972 + * event handler function. It has as its only argument an
1.973 + * srtp_event_data_t which describes the event that needs to be handled.
1.974 + * There can only be a single, global handler for all events in
1.975 + * libSRTP.
1.976 + */
1.977 +
1.978 +typedef void (srtp_event_handler_func_t)(srtp_event_data_t *data);
1.979 +
1.980 +/**
1.981 + * @brief sets the event handler to the function supplied by the caller.
1.982 + *
1.983 + * The function call srtp_install_event_handler(func) sets the event
1.984 + * handler function to the value func. The value NULL is acceptable
1.985 + * as an argument; in this case, events will be ignored rather than
1.986 + * handled.
1.987 + *
1.988 + * @param func is a pointer to a fuction that takes an srtp_event_data_t
1.989 + * pointer as an argument and returns void. This function
1.990 + * will be used by libSRTP to handle events.
1.991 + */
1.992 +
1.993 +err_status_t
1.994 +srtp_install_event_handler(srtp_event_handler_func_t func);
1.995 +
1.996 +/**
1.997 + * @}
1.998 + */
1.999 +/* in host order, so outside the #if */
1.1000 +#define SRTCP_E_BIT 0x80000000
1.1001 +/* for byte-access */
1.1002 +#define SRTCP_E_BYTE_BIT 0x80
1.1003 +#define SRTCP_INDEX_MASK 0x7fffffff
1.1004 +
1.1005 +#ifdef __cplusplus
1.1006 +}
1.1007 +#endif
1.1008 +
1.1009 +#endif /* SRTP_H */
