← Back to branch summary

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

« back to all changes in this revision

Viewing changes to daemon/libs/pjproject-2.1.0/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.1.0/pjsip/include/pjsip/sip_transport_tls.h
1
 
/* $Id: sip_transport_tls.h 4262 2012-09-20 06:00:23Z 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
 
     * QoS traffic type to be set on this transport. When application wants
178
 
     * to apply QoS tagging to the transport, it's preferable to set this
179
 
     * field rather than \a qos_param fields since this is more portable.
180
 
     *
181
 
     * Default value is PJ_QOS_TYPE_BEST_EFFORT.
182
 
     */
183
 
    pj_qos_type qos_type;
184
 
 
185
 
    /**
186
 
     * Set the low level QoS parameters to the transport. This is a lower
187
 
     * level operation than setting the \a qos_type field and may not be
188
 
     * supported on all platforms.
189
 
     *
190
 
     * By default all settings in this structure are disabled.
191
 
     */
192
 
    pj_qos_params qos_params;
193
 
 
194
 
    /**
195
 
     * Specify if the transport should ignore any errors when setting the QoS
196
 
     * traffic type/parameters.
197
 
     *
198
 
     * Default: PJ_TRUE
199
 
     */
200
 
    pj_bool_t qos_ignore_error;
201
 
 
202
 
} pjsip_tls_setting;
203
 
 
204
 
 
205
 
/**
206
 
 * This structure defines TLS transport extended info in <tt>ext_info</tt>
207
 
 * field of #pjsip_transport_state_info for the transport state notification
208
 
 * callback #pjsip_tp_state_callback.
209
 
 */
210
 
typedef struct pjsip_tls_state_info
211
 
{
212
 
    /**
213
 
     * SSL socket info.
214
 
     */
215
 
    pj_ssl_sock_info    *ssl_sock_info;
216
 
 
217
 
} pjsip_tls_state_info;
218
 
 
219
 
 
220
 
/**
221
 
 * Initialize TLS setting with default values.
222
 
 *
223
 
 * @param tls_opt   The TLS setting to be initialized.
224
 
 */
225
 
PJ_INLINE(void) pjsip_tls_setting_default(pjsip_tls_setting *tls_opt)
226
 
{
227
 
    pj_memset(tls_opt, 0, sizeof(*tls_opt));
228
 
    tls_opt->qos_type = PJ_QOS_TYPE_BEST_EFFORT;
229
 
    tls_opt->qos_ignore_error = PJ_TRUE;
230
 
}
231
 
 
232
 
 
233
 
/**
234
 
 * Copy TLS setting.
235
 
 *
236
 
 * @param pool      The pool to duplicate strings etc.
237
 
 * @param dst       Destination structure.
238
 
 * @param src       Source structure.
239
 
 */
240
 
PJ_INLINE(void) pjsip_tls_setting_copy(pj_pool_t *pool,
241
 
                                       pjsip_tls_setting *dst,
242
 
                                       const pjsip_tls_setting *src)
243
 
{
244
 
    pj_memcpy(dst, src, sizeof(*dst));
245
 
    pj_strdup_with_null(pool, &dst->ca_list_file, &src->ca_list_file);
246
 
    pj_strdup_with_null(pool, &dst->cert_file, &src->cert_file);
247
 
    pj_strdup_with_null(pool, &dst->privkey_file, &src->privkey_file);
248
 
    pj_strdup_with_null(pool, &dst->password, &src->password);
249
 
    if (src->ciphers_num) {
250
 
        unsigned i;
251
 
        dst->ciphers = (pj_ssl_cipher*) pj_pool_calloc(pool, src->ciphers_num,
252
 
                                                       sizeof(pj_ssl_cipher));
253
 
        for (i=0; i<src->ciphers_num; ++i)
254
 
            dst->ciphers[i] = src->ciphers[i];
255
 
    }
256
 
}
257
 
 
258
 
 
259
 
