← Back to branch summary

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

« back to all changes in this revision

Viewing changes to daemon/libs/pjproject-2.2.1/pjsip/include/pjsip/sip_transport_tls.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.2.1/pjsip/include/pjsip/sip_transport_tls.h
 
1
/* $Id: sip_transport_tls.h 4506 2013-04-26 06:01:43Z 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 __PJSIP_TRANSPORT_TLS_H__
 
21
#define __PJSIP_TRANSPORT_TLS_H__
 
22
 
 
23
/**
 
24
 * @file sip_transport_tls.h
 
25
 * @brief SIP TLS Transport.
 
26
 */
 
27
 
 
28
#include <pjsip/sip_transport.h>
 
29
#include <pj/pool.h>
 
30
#include <pj/ssl_sock.h>
 
31
#include <pj/string.h>
 
32
#include <pj/sock_qos.h>
 
33
 
 
34
 
 
35
PJ_BEGIN_DECL
 
36
 
 
37
/**
 
38
 * @defgroup PJSIP_TRANSPORT_TLS TLS Transport
 
39
 * @ingroup PJSIP_TRANSPORT
 
40
 * @brief API to create and register TLS transport.
 
41
 * @{
 
42
 * The functions below are used to create TLS transport and register 
 
43
 * the transport to the framework.
 
44
 */
 
45
 
 
46
/**
 
47
 * The default SSL method to be used by PJSIP.
 
48
 * Default is PJSIP_TLSV1_METHOD
 
49
 */
 
50
#ifndef PJSIP_SSL_DEFAULT_METHOD
 
51
#   define PJSIP_SSL_DEFAULT_METHOD     PJSIP_TLSV1_METHOD
 
52
#endif
 
53
 
 
54
/** SSL protocol method constants. */
 
55
typedef enum pjsip_ssl_method
 
56
{
 
57
    PJSIP_SSL_UNSPECIFIED_METHOD= 0,    /**< Default protocol method.   */
 
58
    PJSIP_TLSV1_METHOD          = 31,   /**< Use SSLv1 method.          */
 
59
    PJSIP_SSLV2_METHOD          = 20,   /**< Use SSLv2 method.          */
 
60
    PJSIP_SSLV3_METHOD          = 30,   /**< Use SSLv3 method.          */
 
61
    PJSIP_SSLV23_METHOD         = 23    /**< Use SSLv23 method.         */
 
62
} pjsip_ssl_method;
 
63
 
 
64
 
 
65
 
 
66
 
 
67
/**
 
68
 * TLS transport settings.
 
69
 */
 
70
typedef struct pjsip_tls_setting
 
