← Back to branch summary

~ubuntu-branches/ubuntu/wily/sflphone/wily

« back to all changes in this revision

Viewing changes to daemon/libs/pjproject-2.1.0/third_party/srtp/include/srtp.h

  • Committer: Package Import Robot
  • Author(s): Jonathan Riddell
  • Date: 2015-01-07 14:51:16 UTC
  • mfrom: (4.3.5 sid)
  • Revision ID: package-import@ubuntu.com-20150107145116-yxnafinf4lrdvrmx
Tags: 1.4.1-0.1ubuntu1
* Merge with Debian, remaining changes:
 - Drop soprano, nepomuk build-dep
* Drop ubuntu patches, now upstream

Show diffs side-by-side

added added

removed removed

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