Asterisk - The Open Source Telephony Project  18.5.0
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 <[email protected]>
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 http.h
28  * \brief Support for Private Asterisk HTTP Servers.
29  * \note Note: The Asterisk HTTP servers are extremely simple and minimal and
30  * only support the "GET" method.
31  *
32  * \author Mark Spencer <[email protected]>
33  *
34  * \note In order to have TLS/SSL support, we need the openssl libraries.
35  * Still we can decide whether or not to use them by commenting
36  * in or out the DO_SSL macro.
37  * TLS/SSL support is basically implemented by reading from a config file
38  * (currently http.conf) the names of the certificate and cipher to use,
39  * and then run ssl_setup() to create an appropriate SSL_CTX (ssl_ctx)
40  * If we support multiple domains, presumably we need to read multiple
41  * certificates.
42  * When we are requested to open a TLS socket, we run make_file_from_fd()
43  * on the socket, to do the necessary setup. At the moment the context's name
44  * is hardwired in the function, but we can certainly make it into an extra
45  * parameter to the function.
46  * We declare most of ssl support variables unconditionally,
47  * because their number is small and this simplifies the code.
48  *
49  * \note: the ssl-support variables (ssl_ctx, do_ssl, certfile, cipher)
50  * and their setup should be moved to a more central place, e.g. asterisk.conf
51  * and the source files that processes it. Similarly, ssl_setup() should
52  * be run earlier in the startup process so modules have it available.
53  */
54 
55 /*! \brief HTTP Request methods known by Asterisk */
57  AST_HTTP_UNKNOWN = -1, /*!< Unknown response */
64  AST_HTTP_MAX_METHOD, /*!< Last entry in ast_http_method enum */
65 };
66 
67 struct ast_http_uri;
68 
69 /*!
70  * \brief HTTP Callbacks
71  *
72  * \param ser TCP/TLS session object
73  * \param urih Registered URI handler struct for the URI.
74  * \param uri Remaining request URI path (also with the get_params removed).
75  * \param method enum ast_http_method GET, POST, etc.
76  * \param get_params URI argument list passed with the HTTP request.
77  * \param headers HTTP request header-name/value pair list
78  *
79  * \note Should use the ast_http_send() function for sending content
80  * allocated with ast_str and/or content from an opened file descriptor.
81  *
82  * Status and status text should be sent as arguments to the ast_http_send()
83  * function to reflect the status of the request (200 or 304, for example).
84  * Content length is calculated by ast_http_send() automatically.
85  *
86  * Static content may be indicated to the ast_http_send() function,
87  * to indicate that it may be cached.
88  *
89  * For a need authentication response, the ast_http_auth() function
90  * should be used.
91  *
92  * For an error response, the ast_http_error() function should be used.
93  *
94  * \retval 0 Continue and process the next HTTP request.
95  * \retval -1 Fatal HTTP connection error. Force the HTTP connection closed.
96  */
97 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);
98 
99 /*! \brief Definition of a URI handler */
100 struct ast_http_uri {
102  const char *description;
103  const char *uri;
104  const char *prefix;
106  unsigned int has_subtree:1;
107  /*! Structure is malloc'd */
108  unsigned int mallocd:1;
109  /*! Data structure is malloc'd */
110  unsigned int dmallocd:1;
111  /*! Don't automatically decode URI before passing it to the callback */
112  unsigned int no_decode_uri:1;
113  /*! Data to bind to the uri if needed */
114  void *data;
115  /*! Key to be used for unlinking if multiple URIs registered */
116  const char *key;
117 };
118 
119 /*! \brief Get cookie from Request headers */
120 struct ast_variable *ast_http_get_cookies(struct ast_variable *headers);
121 
122 /*! \brief HTTP authentication information. */
124  /*! Provided userid. */
125  char *userid;
126  /*! For Basic auth, the provided password. */
127  char *password;
128 };
129 
130 /*!
131  * \brief Get HTTP authentication information from headers.
132  *
133  * The returned object is AO2 managed, so clean up with ao2_cleanup().
134  *
135  * \param headers HTTP request headers.
136  * \return HTTP auth structure.
137  * \return \c NULL if no supported HTTP auth headers present.
138  * \since 12
139  */
140 struct ast_http_auth *ast_http_get_auth(struct ast_variable *headers);
141 
142 /*! \brief Register a URI handler */
143 int ast_http_uri_link(struct ast_http_uri *urihandler);
144 
145 /*! \brief Unregister a URI handler */
146 void ast_http_uri_unlink(struct ast_http_uri *urihandler);
147 
148 /*! \brief Unregister all handlers with matching key */
149 void ast_http_uri_unlink_all_with_key(const char *key);
150 
151 /*!
152  * \brief Return http method name string
153  * \since 1.8
154  */
156 
157 /*!
158  * \brief Return mime type based on extension
159  * \param ftype filename extension
160  * \return String containing associated MIME type
161  * \since 1.8
162  */
163 const char *ast_http_ftype2mtype(const char *ftype) attribute_pure;
164 
165 /*!
166  * \brief Return manager id, if exist, from request headers
167  * \param headers List of HTTP headers
168  * \return 32-bit associated manager session identifier
169  * \since 1.8
170  */
171 uint32_t ast_http_manid_from_vars(struct ast_variable *headers) attribute_pure;
172 
173 /*!
174  * \brief Generic function for sending HTTP/1.1 response.
175  * \param ser TCP/TLS session object
176  * \param method GET/POST/HEAD
177  * \param status_code HTTP response code (200/401/403/404/500)
178  * \param status_title English equivalent to the status_code parameter
179  * \param http_header An ast_str object containing all headers
180  * \param out An ast_str object containing the body of the response
181  * \param fd If out is NULL, a file descriptor where the body of the response is held (otherwise -1)
182  * \param static_content Zero if the content is dynamically generated and should not be cached; nonzero otherwise
183  *
184  * \note Function determines the HTTP response header from status_code,
185  * status_header, and http_header.
186  *
187  * Extra HTTP headers MUST be present only in the http_header argument. The
188  * argument "out" should contain only content of the response (no headers!).
189  *
190  * HTTP content can be constructed from the argument "out", if it is not NULL;
191  * otherwise, the function will read content from FD.
192  *
193  * This function calculates the content-length http header itself.
194  *
195  * Both the http_header and out arguments will be freed by this function;
196  * however, if FD is open, it will remain open.
197  *
198  * \since 1.8
199  */
201  int status_code, const char *status_title, struct ast_str *http_header,
202  struct ast_str *out, int fd, unsigned int static_content);
203 
204 /*!
205  * \brief Creates and sends a formatted http response message.
206  * \param ser TCP/TLS session object
207  * \param status_code HTTP response code (200/401/403/404/500)
208  * \param status_title English equivalent to the status_code parameter
209  * \param http_header_data The formatted text to use in the http header
210  * \param text Additional informational text to use in the
211  * response
212  *
213  * \note Function constructs response headers from the status_code, status_title and
214  * http_header_data parameters.
215  *
216  * The response body is created as HTML content, from the status_code,
217  * status_title, and the text parameters.
218  *
219  * The http_header_data parameter will be freed as a result of calling function.
220  *
221  * \since 13.2.0
222  */
223 void ast_http_create_response(struct ast_tcptls_session_instance *ser, int status_code,
224  const char *status_title, struct ast_str *http_header_data, const char *text);
225 
226 /*! \brief Send http "401 Unauthorized" response and close socket */
227 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);
228 
229 /*! \brief Send HTTP error message and close socket */
230 void ast_http_error(struct ast_tcptls_session_instance *ser, int status, const char *title, const char *text);
231 
232 /*!
233  * \brief Return the current prefix
234  * \param[out] buf destination buffer for previous
235  * \param[in] len length of prefix to copy
236  * \since 1.6.1
237  */
238 void ast_http_prefix(char *buf, int len);
239 
240 /*!
241  * \brief Request the HTTP connection be closed after this HTTP request.
242  * \since 12.4.0
243  *
244  * \param ser HTTP TCP/TLS session object.
245  *
246  * \note Call before ast_http_error() to make the connection close.
247  *
248  * \return Nothing
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  * \return Nothing
260  */
261 void ast_http_body_read_status(struct ast_tcptls_session_instance *ser, int read_success);
262 
263 /*!
264  * \brief Read and discard any unread HTTP request body.
265  * \since 12.4.0
266  *
267  * \param ser HTTP TCP/TLS session object.
268  *
269  * \retval 0 on success.
270  * \retval -1 on error.
271  */
273 
274 /*!
275  * \brief Get post variables from client Request Entity-Body, if content type is application/x-www-form-urlencoded.
276  * \param ser TCP/TLS session object
277  * \param headers List of HTTP headers
278  * \return List of variables within the POST body
279  * \note Since returned list is malloc'd, list should be free'd by the calling function
280  * \since 1.8
281  */
283 
284 struct ast_json;
285 
286 /*!
287  * \brief Get JSON from client Request Entity-Body, if content type is
288  * application/json.
289  * \param ser TCP/TLS session object
290  * \param headers List of HTTP headers
291  * \return Parsed JSON content body
292  * \return \c NULL on error, if no content, or if different content type.
293  * \since 12
294  */
296  struct ast_tcptls_session_instance *ser, struct ast_variable *headers);
297 
298 /*!\brief Parse the http response status line.
299  *
300  * \param buf the http response line information
301  * \param version the expected http version (e.g. HTTP/1.1)
302  * \param code the expected status code
303  * \return -1 if version didn't match or status code conversion fails.
304  * \return status code (>0)
305  * \since 13
306  */
307 int ast_http_response_status_line(const char *buf, const char *version, int code);
308 
309 /*!\brief Parse a header into the given name/value strings.
310  *
311  * \note This modifies the given buffer and the out parameters point (not
312  * allocated) to the start of the header name and header value,
313  * respectively.
314  *
315  * \param buf a string containing the name/value to point to
316  * \param name out parameter pointing to the header name
317  * \param value out parameter pointing to header value
318  * \return -1 if buf is empty
319  * \return 0 if buf could be separated into name and value
320  * \return 1 if name or value portion don't exist
321  * \since 13
322  */
323 int ast_http_header_parse(char *buf, char **name, char **value);
324 
325 /*!\brief Check if the header and value match (case insensitive) their
326  * associated expected values.
327  *
328  * \param name header name to check
329  * \param expected_name the expected name of the header
330  * \param value header value to check
331  * \param expected_value the expected value of the header
332  * \return 0 if the name and expected name do not match
333  * \return -1 if the value and expected value do not match
334  * \return 1 if the both the name and value match their expected value
335  * \since 13
336  */
337 int ast_http_header_match(const char *name, const char *expected_name,
338  const char *value, const char *expected_value);
339 
340 /*!\brief Check if the header name matches the expected header name. If so,
341  * then check to see if the value can be located in the expected value.
342  *
343  * \note Both header and value checks are case insensitive.
344  *
345  * \param name header name to check
346  * \param expected_name the expected name of the header
347  * \param value header value to check if in expected value
348  * \param expected_value the expected value(s)
349  * \return 0 if the name and expected name do not match
350  * \return -1 if the value and is not in the expected value
351  * \return 1 if the name matches expected name and value is in expected value
352  * \since 13
353  */
354 int ast_http_header_match_in(const char *name, const char *expected_name,
355  const char *value, const char *expected_value);
356 
357 #endif /* _ASTERISK_SRV_H */
struct ast_http_uri::@265 entry
#define attribute_pure
Definition: compiler.h:35
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:648
ast_http_callback callback
Definition: http.h:105
char * userid
Definition: http.h:125
int ast_http_body_discard(struct ast_tcptls_session_instance *ser)
Read and discard any unread HTTP request body.
Definition: http.c:1120
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:622
char buf[BUFSIZE]
Definition: eagi_proxy.c:66
int ast_http_uri_link(struct ast_http_uri *urihandler)
Register a URI handler.
Definition: http.c:673
const char * ast_http_ftype2mtype(const char *ftype) attribute_pure
Return mime type based on extension.
Definition: http.c:203
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:97
Structure for variables, used for configurations and for channel variables.
void ast_http_uri_unlink(struct ast_http_uri *urihandler)
Unregister a URI handler.
Definition: http.c:705
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:1314
const char * key
Definition: http.h:116
char * text
Definition: app_queue.c:1508
uint32_t ast_http_manid_from_vars(struct ast_variable *headers) attribute_pure
Return manager id, if exist, from request headers.
Definition: http.c:217
unsigned int has_subtree
Definition: http.h:106
int value
Definition: syslog.c:37
Generic support for tcp/tls servers in Asterisk.
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:456
unsigned int mallocd
Definition: http.h:108
Configuration File Parser.
int ast_http_header_parse(char *buf, char **name, char **value)
Parse a header into the given name/value strings.
Definition: http.c:1688
const char * method
Definition: res_pjsip.c:4335
A set of macros to manage forward-linked lists.
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:1726
describes a server instance
Definition: tcptls.h:149
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:1710
The descriptor of a dynamic string XXX storage will be optimized later if needed We use the ts field ...
Definition: strings.h:584
static int len(struct ast_channel *chan, const char *cmd, char *data, char *buf, size_t buflen)
const char * description
Definition: http.h:102
void ast_http_body_read_status(struct ast_tcptls_session_instance *ser, int read_success)
Update the body read success status.
Definition: http.c:899
char * password
Definition: http.h:127
#define AST_LIST_ENTRY(type)
Declare a forward link structure inside a list entry.
Definition: linkedlists.h:409
static char version[AST_MAX_EXTENSION]
Definition: chan_ooh323.c:391
static const char name[]
Definition: cdr_mysql.c:74
const char * ast_get_http_method(enum ast_http_method method) attribute_pure
Return http method name string.
Definition: http.c:190
const char * prefix
Definition: http.h:104
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:567
FILE * out
Definition: utils/frame.c:33
HTTP authentication information.
Definition: http.h:123
Definition of a URI handler.
Definition: http.h:100
void ast_http_prefix(char *buf, int len)
Return the current prefix.
Definition: http.c:233
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:1353
void ast_http_uri_unlink_all_with_key(const char *key)
Unregister all handlers with matching key.
Definition: http.c:712
struct ast_http_auth * ast_http_get_auth(struct ast_variable *headers)
Get HTTP authentication information from headers.
Definition: http.c:1579
unsigned int dmallocd
Definition: http.h:110
Abstract JSON element (object, array, string, int, ...).
const char * uri
Definition: http.h:103
ast_http_method
HTTP Request methods known by Asterisk.
Definition: http.h:56
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:836
void * data
Definition: http.h:114
unsigned int no_decode_uri
Definition: http.h:112
int ast_http_response_status_line(const char *buf, const char *version, int code)
Parse the http response status line.
Definition: http.c:1636
jack_status_t status
Definition: app_jack.c:146
struct ast_variable * ast_http_get_cookies(struct ast_variable *headers)
Get cookie from Request headers.
Definition: http.c:1532