/**
260
 
 * Register support for SIP TLS transport by creating TLS listener on
261
 
 * the specified address and port. This function will create an
262
 
 * instance of SIP TLS transport factory and register it to the
263
 
 * transport manager.
264
 
 *
265
 
 * See also #pjsip_tls_transport_start2() which supports IPv6.
266
 
 *
267
 
 * @param endpt         The SIP endpoint.
268
 
 * @param opt           Optional TLS settings.
269
 
 * @param local         Optional local address to bind, or specify the
270
 
 *                      address to bind the server socket to. Both IP 
271
 
 *                      interface address and port fields are optional.
272
 
 *                      If IP interface address is not specified, socket
273
 
 *                      will be bound to PJ_INADDR_ANY. If port is not
274
 
 *                      specified, socket will be bound to any port
275
 
 *                      selected by the operating system.
276
 
 * @param a_name        Optional published address, which is the address to be
277
 
 *                      advertised as the address of this SIP transport. 
278
 
 *                      If this argument is NULL, then the bound address
279
 
 *                      will be used as the published address.
280
 
 * @param async_cnt     Number of simultaneous asynchronous accept()
281
 
 *                      operations to be supported. It is recommended that
282
 
 *                      the number here corresponds to the number of
283
 
 *                      processors in the system (or the number of SIP
284
 
 *                      worker threads).
285
 
 * @param p_factory     Optional pointer to receive the instance of the
286
 
 *                      SIP TLS transport factory just created.
287
 
 *
288
 
 * @return              PJ_SUCCESS when the transport has been successfully
289
 
 *                      started and registered to transport manager, or
290
 
 *                      the appropriate error code.
291
 
 */
292
 
PJ_DECL(pj_status_t) pjsip_tls_transport_start(pjsip_endpoint *endpt,
293
 
                                               const pjsip_tls_setting *opt,
294
 
                                               const pj_sockaddr_in *local,
295
 
                                               const pjsip_host_port *a_name,
296
 
                                               unsigned async_cnt,
297
 
                                               pjsip_tpfactory **p_factory);
298
 
 
299
 
/**
300
 
 * Variant of #pjsip_tls_transport_start() that supports IPv6. To instantiate
301
 
 * IPv6 listener, set the address family of the "local" argument to IPv6
302
 
 * (the host and port part may be left unspecified if not desired, i.e. by
303
 
 * filling them with zeroes).
304
 
 *
305
 
 * @param endpt         The SIP endpoint.
306
 
 * @param opt           Optional TLS settings.
307
 
 * @param local         Optional local address to bind, or specify the
308
 
 *                      address to bind the server socket to. Both IP
309
 
 *                      interface address and port fields are optional.
310
 
 *                      If IP interface address is not specified, socket
311
 
 *                      will be bound to any address. If port is not
312
 
 *                      specified, socket will be bound to any port
313
 
 *                      selected by the operating system.
314
 
 * @param a_name        Optional published address, which is the address to be
315
 
 *                      advertised as the address of this SIP transport.
316
 
 *                      If this argument is NULL, then the bound address
317
 
 *                      will be used as the published address.
318
 
 * @param async_cnt     Number of simultaneous asynchronous accept()
319
 
 *                      operations to be supported. It is recommended that
320
 
 *                      the number here corresponds to the number of
321
 
 *                      processors in the system (or the number of SIP
322
 
 *                      worker threads).
323
 
 * @param p_factory     Optional pointer to receive the instance of the
324
 
 *                      SIP TLS transport factory just created.
325
 
 *
326
 
 * @return              PJ_SUCCESS when the transport has been successfully
327
 
 *                      started and registered to transport manager, or
328
 
 *                      the appropriate error code.
329
 
 */
330
 
PJ_DECL(pj_status_t) pjsip_tls_transport_start2(pjsip_endpoint *endpt,
331
 
                                                const pjsip_tls_setting *opt,
332
 
                                                const pj_sockaddr *local,
333
 
                                                const pjsip_host_port *a_name,
334
 
                                                unsigned async_cnt,
335
 
                                                pjsip_tpfactory **p_factory);
336
 
 
337
 
PJ_END_DECL
338
 
 
339
 
/**
340
 
 * @}
341
 
 */
342
 
 
343
 
#endif  /* __PJSIP_TRANSPORT_TLS_H__ */