Add support for ICE/STUN/TURN in res_rtp_asterisk and chan_sip.
[asterisk/asterisk.git] / res / pjproject / pjmedia / include / pjmedia / transport_srtp.h
1 /* $Id$ */
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__ */