2cc2c0fa3e912ed37a6b389c5305171401560eee
[asterisk/asterisk.git] / 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 #ifndef _ASTERISK_TCPTLS_H
49 #define _ASTERISK_TCPTLS_H
50
51 #include "asterisk/netsock2.h"
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         /*! Use SSLv2 for outgoing client connections */
78         AST_SSL_SSLV2_CLIENT = (1 << 3),
79         /*! Use SSLv3 for outgoing client connections */
80         AST_SSL_SSLV3_CLIENT = (1 << 4),
81         /*! Use TLSv1 for outgoing client connections */
82         AST_SSL_TLSV1_CLIENT = (1 << 5)
83 };
84
85 struct ast_tls_config {
86         int enabled;
87         char *certfile;
88         char *pvtfile;
89         char *cipher;
90         char *cafile;
91         char *capath;
92         struct ast_flags flags;
93         SSL_CTX *ssl_ctx;
94 };
95
96 /*!
97  * The following code implements a generic mechanism for starting
98  * services on a TCP or TLS socket.
99  * The service is configured in the struct session_args, and
100  * then started by calling server_start(desc) on the descriptor.
101  * server_start() first verifies if an instance of the service is active,
102  * and in case shuts it down. Then, if the service must be started, creates
103  * a socket and a thread in charge of doing the accept().
104  *
105  * The body of the thread is desc->accept_fn(desc), which the user can define
106  * freely. We supply a sample implementation, server_root(), structured as an
107  * infinite loop. At the beginning of each iteration it runs periodic_fn()
108  * if defined (e.g. to perform some cleanup etc.) then issues a poll()
109  * or equivalent with a timeout of 'poll_timeout' milliseconds, and if the
110  * following accept() is successful it creates a thread in charge of
111  * running the session, whose body is desc->worker_fn(). The argument of
112  * worker_fn() is a struct ast_tcptls_session_instance, which contains the address
113  * of the other party, a pointer to desc, the file descriptors (fd) on which
114  * we can do a select/poll (but NOT I/O), and a FILE *on which we can do I/O.
115  * We have both because we want to support plain and SSL sockets, and
116  * going through a FILE * lets us provide the encryption/decryption
117  * on the stream without using an auxiliary thread.
118  */
119
120 /*! \brief
121  * arguments for the accepting thread
122  */
123 struct ast_tcptls_session_args {
124         struct ast_sockaddr local_address;
125         struct ast_sockaddr old_address; /*!< copy of the local or remote address depending on if its a client or server session */
126         struct ast_sockaddr remote_address;
127         char hostname[MAXHOSTNAMELEN]; /*!< only necessary for SSL clients so we can compare to common name */
128         struct ast_tls_config *tls_cfg; /*!< points to the SSL configuration if any */
129         int accept_fd;
130         int poll_timeout;
131         pthread_t master;
132         void *(*accept_fn)(void *); /*!< the function in charge of doing the accept */
133         void (*periodic_fn)(void *);/*!< something we may want to run before after select on the accept socket */
134         void *(*worker_fn)(void *); /*!< the function in charge of doing the actual work */
135         const char *name;
136 };
137
138 /*
139  * describes a server instance
140  */
141 struct ast_tcptls_session_instance {
142         FILE *f;    /* fopen/funopen result */
143         int fd;     /* the socket returned by accept() */
144         SSL *ssl;   /* ssl state */
145 /*      iint (*ssl_setup)(SSL *); */
146         int client;
147         struct ast_sockaddr remote_address;
148         struct ast_tcptls_session_args *parent;
149         ast_mutex_t lock;
150 };
151
152 #if defined(HAVE_FUNOPEN)
153 #define HOOK_T int
154 #define LEN_T int
155 #else
156 #define HOOK_T ssize_t
157 #define LEN_T size_t
158 #endif
159
160 /*! 
161   * \brief attempts to connect and start tcptls session, on error the tcptls_session's
162   * ref count is decremented, fd and file are closed, and NULL is returned.
163   */
164 struct ast_tcptls_session_instance *ast_tcptls_client_start(struct ast_tcptls_session_instance *tcptls_session);
165
166 /* \brief Creates a client connection's ast_tcptls_session_instance. */
167 struct ast_tcptls_session_instance *ast_tcptls_client_create(struct ast_tcptls_session_args *desc);
168
169 void *ast_tcptls_server_root(void *);
170
171 /*!
172  * \brief This is a generic (re)start routine for a TCP server,
173  * which does the socket/bind/listen and starts a thread for handling
174  * accept().
175  * \version 1.6.1 changed desc parameter to be of ast_tcptls_session_args type
176  */
177 void ast_tcptls_server_start(struct ast_tcptls_session_args *desc);
178
179 /*!
180  * \brief Shutdown a running server if there is one
181  * \version 1.6.1 changed desc parameter to be of ast_tcptls_session_args type
182  */
183 void ast_tcptls_server_stop(struct ast_tcptls_session_args *desc);
184 int ast_ssl_setup(struct ast_tls_config *cfg);
185
186 /*!
187  * \brief Used to parse conf files containing tls/ssl options.
188  */
189 int ast_tls_read_conf(struct ast_tls_config *tls_cfg, struct ast_tcptls_session_args *tls_desc, const char *varname, const char *value);
190
191 HOOK_T ast_tcptls_server_read(struct ast_tcptls_session_instance *ser, void *buf, size_t count);
192 HOOK_T ast_tcptls_server_write(struct ast_tcptls_session_instance *ser, const void *buf, size_t count);
193
194 #endif /* _ASTERISK_TCPTLS_H */