71
{
 
72
    /**
 
73
     * Certificate of Authority (CA) list file.
 
74
     */
 
75
    pj_str_t    ca_list_file;
 
76
 
 
77
    /**
 
78
     * Public endpoint certificate file, which will be used as client-
 
79
     * side  certificate for outgoing TLS connection, and server-side
 
80
     * certificate for incoming TLS connection.
 
81
     */
 
82
    pj_str_t    cert_file;
 
83
 
 
84
    /**
 
85
     * Optional private key of the endpoint certificate to be used.
 
86
     */
 
87
    pj_str_t    privkey_file;
 
88
 
 
89
    /**
 
90
     * Password to open private key.
 
91
     */
 
92
    pj_str_t    password;
 
93
 
 
94
    /**
 
95
     * TLS protocol method from #pjsip_ssl_method, which can be:
 
96
     *  - PJSIP_SSL_UNSPECIFIED_METHOD(0): default (which will use 
 
97
     *                                     PJSIP_SSL_DEFAULT_METHOD)
 
98
     *  - PJSIP_TLSV1_METHOD(1):           TLSv1
 
99
     *  - PJSIP_SSLV2_METHOD(2):           SSLv2
 
100
     *  - PJSIP_SSLV3_METHOD(3):           SSL3
 
101
     *  - PJSIP_SSLV23_METHOD(23):         SSL23
 
102
     *
 
103
     * Default is PJSIP_SSL_UNSPECIFIED_METHOD (0), which in turn will
 
104
     * use PJSIP_SSL_DEFAULT_METHOD, which default value is 
 
105
     * PJSIP_TLSV1_METHOD.
 
106
     */
 
107
    int         method;
 
108
 
 
109
    /**
 
110
     * Number of ciphers contained in the specified cipher preference. 
 
111
     * If this is set to zero, then default cipher list of the backend 
 
112
     * will be used.
 
113
     *
 
114
     * Default: 0 (zero).
 
115
     */
 
116
    unsigned ciphers_num;
 
117
 
 
118
    /**
 
119
     * Ciphers and order preference. The #pj_ssl_cipher_get_availables()
 
120
     * can be used to check the available ciphers supported by backend.
 
121
     */
 
122
    pj_ssl_cipher *ciphers;
 
123
 
 
124
    /**
 
125
     * Specifies TLS transport behavior on the server TLS certificate 
 
126
     * verification result:
 
127
     * - If \a verify_server is disabled (set to PJ_FALSE), TLS transport 
 
128
     *   will just notify the application via #pjsip_tp_state_callback with
 
129
     *   state PJSIP_TP_STATE_CONNECTED regardless TLS verification result.
 
130
     * - If \a verify_server is enabled (set to PJ_TRUE), TLS transport 
 
131
     *   will be shutdown and application will be notified with state
 
132
     *   PJSIP_TP_STATE_DISCONNECTED whenever there is any TLS verification
 
133
     *   error, otherwise PJSIP_TP_STATE_CONNECTED will be notified.
 
134
     *
 
135
     * In any cases, application can inspect #pjsip_tls_state_info in the
 
136
     * callback to see the verification detail.
 
137
     *
 
138
     * Default value is PJ_FALSE.
 
139
     */
 
140
    pj_bool_t   verify_server;
 
141
 
 
142
    /**
 
143
     * Specifies TLS transport behavior on the client TLS certificate 
 
144
     * verification result:
 
145
     * - If \a verify_client is disabled (set to PJ_FALSE), TLS transport 
 
146
     *   will just notify the application via #pjsip_tp_state_callback with
 
147
     *   state PJSIP_TP_STATE_CONNECTED regardless TLS verification result.
 
148
     * - If \a verify_client is enabled (set to PJ_TRUE), TLS transport 
 
149
     *   will be shutdown and application will be notified with state
 
150
     *   PJSIP_TP_STATE_DISCONNECTED whenever there is any TLS verification
 
151
     *   error, otherwise PJSIP_TP_STATE_CONNECTED will be notified.
 
152
     *
 
153
     * In any cases, application can inspect #pjsip_tls_state_info in the
 
154
     * callback to see the verification detail.
 
155
     *
 
156
     * Default value is PJ_FALSE.
 
157
     */
 
158
    pj_bool_t   verify_client;
 
159
 
 
160
    /**
 
161
     * When acting as server (incoming TLS connections), reject inocming
 
162
     * connection if client doesn't supply a TLS certificate.
 
163
     *
 
164
     * This setting corresponds to SSL_VERIFY_FAIL_IF_NO_PEER_CERT flag.
 
165
     * Default value is PJ_FALSE.
 
166
     */
 
167
    pj_bool_t   require_client_cert;
 
168
 
 
169
    /**
 
170
     * TLS negotiation timeout to be applied for both outgoing and
 
171
     * incoming connection. If both sec and msec member is set to zero,
 
172
     * the SSL negotiation doesn't have a timeout.
 
173
     */
 
174
    pj_time_val timeout;
 
175
 
 
176
    /**
 
177
     * Should SO_REUSEADDR be used for the listener socket.
 
178
     * Default value is PJSIP_TLS_TRANSPORT_REUSEADDR.
 
179
     */
 
180
    pj_bool_t reuse_addr;
 
181
 
 
182
    /**
 
183
     * QoS traffic type to be set on this transport. When application wants
 
184
     * to apply QoS tagging to the transport, it's preferable to set this
 
185
     * field rather than \a qos_param fields since this is more portable.
 
186
     *
 
187
     * Default value is PJ_QOS_TYPE_BEST_EFFORT.
 
188
     */
 
189
    pj_qos_type qos_type;
 
190
 
 
191
    /**
 
192
     * Set the low level QoS parameters to the transport. This is a lower
 
193
     * level operation than setting the \a qos_type field and may not be
 
194
     * supported on all platforms.
 
195
     *
 
196
     * By default all settings in this structure are disabled.
 
197
     */
 
198
    pj_qos_params qos_params;
 
199
 
 
200
    /**
 
201
     * Specify if the transport should ignore any errors when setting the QoS
 
202
     * traffic type/parameters.
 
203
     *
 
204
     * Default: PJ_TRUE
 
205
     */
 
206
    pj_bool_t qos_ignore_error;
 
207
 
 
208
} pjsip_tls_setting;
 
