Wed Oct 28 11:45:42 2009

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 
00049 #ifndef _ASTERISK_SERVER_H
00050 #define _ASTERISK_SERVER_H
00051 
00052 #include "asterisk/utils.h"
00053 #include "asterisk/astobj2.h"
00054 
00055 #if defined(HAVE_OPENSSL) && (defined(HAVE_FUNOPEN) || defined(HAVE_FOPENCOOKIE))
00056 #define DO_SSL  /* comment in/out if you want to support ssl */
00057 #endif
00058 
00059 #ifdef DO_SSL
00060 #include <openssl/ssl.h>
00061 #include <openssl/err.h>
00062 #else
00063 /* declare dummy types so we can define a pointer to them */
00064 typedef struct {} SSL;
00065 typedef struct {} SSL_CTX;
00066 #endif /* DO_SSL */
00067 
00068 /*! SSL support */
00069 #define AST_CERTFILE "asterisk.pem"
00070 
00071 enum ast_ssl_flags {
00072    /*! Verify certificate when acting as server */
00073    AST_SSL_VERIFY_CLIENT = (1 << 0),
00074    /*! Don't verify certificate when connecting to a server */
00075    AST_SSL_DONT_VERIFY_SERVER = (1 << 1),
00076    /*! Don't compare "Common Name" against IP or hostname */
00077    AST_SSL_IGNORE_COMMON_NAME = (1 << 2)
00078 };
00079 
00080 struct ast_tls_config {
00081    int enabled;
00082    char *certfile;
00083    char *cipher;
00084    char *cafile;
00085    char *capath;
00086    struct ast_flags flags;
00087    SSL_CTX *ssl_ctx;
00088 };
00089 
00090 /*!
00091  * The following code implements a generic mechanism for starting
00092  * services on a TCP or TLS socket.
00093  * The service is configured in the struct server_args, and
00094  * then started by calling server_start(desc) on the descriptor.
00095  * server_start() first verifies if an instance of the service is active,
00096  * and in case shuts it down. Then, if the service must be started, creates
00097  * a socket and a thread in charge of doing the accept().
00098  *
00099  * The body of the thread is desc->accept_fn(desc), which the user can define
00100  * freely. We supply a sample implementation, server_root(), structured as an
00101  * infinite loop. At the beginning of each iteration it runs periodic_fn()
00102  * if defined (e.g. to perform some cleanup etc.) then issues a poll()
00103  * or equivalent with a timeout of 'poll_timeout' milliseconds, and if the
00104  * following accept() is successful it creates a thread in charge of
00105  * running the session, whose body is desc->worker_fn(). The argument of
00106  * worker_fn() is a struct ast_tcptls_session_instance, which contains the address
00107  * of the other party, a pointer to desc, the file descriptors (fd) on which
00108  * we can do a select/poll (but NOT IO/, and a FILE *on which we can do I/O.
00109  * We have both because we want to support plain and SSL sockets, and
00110  * going through a FILE *lets us provide the encryption/decryption
00111  * on the stream without using an auxiliary thread.
00112  *
00113  * NOTE: in order to let other parts of asterisk use these services,
00114  * we need to do the following:
00115  * + move struct ast_tcptls_session_instance and struct server_args to
00116  * a common header file, together with prototypes for
00117  * server_start() and server_root().
00118  */
00119 
00120 /*! \brief
00121  * describes a server instance
00122  */
00123 struct ast_tcptls_session_instance {
00124    FILE *f;    /* fopen/funopen result */
00125    int fd;     /* the socket returned by accept() */
00126    SSL *ssl;   /* ssl state */
00127 /* iint (*ssl_setup)(SSL *); */
00128    int client;
00129    struct sockaddr_in requestor;
00130    struct server_args *parent;
00131    ast_mutex_t lock;
00132 };
00133 
00134 /*! \brief
00135  * arguments for the accepting thread
00136  */
00137 struct server_args {
00138    struct sockaddr_in sin;
00139    struct sockaddr_in oldsin;
00140    char hostname[MAXHOSTNAMELEN]; /*!< only necessary for SSL clients so we can compare to common name */
00141    struct ast_tls_config *tls_cfg; /*!< points to the SSL configuration if any */
00142    int accept_fd;
00143    int poll_timeout;
00144    pthread_t master;
00145    void *(*accept_fn)(void *); /*!< the function in charge of doing the accept */
00146    void (*periodic_fn)(void *);/*!< something we may want to run before after select on the accept socket */
00147    void *(*worker_fn)(void *); /*!< the function in charge of doing the actual work */
00148    const char *name;
00149 };
00150 
00151 #if defined(HAVE_FUNOPEN)
00152 #define HOOK_T int
00153 #define LEN_T int
00154 #else
00155 #define HOOK_T ssize_t
00156 #define LEN_T size_t
00157 #endif
00158 
00159 struct ast_tcptls_session_instance *ast_tcptls_client_start(struct server_args *desc);
00160 
00161 void *ast_tcptls_server_root(void *);
00162 void ast_tcptls_server_start(struct server_args *desc);
00163 void ast_tcptls_server_stop(struct server_args *desc);
00164 int ast_ssl_setup(struct ast_tls_config *cfg);
00165 
00166 void *ast_make_file_from_fd(void *data);
00167 
00168 HOOK_T ast_tcptls_server_read(struct ast_tcptls_session_instance *ser, void *buf, size_t count);
00169 HOOK_T ast_tcptls_server_write(struct ast_tcptls_session_instance *ser, void *buf, size_t count);
00170 
00171 #endif /* _ASTERISK_SERVER_H */

Generated on Wed Oct 28 11:45:42 2009 for Asterisk - the Open Source PBX by  doxygen 1.5.6