include/asterisk/tcptls.h

   1 /*
   2  * Asterisk -- An open source telephony toolkit.
   3  *
   4  * Copyright (C) 1999 - 2006, Digium, Inc.
   5  *
   6  * Mark Spencer <markster@digium.com>
   7  *
   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.
  13  *
  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.
  17  */
  18
  19 /*!
  20  * \file tcptls.h
  21  *
  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.
  26  *
  27  * TLS/SSL support is basically implemented by reading from a config file
  28  * (currently manager.conf, http.conf and sip.conf) the names of the certificate
  29  * files and cipher to use, and then run ssl_setup() to create an appropriate
  30  * data structure named ssl_ctx.
  31  *
  32  * If we support multiple domains, presumably we need to read multiple
  33  * certificates.
  34  *
  35  * When we are requested to open a TLS socket, we run make_file_from_fd()
  36  * on the socket, to do the necessary setup. At the moment the context's name
  37  * is hardwired in the function, but we can certainly make it into an extra
  38  * parameter to the function.
  39  *
  40  * We declare most of ssl support variables unconditionally,
  41  * because their number is small and this simplifies the code.
  42  *
  43  * \note The ssl-support variables (ssl_ctx, do_ssl, certfile, cipher)
  44  * and their setup should be moved to a more central place, e.g. asterisk.conf
  45  * and the source files that processes it. Similarly, ssl_setup() should
  46  * be run earlier in the startup process so modules have it available.
  47  *
  48  * \ref AstTlsOverview
  49  *
  50  * \todo For SIP, the SubjectAltNames should be checked on verification
  51  *       of the certificate. (Check RFC 5922)
  52  *
  53  */
  54
  55 #ifndef _ASTERISK_TCPTLS_H
  56 #define _ASTERISK_TCPTLS_H
  57
  58 #include "asterisk/netsock2.h"
  59 #include "asterisk/utils.h"
  60
  61 #if defined(HAVE_OPENSSL) && (defined(HAVE_FUNOPEN) || defined(HAVE_FOPENCOOKIE))
  62 #define DO_SSL  /* comment in/out if you want to support ssl */
  63 #endif
  64
  65 #ifdef DO_SSL
  66 #include <openssl/ssl.h>
  67 #include <openssl/err.h>
  68 #else
  69 /* declare dummy types so we can define a pointer to them */
  70 typedef struct {} SSL;
  71 typedef struct {} SSL_CTX;
  72 #endif /* DO_SSL */
  73
  74 /*! SSL support */
  75 #define AST_CERTFILE "asterisk.pem"
  76
  77 enum ast_ssl_flags {
  78         /*! Verify certificate when acting as server */
  79         AST_SSL_VERIFY_CLIENT = (1 << 0),
  80         /*! Don't verify certificate when connecting to a server */
  81         AST_SSL_DONT_VERIFY_SERVER = (1 << 1),
  82         /*! Don't compare "Common Name" against IP or hostname */
  83         AST_SSL_IGNORE_COMMON_NAME = (1 << 2),
  84         /*! Use SSLv2 for outgoing client connections */
  85         AST_SSL_SSLV2_CLIENT = (1 << 3),
  86         /*! Use SSLv3 for outgoing client connections */
  87         AST_SSL_SSLV3_CLIENT = (1 << 4),
  88         /*! Use TLSv1 for outgoing client connections */
  89         AST_SSL_TLSV1_CLIENT = (1 << 5)
  90 };
  91
  92 struct ast_tls_config {
  93         int enabled;
  94         char *certfile;
  95         char *pvtfile;
  96         char *cipher;
  97         char *cafile;
  98         char *capath;
  99         struct ast_flags flags;
 100         SSL_CTX *ssl_ctx;
 101 };
 102
 103 /*! \page AstTlsOverview TLS Implementation Overview
 104  *
 105  * The following code implements a generic mechanism for starting
 106  * services on a TCP or TLS socket.
 107  * The service is configured in the struct session_args, and
 108  * then started by calling server_start(desc) on the descriptor.
 109  * server_start() first verifies if an instance of the service is active,
 110  * and in case shuts it down. Then, if the service must be started, creates
 111  * a socket and a thread in charge of doing the accept().
 112  *
 113  * The body of the thread is desc->accept_fn(desc), which the user can define
 114  * freely. We supply a sample implementation, server_root(), structured as an
 115  * infinite loop. At the beginning of each iteration it runs periodic_fn()
 116  * if defined (e.g. to perform some cleanup etc.) then issues a poll()
 117  * or equivalent with a timeout of 'poll_timeout' milliseconds, and if the
 118  * following accept() is successful it creates a thread in charge of
 119  * running the session, whose body is desc->worker_fn(). The argument of
 120  * worker_fn() is a struct ast_tcptls_session_instance, which contains the address
 121  * of the other party, a pointer to desc, the file descriptors (fd) on which
 122  * we can do a select/poll (but NOT I/O), and a FILE *on which we can do I/O.
 123  * We have both because we want to support plain and SSL sockets, and
 124  * going through a FILE * lets us provide the encryption/decryption
 125  * on the stream without using an auxiliary thread.
 126  */
 127
 128 /*! \brief
 129  * arguments for the accepting thread
 130  */
 131 struct ast_tcptls_session_args {
 132         struct ast_sockaddr local_address;
 133         struct ast_sockaddr old_address; /*!< copy of the local or remote address depending on if its a client or server session */
 134         struct ast_sockaddr remote_address;
 135         char hostname[MAXHOSTNAMELEN]; /*!< only necessary for SSL clients so we can compare to common name */
 136         struct ast_tls_config *tls_cfg; /*!< points to the SSL configuration if any */
 137         int accept_fd;
 138         int poll_timeout;
 139         /*! Server accept_fn thread ID used for external shutdown requests. */
 140         pthread_t master;
 141         void *(*accept_fn)(void *); /*!< the function in charge of doing the accept */
 142         void (*periodic_fn)(void *);/*!< something we may want to run before after select on the accept socket */
 143         void *(*worker_fn)(void *); /*!< the function in charge of doing the actual work */
 144         const char *name;
 145 };
 146
 147 struct ast_tcptls_stream;
 148
 149 /*!
 150  * \brief Disable the TCP/TLS stream timeout timer.
 151  *
 152  * \param stream TCP/TLS stream control data.
 153  *
 154  * \return Nothing
 155  */
 156 void ast_tcptls_stream_set_timeout_disable(struct ast_tcptls_stream *stream);
 157
 158 /*!
 159  * \brief Set the TCP/TLS stream inactivity timeout timer.
 160  *
 161  * \param stream TCP/TLS stream control data.
 162  * \param timeout Number of milliseconds to wait for data transfer with the peer.
 163  *
 164  * \details This is basically how much time we are willing to spend
 165  * in an I/O call before we declare the peer unresponsive.
 166  *
 167  * \note Setting timeout to -1 disables the timeout.
 168  * \note Setting this timeout replaces the I/O sequence timeout timer.
 169  *
 170  * \return Nothing
 171  */
 172 void ast_tcptls_stream_set_timeout_inactivity(struct ast_tcptls_stream *stream, int timeout);
 173
 174 /*!
 175  * \brief Set the TCP/TLS stream I/O sequence timeout timer.
 176  *
 177  * \param stream TCP/TLS stream control data.
 178  * \param start Time the I/O sequence timer starts.
 179  * \param timeout Number of milliseconds from the start time before timeout.
 180  *
 181  * \details This is how much time are we willing to allow the peer
 182  * to complete an operation that can take several I/O calls.  The
 183  * main use is as an authentication timer with us.
 184  *
 185  * \note Setting timeout to -1 disables the timeout.
 186  * \note Setting this timeout replaces the inactivity timeout timer.
 187  *
 188  * \return Nothing
 189  */
 190 void ast_tcptls_stream_set_timeout_sequence(struct ast_tcptls_stream *stream, struct timeval start, int timeout);
 191
 192 /*! \brief
 193  * describes a server instance
 194  */
 195 struct ast_tcptls_session_instance {
 196         FILE *f;    /*!< fopen/funopen result */
 197         int fd;     /*!< the socket returned by accept() */
 198         SSL *ssl;   /*!< ssl state */
 199 /*      iint (*ssl_setup)(SSL *); */
 200         int client;
 201         struct ast_sockaddr remote_address;
 202         struct ast_tcptls_session_args *parent;
 203         /* Sometimes, when an entity reads TCP data, multiple
 204          * logical messages might be read at the same time. In such
 205          * a circumstance, there needs to be a place to stash the
 206          * extra data.
 207          */
 208         struct ast_str *overflow_buf;
 209         /*! ao2 FILE stream cookie object associated with f. */
 210         struct ast_tcptls_stream *stream_cookie;
 211 };
 212
 213 #if defined(HAVE_FUNOPEN)
 214 #define HOOK_T int
 215 #define LEN_T int
 216 #else
 217 #define HOOK_T ssize_t
 218 #define LEN_T size_t
 219 #endif
 220
 221 /*!
 222   * \brief attempts to connect and start tcptls session, on error the tcptls_session's
 223   * ref count is decremented, fd and file are closed, and NULL is returned.
 224   */
 225 struct ast_tcptls_session_instance *ast_tcptls_client_start(struct ast_tcptls_session_instance *tcptls_session);
 226
 227 /* \brief Creates a client connection's ast_tcptls_session_instance. */
 228 struct ast_tcptls_session_instance *ast_tcptls_client_create(struct ast_tcptls_session_args *desc);
 229
 230 void *ast_tcptls_server_root(void *);
 231
 232 /*!
 233  * \brief Closes a tcptls session instance's file and/or file descriptor.
 234  * The tcptls_session will be set to NULL and it's file descriptor will be set to -1
 235  * by this function.
 236  */
 237 void ast_tcptls_close_session_file(struct ast_tcptls_session_instance *tcptls_session);
 238
 239 /*!
 240  * \brief This is a generic (re)start routine for a TCP server,
 241  * which does the socket/bind/listen and starts a thread for handling
 242  * accept().
 243  * \version 1.6.1 changed desc parameter to be of ast_tcptls_session_args type
 244  */
 245 void ast_tcptls_server_start(struct ast_tcptls_session_args *desc);
 246
 247 /*!
 248  * \brief Shutdown a running server if there is one
 249  * \version 1.6.1 changed desc parameter to be of ast_tcptls_session_args type
 250  */
 251 void ast_tcptls_server_stop(struct ast_tcptls_session_args *desc);
 252
 253 /*!
 254  * \brief Set up an SSL server
 255  *
 256  * \param cfg Configuration for the SSL server
 257  * \retval 1 Success
 258  * \retval 0 Failure
 259  */
 260 int ast_ssl_setup(struct ast_tls_config *cfg);
 261
 262 /*!
 263  * \brief free resources used by an SSL server
 264  *
 265  * \note This only needs to be called if ast_ssl_setup() was
 266  * directly called first.
 267  * \param cfg Configuration for the SSL server
 268  */
 269 void ast_ssl_teardown(struct ast_tls_config *cfg);
 270
 271 /*!
 272  * \brief Used to parse conf files containing tls/ssl options.
 273  */
 274 int ast_tls_read_conf(struct ast_tls_config *tls_cfg, struct ast_tcptls_session_args *tls_desc, const char *varname, const char *value);
 275
 276 HOOK_T ast_tcptls_server_read(struct ast_tcptls_session_instance *ser, void *buf, size_t count);
 277 HOOK_T ast_tcptls_server_write(struct ast_tcptls_session_instance *ser, const void *buf, size_t count);
 278
 279 #endif /* _ASTERISK_TCPTLS_H */