209
 
 
210
 
 
211
/**
 
212
 * This structure defines TLS transport extended info in <tt>ext_info</tt>
 
213
 * field of #pjsip_transport_state_info for the transport state notification
 
214
 * callback #pjsip_tp_state_callback.
 
215
 */
 
216
typedef struct pjsip_tls_state_info
 
217
{
 
218
    /**
 
219
     * SSL socket info.
 
220
     */
 
221
    pj_ssl_sock_info    *ssl_sock_info;
 
222
 
 
223
} pjsip_tls_state_info;
 
224
 
 
225
 
 
226
/**
 
227
 * Initialize TLS setting with default values.
 
228
 *
 
229
 * @param tls_opt   The TLS setting to be initialized.
 
230
 */
 
231
PJ_INLINE(void) pjsip_tls_setting_default(pjsip_tls_setting *tls_opt)
 
232
{
 
233
    pj_memset(tls_opt, 0, sizeof(*tls_opt));
 
234
    tls_opt->reuse_addr = PJSIP_TLS_TRANSPORT_REUSEADDR;
 
235
    tls_opt->qos_type = PJ_QOS_TYPE_BEST_EFFORT;
 
236
    tls_opt->qos_ignore_error = PJ_TRUE;
 
237
}
 
238
 
 
239
 
 
240
/**
 
241
 * Copy TLS setting.
 
242
 *
 
243
 * @param pool      The pool to duplicate strings etc.
 
244
 * @param dst       Destination structure.
 
245
 * @param src       Source structure.
 
246
 */
 
247
PJ_INLINE(void) pjsip_tls_setting_copy(pj_pool_t *pool,
 
248
                                       pjsip_tls_setting *dst,
 
249
                                       const pjsip_tls_setting *src)
 
250
{
 
251
    pj_memcpy(dst, src, sizeof(*dst));
 
252
    pj_strdup_with_null(pool, &dst->ca_list_file, &src->ca_list_file);
 
253
    pj_strdup_with_null(pool, &dst->cert_file, &src->cert_file);
 
254
    pj_strdup_with_null(pool, &dst->privkey_file, &src->privkey_file);
 
255
    pj_strdup_with_null(pool, &dst->password, &src->password);
 
256
    if (src->ciphers_num) {
 
257
        unsigned i;
 
258
        dst->ciphers = (pj_ssl_cipher*) pj_pool_calloc(pool, src->ciphers_num,
 
259
                                                       sizeof(pj_ssl_cipher));
 
260
        for (i=0; i<src->ciphers_num; ++i)
 
261
            dst->ciphers[i] = src->ciphers[i];
 
262
    }
 
263
}
 
