STIR/SHAKEN: Option split and response codes.
[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 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
51 #ifndef _ASTERISK_TCPTLS_H
52 #define _ASTERISK_TCPTLS_H
53
54 #include <pthread.h>            /* for pthread_t */
55 #include <sys/param.h>          /* for MAXHOSTNAMELEN */
56
57 #include "asterisk/iostream.h"
58 #include "asterisk/netsock2.h"  /* for ast_sockaddr */
59 #include "asterisk/utils.h"     /* for ast_flags */
60
61 /*! SSL support */
62 #define AST_CERTFILE "asterisk.pem"
63
64 enum ast_ssl_flags {
65         /*! Verify certificate when acting as server */
66         AST_SSL_VERIFY_CLIENT = (1 << 0),
67         /*! Don't verify certificate when connecting to a server */
68         AST_SSL_DONT_VERIFY_SERVER = (1 << 1),
69         /*! Don't compare "Common Name" against IP or hostname */
70         AST_SSL_IGNORE_COMMON_NAME = (1 << 2),
71         /*! Use SSLv2 for outgoing client connections */
72         AST_SSL_SSLV2_CLIENT = (1 << 3),
73         /*! Use SSLv3 for outgoing client connections */
74         AST_SSL_SSLV3_CLIENT = (1 << 4),
75         /*! Use TLSv1 for outgoing client connections */
76         AST_SSL_TLSV1_CLIENT = (1 << 5),
77         /*! Use server cipher order instead of the client order */
78         AST_SSL_SERVER_CIPHER_ORDER = (1 << 6),
79         /*! Disable TLSv1 support */
80         AST_SSL_DISABLE_TLSV1 = (1 << 7),
81         /*! Disable TLSv1.1 support */
82         AST_SSL_DISABLE_TLSV11 = (1 << 8),
83         /*! Disable TLSv1.2 support */
84         AST_SSL_DISABLE_TLSV12 = (1 << 9),
85 };
86
87 struct ast_tls_config {
88         int enabled;
89         char *certfile;
90         char *pvtfile;
91         char *cipher;
92         char *cafile;
93         char *capath;
94         struct ast_flags flags;
95         SSL_CTX *ssl_ctx;
96         char certhash[41];
97         char pvthash[41];
98         char cahash[41];
99 };
100
101 /*! \page AstTlsOverview TLS Implementation Overview
102  *
103  * The following code implements a generic mechanism for starting
104  * services on a TCP or TLS socket.
105  * The service is configured in the struct session_args, and
106  * then started by calling server_start(desc) on the descriptor.
107  * server_start() first verifies if an instance of the service is active,
108  * and in case shuts it down. Then, if the service must be started, creates
109  * a socket and a thread in charge of doing the accept().
110  *
111  * The body of the thread is desc->accept_fn(desc), which the user can define
112  * freely. We supply a sample implementation, server_root(), structured as an
113  * infinite loop. At the beginning of each iteration it runs periodic_fn()
114  * if defined (e.g. to perform some cleanup etc.) then issues a poll()
115  * or equivalent with a timeout of 'poll_timeout' milliseconds, and if the
116  * following accept() is successful it creates a thread in charge of
117  * running the session, whose body is desc->worker_fn(). The argument of
118  * worker_fn() is a struct ast_tcptls_session_instance, which contains the address
119  * of the other party, a pointer to desc, the file descriptors (fd) on which
120  * we can do a select/poll (but NOT I/O), and a FILE *on which we can do I/O.
121  * We have both because we want to support plain and SSL sockets, and
122  * going through a FILE * lets us provide the encryption/decryption
123  * on the stream without using an auxiliary thread.
124  */
125
126 /*! \brief
127  * arguments for the accepting thread
128  */
129 struct ast_tcptls_session_args {
130         struct ast_sockaddr local_address;
131         struct ast_sockaddr old_address; /*!< copy of the local or remote address depending on if its a client or server session */
132         struct ast_sockaddr remote_address;
133         char hostname[MAXHOSTNAMELEN]; /*!< only necessary for SSL clients so we can compare to common name */
134         struct ast_tls_config *tls_cfg; /*!< points to the SSL configuration if any */
135         int accept_fd;
136         int poll_timeout;
137         /*! Server accept_fn thread ID used for external shutdown requests. */
138         pthread_t master;
139         void *(*accept_fn)(void *); /*!< the function in charge of doing the accept */
140         void (*periodic_fn)(void *);/*!< something we may want to run before after select on the accept socket */
141         void *(*worker_fn)(void *); /*!< the function in charge of doing the actual work */
142         const char *name;
143         struct ast_tls_config *old_tls_cfg; /*!< copy of the SSL configuration to determine whether changes have been made */
144 };
145
146 /*! \brief
147  * describes a server instance
148  */
149 struct ast_tcptls_session_instance {
150         int client;
151         struct ast_sockaddr remote_address;
152         struct ast_tcptls_session_args *parent;
153         /* Sometimes, when an entity reads TCP data, multiple
154          * logical messages might be read at the same time. In such
155          * a circumstance, there needs to be a place to stash the
156          * extra data.
157          */
158         struct ast_str *overflow_buf;
159         /*! ao2 stream object associated with this session. */
160         struct ast_iostream *stream;
161         /*! ao2 object private data of parent->worker_fn */
162         void *private_data;
163 };
164
165 /*!
166   * \brief attempts to connect and start tcptls session, on error the tcptls_session's
167   * ref count is decremented, fd and file are closed, and NULL is returned.
168   */
169 struct ast_tcptls_session_instance *ast_tcptls_client_start(struct ast_tcptls_session_instance *tcptls_session);
170
171 /* \brief Creates a client connection's ast_tcptls_session_instance. */
172 struct ast_tcptls_session_instance *ast_tcptls_client_create(struct ast_tcptls_session_args *desc);
173
174 void *ast_tcptls_server_root(void *);
175
176 /*!
177  * \brief Closes a tcptls session instance's file and/or file descriptor.
178  * The tcptls_session will be set to NULL and it's file descriptor will be set to -1
179  * by this function.
180  */
181 void ast_tcptls_close_session_file(struct ast_tcptls_session_instance *tcptls_session);
182
183 /*!
184  * \brief This is a generic (re)start routine for a TCP server,
185  * which does the socket/bind/listen and starts a thread for handling
186  * accept().
187  * \version 1.6.1 changed desc parameter to be of ast_tcptls_session_args type
188  */
189 void ast_tcptls_server_start(struct ast_tcptls_session_args *desc);
190
191 /*!
192  * \brief Shutdown a running server if there is one
193  * \version 1.6.1 changed desc parameter to be of ast_tcptls_session_args type
194  */
195 void ast_tcptls_server_stop(struct ast_tcptls_session_args *desc);
196
197 /*!
198  * \brief Set up an SSL server
199  *
200  * \param cfg Configuration for the SSL server
201  * \retval 1 Success
202  * \retval 0 Failure
203  */
204 int ast_ssl_setup(struct ast_tls_config *cfg);
205
206 /*!
207  * \brief free resources used by an SSL server
208  *
209  * \note This only needs to be called if ast_ssl_setup() was
210  * directly called first.
211  * \param cfg Configuration for the SSL server
212  */
213 void ast_ssl_teardown(struct ast_tls_config *cfg);
214
215 /*!
216  * \brief Used to parse conf files containing tls/ssl options.
217  */
218 int ast_tls_read_conf(struct ast_tls_config *tls_cfg, struct ast_tcptls_session_args *tls_desc, const char *varname, const char *value);
219
220 #endif /* _ASTERISK_TCPTLS_H */