Wed Aug 7 17:15:45 2019

Asterisk developer's documentation


tcptls.h

Go to the documentation of this file.
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 */

Generated on 7 Aug 2019 for Asterisk - The Open Source Telephony Project by  doxygen 1.6.1