← Back to branch summary

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

« back to all changes in this revision

Viewing changes to daemon/libs/pjproject-2.0.1/pjmedia/include/pjmedia/transport_srtp.h

  • Committer: Package Import Robot
  • Author(s): Mark Purcell
  • Date: 2014-01-28 18:23:36 UTC
  • mfrom: (1.1.11)
  • mto: This revision was merged to the branch mainline in revision 24.
  • Revision ID: package-import@ubuntu.com-20140128182336-3xenud1kbnwmf3mz
http://bugs.debian.org/735846
http://bugs.debian.org/727164
http://bugs.debian.org/718178
http://bugs.debian.org/736583
http://bugs.debian.org/722040
http://bugs.debian.org/736746
* New upstream release 
  - Fixes "New Upstream Release" (Closes: #735846)
  - Fixes "Ringtone does not stop" (Closes: #727164)
  - Fixes "[sflphone-kde] crash on startup" (Closes: #718178)
  - Fixes "sflphone GUI crashes when call is hung up" (Closes: #736583)
* Build-Depends: ensure GnuTLS 2.6
  - libucommon-dev (>= 6.0.7-1.1), libccrtp-dev (>= 2.0.6-3)
  - Fixes "FTBFS Build-Depends libgnutls{26,28}-dev" (Closes: #722040)
* Fix "boost 1.49 is going away" unversioned Build-Depends: (Closes: #736746)
* Add Build-Depends: libsndfile-dev, nepomuk-core-dev

Show diffs side-by-side

added added

removed removed

Lines of Context:
daemon/libs/pjproject-2.0.1/pjmedia/include/pjmedia/transport_srtp.h
1
 
/* $Id: transport_srtp.h 3999 2012-03-30 07:10:13Z bennylp $ */
2
 
/*
3
 
 * Copyright (C) 2008-2011 Teluu Inc. (http://www.teluu.com)
4
 
 * Copyright (C) 2003-2008 Benny Prijono <benny@prijono.org>
5
 
 *
6
 
 * This program is free software; you can redistribute it and/or modify
7
 
 * it under the terms of the GNU General Public License as published by
8
 
 * the Free Software Foundation; either version 2 of the License, or
9
 
 * (at your option) any later version.
10
 
 *
11
 
 * This program is distributed in the hope that it will be useful,
12
 
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13
 
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
14
 
 * GNU General Public License for more details.
15
 
 *
16
 
 * You should have received a copy of the GNU General Public License
17
 
 * along with this program; if not, write to the Free Software
18
 
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307 USA
19
 
 */
20
 
#ifndef __PJMEDIA_TRANSPORT_SRTP_H__
21
 
#define __PJMEDIA_TRANSPORT_SRTP_H__
22
 
 
23
 
/**
24
 
 * @file transport_srtp.h
25
 
 * @brief Secure RTP (SRTP) transport.
26
 
 */
27
 
 
28
 
#include <pjmedia/transport.h>
29
 
 
30
 
 
31
 
/**
32
 
 * @defgroup PJMEDIA_TRANSPORT_SRTP Secure RTP (SRTP) Media Transport
33
 
 * @ingroup PJMEDIA_TRANSPORT
34
 
 * @brief Media transport adapter to add SRTP feature to existing transports
35
 
 * @{
36
 
 *
37
 
 * This module implements SRTP as described by RFC 3711, using RFC 4568 as
38
 
 * key exchange method. It implements \ref PJMEDIA_TRANSPORT to integrate
39
 
 * with the rest of PJMEDIA framework.
40
 
 *
41
 
 * As we know, media transport is separated from the stream object (which
42
 
 * does the encoding/decoding of PCM frames, (de)packetization of RTP/RTCP
43
 
 * packets, and de-jitter buffering). The connection between stream and media
44
 
 * transport is established when the stream is created (we need to specify
45
 
 * media transport during stream creation), and the interconnection can be
46
 
 * depicted from the diagram below:
47
 
 *
48
 
   \image html media-transport.PNG
49
 
 
50
 
 * I think the diagram above is self-explanatory.
51
 
 *
52
 
 * SRTP functionality is implemented as some kind of "adapter", which is
53
 
 * plugged between the stream and the actual media transport that does
54
 
 * sending/receiving RTP/RTCP packets. When SRTP is used, the interconnection
55
 
 * between stream and transport is like the diagram below:
56
 
 *
57
 
    \image html media-srtp-transport.PNG
58
 
 
59
 
 * So to stream, the SRTP transport behaves as if it is a media transport
60
 
 * (because it is a media transport), and to the media transport it behaves
61
 
 * as if it is a stream. The SRTP object then forwards RTP packets back and
62
 
 * forth between stream and the actual transport, encrypting/decrypting
63
 
 * the RTP/RTCP packets as necessary.
64
 
 *
65
 
 * The neat thing about this design is the SRTP "adapter" then can be used
66
 
 * to encrypt any kind of media transports. We currently have UDP and ICE
67
 
 * media transports that can benefit SRTP, and we could add SRTP to any
68
 
 * media transports that will be added in the future.
69
 
 */
70
 
 
71
 
PJ_BEGIN_DECL
72
 
 
73
 
 
74
 
/**
75
 
 * Crypto option.
76
 
 */
77
 
typedef enum pjmedia_srtp_crypto_option
78
 
{
79
 
    /** When this flag is specified, encryption will be disabled. */
80
 
    PJMEDIA_SRTP_NO_ENCRYPTION  = 1,
81
 
 
82
 
    /** When this flag is specified, authentication will be disabled. */
83
 
    PJMEDIA_SRTP_NO_AUTHENTICATION  = 2
84
 
 
85
 
} pjmedia_srtp_crypto_option;
86
 
 
87
 
 
88
 
/**
89
 
 * This structure describes an individual crypto setting.
90
 
 */
91
 
typedef struct pjmedia_srtp_crypto
92
 
{
93
 
    /** Optional key. If empty, a random key will be autogenerated. */
94
 
    pj_str_t    key;
95
 
 
96
 
    /** Crypto name.   */
97
 
    pj_str_t    name;
98
 
 
99
 
    /** Flags, bitmask from #pjmedia_srtp_crypto_option */
100
 
    unsigned    flags;
101
 
 
102
 
} pjmedia_srtp_crypto;
103
 
 
104
 
 
105
 
/**
106
 
 * This enumeration specifies the behavior of the SRTP transport regarding
107
 
 * media security offer and answer.
108
 
 */
109
 
typedef enum pjmedia_srtp_use
110
 
{
111
 
    /**
112
 
     * When this flag is specified, SRTP will be disabled, and the transport
113
 
     * will reject RTP/SAVP offer.
114
 
     */
115
 
    PJMEDIA_SRTP_DISABLED,
116
 
 
117
 
    /**
118
 
     * When this flag is specified, SRTP will be advertised as optional and
119
 
     * incoming SRTP offer will be accepted.
120
 
     */
121
 
    PJMEDIA_SRTP_OPTIONAL,
122
 
 
123
 
    /**
124
 
     * When this flag is specified, the transport will require that RTP/SAVP
125
 
     * media shall be used.
126
 
     */
127
 
    PJMEDIA_SRTP_MANDATORY
128
 
 
129
 
} pjmedia_srtp_use;
130
 
 
131
 
 
132
 
/**
133
 
 * Settings to be given when creating SRTP transport. Application should call
134
 
 * #pjmedia_srtp_setting_default() to initialize this structure with its
135
 
 * default values.
136
 
 */
137
 
typedef struct pjmedia_srtp_setting
138
 
{
139
 
    /**
140
 
     * Specify the usage policy. Default is PJMEDIA_SRTP_OPTIONAL.
141
 
     */
142
 
    pjmedia_srtp_use            use;
143
 
 
144
 
    /**
145
 
     * Specify whether the SRTP transport should close the member transport
146
 
     * when it is destroyed. Default: PJ_TRUE.
147
 
     */
148
 
    pj_bool_t                   close_member_tp;
149
 
 
150
 
    /**
151
 
     * Specify the number of crypto suite settings.
152
 
     */
153
 
    unsigned                    crypto_count;
154
 
 
155
 
    /**
156
 
     * Specify individual crypto suite setting.
157
 
     */
158
 
    pjmedia_srtp_crypto         crypto[8];
159
 
 
160
 
} pjmedia_srtp_setting;
161
 
 
162
 
 
163
 
/**
164
 
 * This structure specifies SRTP transport specific info. This will fit
165
 
 * into \a buffer field of pjmedia_transport_specific_info.
166
 
 */
167
 
typedef struct pjmedia_srtp_info
168
 
{
169
 
    /**
170
 
     * Specify whether the SRTP transport is active for SRTP session.
171
 
     */
172
 
    pj_bool_t                   active;
173
 
 
174
 
    /**
175
 
     * Specify the policy used by the SRTP session for receive direction.
176
 
     */
177
 
    pjmedia_srtp_crypto         rx_policy;
178
 
 
179
 
    /**
180
 
     * Specify the policy used by the SRTP session for transmit direction.
181
 
     */
182
 
    pjmedia_srtp_crypto         tx_policy;
183
 
 
184
 
    /**
185
 
     * Specify the usage policy.
186
 
     */
187
 
    pjmedia_srtp_use            use;
188
 
 
189
 
    /**
190
 
     * Specify the peer's usage policy.
191
 
     */
192
 
    pjmedia_srtp_use            peer_use;
193
 
 
194
 
} pjmedia_srtp_info;
195
 
 
196
 
 
197
 
/**
198
 
 * Initialize SRTP library. This function should be called before
199
 
 * any SRTP functions, however calling #pjmedia_transport_srtp_create()
200
 
 * will also invoke this function. This function will also register SRTP
201
 
 * library deinitialization to #pj_atexit(), so the deinitialization
202
 
 * of SRTP library will be performed automatically by PJLIB destructor.
203
 
 *
204
 
 * @param endpt     The media endpoint instance.
205
 
 *
206
 
 * @return          PJ_SUCCESS on success.
207
 
 */
208
 
PJ_DECL(pj_status_t) pjmedia_srtp_init_lib(pjmedia_endpt *endpt);
209
 
 
210
 
 
211
 
/**
212
 
 * Initialize SRTP setting with its default values.
213
 
 *
214
 
 * @param opt   SRTP setting to be initialized.
215
 
 */
216
 
PJ_DECL(void) pjmedia_srtp_setting_default(pjmedia_srtp_setting *opt);
217
 
 
218
 
 
219
 
/**
220
 
 * Create an SRTP media transport.
221
 
 *
222
 
 * @param endpt     The media endpoint instance.
223
 
 * @param tp        The actual media transport to send and receive
224
 
 *                  RTP/RTCP packets. This media transport will be
225
 
 *                  kept as member transport of this SRTP instance.
226
 
 * @param opt       Optional settings. If NULL is given, default
227
 
 *                  settings will be used.
228
 
 * @param p_tp      Pointer to receive the transport SRTP instance.
229
 
 *
230
 
 * @return          PJ_SUCCESS on success.
231
 
 */
232
 
PJ_DECL(pj_status_t) pjmedia_transport_srtp_create(
233
 
                                       pjmedia_endpt *endpt,
234
 
                                       pjmedia_transport *tp,
235
 
                                       const pjmedia_srtp_setting *opt,
236
 
                                       pjmedia_transport **p_tp);
237
 
 
238
 
 
239
 
/**
240
 
 * Manually start SRTP session with the given parameters. Application only
241
 
 * needs to call this function when the SRTP transport is used without SDP
242
 
 * offer/answer. When SDP offer/answer framework is used, the SRTP transport
243
 
 * will be started/stopped by #pjmedia_transport_media_start() and
244
 
 * #pjmedia_transport_media_stop() respectively.
245
 
 *
246
 
 * Please note that even if an RTP stream is only one direction, application
247
 
 * will still need to provide both crypto suites, because it is needed by
248
 
 * RTCP.
249
 
 
250
 
 * If application specifies the crypto keys, the keys for transmit and receive
251
 
 * direction MUST be different.
252
 
 *
253
 
 * @param srtp      The SRTP transport.
254
 
 * @param tx        Crypto suite setting for transmit direction.
255
 
 * @param rx        Crypto suite setting for receive direction.
256
 
 *
257
 
 * @return          PJ_SUCCESS on success.
258
 
 */
259
 
PJ_DECL(pj_status_t) pjmedia_transport_srtp_start(
260
 
                                            pjmedia_transport *srtp,
261
 
                                            const pjmedia_srtp_crypto *tx,
262
 
                                            const pjmedia_srtp_crypto *rx);
263
 
 
264
 
/**
265
 
 * Stop SRTP session.
266
 
 *
267
 
 * @param srtp      The SRTP media transport.
268
 
 *
269
 
 * @return          PJ_SUCCESS on success.
270
 
 *
271
 
 * @see #pjmedia_transport_srtp_start()
272
 
 */
273
 
PJ_DECL(pj_status_t) pjmedia_transport_srtp_stop(pjmedia_transport *srtp);
274
 
 
275
 
 
276
 
/**
277
 
 * This is a utility function to decrypt SRTP packet using SRTP transport.
278
 
 * This function is not part of SRTP transport's API, but it can be used
279
 
 * to decrypt SRTP packets from non-network (for example, from a saved file)
280
 
 * without having to use the transport framework. See pcaputil.c in the
281
 
 * samples collection on how to use this function.
282
 
 *
283
 
 * @param tp            The SRTP transport.
284
 
 * @param is_rtp        Set to non-zero if the packet is SRTP, otherwise set
285
 
 *                      to zero if the packet is SRTCP.
286
 
 * @param pkt           On input, it contains SRTP or SRTCP packet. On
287
 
 *                      output, it contains the decrypted RTP/RTCP packet.
288
 
 * @param pkt_len       On input, specify the length of the buffer. On
289
 
 *                      output, it will be filled with the actual length
290
 
 *                      of decrypted packet.
291
 
 *
292
 
 * @return              PJ_SUCCESS on success.
293
 
 */
294
 
PJ_DECL(pj_status_t) pjmedia_transport_srtp_decrypt_pkt(pjmedia_transport *tp,
295
 
                                                        pj_bool_t is_rtp,
296
 
                                                        void *pkt,
297
 
                                                        int *pkt_len);
298
 
 
299
 
 
300
 
/**
301
 
 * Query member transport of SRTP.
302
 
 *
303
 
 * @param srtp              The SRTP media transport.
304
 
 *
305
 
 * @return                  member media transport.
306
 
 */
307
 
PJ_DECL(pjmedia_transport*) pjmedia_transport_srtp_get_member(
308
 
                                                    pjmedia_transport *srtp);
309
 
 
310
 
 
311
 
PJ_END_DECL
312
 
 
313
 
/**
314
 
 * @}
315
 
 */
316
 
 
317
 
#endif /* __PJMEDIA_TRANSPORT_SRTP_H__ */