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 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
  31  * certificates.
  32  *
  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.
  37  *
  38  * We declare most of ssl support variables unconditionally,
  39  * because their number is small and this simplifies the code.
  40  *
  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.
  45  *
  46  */
  47
  48
  49 #ifndef _ASTERISK_SERVER_H
  50 #define _ASTERISK_SERVER_H
  51
  52 #include "asterisk/utils.h"
  53
  54 #if defined(HAVE_OPENSSL) && (defined(HAVE_FUNOPEN) || defined(HAVE_FOPENCOOKIE))
  55 #define DO_SSL  /* comment in/out if you want to support ssl */
  56 #endif
  57
  58 #ifdef DO_SSL
  59 #include <openssl/ssl.h>
  60 #include <openssl/err.h>
  61 #else
  62 /* declare dummy types so we can define a pointer to them */
  63 typedef struct {} SSL;
  64 typedef struct {} SSL_CTX;
  65 #endif /* DO_SSL */
  66
  67 /*! SSL support */
  68 #define AST_CERTFILE "asterisk.pem"
  69
  70 enum ast_ssl_flags {
  71         /*! Verify certificate when acting as server */
  72         AST_SSL_VERIFY_CLIENT = (1 << 0),
  73         /*! Don't verify certificate when connecting to a server */
  74         AST_SSL_DONT_VERIFY_SERVER = (1 << 1),
  75         /*! Don't compare "Common Name" against IP or hostname */
  76         AST_SSL_IGNORE_COMMON_NAME = (1 << 2)
  77 };
  78
  79 struct ast_tls_config {
  80         int enabled;
  81         char *certfile;
  82         char *cipher;
  83         char *cafile;
  84         char *capath;
  85         struct ast_flags flags;
  86         SSL_CTX *ssl_ctx;
  87 };
  88
  89 /*!
  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 server_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().
  97  *
  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 IO/, 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.
 111  *
 112  * NOTE: in order to let other parts of asterisk use these services,
 113  * we need to do the following:
 114  * + move struct ast_tcptls_session_instance and struct server_args to
 115  * a common header file, together with prototypes for
 116  * server_start() and server_root().
 117  */
 118
 119 /*! \brief
 120  * describes a server instance
 121  */
 122 struct ast_tcptls_session_instance {
 123         FILE *f;    /* fopen/funopen result */
 124         int fd;     /* the socket returned by accept() */
 125         SSL *ssl;   /* ssl state */
 126 /*      iint (*ssl_setup)(SSL *); */
 127         int client;
 128         struct sockaddr_in requestor;
 129         struct server_args *parent;
 130 };
 131
 132 /*! \brief
 133  * arguments for the accepting thread
 134  */
 135 struct server_args {
 136         struct sockaddr_in sin;
 137         struct sockaddr_in oldsin;
 138         char hostname[MAXHOSTNAMELEN]; /*!< only necessary for SSL clients so we can compare to common name */
 139         struct ast_tls_config *tls_cfg; /*!< points to the SSL configuration if any */
 140         int accept_fd;
 141         int poll_timeout;
 142         pthread_t master;
 143         void *(*accept_fn)(void *); /*!< the function in charge of doing the accept */
 144         void (*periodic_fn)(void *);/*!< something we may want to run before after select on the accept socket */
 145         void *(*worker_fn)(void *); /*!< the function in charge of doing the actual work */
 146         const char *name;
 147 };
 148
 149 #if defined(HAVE_FUNOPEN)
 150 #define HOOK_T int
 151 #define LEN_T int
 152 #else
 153 #define HOOK_T ssize_t
 154 #define LEN_T size_t
 155 #endif
 156
 157 struct ast_tcptls_session_instance *ast_tcptls_client_start(struct server_args *desc);
 158
 159 void *ast_tcptls_server_root(void *);
 160 void ast_tcptls_server_start(struct server_args *desc);
 161 void ast_tcptls_server_stop(struct server_args *desc);
 162 int ast_ssl_setup(struct ast_tls_config *cfg);
 163
 164 void *ast_make_file_from_fd(void *data);
 165
 166 HOOK_T ast_tcptls_server_read(struct ast_tcptls_session_instance *ser, void *buf, size_t count);
 167 HOOK_T ast_tcptls_server_write(struct ast_tcptls_session_instance *ser, void *buf, size_t count);
 168
 169 /*!
 170  * \brief Destroy a server instance
 171  *
 172  * \return NULL for convenience
 173  */
 174 struct ast_tcptls_session_instance *ast_tcptls_session_instance_destroy(struct ast_tcptls_session_instance *i);
 175
 176 #endif /* _ASTERISK_SERVER_H */