264
 
 
265
 
 
266
/**
 
267
 * Register support for SIP TLS transport by creating TLS listener on
 
268
 * the specified address and port. This function will create an
 
269
 * instance of SIP TLS transport factory and register it to the
 
270
 * transport manager.
 
271
 *
 
272
 * See also #pjsip_tls_transport_start2() which supports IPv6.
 
273
 *
 
274
 * @param endpt         The SIP endpoint.
 
275
 * @param opt           Optional TLS settings.
 
276
 * @param local         Optional local address to bind, or specify the
 
277
 *                      address to bind the server socket to. Both IP 
 
278
 *                      interface address and port fields are optional.
 
279
 *                      If IP interface address is not specified, socket
 
280
 *                      will be bound to PJ_INADDR_ANY. If port is not
 
281
 *                      specified, socket will be bound to any port
 
282
 *                      selected by the operating system.
 
283
 * @param a_name        Optional published address, which is the address to be
 
284
 *                      advertised as the address of this SIP transport. 
 
285
 *                      If this argument is NULL, then the bound address
 
286
 *                      will be used as the published address.
 
287
 * @param async_cnt     Number of simultaneous asynchronous accept()
 
288
 *                      operations to be supported. It is recommended that
 
289
 *                      the number here corresponds to the number of
 
290
 *                      processors in the system (or the number of SIP
 
291
 *                      worker threads).
 
292
 * @param p_factory     Optional pointer to receive the instance of the
 
293
 *                      SIP TLS transport factory just created.
 
294
 *
 
295
 * @return              PJ_SUCCESS when the transport has been successfully
 
296
 *                      started and registered to transport manager, or
 
297
 *                      the appropriate error code.
 
298
 */
 
299
PJ_DECL(pj_status_t) pjsip_tls_transport_start(pjsip_endpoint *endpt,
 
300
                                               const pjsip_tls_setting *opt,
 
301
                                               const pj_sockaddr_in *local,
 
302
                                               const pjsip_host_port *a_name,
 
303
                                               unsigned async_cnt,
 
304
                                               pjsip_tpfactory **p_factory);
 
305
 
 
306
/**
 
307
 * Variant of #pjsip_tls_transport_start() that supports IPv6. To instantiate
 
308
 * IPv6 listener, set the address family of the "local" argument to IPv6
 
309
 * (the host and port part may be left unspecified if not desired, i.e. by
 
310
 * filling them with zeroes).
 
311
 *
 
312
 * @param endpt         The SIP endpoint.
 
313
 * @param opt           Optional TLS settings.
 
314
 * @param local         Optional local address to bind, or specify the
 
315
 *                      address to bind the server socket to. Both IP
 
316
 *                      interface address and port fields are optional.
 
317
 *                      If IP interface address is not specified, socket
 
318
 *                      will be bound to any address. If port is not
 
319
 *                      specified, socket will be bound to any port
 
320
 *                      selected by the operating system.
 
321
 * @param a_name        Optional published address, which is the address to be
 
322
 *                      advertised as the address of this SIP transport.
 
323
 *                      If this argument is NULL, then the bound address
 
324
 *                      will be used as the published address.
 
325
 * @param async_cnt     Number of simultaneous asynchronous accept()
 
326
 *                      operations to be supported. It is recommended that
 
327
 *                      the number here corresponds to the number of
 
328
 *                      processors in the system (or the number of SIP
 
329
 *                      worker threads).
 
330
 * @param p_factory     Optional pointer to receive the instance of the
 
331
 *                      SIP TLS transport factory just created.
 
332
 *
 
333
 * @return              PJ_SUCCESS when the transport has been successfully
 
334
 *                      started and registered to transport manager, or
 
335
 *                      the appropriate error code.
 
336
 */
 
337
PJ_DECL(pj_status_t) pjsip_tls_transport_start2(pjsip_endpoint *endpt,
 
338
                                                const pjsip_tls_setting *opt,
 
339
                                                const pj_sockaddr *local,
 
340
                                                const pjsip_host_port *a_name,
 
341
                                                unsigned async_cnt,
 
342
                                                pjsip_tpfactory **p_factory);
 
343
 
 
344
PJ_END_DECL
 
345
 
 
346
/**
 
347
 * @}
 
348
 */
 
349
 
 
350
#endif  /* __PJSIP_TRANSPORT_TLS_H__ */