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 __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
55 /** SSL protocol method constants. */
56 typedef enum pjsip_ssl_method
57 {
58 PJSIP_SSL_UNSPECIFIED_METHOD = 0, /**< Default protocol method. */
59 PJSIP_SSLV2_METHOD = 20, /**< Use SSLv2 method. */
60 PJSIP_SSLV3_METHOD = 30, /**< Use SSLv3 method. */
61 PJSIP_TLSV1_METHOD = 31, /**< Use TLSv1 method. */
62 PJSIP_TLSV1_1_METHOD = 32, /**< Use TLSv1_1 method. */
63 PJSIP_TLSV1_2_METHOD = 33, /**< Use TLSv1_2 method. */
64 PJSIP_TLSV1_3_METHOD = 34, /**< Use TLSv1_3 method. */
65 PJSIP_SSLV23_METHOD = 23, /**< Use SSLv23 method. */
66 } pjsip_ssl_method;
67
68 /**
69 * The default enabled SSL proto to be used.
70 * Default is all protocol above TLSv1 (TLSv1 & TLS v1.1 & TLS v1.2).
71 */
72 #ifndef PJSIP_SSL_DEFAULT_PROTO
73 # define PJSIP_SSL_DEFAULT_PROTO (PJ_SSL_SOCK_PROTO_TLS1 | \
74 PJ_SSL_SOCK_PROTO_TLS1_1 | \
75 PJ_SSL_SOCK_PROTO_TLS1_2)
76 #endif
77
78
79 /**
80 * This structure describe the parameter passed from #on_accept_fail_cb().
81 */
82 typedef struct pjsip_tls_on_accept_fail_param {
83 /**
84 * Local address of the fail accept operation of the TLS listener.
85 */
86 const pj_sockaddr_t *local_addr;
87
88 /**
89 * Remote address of the fail accept operation of the TLS listener.
90 */
91 const pj_sockaddr_t *remote_addr;
92
93 /**
94 * Error status of the fail accept operation of the TLS listener.
95 */
96 pj_status_t status;
97
98 /**
99 * Last error code returned by native SSL backend. Note that this may be
100 * zero, if the failure is not SSL related (e.g: accept rejection).
101 */
102 pj_status_t last_native_err;
103
104 } pjsip_tls_on_accept_fail_param;
105
106
107 /**
108 * TLS transport settings.
109 */
110 typedef struct pjsip_tls_setting
111 {
112 /**
113 * Certificate of Authority (CA) list file.
114 */
115 pj_str_t ca_list_file;
116
117 /**
118 * Certificate of Authority (CA) list directory path.
119 */
120 pj_str_t ca_list_path;
121
122 /**
123 * Public endpoint certificate file, which will be used as client-
124 * side certificate for outgoing TLS connection, and server-side
125 * certificate for incoming TLS connection.
126 */
127 pj_str_t cert_file;
128
129 /**
130 * Optional private key of the endpoint certificate to be used.
131 */
132 pj_str_t privkey_file;
133
134 /**
135 * Certificate of Authority (CA) buffer. If ca_list_file, ca_list_path,
136 * cert_file or privkey_file are set, this setting will be ignored.
137 */
138 pj_ssl_cert_buffer ca_buf;
139
140 /**
141 * Public endpoint certificate buffer, which will be used as client-
142 * side certificate for outgoing TLS connection, and server-side
143 * certificate for incoming TLS connection. If ca_list_file, ca_list_path,
144 * cert_file or privkey_file are set, this setting will be ignored.
145 */
146 pj_ssl_cert_buffer cert_buf;
147
148 /**
149 * Optional private key buffer of the endpoint certificate to be used.
150 * If ca_list_file, ca_list_path, cert_file or privkey_file are set,
151 * this setting will be ignored.
152 */
153 pj_ssl_cert_buffer privkey_buf;
154
155 /**
156 * Password to open private key.
157 */
158 pj_str_t password;
159
160 /**
161 * TLS protocol method from #pjsip_ssl_method. In the future, this field
162 * might be deprecated in favor of <b>proto</b> field. For now, this field
163 * is only applicable only when <b>proto</b> field is set to zero.
164 *
165 * Default is PJSIP_SSL_UNSPECIFIED_METHOD (0), which in turn will
166 * use PJSIP_SSL_DEFAULT_METHOD, which default value is PJSIP_TLSV1_METHOD.
167 */
168 pjsip_ssl_method method;
169
170 /**
171 * TLS protocol type from #pj_ssl_sock_proto. Use this field to enable
172 * specific protocol type. Use bitwise OR operation to combine the protocol
173 * type.
174 *
175 * Default is PJSIP_SSL_DEFAULT_PROTO.
176 */
177 pj_uint32_t proto;
178
179 /**
180 * Number of ciphers contained in the specified cipher preference.
181 * If this is set to zero, then default cipher list of the backend
182 * will be used.
183 *
184 * Default: 0 (zero).
185 */
186 unsigned ciphers_num;
187
188 /**
189 * Ciphers and order preference. The #pj_ssl_cipher_get_availables()
190 * can be used to check the available ciphers supported by backend.
191 */
192 pj_ssl_cipher *ciphers;
193
194 /**
195 * Number of curves contained in the specified curve preference.
196 * If this is set to zero, then default curve list of the backend
197 * will be used.
198 *
199 * Default: 0 (zero).
200 */
201 unsigned curves_num;
202
203 /**
204 * Curves and order preference. The #pj_ssl_curve_get_availables()
205 * can be used to check the available curves supported by backend.
206 */
207 pj_ssl_curve *curves;
208
209 /**
210 * The supported signature algorithms. Set the sigalgs string
211 * using this form:
212 * "<DIGEST>+<ALGORITHM>:<DIGEST>+<ALGORITHM>"
213 * Digests are: "RSA", "DSA" or "ECDSA"
214 * Algorithms are: "MD5", "SHA1", "SHA224", "SHA256", "SHA384", "SHA512"
215 * Example: "ECDSA+SHA256:RSA+SHA256"
216 */
217 pj_str_t sigalgs;
218
219 /**
220 * Reseed random number generator.
221 * For type #PJ_SSL_ENTROPY_FILE, parameter \a entropy_path
222 * must be set to a file.
223 * For type #PJ_SSL_ENTROPY_EGD, parameter \a entropy_path
224 * must be set to a socket.
225 *
226 * Default value is PJ_SSL_ENTROPY_NONE.
227 */
228 pj_ssl_entropy_t entropy_type;
229
230 /**
231 * When using a file/socket for entropy #PJ_SSL_ENTROPY_EGD or
232 * #PJ_SSL_ENTROPY_FILE, \a entropy_path must contain the path
233 * to entropy socket/file.
234 *
235 * Default value is an empty string.
236 */
237 pj_str_t entropy_path;
238
239 /**
240 * Specifies TLS transport behavior on the server TLS certificate
241 * verification result:
242 * - If \a verify_server is disabled (set to PJ_FALSE), TLS transport
243 * will just notify the application via #pjsip_tp_state_callback with
244 * state PJSIP_TP_STATE_CONNECTED regardless TLS verification result.
245 * - If \a verify_server is enabled (set to PJ_TRUE), TLS transport
246 * will be shutdown and application will be notified with state
247 * PJSIP_TP_STATE_DISCONNECTED whenever there is any TLS verification
248 * error, otherwise PJSIP_TP_STATE_CONNECTED will be notified.
249 *
250 * In any cases, application can inspect #pjsip_tls_state_info in the
251 * callback to see the verification detail.
252 *
253 * Default value is PJ_FALSE.
254 */
255 pj_bool_t verify_server;
256
257 /**
258 * Specifies TLS transport behavior on the client TLS certificate
259 * verification result:
260 * - If \a verify_client is disabled (set to PJ_FALSE), TLS transport
261 * will just notify the application via #pjsip_tp_state_callback with
262 * state PJSIP_TP_STATE_CONNECTED regardless TLS verification result.
263 * - If \a verify_client is enabled (set to PJ_TRUE), TLS transport
264 * will be shutdown and application will be notified with state
265 * PJSIP_TP_STATE_DISCONNECTED whenever there is any TLS verification
266 * error, otherwise PJSIP_TP_STATE_CONNECTED will be notified.
267 *
268 * In any cases, application can inspect #pjsip_tls_state_info in the
269 * callback to see the verification detail.
270 *
271 * Default value is PJ_FALSE.
272 */
273 pj_bool_t verify_client;
274
275 /**
276 * When acting as server (incoming TLS connections), reject inocming
277 * connection if client doesn't supply a TLS certificate.
278 *
279 * This setting corresponds to SSL_VERIFY_FAIL_IF_NO_PEER_CERT flag.
280 * Default value is PJ_FALSE.
281 */
282 pj_bool_t require_client_cert;
283
284 /**
285 * TLS negotiation timeout to be applied for both outgoing and
286 * incoming connection. If both sec and msec member is set to zero,
287 * the SSL negotiation doesn't have a timeout.
288 */
289 pj_time_val timeout;
290
291 /**
292 * Should SO_REUSEADDR be used for the listener socket.
293 * Default value is PJSIP_TLS_TRANSPORT_REUSEADDR.
294 */
295 pj_bool_t reuse_addr;
296
297 /**
298 * QoS traffic type to be set on this transport. When application wants
299 * to apply QoS tagging to the transport, it's preferable to set this
300 * field rather than \a qos_param fields since this is more portable.
301 *
302 * Default value is PJ_QOS_TYPE_BEST_EFFORT.
303 */
304 pj_qos_type qos_type;
305
306 /**
307 * Set the low level QoS parameters to the transport. This is a lower
308 * level operation than setting the \a qos_type field and may not be
309 * supported on all platforms.
310 *
311 * By default all settings in this structure are disabled.
312 */
313 pj_qos_params qos_params;
314
315 /**
316 * Specify if the transport should ignore any errors when setting the QoS
317 * traffic type/parameters.
318 *
319 * Default: PJ_TRUE
320 */
321 pj_bool_t qos_ignore_error;
322
323 /**
324 * Specify options to be set on the transport.
325 *
326 * By default there is no options.
327 *
328 */
329 pj_sockopt_params sockopt_params;
330
331 /**
332 * Specify if the transport should ignore any errors when setting the
333 * sockopt parameters.
334 *
335 * Default: PJ_TRUE
336 *
337 */
338 pj_bool_t sockopt_ignore_error;
339
340 /**
341 * Callback to be called when a accept operation of the TLS listener fails.
342 *
343 * @param param The parameter to the callback.
344 */
345 void(*on_accept_fail_cb)(const pjsip_tls_on_accept_fail_param *param);
346
347 } pjsip_tls_setting;
348
349
350 /**
351 * This structure defines TLS transport extended info in <tt>ext_info</tt>
352 * field of #pjsip_transport_state_info for the transport state notification
353 * callback #pjsip_tp_state_callback.
354 */
355 typedef struct pjsip_tls_state_info
356 {
357 /**
358 * SSL socket info.
359 */
360 pj_ssl_sock_info *ssl_sock_info;
361
362 } pjsip_tls_state_info;
363
364
365 /**
366 * Initialize TLS setting with default values.
367 *
368 * @param tls_opt The TLS setting to be initialized.
369 */
pjsip_tls_setting_default(pjsip_tls_setting * tls_opt)370 PJ_INLINE(void) pjsip_tls_setting_default(pjsip_tls_setting *tls_opt)
371 {
372 pj_memset(tls_opt, 0, sizeof(*tls_opt));
373 tls_opt->reuse_addr = PJSIP_TLS_TRANSPORT_REUSEADDR;
374 tls_opt->qos_type = PJ_QOS_TYPE_BEST_EFFORT;
375 tls_opt->qos_ignore_error = PJ_TRUE;
376 tls_opt->sockopt_ignore_error = PJ_TRUE;
377 tls_opt->proto = PJSIP_SSL_DEFAULT_PROTO;
378 }
379
380
381 /**
382 * Copy TLS setting.
383 *
384 * @param pool The pool to duplicate strings etc.
385 * @param dst Destination structure.
386 * @param src Source structure.
387 */
pjsip_tls_setting_copy(pj_pool_t * pool,pjsip_tls_setting * dst,const pjsip_tls_setting * src)388 PJ_INLINE(void) pjsip_tls_setting_copy(pj_pool_t *pool,
389 pjsip_tls_setting *dst,
390 const pjsip_tls_setting *src)
391 {
392 pj_memcpy(dst, src, sizeof(*dst));
393 pj_strdup_with_null(pool, &dst->ca_list_file, &src->ca_list_file);
394 pj_strdup_with_null(pool, &dst->ca_list_path, &src->ca_list_path);
395 pj_strdup_with_null(pool, &dst->cert_file, &src->cert_file);
396 pj_strdup_with_null(pool, &dst->privkey_file, &src->privkey_file);
397 pj_strdup_with_null(pool, &dst->password, &src->password);
398 pj_strdup_with_null(pool, &dst->sigalgs, &src->sigalgs);
399 pj_strdup_with_null(pool, &dst->entropy_path, &src->entropy_path);
400
401 pj_strdup(pool, &dst->ca_buf, &src->ca_buf);
402 pj_strdup(pool, &dst->cert_buf, &src->cert_buf);
403 pj_strdup(pool, &dst->privkey_buf, &src->privkey_buf);
404
405 if (src->ciphers_num) {
406 unsigned i;
407 dst->ciphers = (pj_ssl_cipher*) pj_pool_calloc(pool, src->ciphers_num,
408 sizeof(pj_ssl_cipher));
409 for (i=0; i<src->ciphers_num; ++i)
410 dst->ciphers[i] = src->ciphers[i];
411 }
412
413 if (src->curves_num) {
414 unsigned i;
415 dst->curves = (pj_ssl_curve*) pj_pool_calloc(pool, src->curves_num,
416 sizeof(pj_ssl_curve));
417 for (i=0; i<src->curves_num; ++i)
418 dst->curves[i] = src->curves[i];
419 }
420 }
421
422
423 /**
424 * Wipe out certificates and keys in the TLS setting buffer.
425 *
426 * @param opt TLS setting.
427 */
428 PJ_DECL(void) pjsip_tls_setting_wipe_keys(pjsip_tls_setting *opt);
429
430
431 /**
432 * Register support for SIP TLS transport by creating TLS listener on
433 * the specified address and port. This function will create an
434 * instance of SIP TLS transport factory and register it to the
435 * transport manager.
436 *
437 * See also #pjsip_tls_transport_start2() which supports IPv6.
438 *
439 * @param endpt The SIP endpoint.
440 * @param opt Optional TLS settings.
441 * @param local Optional local address to bind, or specify the
442 * address to bind the server socket to. Both IP
443 * interface address and port fields are optional.
444 * If IP interface address is not specified, socket
445 * will be bound to PJ_INADDR_ANY. If port is not
446 * specified, socket will be bound to any port
447 * selected by the operating system.
448 * @param a_name Optional published address, which is the address to be
449 * advertised as the address of this SIP transport.
450 * If this argument is NULL, then the bound address
451 * will be used as the published address.
452 * @param async_cnt Number of simultaneous asynchronous accept()
453 * operations to be supported. It is recommended that
454 * the number here corresponds to the number of
455 * processors in the system (or the number of SIP
456 * worker threads).
457 * @param p_factory Optional pointer to receive the instance of the
458 * SIP TLS transport factory just created.
459 *
460 * @return PJ_SUCCESS when the transport has been successfully
461 * started and registered to transport manager, or
462 * the appropriate error code.
463 */
464 PJ_DECL(pj_status_t) pjsip_tls_transport_start(pjsip_endpoint *endpt,
465 const pjsip_tls_setting *opt,
466 const pj_sockaddr_in *local,
467 const pjsip_host_port *a_name,
468 unsigned async_cnt,
469 pjsip_tpfactory **p_factory);
470
471 /**
472 * Variant of #pjsip_tls_transport_start() that supports IPv6. To instantiate
473 * IPv6 listener, set the address family of the "local" argument to IPv6
474 * (the host and port part may be left unspecified if not desired, i.e. by
475 * filling them with zeroes).
476 *
477 * @param endpt The SIP endpoint.
478 * @param opt Optional TLS settings.
479 * @param local Optional local address to bind, or specify the
480 * address to bind the server socket to. Both IP
481 * interface address and port fields are optional.
482 * If IP interface address is not specified, socket
483 * will be bound to any address. If port is not
484 * specified, socket will be bound to any port
485 * selected by the operating system.
486 * @param a_name Optional published address, which is the address to be
487 * advertised as the address of this SIP transport.
488 * If this argument is NULL, then the bound address
489 * will be used as the published address.
490 * @param async_cnt Number of simultaneous asynchronous accept()
491 * operations to be supported. It is recommended that
492 * the number here corresponds to the number of
493 * processors in the system (or the number of SIP
494 * worker threads).
495 * @param p_factory Optional pointer to receive the instance of the
496 * SIP TLS transport factory just created.
497 *
498 * @return PJ_SUCCESS when the transport has been successfully
499 * started and registered to transport manager, or
500 * the appropriate error code.
501 */
502 PJ_DECL(pj_status_t) pjsip_tls_transport_start2(pjsip_endpoint *endpt,
503 const pjsip_tls_setting *opt,
504 const pj_sockaddr *local,
505 const pjsip_host_port *a_name,
506 unsigned async_cnt,
507 pjsip_tpfactory **p_factory);
508
509 /**
510 * Start the TLS listener, if the listener is not started yet. This is useful
511 * to start the listener manually, if listener was not started when
512 * PJSIP_TLS_TRANSPORT_DONT_CREATE_LISTENER is set to 0.
513 *
514 * @param factory The SIP TLS transport factory.
515 *
516 * @param local The address where the listener should be bound to.
517 * Both IP interface address and port fields are optional.
518 * If IP interface address is not specified, socket
519 * will be bound to PJ_INADDR_ANY. If port is not
520 * specified, socket will be bound to any port
521 * selected by the operating system.
522 *
523 * @param a_name The published address for the listener.
524 * If this argument is NULL, then the bound address will
525 * be used as the published address.
526 *
527 * @return PJ_SUCCESS when the listener has been successfully
528 * started.
529 */
530 PJ_DECL(pj_status_t) pjsip_tls_transport_lis_start(pjsip_tpfactory *factory,
531 const pj_sockaddr *local,
532 const pjsip_host_port *a_name);
533
534
535 /**
536 * Restart the TLS listener. This will close the listener socket and recreate
537 * the socket based on the config used when starting the transport.
538 *
539 * @param factory The SIP TLS transport factory.
540 *
541 * @param local The address where the listener should be bound to.
542 * Both IP interface address and port fields are optional.
543 * If IP interface address is not specified, socket
544 * will be bound to PJ_INADDR_ANY. If port is not
545 * specified, socket will be bound to any port
546 * selected by the operating system.
547 *
548 * @param a_name The published address for the listener.
549 * If this argument is NULL, then the bound address will
550 * be used as the published address.
551 *
552 * @return PJ_SUCCESS when the listener has been successfully
553 * restarted.
554 *
555 */
556 PJ_DECL(pj_status_t) pjsip_tls_transport_restart(pjsip_tpfactory *factory,
557 const pj_sockaddr *local,
558 const pjsip_host_port *a_name);
559
560 PJ_END_DECL
561
562 /**
563 * @}
564 */
565
566 #endif /* __PJSIP_TRANSPORT_TLS_H__ */
567