Asterisk - The Open Source Telephony Project  GIT-master-a24979a
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
21  *
22  * \brief Generic support for tcp/tls servers in Asterisk.
23  *
24  * \note In order to have TLS/SSL support, we need the openssl libraries.
25  * Still we can decide whether or not to use them by commenting
26  * in or out the DO_SSL macro.
27  *
28  * TLS/SSL support is basically implemented by reading from a config file
29  * (currently manager.conf, http.conf and sip.conf) the names of the certificate
30  * files and cipher to use, and then run ssl_setup() to create an appropriate
31  * data structure named ssl_ctx.
32  *
33  * If we support multiple domains, presumably we need to read multiple
34  * certificates.
35  *
36  * When we are requested to open a TLS socket, we run make_file_from_fd()
37  * on the socket, to do the necessary setup. At the moment the context's name
38  * is hardwired in the function, but we can certainly make it into an extra
39  * parameter to the function.
40  *
41  * We declare most of ssl support variables unconditionally,
42  * because their number is small and this simplifies the code.
43  *
44  * \note The ssl-support variables (ssl_ctx, do_ssl, certfile, cipher)
45  * and their setup should be moved to a more central place, e.g. asterisk.conf
46  * and the source files that processes it. Similarly, ssl_setup() should
47  * be run earlier in the startup process so modules have it available.
48  *
49  * \ref AstTlsOverview
50  */
51 
52 #ifndef _ASTERISK_TCPTLS_H
53 #define _ASTERISK_TCPTLS_H
54 
55 #include <pthread.h> /* for pthread_t */
56 #include <sys/param.h> /* for MAXHOSTNAMELEN */
57 
58 #include "asterisk/iostream.h"
59 #include "asterisk/netsock2.h" /* for ast_sockaddr */
60 #include "asterisk/utils.h" /* for ast_flags */
61 
62 /*! SSL support */
63 #define AST_CERTFILE "asterisk.pem"
64 
66  /*! Verify certificate when acting as server */
68  /*! Don't verify certificate when connecting to a server */
70  /*! Don't compare "Common Name" against IP or hostname */
72  /*! Use SSLv2 for outgoing client connections */
74  /*! Use SSLv3 for outgoing client connections */
76  /*! Use TLSv1 for outgoing client connections */
78  /*! Use server cipher order instead of the client order */
80  /*! Disable TLSv1 support */
82  /*! Disable TLSv1.1 support */
84  /*! Disable TLSv1.2 support */
86 };
87 
89  int enabled;
90  char *certfile;
91  char *pvtfile;
92  char *cipher;
93  char *cafile;
94  char *capath;
95  struct ast_flags flags;
97  char certhash[41];
98  char pvthash[41];
99  char cahash[41];
100 };
101 
102 /*! \page AstTlsOverview TLS Implementation Overview
103  *
104  * The following code implements a generic mechanism for starting
105  * services on a TCP or TLS socket.
106  * The service is configured in the struct session_args, and
107  * then started by calling server_start(desc) on the descriptor.
108  * server_start() first verifies if an instance of the service is active,
109  * and in case shuts it down. Then, if the service must be started, creates
110  * a socket and a thread in charge of doing the accept().
111  *
112  * The body of the thread is desc->accept_fn(desc), which the user can define
113  * freely. We supply a sample implementation, server_root(), structured as an
114  * infinite loop. At the beginning of each iteration it runs periodic_fn()
115  * if defined (e.g. to perform some cleanup etc.) then issues a poll()
116  * or equivalent with a timeout of 'poll_timeout' milliseconds, and if the
117  * following accept() is successful it creates a thread in charge of
118  * running the session, whose body is desc->worker_fn(). The argument of
119  * worker_fn() is a struct ast_tcptls_session_instance, which contains the address
120  * of the other party, a pointer to desc, the file descriptors (fd) on which
121  * we can do a select/poll (but NOT I/O), and a FILE *on which we can do I/O.
122  * We have both because we want to support plain and SSL sockets, and
123  * going through a FILE * lets us provide the encryption/decryption
124  * on the stream without using an auxiliary thread.
125  */
126 
127 /*! \brief
128  * arguments for the accepting thread
129  */
132  struct ast_sockaddr old_address; /*!< copy of the local or remote address depending on if its a client or server session */
134  char hostname[MAXHOSTNAMELEN]; /*!< only necessary for SSL clients so we can compare to common name */
135  struct ast_tls_config *tls_cfg; /*!< points to the SSL configuration if any */
138  /*! Server accept_fn thread ID used for external shutdown requests. */
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  struct ast_tls_config *old_tls_cfg; /*!< copy of the SSL configuration to determine whether changes have been made */
145 };
146 
147 /*! \brief
148  * describes a server instance
149  */
151  int client;
154  /* Sometimes, when an entity reads TCP data, multiple
155  * logical messages might be read at the same time. In such
156  * a circumstance, there needs to be a place to stash the
157  * extra data.
158  */
160  /*! ao2 stream object associated with this session. */
162  /*! ao2 object private data of parent->worker_fn */
164 };
165 
166 /*!
167  * \brief Attempt to connect and start a tcptls session within the given timeout
168  *
169  * \note On error the tcptls_session's ref count is decremented, fd and file
170  * are closed, and NULL is returned.
171  *
172  * \param tcptls_session The session instance to connect and start
173  * \param timeout How long (in milliseconds) to attempt to connect (-1 equals infinite)
174  *
175  * \return The tcptls_session, or NULL on error
176  */
178  struct ast_tcptls_session_instance *tcptls_session, int timeout);
179 
180 /*!
181  * \brief Attempt to connect and start a tcptls session
182  *
183  * Blocks until a connection is established, or an error occurs.
184  *
185  * \note On error the tcptls_session's ref count is decremented, fd and file
186  * are closed, and NULL is returned.
187  *
188  * \param tcptls_session The session instance to connect and start
189  *
190  * \return The tcptls_session, or NULL on error
191  */
193 
194 /*! \brief Creates a client connection's ast_tcptls_session_instance. */
196 
197 void *ast_tcptls_server_root(void *);
198 
199 /*!
200  * \brief Closes a tcptls session instance's file and/or file descriptor.
201  * The tcptls_session will be set to NULL and it's file descriptor will be set to -1
202  * by this function.
203  */
205 
206 /*!
207  * \brief This is a generic (re)start routine for a TCP server,
208  * which does the socket/bind/listen and starts a thread for handling
209  * accept().
210  * \version 1.6.1 changed desc parameter to be of ast_tcptls_session_args type
211  */
213 
214 /*!
215  * \brief Shutdown a running server if there is one
216  * \version 1.6.1 changed desc parameter to be of ast_tcptls_session_args type
217  */
219 
220 /*!
221  * \brief Set up an SSL server
222  *
223  * \param cfg Configuration for the SSL server
224  * \retval 1 Success
225  * \retval 0 Failure
226  */
227 int ast_ssl_setup(struct ast_tls_config *cfg);
228 
229 /*!
230  * \brief free resources used by an SSL server
231  *
232  * \note This only needs to be called if ast_ssl_setup() was
233  * directly called first.
234  * \param cfg Configuration for the SSL server
235  */
236 void ast_ssl_teardown(struct ast_tls_config *cfg);
237 
238 /*!
239  * \brief Used to parse conf files containing tls/ssl options.
240  */
241 int ast_tls_read_conf(struct ast_tls_config *tls_cfg, struct ast_tcptls_session_args *tls_desc, const char *varname, const char *value);
242 
243 #endif /* _ASTERISK_TCPTLS_H */
static const char desc[]
Definition: cdr_radius.c:84
Generic abstraction for input/output streams.
struct ssl_ctx_st SSL_CTX
Definition: iostream.h:38
Network socket handling.
#define MAXHOSTNAMELEN
Definition: network.h:69
Structure used to handle boolean flags.
Definition: utils.h:199
Socket address structure.
Definition: netsock2.h:97
Support for dynamic strings.
Definition: strings.h:604
arguments for the accepting thread
Definition: tcptls.h:130
struct ast_tls_config * old_tls_cfg
Definition: tcptls.h:144
void(* periodic_fn)(void *)
Definition: tcptls.h:141
struct ast_sockaddr local_address
Definition: tcptls.h:131
const char * name
Definition: tcptls.h:143
struct ast_sockaddr remote_address
Definition: tcptls.h:133
struct ast_sockaddr old_address
Definition: tcptls.h:132
struct ast_tls_config * tls_cfg
Definition: tcptls.h:135
char hostname[MAXHOSTNAMELEN]
Definition: tcptls.h:134
describes a server instance
Definition: tcptls.h:150
struct ast_iostream * stream
Definition: tcptls.h:161
struct ast_sockaddr remote_address
Definition: tcptls.h:152
struct ast_tcptls_session_args * parent
Definition: tcptls.h:153
struct ast_str * overflow_buf
Definition: tcptls.h:159
int enabled
Definition: tcptls.h:89
char pvthash[41]
Definition: tcptls.h:98
char * certfile
Definition: tcptls.h:90
char * cipher
Definition: tcptls.h:92
SSL_CTX * ssl_ctx
Definition: tcptls.h:96
char cahash[41]
Definition: tcptls.h:99
char * pvtfile
Definition: tcptls.h:91
char * capath
Definition: tcptls.h:94
char * cafile
Definition: tcptls.h:93
char certhash[41]
Definition: tcptls.h:97
struct ast_flags flags
Definition: tcptls.h:95
int value
Definition: syslog.c:37
struct ast_tcptls_session_instance * ast_tcptls_client_start_timeout(struct ast_tcptls_session_instance *tcptls_session, int timeout)
Attempt to connect and start a tcptls session within the given timeout.
Definition: tcptls.c:645
void ast_tcptls_server_stop(struct ast_tcptls_session_args *desc)
Shutdown a running server if there is one.
Definition: tcptls.c:913
int ast_ssl_setup(struct ast_tls_config *cfg)
Set up an SSL server.
Definition: tcptls.c:570
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:749
void ast_ssl_teardown(struct ast_tls_config *cfg)
free resources used by an SSL server
Definition: tcptls.c:575
ast_ssl_flags
Definition: tcptls.h:65
@ AST_SSL_VERIFY_CLIENT
Definition: tcptls.h:67
@ AST_SSL_DONT_VERIFY_SERVER
Definition: tcptls.h:69
@ AST_SSL_SSLV3_CLIENT
Definition: tcptls.h:75
@ AST_SSL_DISABLE_TLSV11
Definition: tcptls.h:83
@ AST_SSL_IGNORE_COMMON_NAME
Definition: tcptls.h:71
@ AST_SSL_TLSV1_CLIENT
Definition: tcptls.h:77
@ AST_SSL_DISABLE_TLSV12
Definition: tcptls.h:85
@ AST_SSL_SERVER_CIPHER_ORDER
Definition: tcptls.h:79
@ AST_SSL_DISABLE_TLSV1
Definition: tcptls.h:81
@ AST_SSL_SSLV2_CLIENT
Definition: tcptls.h:73
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:939
struct ast_tcptls_session_instance * ast_tcptls_client_create(struct ast_tcptls_session_args *desc)
Creates a client connection's ast_tcptls_session_instance.
Definition: tcptls.c:678
void * ast_tcptls_server_root(void *)
Definition: tcptls.c:280
void ast_tcptls_close_session_file(struct ast_tcptls_session_instance *tcptls_session)
Closes a tcptls session instance's file and/or file descriptor. The tcptls_session will be set to NUL...
Definition: tcptls.c:903
struct ast_tcptls_session_instance * ast_tcptls_client_start(struct ast_tcptls_session_instance *tcptls_session)
Attempt to connect and start a tcptls session.
Definition: tcptls.c:673
Utility functions.