Asterisk - The Open Source Telephony Project  GIT-master-a24979a
http.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 #ifndef _ASTERISK_HTTP_H
20 #define _ASTERISK_HTTP_H
21 
22 #include "asterisk/config.h"
23 #include "asterisk/tcptls.h"
24 #include "asterisk/linkedlists.h"
25 
26 /*!
27  * \file
28  *
29  * \brief Support for Private Asterisk HTTP Servers.
30  *
31  * \note Note: The Asterisk HTTP servers are extremely simple and minimal and
32  * only support the "GET" method.
33  *
34  * \author Mark Spencer <markster@digium.com>
35  *
36  * \note In order to have TLS/SSL support, we need the openssl libraries.
37  * Still we can decide whether or not to use them by commenting
38  * in or out the DO_SSL macro.
39  * TLS/SSL support is basically implemented by reading from a config file
40  * (currently http.conf) the names of the certificate and cipher to use,
41  * and then run ssl_setup() to create an appropriate SSL_CTX (ssl_ctx)
42  * If we support multiple domains, presumably we need to read multiple
43  * certificates.
44  * When we are requested to open a TLS socket, we run make_file_from_fd()
45  * on the socket, to do the necessary setup. At the moment the context's name
46  * is hardwired in the function, but we can certainly make it into an extra
47  * parameter to the function.
48  * We declare most of ssl support variables unconditionally,
49  * because their number is small and this simplifies the code.
50  *
51  * \note: the ssl-support variables (ssl_ctx, do_ssl, certfile, cipher)
52  * and their setup should be moved to a more central place, e.g. asterisk.conf
53  * and the source files that processes it. Similarly, ssl_setup() should
54  * be run earlier in the startup process so modules have it available.
55  */
56 
57 /*! \brief HTTP Request methods known by Asterisk */
59  AST_HTTP_UNKNOWN = -1, /*!< Unknown response */
66  AST_HTTP_MAX_METHOD, /*!< Last entry in ast_http_method enum */
67 };
68 
69 struct ast_http_uri;
70 
71 /*!
72  * \brief HTTP Callbacks
73  *
74  * \param ser TCP/TLS session object
75  * \param urih Registered URI handler struct for the URI.
76  * \param uri Remaining request URI path (also with the get_params removed).
77  * \param method enum ast_http_method GET, POST, etc.
78  * \param get_params URI argument list passed with the HTTP request.
79  * \param headers HTTP request header-name/value pair list
80  *
81  * \note Should use the ast_http_send() function for sending content
82  * allocated with ast_str and/or content from an opened file descriptor.
83  *
84  * Status and status text should be sent as arguments to the ast_http_send()
85  * function to reflect the status of the request (200 or 304, for example).
86  * Content length is calculated by ast_http_send() automatically.
87  *
88  * Static content may be indicated to the ast_http_send() function,
89  * to indicate that it may be cached.
90  *
91  * For a need authentication response, the ast_http_auth() function
92  * should be used.
93  *
94  * For an error response, the ast_http_error() function should be used.
95  *
96  * \retval 0 Continue and process the next HTTP request.
97  * \retval -1 Fatal HTTP connection error. Force the HTTP connection closed.
98  */
99 typedef int (*ast_http_callback)(struct ast_tcptls_session_instance *ser, const struct ast_http_uri *urih, const char *uri, enum ast_http_method method, struct ast_variable *get_params, struct ast_variable *headers);
100 
101 /*! \brief Definition of a URI handler */
102 struct ast_http_uri {
104  const char *description;
105  const char *uri;
106  const char *prefix;
108  unsigned int has_subtree:1;
109  /*! Structure is malloc'd */
110  unsigned int mallocd:1;
111  /*! Data structure is malloc'd */
112  unsigned int dmallocd:1;
113  /*! Don't automatically decode URI before passing it to the callback */
114  unsigned int no_decode_uri:1;
115  /*! Data to bind to the uri if needed */
116  void *data;
117  /*! Key to be used for unlinking if multiple URIs registered */
118  const char *key;
119 };
120 
121 /*! \brief Get cookie from Request headers */
122 struct ast_variable *ast_http_get_cookies(struct ast_variable *headers);
123 
124 /*! \brief HTTP authentication information. */
126  /*! Provided userid. */
127  char *userid;
128  /*! For Basic auth, the provided password. */
129  char *password;
130 };
131 
132 /*!
133  * \brief Get HTTP authentication information from headers.
134  *
135  * The returned object is AO2 managed, so clean up with ao2_cleanup().
136  *
137  * \param headers HTTP request headers.
138  * \return HTTP auth structure.
139  * \retval NULL if no supported HTTP auth headers present.
140  * \since 12
141  */
142 struct ast_http_auth *ast_http_get_auth(struct ast_variable *headers);
143 
144 /*! \brief Register a URI handler */
145 int ast_http_uri_link(struct ast_http_uri *urihandler);
146 
147 /*! \brief Unregister a URI handler */
148 void ast_http_uri_unlink(struct ast_http_uri *urihandler);
149 
150 /*! \brief Unregister all handlers with matching key */
151 void ast_http_uri_unlink_all_with_key(const char *key);
152 
153 /*!
154  * \brief Return http method name string
155  * \since 1.8
156  */
158 
159 /*!
160  * \brief Return mime type based on extension
161  * \param ftype filename extension
162  * \return String containing associated MIME type
163  * \since 1.8
164  */
165 const char *ast_http_ftype2mtype(const char *ftype) attribute_pure;
166 
167 /*!
168  * \brief Return manager id, if exist, from request headers
169  * \param headers List of HTTP headers
170  * \return 32-bit associated manager session identifier
171  * \since 1.8
172  */
173 uint32_t ast_http_manid_from_vars(struct ast_variable *headers) attribute_pure;
174 
175 /*!
176  * \brief Generic function for sending HTTP/1.1 response.
177  * \param ser TCP/TLS session object
178  * \param method GET/POST/HEAD
179  * \param status_code HTTP response code (200/401/403/404/500)
180  * \param status_title English equivalent to the status_code parameter
181  * \param http_header An ast_str object containing all headers
182  * \param out An ast_str object containing the body of the response
183  * \param fd If out is NULL, a file descriptor where the body of the response is held (otherwise -1)
184  * \param static_content Zero if the content is dynamically generated and should not be cached; nonzero otherwise
185  *
186  * \note Function determines the HTTP response header from status_code,
187  * status_header, and http_header.
188  *
189  * Extra HTTP headers MUST be present only in the http_header argument. The
190  * argument "out" should contain only content of the response (no headers!).
191  *
192  * HTTP content can be constructed from the argument "out", if it is not NULL;
193  * otherwise, the function will read content from FD.
194  *
195  * This function calculates the content-length http header itself.
196  *
197  * Both the http_header and out arguments will be freed by this function;
198  * however, if FD is open, it will remain open.
199  *
200  * \since 1.8
201  */
203  int status_code, const char *status_title, struct ast_str *http_header,
204  struct ast_str *out, int fd, unsigned int static_content);
205 
206 /*!
207  * \brief Creates and sends a formatted http response message.
208  * \param ser TCP/TLS session object
209  * \param status_code HTTP response code (200/401/403/404/500)
210  * \param status_title English equivalent to the status_code parameter
211  * \param http_header_data The formatted text to use in the http header
212  * \param text Additional informational text to use in the
213  * response
214  *
215  * \note Function constructs response headers from the status_code, status_title and
216  * http_header_data parameters.
217  *
218  * The response body is created as HTML content, from the status_code,
219  * status_title, and the text parameters.
220  *
221  * The http_header_data parameter will be freed as a result of calling function.
222  *
223  * \since 13.2.0
224  */
225 void ast_http_create_response(struct ast_tcptls_session_instance *ser, int status_code,
226  const char *status_title, struct ast_str *http_header_data, const char *text);
227 
228 /*! \brief Send http "401 Unauthorized" response and close socket */
229 void ast_http_auth(struct ast_tcptls_session_instance *ser, const char *realm, const unsigned long nonce, const unsigned long opaque, int stale, const char *text);
230 
231 /*! \brief Send HTTP error message and close socket */
232 void ast_http_error(struct ast_tcptls_session_instance *ser, int status, const char *title, const char *text);
233 
234 /*!
235  * \brief Return the current prefix
236  * \param[out] buf destination buffer for previous
237  * \param[in] len length of prefix to copy
238  * \since 1.6.1
239  */
240 void ast_http_prefix(char *buf, int len);
241 
242 /*!
243  * \brief Request the HTTP connection be closed after this HTTP request.
244  * \since 12.4.0
245  *
246  * \param ser HTTP TCP/TLS session object.
247  *
248  * \note Call before ast_http_error() to make the connection close.
249  */
251 
252 /*!
253  * \brief Update the body read success status.
254  * \since 12.4.0
255  *
256  * \param ser HTTP TCP/TLS session object.
257  * \param read_success TRUE if body was read successfully.
258  */
259 void ast_http_body_read_status(struct ast_tcptls_session_instance *ser, int read_success);
260 
261 /*!
262  * \brief Read and discard any unread HTTP request body.
263  * \since 12.4.0
264  *
265  * \param ser HTTP TCP/TLS session object.
266  *
267  * \retval 0 on success.
268  * \retval -1 on error.
269  */
271 
272 /*!
273  * \brief Get post variables from client Request Entity-Body, if content type is application/x-www-form-urlencoded.
274  * \param ser TCP/TLS session object
275  * \param headers List of HTTP headers
276  * \return List of variables within the POST body
277  * \note Since returned list is malloc'd, list should be free'd by the calling function
278  * \since 1.8
279  */
281 
282 struct ast_json;
283 
284 /*!
285  * \brief Get JSON from client Request Entity-Body, if content type is
286  * application/json.
287  * \param ser TCP/TLS session object
288  * \param headers List of HTTP headers
289  * \return Parsed JSON content body
290  * \retval NULL on error, if no content, or if different content type.
291  * \since 12
292  */
294  struct ast_tcptls_session_instance *ser, struct ast_variable *headers);
295 
296 /*!\brief Parse the http response status line.
297  *
298  * \param buf the http response line information
299  * \param version the expected http version (e.g. HTTP/1.1)
300  * \param code the expected status code
301  * \retval -1 if version didn't match or status code conversion fails.
302  * \return status code (>0)
303  * \since 13
304  */
305 int ast_http_response_status_line(const char *buf, const char *version, int code);
306 
307 /*!\brief Parse a header into the given name/value strings.
308  *
309  * \note This modifies the given buffer and the out parameters point (not
310  * allocated) to the start of the header name and header value,
311  * respectively.
312  *
313  * \param buf a string containing the name/value to point to
314  * \param[out] name header name
315  * \param[out] value header value
316  * \retval -1 if buf is empty
317  * \retval 0 if buf could be separated into name and value
318  * \retval 1 if name or value portion don't exist
319  * \since 13
320  */
321 int ast_http_header_parse(char *buf, char **name, char **value);
322 
323 /*!\brief Check if the header and value match (case insensitive) their
324  * associated expected values.
325  *
326  * \param name header name to check
327  * \param expected_name the expected name of the header
328  * \param value header value to check
329  * \param expected_value the expected value of the header
330  * \retval 0 if the name and expected name do not match
331  * \retval -1 if the value and expected value do not match
332  * \retval 1 if the both the name and value match their expected value
333  * \since 13
334  */
335 int ast_http_header_match(const char *name, const char *expected_name,
336  const char *value, const char *expected_value);
337 
338 /*!\brief Check if the header name matches the expected header name. If so,
339  * then check to see if the value can be located in the expected value.
340  *
341  * \note Both header and value checks are case insensitive.
342  *
343  * \param name header name to check
344  * \param expected_name the expected name of the header
345  * \param value header value to check if in expected value
346  * \param expected_value the expected value(s)
347  * \retval 0 if the name and expected name do not match
348  * \retval -1 if the value and is not in the expected value
349  * \retval 1 if the name matches expected name and value is in expected value
350  * \since 13
351  */
352 int ast_http_header_match_in(const char *name, const char *expected_name,
353  const char *value, const char *expected_value);
354 
355 #ifdef TEST_FRAMEWORK
356 
357 /*!
358  * Currently multiple HTTP servers are only allowed when the TEST_FRAMEWORK
359  * is enabled, so putting this here:
360  *
361  * If a server is listening on 'any' (i.e. 0.0.0.0), and another server attempts
362  * to listen on 'localhost' on the same port (and vice versa) then you'll get an
363  * "Address already in use" error. For now use a different port, or match the
364  * addresses exactly.
365  */
366 
367 struct ast_http_server;
368 
369 /*!
370  * \brief Retrieve a HTTP server listening at the given host
371  *
372  * A given host can include the port, e.g. <host>[:<port>]. If no port is specified
373  * then the port defaults to '8088'. If a host parameter is NULL, or empty and a
374  * configured server is already listening then that server is returned. If no
375  * server is and enabled then the host defaults to 'localhost:8088'.
376  *
377  * \note When finished with a successfully returned server object
378  * ast_http_test_server_discard MUST be called on the object
379  * in order for proper 'cleanup' to occur.
380  *
381  * \param name Optional name for the server (default 'http test server')
382  * \param host Optional host, or address with port to bind to (default 'localhost:8088')
383  *
384  * \return a HTTP server object, or NULL on error
385  */
386 struct ast_http_server *ast_http_test_server_get(const char *name, const char *host);
387 
388 /*!
389  * \brief Discard, or drop a HTTP server
390  *
391  * This function MUST eventually be called for every successful call to
392  * ast_http_test_server_get.
393  *
394  * \note NULL tolerant
395  *
396  * \param server The HTTP server to discard
397  */
398 void ast_http_test_server_discard(struct ast_http_server *server);
399 
400 #endif
401 
402 #endif /* _ASTERISK_SRV_H */
jack_status_t status
Definition: app_jack.c:146
char * text
Definition: app_queue.c:1641
static char version[AST_MAX_EXTENSION]
Definition: chan_ooh323.c:391
#define attribute_pure
Definition: compiler.h:35
char buf[BUFSIZE]
Definition: eagi_proxy.c:66
static const char name[]
Definition: format_mp3.c:68
static int len(struct ast_channel *chan, const char *cmd, char *data, char *buf, size_t buflen)
void ast_http_prefix(char *buf, int len)
Return the current prefix.
Definition: http.c:236
void ast_http_send(struct ast_tcptls_session_instance *ser, enum ast_http_method method, int status_code, const char *status_title, struct ast_str *http_header, struct ast_str *out, int fd, unsigned int static_content)
Generic function for sending HTTP/1.1 response.
Definition: http.c:459
ast_http_method
HTTP Request methods known by Asterisk.
Definition: http.h:58
@ AST_HTTP_PUT
Definition: http.h:63
@ AST_HTTP_DELETE
Definition: http.h:64
@ AST_HTTP_POST
Definition: http.h:61
@ AST_HTTP_GET
Definition: http.h:60
@ AST_HTTP_MAX_METHOD
Definition: http.h:66
@ AST_HTTP_UNKNOWN
Definition: http.h:59
@ AST_HTTP_OPTIONS
Definition: http.h:65
@ AST_HTTP_HEAD
Definition: http.h:62
int ast_http_header_parse(char *buf, char **name, char **value)
Parse a header into the given name/value strings.
Definition: http.c:1691
int ast_http_header_match_in(const char *name, const char *expected_name, const char *value, const char *expected_value)
Check if the header name matches the expected header name. If so, then check to see if the value can ...
Definition: http.c:1729
struct ast_variable * ast_http_get_cookies(struct ast_variable *headers)
Get cookie from Request headers.
Definition: http.c:1535
void ast_http_uri_unlink(struct ast_http_uri *urihandler)
Unregister a URI handler.
Definition: http.c:708
int ast_http_body_discard(struct ast_tcptls_session_instance *ser)
Read and discard any unread HTTP request body.
Definition: http.c:1122
const char * ast_get_http_method(enum ast_http_method method) attribute_pure
Return http method name string.
Definition: http.c:193
struct ast_json * ast_http_get_json(struct ast_tcptls_session_instance *ser, struct ast_variable *headers)
Get JSON from client Request Entity-Body, if content type is application/json.
Definition: http.c:1317
int(* ast_http_callback)(struct ast_tcptls_session_instance *ser, const struct ast_http_uri *urih, const char *uri, enum ast_http_method method, struct ast_variable *get_params, struct ast_variable *headers)
HTTP Callbacks.
Definition: http.h:99
int ast_http_header_match(const char *name, const char *expected_name, const char *value, const char *expected_value)
Check if the header and value match (case insensitive) their associated expected values.
Definition: http.c:1713
struct ast_http_auth * ast_http_get_auth(struct ast_variable *headers)
Get HTTP authentication information from headers.
Definition: http.c:1582
uint32_t ast_http_manid_from_vars(struct ast_variable *headers) attribute_pure
Return manager id, if exist, from request headers.
Definition: http.c:220
int ast_http_response_status_line(const char *buf, const char *version, int code)
Parse the http response status line.
Definition: http.c:1639
void ast_http_auth(struct ast_tcptls_session_instance *ser, const char *realm, const unsigned long nonce, const unsigned long opaque, int stale, const char *text)
Send http "401 Unauthorized" response and close socket.
Definition: http.c:625
void ast_http_request_close_on_completion(struct ast_tcptls_session_instance *ser)
Request the HTTP connection be closed after this HTTP request.
Definition: http.c:840
void ast_http_error(struct ast_tcptls_session_instance *ser, int status, const char *title, const char *text)
Send HTTP error message and close socket.
Definition: http.c:651
struct ast_variable * ast_http_get_post_vars(struct ast_tcptls_session_instance *ser, struct ast_variable *headers)
Get post variables from client Request Entity-Body, if content type is application/x-www-form-urlenco...
Definition: http.c:1356
int ast_http_uri_link(struct ast_http_uri *urihandler)
Register a URI handler.
Definition: http.c:676
void ast_http_create_response(struct ast_tcptls_session_instance *ser, int status_code, const char *status_title, struct ast_str *http_header_data, const char *text)
Creates and sends a formatted http response message.
Definition: http.c:570
void ast_http_uri_unlink_all_with_key(const char *key)
Unregister all handlers with matching key.
Definition: http.c:715
void ast_http_body_read_status(struct ast_tcptls_session_instance *ser, int read_success)
Update the body read success status.
Definition: http.c:901
const char * ast_http_ftype2mtype(const char *ftype) attribute_pure
Return mime type based on extension.
Definition: http.c:206
Configuration File Parser.
A set of macros to manage forward-linked lists.
#define AST_LIST_ENTRY(type)
Declare a forward link structure inside a list entry.
Definition: linkedlists.h:410
const char * method
Definition: res_pjsip.c:1130
HTTP authentication information.
Definition: http.h:125
char * password
Definition: http.h:129
char * userid
Definition: http.h:127
Definition of a URI handler.
Definition: http.h:102
unsigned int has_subtree
Definition: http.h:108
unsigned int no_decode_uri
Definition: http.h:114
ast_http_callback callback
Definition: http.h:107
unsigned int dmallocd
Definition: http.h:112
const char * prefix
Definition: http.h:106
const char * description
Definition: http.h:104
const char * uri
Definition: http.h:105
void * data
Definition: http.h:116
struct ast_http_uri::@256 entry
const char * key
Definition: http.h:118
unsigned int mallocd
Definition: http.h:110
Abstract JSON element (object, array, string, int, ...).
Support for dynamic strings.
Definition: strings.h:604
describes a server instance
Definition: tcptls.h:150
Structure for variables, used for configurations and for channel variables.
int value
Definition: syslog.c:37
Generic support for tcp/tls servers in Asterisk.
FILE * out
Definition: utils/frame.c:33