/
srtp.h
1893 lines (1699 loc) · 70.6 KB
/
srtp.h
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
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
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
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
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
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
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
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
/*
* srtp.h
*
* interface to libsrtp
*
* David A. McGrew
* Cisco Systems, Inc.
*/
/*
*
* Copyright (c) 2001-2017, Cisco Systems, Inc.
* All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
*
* Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
*
* 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.
*
* 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.
*
* 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.
*
*/
#ifndef SRTP_SRTP_H
#define SRTP_SRTP_H
#include <stdint.h>
#ifdef __cplusplus
extern "C" {
#endif
/**
* @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
*/
#define SRTP_MAX_KEY_LEN 64
/*
* SRTP_MAX_TAG_LEN is the maximum tag length supported by libSRTP
*/
#define SRTP_MAX_TAG_LEN 16
/**
* SRTP_MAX_MKI_LEN is the maximum size the MKI could be which is
* 128 bytes
*/
#define SRTP_MAX_MKI_LEN 128
/**
* SRTP_MAX_TRAILER_LEN is the maximum length of the SRTP trailer
* (authentication tag and MKI) supported by libSRTP. This value is
* the maixmum number of octets that will be added to an RTP packet by
* srtp_protect().
*
* @brief the maximum number of octets added by srtp_protect().
*/
#define SRTP_MAX_TRAILER_LEN (SRTP_MAX_TAG_LEN + SRTP_MAX_MKI_LEN)
/**
* SRTP_MAX_NUM_MASTER_KEYS is the maximum number of Master keys for
* MKI supported by libSRTP.
*
*/
#define SRTP_MAX_NUM_MASTER_KEYS 16
#define SRTP_SALT_LEN 14
/*
* SRTP_AEAD_SALT_LEN is the length of the SALT values used with
* GCM mode. GCM mode requires an IV. The SALT value is used
* as part of the IV formation logic applied to each RTP packet.
*/
#define SRTP_AEAD_SALT_LEN 12
#define SRTP_AES_128_KEY_LEN 16
#define SRTP_AES_192_KEY_LEN 24
#define SRTP_AES_256_KEY_LEN 32
#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)
#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)
/*
* an srtp_hdr_t represents the srtp header
*
* in this implementation, an srtp_hdr_t is assumed to be 32-bit aligned
*
* (note that this definition follows that of RFC 1889 Appendix A, but
* is not identical)
*/
#ifndef WORDS_BIGENDIAN
/*
* srtp_hdr_t represents an RTP or SRTP header. The bit-fields in
* this structure should be declared "unsigned int" instead of
* "unsigned char", but doing so causes the MS compiler to not
* fully pack the bit fields.
*/
typedef struct {
unsigned char cc:4; /* CSRC count */
unsigned char x:1; /* header extension flag */
unsigned char p:1; /* padding flag */
unsigned char version:2; /* protocol version */
unsigned char pt:7; /* payload type */
unsigned char m:1; /* marker bit */
uint16_t seq; /* sequence number */
uint32_t ts; /* timestamp */
uint32_t ssrc; /* synchronization source */
} srtp_hdr_t;
#else /* BIG_ENDIAN */
typedef struct {
unsigned char version:2; /* protocol version */
unsigned char p:1; /* padding flag */
unsigned char x:1; /* header extension flag */
unsigned char cc:4; /* CSRC count */
unsigned char m:1; /* marker bit */
unsigned char pt:7; /* payload type */
uint16_t seq; /* sequence number */
uint32_t ts; /* timestamp */
uint32_t ssrc; /* synchronization source */
} srtp_hdr_t;
#endif
typedef struct {
uint16_t profile_specific; /* profile-specific info */
uint16_t length; /* number of 32-bit words in extension */
} srtp_hdr_xtnd_t;
/*
* srtcp_hdr_t represents a secure rtcp header
*
* in this implementation, an srtcp header is assumed to be 32-bit
* alinged
*/
#ifndef WORDS_BIGENDIAN
typedef struct {
unsigned char rc:5; /* reception report count */
unsigned char p:1; /* padding flag */
unsigned char version:2; /* protocol version */
unsigned char pt:8; /* payload type */
uint16_t len; /* length */
uint32_t ssrc; /* synchronization source */
} srtcp_hdr_t;
typedef struct {
unsigned int index:31; /* srtcp packet index in network order! */
unsigned int e:1; /* encrypted? 1=yes */
/* optional mikey/etc go here */
/* and then the variable-length auth tag */
} srtcp_trailer_t;
#else /* BIG_ENDIAN */
typedef struct {
unsigned char version:2; /* protocol version */
unsigned char p:1; /* padding flag */
unsigned char rc:5; /* reception report count */
unsigned char pt:8; /* payload type */
uint16_t len; /* length */
uint32_t ssrc; /* synchronization source */
} srtcp_hdr_t;
typedef struct {
unsigned int version:2; /* protocol version */
unsigned int p:1; /* padding flag */
unsigned int count:5; /* varies by packet type */
unsigned int pt:8; /* payload type */
uint16_t length; /* len of uint32s of packet less header */
} rtcp_common_t;
typedef struct {
unsigned int e:1; /* encrypted? 1=yes */
unsigned int index:31; /* srtcp packet index */
/* optional mikey/etc go here */
/* and then the variable-length auth tag */
} srtcp_trailer_t;
#endif
/**
* @brief A srtp_cipher_type_id_t is an identifier for a particular cipher
* type.
*
* A srtp_cipher_type_id_t is an integer that represents a particular
* cipher type, e.g. the Advanced Encryption Standard (AES). A
* SRTP_NULL_CIPHER is avaliable; this cipher leaves the data unchanged,
* and can be selected to indicate that no encryption is to take
* place.
*
* @ingroup Ciphers
*/
typedef uint32_t srtp_cipher_type_id_t;
/**
* @brief An srtp_auth_type_id_t is an identifier for a particular authentication
* function.
*
* An srtp_auth_type_id_t is an integer that represents a particular
* authentication function type, e.g. HMAC-SHA1. A SRTP_NULL_AUTH is
* avaliable; this authentication function performs no computation,
* and can be selected to indicate that no authentication is to take
* place.
*
* @ingroup Authentication
*/
typedef uint32_t srtp_auth_type_id_t;
/**
* @brief srtp_err_status_t defines error codes.
*
* 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
* checking somewhat.
*
*/
typedef enum {
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_t;
typedef struct srtp_ctx_t_ srtp_ctx_t;
/**
* @brief srtp_sec_serv_t describes a set of security services.
*
* A srtp_sec_serv_t enumeration is used to describe the particular
* security services that will be applied by a particular crypto
* policy (or other mechanism).
*/
typedef enum {
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 */
} srtp_sec_serv_t;
/**
* @brief srtp_crypto_policy_t describes a particular crypto policy that
* can be applied to an SRTP stream.
*
* A srtp_crypto_policy_t describes a particular cryptographic policy that
* can be applied to an SRTP or SRTCP stream. An SRTP session policy
* consists of a list of these policies, one for each SRTP stream
* in the session.
*/
typedef struct srtp_crypto_policy_t {
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. */
} srtp_crypto_policy_t;
/**
* @brief srtp_ssrc_type_t describes the type of an SSRC.
*
* An srtp_ssrc_type_t enumeration is used to indicate a type of SSRC. See
* @ref srtp_policy_t for more informataion.
*/
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()) */
} srtp_ssrc_type_t;
/**
* @brief An srtp_ssrc_t represents a particular SSRC value, or a `wildcard' SSRC.
*
* An srtp_ssrc_t represents a particular SSRC value (if its type is
* ssrc_specific), or a wildcard SSRC value that will match all
* outbound SSRCs (if its type is ssrc_any_outbound) or all inbound
* SSRCs (if its type is ssrc_any_inbound).
*
*/
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 */
} srtp_ssrc_t;
/**
* @brief points to an EKT policy
*/
typedef struct srtp_ekt_policy_ctx_t *srtp_ekt_policy_t;
/**
* @brief points to EKT stream data
*/
typedef struct srtp_ekt_stream_ctx_t *srtp_ekt_stream_t;
/**
* @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 {
unsigned char *key;
unsigned char *mki_id;
unsigned int mki_size;
} srtp_master_key_t;
/**
* @brief represents the policy for an SRTP session.
*
* 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,
* or NULL if it is the last element.
*
* 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.
*
*
* @warning The final element of the list @b must have its `next' pointer
* set to NULL.
*/
typedef struct srtp_policy_t {
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. */
} 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
* an SRTP session. This datatype is intentially opaque in
* 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.
*/
typedef srtp_ctx_t *srtp_t;
/**
* @brief srtp_init() initializes the srtp library.
*
* @warning This function @b must be called before any other srtp
* functions.
*/
srtp_err_status_t srtp_init(void);
/**
* @brief srtp_shutdown() de-initializes the srtp library.
*
* @warning No srtp functions may be called after calling this function.
*/
srtp_err_status_t srtp_shutdown(void);
/**
* @brief srtp_protect() is the Secure RTP sender-side packet processing
* function.
*
* 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.
*
* 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.
*
* @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
* the buffer that holds the RTP packet.
*
* @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
* 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.
*
* @return
* - srtp_err_status_ok no problems
* - srtp_err_status_replay_fail rtp sequence number was non-increasing
* - @e other failure in cryptographic mechanisms
*/
srtp_err_status_t srtp_protect(srtp_t ctx, void *rtp_hdr, int *len_ptr);
/**
* @brief srtp_protect_mki() is the Secure RTP sender-side packet processing
* function that can utilize MKI.
*
* 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.
*
* 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.
*
* @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
* the buffer that holds the RTP packet.
*
* @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 pkt_octet_len is a pointer to the length in octets of the complete
* 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.
*
* @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
* use the session keys identified by the mki_index
*
* @param mki_index integer value specifying which set of session keys should be
* used if use_mki is set to true.
*
* @return
* - srtp_err_status_ok no problems
* - srtp_err_status_replay_fail rtp sequence number was non-increasing
* - @e other failure in cryptographic mechanisms
*/
srtp_err_status_t srtp_protect_mki(srtp_ctx_t *ctx, void *rtp_hdr,
int *pkt_octet_len, unsigned int use_mki,
unsigned int mki_index);
/**
* @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
* 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
* data elements.
*
* 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 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.
*
* @return
* - srtp_err_status_ok if the RTP packet is valid.
* - 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).
* - [other] if there has been an error in the cryptographic mechanisms.
*
*/
srtp_err_status_t srtp_unprotect(srtp_t ctx, void *srtp_hdr, int *len_ptr);
/**
* @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
* data elements.
*
* 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 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.
*
* @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
* use the session keys identified by the mki_index
*
* @return
* - srtp_err_status_ok if the RTP packet is valid.
* - 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).
* - 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.
*
*/
srtp_err_status_t srtp_unprotect_mki(srtp_t ctx, void *srtp_hdr, int *len_ptr,
unsigned int use_mki);
/**
* @brief srtp_create() allocates and initializes an SRTP session.
* The function call srtp_create(session, policy) allocates and
* initializes an SRTP session context, applying the given policy.
*
* @param session is a pointer to the SRTP session to which the policy is
* to be added.
*
* @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. 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.
*
* @return
* - srtp_err_status_ok if creation succeded.
* - srtp_err_status_alloc_fail if allocation failed.
* - srtp_err_status_init_fail if initialization failed.
*/
srtp_err_status_t srtp_create(srtp_t *session, const srtp_policy_t *policy);
/**
* @brief srtp_add_stream() allocates and initializes an SRTP stream
* within a given SRTP session.
*
* 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:
* - 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.
*/
srtp_err_status_t srtp_add_stream(srtp_t session, const srtp_policy_t *policy);
/**
* @brief srtp_remove_stream() deallocates an SRTP stream.
*
* 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.
*
* @param ssrc is the SSRC value of the stream to be removed
* in network byte order.
*
* @warning Wildcard SSRC values cannot be removed from a
* session.
*
* @return
* - srtp_err_status_ok if the stream deallocation succeded.
* - [other] otherwise.
*
*/
srtp_err_status_t srtp_remove_stream(srtp_t session, unsigned int ssrc);
/**
* @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.
*
*/
srtp_err_status_t srtp_update_stream(srtp_t session, const srtp_policy_t *policy);
/**
* @brief srtp_crypto_policy_set_rtp_default() sets a crypto policy
* structure to the SRTP default policy for RTP protection.
*
* @param p is a pointer to the policy structure to be set
*
* 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.
*
* @return void.
*
*/
void srtp_crypto_policy_set_rtp_default(srtp_crypto_policy_t *p);
/**
* @brief srtp_crypto_policy_set_rtcp_default() sets a crypto policy
* structure to the SRTP default policy for RTCP protection.
*
* @param p is a pointer to the policy structure to be set
*
* 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
* 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 srtp_crypto_policy_t datatype.
*
* @return void.
*
*/
void srtp_crypto_policy_set_rtcp_default(srtp_crypto_policy_t *p);
/**
* @brief srtp_crypto_policy_set_aes_cm_128_hmac_sha1_80() sets a crypto
* policy structure to the SRTP default policy for RTP protection.
*
* @param p is a pointer to the policy structure to be set
*
* 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
* naming convention used in RFC 4568 (SDP Security Descriptions for
* Media Streams).
*
* @return void.
*
*/
#define srtp_crypto_policy_set_aes_cm_128_hmac_sha1_80(p) srtp_crypto_policy_set_rtp_default(p)
/**
* @brief srtp_crypto_policy_set_aes_cm_128_hmac_sha1_32() sets a crypto
* policy structure to a short-authentication tag policy
*
* @param p is a pointer to the policy structure to be set
*
* 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
* AES_CM_128_HMAC_SHA1_32 as defined in RFC 4568.
* This policy uses AES-128
* 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 srtp_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_128_hmac_sha1_32(srtp_crypto_policy_t *p);
/**
* @brief srtp_crypto_policy_set_aes_cm_128_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_128_null_auth(&p) sets
* the srtp_crypto_policy_t at location p to use the SRTP default cipher
* (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).
*
* 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 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_128_null_auth(srtp_crypto_policy_t *p);
/**
* @brief srtp_crypto_policy_set_null_cipher_hmac_sha1_80() sets a crypto
* policy structure to an authentication-only policy
*
* @param p is a pointer to the policy structure to be set
*
* 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
* bit authentication tag to provide message authentication, but to
* use no encryption. This policy is NOT RECOMMENDED for SRTP unless
* there is a requirement to forego encryption.
*
* 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
* requirement to forego encryption.
*
* @return void.
*
*/
void srtp_crypto_policy_set_null_cipher_hmac_sha1_80(srtp_crypto_policy_t *p);
/**
* @brief srtp_crypto_policy_set_null_cipher_hmac_null() sets a crypto
* policy structure to use no encryption or authentication.
*
* @param p is a pointer to the policy structure to be set
*
* 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
* troubleshootingl.
*
* 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
* requirement to forego encryption and authentication.
*
* @return void.
*
*/
void srtp_crypto_policy_set_null_cipher_hmac_null(srtp_crypto_policy_t *p);
/**
* @brief srtp_crypto_policy_set_aes_cm_256_hmac_sha1_80() sets a crypto
* policy structure to a encryption and authentication policy using AES-256
* for RTP protection.
*
* @param p is a pointer to the policy structure to be set
*
* 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
* AES_CM_256_HMAC_SHA1_80 as defined in RFC 6188. This policy uses AES-256
* 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 srtp_crypto_policy_t datatype.
*
* @return void.
*
*/
void srtp_crypto_policy_set_aes_cm_256_hmac_sha1_80(srtp_crypto_policy_t *p);
/**
* @brief srtp_crypto_policy_set_aes_cm_256_hmac_sha1_32() sets a crypto
* policy structure to a short-authentication tag policy using AES-256
* encryption.
*