fe4743f33c4ba44d05221e514f23fa0c7aa81481
[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 server.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  * TLS/SSL support is basically implemented by reading from a config file
27  * (currently http.conf) the names of the certificate and cipher to use,
28  * and then run ssl_setup() to create an appropriate SSL_CTX (ssl_ctx)
29  * If we support multiple domains, presumably we need to read multiple
30  * certificates.
31  * When we are requested to open a TLS socket, we run make_file_from_fd()
32  * on the socket, to do the necessary setup. At the moment the context's name
33  * is hardwired in the function, but we can certainly make it into an extra
34  * parameter to the function.
35  * We declare most of ssl support variables unconditionally,
36  * because their number is small and this simplifies the code.
37  *
38  * \note: the ssl-support variables (ssl_ctx, do_ssl, certfile, cipher)
39  * and their setup should be moved to a more central place, e.g. asterisk.conf
40  * and the source files that processes it. Similarly, ssl_setup() should
41  * be run earlier in the startup process so modules have it available.
42  *
43  */
44
45
46 #ifndef _ASTERISK_SERVER_H
47 #define _ASTERISK_SERVER_H
48
49 #include "asterisk/utils.h"
50
51 #if defined(HAVE_OPENSSL) && (defined(HAVE_FUNOPEN) || defined(HAVE_FOPENCOOKIE))
52 #define DO_SSL  /* comment in/out if you want to support ssl */
53 #endif
54
55 #ifdef DO_SSL
56 #include <openssl/ssl.h>
57 #include <openssl/err.h>
58 #else
59 /* declare dummy types so we can define a pointer to them */
60 typedef struct {} SSL;
61 typedef struct {} SSL_CTX;
62 #endif /* DO_SSL */
63
64 /*! SSL support */
65 #define AST_CERTFILE "asterisk.pem"
66
67 enum ast_ssl_flags {
68         /*! Verify certificate when acting as server */
69         AST_SSL_VERIFY_CLIENT = (1 << 0),
70         /*! Don't verify certificate when connecting to a server */
71         AST_SSL_DONT_VERIFY_SERVER = (1 << 1),
72         /*! Don't compare "Common Name" against IP or hostname */
73         AST_SSL_IGNORE_COMMON_NAME = (1 << 2)
74 };
75
76 struct ast_tls_config {
77         int enabled;
78         char *certfile;
79         char *cipher;
80         char *cafile;
81         char *capath;
82         struct ast_flags flags;
83         SSL_CTX *ssl_ctx;
84 };
85
86 /*!
87  * The following code implements a generic mechanism for starting
88  * services on a TCP or TLS socket.
89  * The service is configured in the struct server_args, and
90  * then started by calling server_start(desc) on the descriptor.
91  * server_start() first verifies if an instance of the service is active,
92  * and in case shuts it down. Then, if the service must be started, creates
93  * a socket and a thread in charge of doing the accept().
94  *
95  * The body of the thread is desc->accept_fn(desc), which the user can define
96  * freely. We supply a sample implementation, server_root(), structured as an
97  * infinite loop. At the beginning of each iteration it runs periodic_fn()
98  * if defined (e.g. to perform some cleanup etc.) then issues a poll()
99  * or equivalent with a timeout of 'poll_timeout' milliseconds, and if the
100  * following accept() is successful it creates a thread in charge of
101  * running the session, whose body is desc->worker_fn(). The argument of
102  * worker_fn() is a struct server_instance, which contains the address
103  * of the other party, a pointer to desc, the file descriptors (fd) on which
104  * we can do a select/poll (but NOT IO/, and a FILE *on which we can do I/O.
105  * We have both because we want to support plain and SSL sockets, and
106  * going through a FILE *lets us provide the encryption/decryption
107  * on the stream without using an auxiliary thread.
108  *
109  * NOTE: in order to let other parts of asterisk use these services,
110  * we need to do the following:
111  * + move struct server_instance and struct server_args to
112  * a common header file, together with prototypes for
113  * server_start() and server_root().
114  */
115
116 /*!
117  * describes a server instance
118  */
119 struct server_instance {
120         FILE *f;    /* fopen/funopen result */
121         int fd;     /* the socket returned by accept() */
122         SSL *ssl;   /* ssl state */
123 //      iint (*ssl_setup)(SSL *);
124         int client;
125         struct sockaddr_in requestor;
126         struct server_args *parent;
127 };
128
129 /*!
130  * arguments for the accepting thread
131  */
132 struct server_args {
133         struct sockaddr_in sin;
134         struct sockaddr_in oldsin;
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         pthread_t master;
140         void *(*accept_fn)(void *); /* the function in charge of doing the accept */
141         void (*periodic_fn)(void *);/* something we may want to run before after select on the accept socket */
142         void *(*worker_fn)(void *); /* the function in charge of doing the actual work */
143         const char *name;
144 };
145
146 #if defined(HAVE_FUNOPEN)
147 #define HOOK_T int
148 #define LEN_T int
149 #else
150 #define HOOK_T ssize_t
151 #define LEN_T size_t
152 #endif
153
154 struct server_instance *client_start(struct server_args *desc);
155
156 void *server_root(void *);
157 void server_start(struct server_args *desc);
158 void server_stop(struct server_args *desc);
159 int ssl_setup(struct ast_tls_config *cfg);
160
161 void *ast_make_file_from_fd(void *data);
162
163 HOOK_T server_read(struct server_instance *ser, void *buf, size_t count);
164 HOOK_T server_write(struct server_instance *ser, void *buf, size_t count);
165
166 #endif /* _ASTERISK_SERVER_H */