2 * Asterisk -- An open source telephony toolkit.
4 * Copyright (C) 1999 - 2006, Digium, Inc.
6 * Mark Spencer <markster@digium.com>
8 * See http://www.asterisk.org for more information about
9 * the Asterisk project. Please do not directly contact
10 * any of the maintainers of this project for assistance;
11 * the project provides a web site, mailing lists and IRC
12 * channels for your use.
14 * This program is free software, distributed under the terms of
15 * the GNU General Public License Version 2. See the LICENSE file
16 * at the top of the source tree.
22 * \brief Generic support for tcp/tls servers in Asterisk.
23 * \note In order to have TLS/SSL support, we need the openssl libraries.
24 * Still we can decide whether or not to use them by commenting
25 * in or out the DO_SSL macro.
27 * TLS/SSL support is basically implemented by reading from a config file
28 * (currently http.conf and sip.conf) the names of the certificate and cipher to use,
29 * and then run ssl_setup() to create an appropriate SSL_CTX (ssl_ctx)
30 * If we support multiple domains, presumably we need to read multiple
33 * When we are requested to open a TLS socket, we run make_file_from_fd()
34 * on the socket, to do the necessary setup. At the moment the context's name
35 * is hardwired in the function, but we can certainly make it into an extra
36 * parameter to the function.
38 * We declare most of ssl support variables unconditionally,
39 * because their number is small and this simplifies the code.
41 * \note The ssl-support variables (ssl_ctx, do_ssl, certfile, cipher)
42 * and their setup should be moved to a more central place, e.g. asterisk.conf
43 * and the source files that processes it. Similarly, ssl_setup() should
44 * be run earlier in the startup process so modules have it available.
48 #ifndef _ASTERISK_TCPTLS_H
49 #define _ASTERISK_TCPTLS_H
51 #include "asterisk/utils.h"
53 #if defined(HAVE_OPENSSL) && (defined(HAVE_FUNOPEN) || defined(HAVE_FOPENCOOKIE))
54 #define DO_SSL /* comment in/out if you want to support ssl */
58 #include <openssl/ssl.h>
59 #include <openssl/err.h>
61 /* declare dummy types so we can define a pointer to them */
62 typedef struct {} SSL;
63 typedef struct {} SSL_CTX;
67 #define AST_CERTFILE "asterisk.pem"
70 /*! Verify certificate when acting as server */
71 AST_SSL_VERIFY_CLIENT = (1 << 0),
72 /*! Don't verify certificate when connecting to a server */
73 AST_SSL_DONT_VERIFY_SERVER = (1 << 1),
74 /*! Don't compare "Common Name" against IP or hostname */
75 AST_SSL_IGNORE_COMMON_NAME = (1 << 2)
78 struct ast_tls_config {
85 struct ast_flags flags;
90 * The following code implements a generic mechanism for starting
91 * services on a TCP or TLS socket.
92 * The service is configured in the struct session_args, and
93 * then started by calling server_start(desc) on the descriptor.
94 * server_start() first verifies if an instance of the service is active,
95 * and in case shuts it down. Then, if the service must be started, creates
96 * a socket and a thread in charge of doing the accept().
98 * The body of the thread is desc->accept_fn(desc), which the user can define
99 * freely. We supply a sample implementation, server_root(), structured as an
100 * infinite loop. At the beginning of each iteration it runs periodic_fn()
101 * if defined (e.g. to perform some cleanup etc.) then issues a poll()
102 * or equivalent with a timeout of 'poll_timeout' milliseconds, and if the
103 * following accept() is successful it creates a thread in charge of
104 * running the session, whose body is desc->worker_fn(). The argument of
105 * worker_fn() is a struct ast_tcptls_session_instance, which contains the address
106 * of the other party, a pointer to desc, the file descriptors (fd) on which
107 * we can do a select/poll (but NOT I/O), and a FILE *on which we can do I/O.
108 * We have both because we want to support plain and SSL sockets, and
109 * going through a FILE * lets us provide the encryption/decryption
110 * on the stream without using an auxiliary thread.
114 * arguments for the accepting thread
116 struct ast_tcptls_session_args {
117 struct sockaddr_in local_address;
118 struct sockaddr_in old_address; /*!< copy of the local or remote address depending on if its a client or server session */
119 struct sockaddr_in remote_address;
120 char hostname[MAXHOSTNAMELEN]; /*!< only necessary for SSL clients so we can compare to common name */
121 struct ast_tls_config *tls_cfg; /*!< points to the SSL configuration if any */
125 void *(*accept_fn)(void *); /*!< the function in charge of doing the accept */
126 void (*periodic_fn)(void *);/*!< something we may want to run before after select on the accept socket */
127 void *(*worker_fn)(void *); /*!< the function in charge of doing the actual work */
132 * describes a server instance
134 struct ast_tcptls_session_instance {
135 FILE *f; /* fopen/funopen result */
136 int fd; /* the socket returned by accept() */
137 SSL *ssl; /* ssl state */
138 /* iint (*ssl_setup)(SSL *); */
140 struct sockaddr_in remote_address;
141 struct ast_tcptls_session_args *parent;
145 #if defined(HAVE_FUNOPEN)
149 #define HOOK_T ssize_t
154 * \brief A generic client routine for a TCP client
155 * and starts a thread for handling accept()
156 * \version 1.6.1 changed desc parameter to be of ast_tcptls_session_args type
158 struct ast_tcptls_session_instance *ast_tcptls_client_start(struct ast_tcptls_session_args *desc);
160 void *ast_tcptls_server_root(void *);
163 * \brief This is a generic (re)start routine for a TCP server,
164 * which does the socket/bind/listen and starts a thread for handling
166 * \version 1.6.1 changed desc parameter to be of ast_tcptls_session_args type
168 void ast_tcptls_server_start(struct ast_tcptls_session_args *desc);
171 * \brief Shutdown a running server if there is one
172 * \version 1.6.1 changed desc parameter to be of ast_tcptls_session_args type
174 void ast_tcptls_server_stop(struct ast_tcptls_session_args *desc);
175 int ast_ssl_setup(struct ast_tls_config *cfg);
178 * \brief Used to parse conf files containing tls/ssl options.
180 int ast_tls_read_conf(struct ast_tls_config *tls_cfg, struct ast_tcptls_session_args *tls_desc, const char *varname, const char *value);
182 HOOK_T ast_tcptls_server_read(struct ast_tcptls_session_instance *ser, void *buf, size_t count);
183 HOOK_T ast_tcptls_server_write(struct ast_tcptls_session_instance *ser, const void *buf, size_t count);
185 #endif /* _ASTERISK_TCPTLS_H */