00001 /* 00002 * Asterisk -- An open source telephony toolkit. 00003 * 00004 * Copyright (C) 1999 - 2006, Digium, Inc. 00005 * 00006 * Mark Spencer <markster@digium.com> 00007 * 00008 * See http://www.asterisk.org for more information about 00009 * the Asterisk project. Please do not directly contact 00010 * any of the maintainers of this project for assistance; 00011 * the project provides a web site, mailing lists and IRC 00012 * channels for your use. 00013 * 00014 * This program is free software, distributed under the terms of 00015 * the GNU General Public License Version 2. See the LICENSE file 00016 * at the top of the source tree. 00017 */ 00018 00019 /*! 00020 * \file tcptls.h 00021 * 00022 * \brief Generic support for tcp/tls servers in Asterisk. 00023 * \note In order to have TLS/SSL support, we need the openssl libraries. 00024 * Still we can decide whether or not to use them by commenting 00025 * in or out the DO_SSL macro. 00026 * 00027 * TLS/SSL support is basically implemented by reading from a config file 00028 * (currently http.conf and sip.conf) the names of the certificate and cipher to use, 00029 * and then run ssl_setup() to create an appropriate SSL_CTX (ssl_ctx) 00030 * If we support multiple domains, presumably we need to read multiple 00031 * certificates. 00032 * 00033 * When we are requested to open a TLS socket, we run make_file_from_fd() 00034 * on the socket, to do the necessary setup. At the moment the context's name 00035 * is hardwired in the function, but we can certainly make it into an extra 00036 * parameter to the function. 00037 * 00038 * We declare most of ssl support variables unconditionally, 00039 * because their number is small and this simplifies the code. 00040 * 00041 * \note The ssl-support variables (ssl_ctx, do_ssl, certfile, cipher) 00042 * and their setup should be moved to a more central place, e.g. asterisk.conf 00043 * and the source files that processes it. Similarly, ssl_setup() should 00044 * be run earlier in the startup process so modules have it available. 00045 * 00046 */ 00047 00048 #ifndef _ASTERISK_TCPTLS_H 00049 #define _ASTERISK_TCPTLS_H 00050 00051 #include "asterisk/netsock2.h" 00052 #include "asterisk/utils.h" 00053 00054 #if defined(HAVE_OPENSSL) && (defined(HAVE_FUNOPEN) || defined(HAVE_FOPENCOOKIE)) 00055 #define DO_SSL /* comment in/out if you want to support ssl */ 00056 #endif 00057 00058 #ifdef DO_SSL 00059 #include <openssl/ssl.h> 00060 #include <openssl/err.h> 00061 #else 00062 /* declare dummy types so we can define a pointer to them */ 00063 typedef struct {} SSL; 00064 typedef struct {} SSL_CTX; 00065 #endif /* DO_SSL */ 00066 00067 /*! SSL support */ 00068 #define AST_CERTFILE "asterisk.pem" 00069 00070 enum ast_ssl_flags { 00071 /*! Verify certificate when acting as server */ 00072 AST_SSL_VERIFY_CLIENT = (1 << 0), 00073 /*! Don't verify certificate when connecting to a server */ 00074 AST_SSL_DONT_VERIFY_SERVER = (1 << 1), 00075 /*! Don't compare "Common Name" against IP or hostname */ 00076 AST_SSL_IGNORE_COMMON_NAME = (1 << 2), 00077 /*! Use SSLv2 for outgoing client connections */ 00078 AST_SSL_SSLV2_CLIENT = (1 << 3), 00079 /*! Use SSLv3 for outgoing client connections */ 00080 AST_SSL_SSLV3_CLIENT = (1 << 4), 00081 /*! Use TLSv1 for outgoing client connections */ 00082 AST_SSL_TLSV1_CLIENT = (1 << 5) 00083 }; 00084 00085 struct ast_tls_config { 00086 int enabled; 00087 char *certfile; 00088 char *pvtfile; 00089 char *cipher; 00090 char *cafile; 00091 char *capath; 00092 struct ast_flags flags; 00093 SSL_CTX *ssl_ctx; 00094 }; 00095 00096 /*! 00097 * The following code implements a generic mechanism for starting 00098 * services on a TCP or TLS socket. 00099 * The service is configured in the struct session_args, and 00100 * then started by calling server_start(desc) on the descriptor. 00101 * server_start() first verifies if an instance of the service is active, 00102 * and in case shuts it down. Then, if the service must be started, creates 00103 * a socket and a thread in charge of doing the accept(). 00104 * 00105 * The body of the thread is desc->accept_fn(desc), which the user can define 00106 * freely. We supply a sample implementation, server_root(), structured as an 00107 * infinite loop. At the beginning of each iteration it runs periodic_fn() 00108 * if defined (e.g. to perform some cleanup etc.) then issues a poll() 00109 * or equivalent with a timeout of 'poll_timeout' milliseconds, and if the 00110 * following accept() is successful it creates a thread in charge of 00111 * running the session, whose body is desc->worker_fn(). The argument of 00112 * worker_fn() is a struct ast_tcptls_session_instance, which contains the address 00113 * of the other party, a pointer to desc, the file descriptors (fd) on which 00114 * we can do a select/poll (but NOT I/O), and a FILE *on which we can do I/O. 00115 * We have both because we want to support plain and SSL sockets, and 00116 * going through a FILE * lets us provide the encryption/decryption 00117 * on the stream without using an auxiliary thread. 00118 */ 00119 00120 /*! \brief 00121 * arguments for the accepting thread 00122 */ 00123 struct ast_tcptls_session_args { 00124 struct ast_sockaddr local_address; 00125 struct ast_sockaddr old_address; /*!< copy of the local or remote address depending on if its a client or server session */ 00126 struct ast_sockaddr remote_address; 00127 char hostname[MAXHOSTNAMELEN]; /*!< only necessary for SSL clients so we can compare to common name */ 00128 struct ast_tls_config *tls_cfg; /*!< points to the SSL configuration if any */ 00129 int accept_fd; 00130 int poll_timeout; 00131 /*! Server accept_fn thread ID used for external shutdown requests. */ 00132 pthread_t master; 00133 void *(*accept_fn)(void *); /*!< the function in charge of doing the accept */ 00134 void (*periodic_fn)(void *);/*!< something we may want to run before after select on the accept socket */ 00135 void *(*worker_fn)(void *); /*!< the function in charge of doing the actual work */ 00136 const char *name; 00137 }; 00138 00139 struct ast_tcptls_stream; 00140 00141 /*! 00142 * \brief Disable the TCP/TLS stream timeout timer. 00143 * 00144 * \param stream TCP/TLS stream control data. 00145 * 00146 * \return Nothing 00147 */ 00148 void ast_tcptls_stream_set_timeout_disable(struct ast_tcptls_stream *stream); 00149 00150 /*! 00151 * \brief Set the TCP/TLS stream inactivity timeout timer. 00152 * 00153 * \param stream TCP/TLS stream control data. 00154 * \param timeout Number of milliseconds to wait for data transfer with the peer. 00155 * 00156 * \details This is basically how much time we are willing to spend 00157 * in an I/O call before we declare the peer unresponsive. 00158 * 00159 * \note Setting timeout to -1 disables the timeout. 00160 * \note Setting this timeout replaces the I/O sequence timeout timer. 00161 * 00162 * \return Nothing 00163 */ 00164 void ast_tcptls_stream_set_timeout_inactivity(struct ast_tcptls_stream *stream, int timeout); 00165 00166 /*! 00167 * \brief Set the TCP/TLS stream I/O sequence timeout timer. 00168 * 00169 * \param stream TCP/TLS stream control data. 00170 * \param start Time the I/O sequence timer starts. 00171 * \param timeout Number of milliseconds from the start time before timeout. 00172 * 00173 * \details This is how much time are we willing to allow the peer 00174 * to complete an operation that can take several I/O calls. The 00175 * main use is as an authentication timer with us. 00176 * 00177 * \note Setting timeout to -1 disables the timeout. 00178 * \note Setting this timeout replaces the inactivity timeout timer. 00179 * 00180 * \return Nothing 00181 */ 00182 void ast_tcptls_stream_set_timeout_sequence(struct ast_tcptls_stream *stream, struct timeval start, int timeout); 00183 00184 /*! 00185 * \brief Set the TCP/TLS stream I/O if it can exclusively depend upon the set timeouts. 00186 * 00187 * \param stream TCP/TLS stream control data. 00188 * \param exclusive_input TRUE if stream can exclusively wait for fd input. 00189 * Otherwise, the stream will not wait for fd input. It will wait while 00190 * trying to send data. 00191 * 00192 * \note The stream timeouts still need to be set. 00193 * 00194 * \return Nothing 00195 */ 00196 void ast_tcptls_stream_set_exclusive_input(struct ast_tcptls_stream *stream, int exclusive_input); 00197 00198 /* 00199 * describes a server instance 00200 */ 00201 struct ast_tcptls_session_instance { 00202 FILE *f; /* fopen/funopen result */ 00203 int fd; /* the socket returned by accept() */ 00204 SSL *ssl; /* ssl state */ 00205 /* iint (*ssl_setup)(SSL *); */ 00206 int client; 00207 struct ast_sockaddr remote_address; 00208 struct ast_tcptls_session_args *parent; 00209 /*! XXX Why do we still use this lock when this struct is allocated as an ao2 object which has its own lock? */ 00210 ast_mutex_t lock; 00211 /* Sometimes, when an entity reads TCP data, multiple 00212 * logical messages might be read at the same time. In such 00213 * a circumstance, there needs to be a place to stash the 00214 * extra data. 00215 */ 00216 struct ast_str *overflow_buf; 00217 /*! ao2 FILE stream cookie object associated with f. */ 00218 struct ast_tcptls_stream *stream_cookie; 00219 }; 00220 00221 #if defined(HAVE_FUNOPEN) 00222 #define HOOK_T int 00223 #define LEN_T int 00224 #else 00225 #define HOOK_T ssize_t 00226 #define LEN_T size_t 00227 #endif 00228 00229 /*! 00230 * \brief attempts to connect and start tcptls session, on error the tcptls_session's 00231 * ref count is decremented, fd and file are closed, and NULL is returned. 00232 */ 00233 struct ast_tcptls_session_instance *ast_tcptls_client_start(struct ast_tcptls_session_instance *tcptls_session); 00234 00235 /* \brief Creates a client connection's ast_tcptls_session_instance. */ 00236 struct ast_tcptls_session_instance *ast_tcptls_client_create(struct ast_tcptls_session_args *desc); 00237 00238 void *ast_tcptls_server_root(void *); 00239 00240 /*! 00241 * \brief Closes a tcptls session instance's file and/or file descriptor. 00242 * The tcptls_session will be set to NULL and it's file descriptor will be set to -1 00243 * by this function. 00244 */ 00245 void ast_tcptls_close_session_file(struct ast_tcptls_session_instance *tcptls_session); 00246 00247 /*! 00248 * \brief This is a generic (re)start routine for a TCP server, 00249 * which does the socket/bind/listen and starts a thread for handling 00250 * accept(). 00251 * \version 1.6.1 changed desc parameter to be of ast_tcptls_session_args type 00252 */ 00253 void ast_tcptls_server_start(struct ast_tcptls_session_args *desc); 00254 00255 /*! 00256 * \brief Shutdown a running server if there is one 00257 * \version 1.6.1 changed desc parameter to be of ast_tcptls_session_args type 00258 */ 00259 void ast_tcptls_server_stop(struct ast_tcptls_session_args *desc); 00260 00261 /*! 00262 * \brief Set up an SSL server 00263 * 00264 * \param cfg Configuration for the SSL server 00265 * \retval 1 Success 00266 * \retval 0 Failure 00267 */ 00268 int ast_ssl_setup(struct ast_tls_config *cfg); 00269 00270 /*! 00271 * \brief free resources used by an SSL server 00272 * 00273 * \note This only needs to be called if ast_ssl_setup() was 00274 * directly called first. 00275 * \param cfg Configuration for the SSL server 00276 */ 00277 void ast_ssl_teardown(struct ast_tls_config *cfg); 00278 00279 /*! 00280 * \brief Used to parse conf files containing tls/ssl options. 00281 */ 00282 int ast_tls_read_conf(struct ast_tls_config *tls_cfg, struct ast_tcptls_session_args *tls_desc, const char *varname, const char *value); 00283 00284 HOOK_T ast_tcptls_server_read(struct ast_tcptls_session_instance *ser, void *buf, size_t count); 00285 HOOK_T ast_tcptls_server_write(struct ast_tcptls_session_instance *ser, const void *buf, size_t count); 00286 00287 #endif /* _ASTERISK_TCPTLS_H */