1
/* $Id: transport_srtp.h 3999 2012-03-30 07:10:13Z bennylp $ */
3
* Copyright (C) 2008-2011 Teluu Inc. (http://www.teluu.com)
4
* Copyright (C) 2003-2008 Benny Prijono <benny@prijono.org>
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.
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.
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
20
#ifndef __PJMEDIA_TRANSPORT_SRTP_H__
21
#define __PJMEDIA_TRANSPORT_SRTP_H__
24
* @file transport_srtp.h
25
* @brief Secure RTP (SRTP) transport.
28
#include <pjmedia/transport.h>
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
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.
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:
48
\image html media-transport.PNG
50
* I think the diagram above is self-explanatory.
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:
57
\image html media-srtp-transport.PNG
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.
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.
77
typedef enum pjmedia_srtp_crypto_option
79
/** When this flag is specified, encryption will be disabled. */
80
PJMEDIA_SRTP_NO_ENCRYPTION = 1,
82
/** When this flag is specified, authentication will be disabled. */
83
PJMEDIA_SRTP_NO_AUTHENTICATION = 2
85
} pjmedia_srtp_crypto_option;
89
* This structure describes an individual crypto setting.
91
typedef struct pjmedia_srtp_crypto
93
/** Optional key. If empty, a random key will be autogenerated. */
99
/** Flags, bitmask from #pjmedia_srtp_crypto_option */
102
} pjmedia_srtp_crypto;
106
* This enumeration specifies the behavior of the SRTP transport regarding
107
* media security offer and answer.
109
typedef enum pjmedia_srtp_use
112
* When this flag is specified, SRTP will be disabled, and the transport
113
* will reject RTP/SAVP offer.
115
PJMEDIA_SRTP_DISABLED,
118
* When this flag is specified, SRTP will be advertised as optional and
119
* incoming SRTP offer will be accepted.
121
PJMEDIA_SRTP_OPTIONAL,
124
* When this flag is specified, the transport will require that RTP/SAVP
125
* media shall be used.
127
PJMEDIA_SRTP_MANDATORY
133
* Settings to be given when creating SRTP transport. Application should call
134
* #pjmedia_srtp_setting_default() to initialize this structure with its
137
typedef struct pjmedia_srtp_setting
140
* Specify the usage policy. Default is PJMEDIA_SRTP_OPTIONAL.
142
pjmedia_srtp_use use;
145
* Specify whether the SRTP transport should close the member transport
146
* when it is destroyed. Default: PJ_TRUE.
148
pj_bool_t close_member_tp;
151
* Specify the number of crypto suite settings.
153
unsigned crypto_count;
156
* Specify individual crypto suite setting.
158
pjmedia_srtp_crypto crypto[8];
160
} pjmedia_srtp_setting;
164
* This structure specifies SRTP transport specific info. This will fit
165
* into \a buffer field of pjmedia_transport_specific_info.
167
typedef struct pjmedia_srtp_info
170
* Specify whether the SRTP transport is active for SRTP session.
175
* Specify the policy used by the SRTP session for receive direction.
177
pjmedia_srtp_crypto rx_policy;
180
* Specify the policy used by the SRTP session for transmit direction.
182
pjmedia_srtp_crypto tx_policy;
185
* Specify the usage policy.
187
pjmedia_srtp_use use;
190
* Specify the peer's usage policy.
192
pjmedia_srtp_use peer_use;
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.
204
* @param endpt The media endpoint instance.
206
* @return PJ_SUCCESS on success.
208
PJ_DECL(pj_status_t) pjmedia_srtp_init_lib(pjmedia_endpt *endpt);
212
* Initialize SRTP setting with its default values.
214
* @param opt SRTP setting to be initialized.
216
PJ_DECL(void) pjmedia_srtp_setting_default(pjmedia_srtp_setting *opt);
220
* Create an SRTP media transport.
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.
230
* @return PJ_SUCCESS on success.
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);
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.
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
250
* If application specifies the crypto keys, the keys for transmit and receive
251
* direction MUST be different.
253
* @param srtp The SRTP transport.
254
* @param tx Crypto suite setting for transmit direction.
255
* @param rx Crypto suite setting for receive direction.
257
* @return PJ_SUCCESS on success.
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);
267
* @param srtp The SRTP media transport.
269
* @return PJ_SUCCESS on success.
271
* @see #pjmedia_transport_srtp_start()
273
PJ_DECL(pj_status_t) pjmedia_transport_srtp_stop(pjmedia_transport *srtp);
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.
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.
292
* @return PJ_SUCCESS on success.
294
PJ_DECL(pj_status_t) pjmedia_transport_srtp_decrypt_pkt(pjmedia_transport *tp,
301
* Query member transport of SRTP.
303
* @param srtp The SRTP media transport.
305
* @return member media transport.
307
PJ_DECL(pjmedia_transport*) pjmedia_transport_srtp_get_member(
308
pjmedia_transport *srtp);
317
#endif /* __PJMEDIA_TRANSPORT_SRTP_H__ */