Wed Jan 8 2020 09:49:51

Asterisk developer's documentation


tcptls.h
Go to the documentation of this file.
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 
71  /*! Verify certificate when acting as server */
73  /*! Don't verify certificate when connecting to a server */
75  /*! Don't compare "Common Name" against IP or hostname */
77  /*! Use SSLv2 for outgoing client connections */
79  /*! Use SSLv3 for outgoing client connections */
81  /*! Use TLSv1 for outgoing client connections */
83 };
84 
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  */
125  struct ast_sockaddr old_address; /*!< copy of the local or remote address depending on if its a client or server session */
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 */
131  /*! Server accept_fn thread ID used for external shutdown requests. */
132  pthread_t master;
133  void *(*accept_fn)(void *); /*!< the function in charge of doing the accept */
134  void (*periodic_fn)(void *);/*!< something we may want to run before after select on the accept socket */
135  void *(*worker_fn)(void *); /*!< the function in charge of doing the actual work */
136  const char *name;
137 };
138 
139 struct ast_tcptls_stream;
140 
141 /*!
142  * \brief Disable the TCP/TLS stream timeout timer.
143  *
144  * \param stream TCP/TLS stream control data.
145  *
146  * \return Nothing
147  */
149 
150 /*!
151  * \brief Set the TCP/TLS stream inactivity timeout timer.
152  *
153  * \param stream TCP/TLS stream control data.
154  * \param timeout Number of milliseconds to wait for data transfer with the peer.
155  *
156  * \details This is basically how much time we are willing to spend
157  * in an I/O call before we declare the peer unresponsive.
158  *
159  * \note Setting timeout to -1 disables the timeout.
160  * \note Setting this timeout replaces the I/O sequence timeout timer.
161  *
162  * \return Nothing
163  */
165 
166 /*!
167  * \brief Set the TCP/TLS stream I/O sequence timeout timer.
168  *
169  * \param stream TCP/TLS stream control data.
170  * \param start Time the I/O sequence timer starts.
171  * \param timeout Number of milliseconds from the start time before timeout.
172  *
173  * \details This is how much time are we willing to allow the peer
174  * to complete an operation that can take several I/O calls. The
175  * main use is as an authentication timer with us.
176  *
177  * \note Setting timeout to -1 disables the timeout.
178  * \note Setting this timeout replaces the inactivity timeout timer.
179  *
180  * \return Nothing
181  */
182 void ast_tcptls_stream_set_timeout_sequence(struct ast_tcptls_stream *stream, struct timeval start, int timeout);
183 
184 /*!
185  * \brief Set the TCP/TLS stream I/O if it can exclusively depend upon the set timeouts.
186  *
187  * \param stream TCP/TLS stream control data.
188  * \param exclusive_input TRUE if stream can exclusively wait for fd input.
189  * Otherwise, the stream will not wait for fd input. It will wait while
190  * trying to send data.
191  *
192  * \note The stream timeouts still need to be set.
193  *
194  * \return Nothing
195  */
197 
198 /*
199  * describes a server instance
200  */
202  FILE *f; /* fopen/funopen result */
203  int fd; /* the socket returned by accept() */
204  SSL *ssl; /* ssl state */
205 /* iint (*ssl_setup)(SSL *); */
206  int client;
209  /*! XXX Why do we still use this lock when this struct is allocated as an ao2 object which has its own lock? */
211  /* Sometimes, when an entity reads TCP data, multiple
212  * logical messages might be read at the same time. In such
213  * a circumstance, there needs to be a place to stash the
214  * extra data.
215  */
217  /*! ao2 FILE stream cookie object associated with f. */
219 };
220 
221 #if defined(HAVE_FUNOPEN)
222 #define HOOK_T int
223 #define LEN_T int
224 #else
225 #define HOOK_T ssize_t
226 #define LEN_T size_t
227 #endif
228 
229 /*!
230  * \brief attempts to connect and start tcptls session, on error the tcptls_session's
231  * ref count is decremented, fd and file are closed, and NULL is returned.
232  */
234 
235 /* \brief Creates a client connection's ast_tcptls_session_instance. */
237 
238 void *ast_tcptls_server_root(void *);
239 
240 /*!
241  * \brief Closes a tcptls session instance's file and/or file descriptor.
242  * The tcptls_session will be set to NULL and it's file descriptor will be set to -1
243  * by this function.
244  */
246 
247 /*!
248  * \brief This is a generic (re)start routine for a TCP server,
249  * which does the socket/bind/listen and starts a thread for handling
250  * accept().
251  * \version 1.6.1 changed desc parameter to be of ast_tcptls_session_args type
252  */
254 
255 /*!
256  * \brief Shutdown a running server if there is one
257  * \version 1.6.1 changed desc parameter to be of ast_tcptls_session_args type
258  */
260 
261 /*!
262  * \brief Set up an SSL server
263  *
264  * \param cfg Configuration for the SSL server
265  * \retval 1 Success
266  * \retval 0 Failure
267  */
268 int ast_ssl_setup(struct ast_tls_config *cfg);
269 
270 /*!
271  * \brief free resources used by an SSL server
272  *
273  * \note This only needs to be called if ast_ssl_setup() was
274  * directly called first.
275  * \param cfg Configuration for the SSL server
276  */
277 void ast_ssl_teardown(struct ast_tls_config *cfg);
278 
279 /*!
280  * \brief Used to parse conf files containing tls/ssl options.
281  */
282 int ast_tls_read_conf(struct ast_tls_config *tls_cfg, struct ast_tcptls_session_args *tls_desc, const char *varname, const char *value);
283 
284 HOOK_T ast_tcptls_server_read(struct ast_tcptls_session_instance *ser, void *buf, size_t count);
285 HOOK_T ast_tcptls_server_write(struct ast_tcptls_session_instance *ser, const void *buf, size_t count);
286 
287 #endif /* _ASTERISK_TCPTLS_H */
char * pvtfile
Definition: tcptls.h:88
ast_ssl_flags
Definition: tcptls.h:70
void ast_tcptls_server_start(struct ast_tcptls_session_args *desc)
This is a generic (re)start routine for a TCP server, which does the socket/bind/listen and starts a ...
Definition: tcptls.c:964
void ast_ssl_teardown(struct ast_tls_config *cfg)
free resources used by an SSL server
Definition: tcptls.c:855
int ast_ssl_setup(struct ast_tls_config *cfg)
Set up an SSL server.
Definition: tcptls.c:850
struct timeval start
Start time from when an I/O sequence must complete by struct ast_tcptls_stream.timeout.
Definition: tcptls.c:64
struct ast_str * overflow_buf
Definition: tcptls.h:216
struct ast_tcptls_session_args * parent
Definition: tcptls.h:208
arguments for the accepting thread
Definition: tcptls.h:123
#define MAXHOSTNAMELEN
Definition: network.h:69
int value
Definition: syslog.c:39
int timeout
Timeout in ms relative to struct ast_tcptls_stream.start to wait for an event on struct ast_tcptls_st...
Definition: tcptls.c:79
Socket address structure.
Definition: netsock2.h:63
Utility functions.
void * ast_tcptls_server_root(void *)
Definition: tcptls.c:693
struct ast_sockaddr remote_address
Definition: tcptls.h:126
void ast_tcptls_stream_set_exclusive_input(struct ast_tcptls_stream *stream, int exclusive_input)
Set the TCP/TLS stream I/O if it can exclusively depend upon the set timeouts.
Definition: tcptls.c:107
struct ast_tcptls_stream * stream_cookie
Definition: tcptls.h:218
Network socket handling.
static const char desc[]
Definition: cdr_radius.c:85
The descriptor of a dynamic string XXX storage will be optimized later if needed We use the ts field ...
Definition: strings.h:364
#define HOOK_T
Definition: tcptls.h:225
HOOK_T ast_tcptls_server_read(struct ast_tcptls_session_instance *ser, void *buf, size_t count)
Definition: tcptls.c:519
char * cafile
Definition: tcptls.h:90
void ast_tcptls_stream_set_timeout_inactivity(struct ast_tcptls_stream *stream, int timeout)
Set the TCP/TLS stream inactivity timeout timer.
Definition: tcptls.c:91
struct ast_sockaddr old_address
Definition: tcptls.h:125
Structure used to handle boolean flags.
Definition: utils.h:200
char * certfile
Definition: tcptls.h:87
int exclusive_input
Definition: tcptls.c:81
const char * name
Definition: tcptls.h:136
HOOK_T ast_tcptls_server_write(struct ast_tcptls_session_instance *ser, const void *buf, size_t count)
Definition: tcptls.c:530
void ast_tcptls_close_session_file(struct ast_tcptls_session_instance *tcptls_session)
Closes a tcptls session instance&#39;s file and/or file descriptor. The tcptls_session will be set to NUL...
Definition: tcptls.c:1033
struct ast_tcptls_session_instance * ast_tcptls_client_create(struct ast_tcptls_session_args *desc)
Definition: tcptls.c:902
int ast_tls_read_conf(struct ast_tls_config *tls_cfg, struct ast_tcptls_session_args *tls_desc, const char *varname, const char *value)
Used to parse conf files containing tls/ssl options.
Definition: tcptls.c:1072
struct ast_flags flags
Definition: tcptls.h:92
SSL_CTX * ssl_ctx
Definition: tcptls.h:93
void ast_tcptls_stream_set_timeout_sequence(struct ast_tcptls_stream *stream, struct timeval start, int timeout)
Set the TCP/TLS stream I/O sequence timeout timer.
Definition: tcptls.c:99
struct ast_tcptls_session_instance * ast_tcptls_client_start(struct ast_tcptls_session_instance *tcptls_session)
attempts to connect and start tcptls session, on error the tcptls_session&#39;s ref count is decremented...
Definition: tcptls.c:865
char * capath
Definition: tcptls.h:91
void ast_tcptls_server_stop(struct ast_tcptls_session_args *desc)
Shutdown a running server if there is one.
Definition: tcptls.c:1058
struct ast_tls_config * tls_cfg
Definition: tcptls.h:128
struct ast_sockaddr local_address
Definition: tcptls.h:124
void(* periodic_fn)(void *)
Definition: tcptls.h:134
void ast_tcptls_stream_set_timeout_disable(struct ast_tcptls_stream *stream)
Disable the TCP/TLS stream timeout timer.
Definition: tcptls.c:84
char * cipher
Definition: tcptls.h:89
Structure for mutex and tracking information.
Definition: lock.h:121
char hostname[MAXHOSTNAMELEN]
Definition: tcptls.h:127
struct ast_sockaddr remote_address
Definition: tcptls.h:207
int enabled
Definition: tcptls.h:86