The FreeRADIUS server $Id: a4e7f8c94e8038b7627bcf52356b7ed15955c1d7 $
Loading...
Searching...
No Matches
rest.h
Go to the documentation of this file.
1#pragma once
2/*
3 * This program is free software; you can redistribute it and/or modify
4 * it under the terms of the GNU General Public License as published by
5 * the Free Software Foundation; either version 2 of the License, or
6 * (at your option) any later version.
7 *
8 * This program is distributed in the hope that it will be useful,
9 * but WITHOUT ANY WARRANTY; without even the implied warranty of
10 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
11 * GNU General Public License for more details.
12 *
13 * You should have received a copy of the GNU General Public License
14 * along with this program; if not, write to the Free Software
15 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA
16 */
17
18/**
19 * $Id: 21dd01abdf0cba39149d09b62ae33577fe2a9263 $
20 *
21 * @brief Function prototypes and datatypes for the REST (HTTP) transport.
22 * @file rest.h
23 *
24 * @copyright 2012-2016 Arran Cudbard-Bell (a.cudbardb@freeradius.org)
25 */
26RCSIDH(rest_h, "$Id: 21dd01abdf0cba39149d09b62ae33577fe2a9263 $")
27
28#include <freeradius-devel/curl/base.h>
29#include <freeradius-devel/util/slab.h>
30
31/*
32 * The common JSON library (also tells us if we have json-c)
33 */
34#include <freeradius-devel/json/base.h>
35
36#define REST_URI_MAX_LEN 2048
37#define REST_BODY_MAX_LEN 8192
38#define REST_BODY_ALLOC_CHUNK 1024
39#define REST_BODY_MAX_ATTRS 256
40
50
67
82
83/** Magic pointer value for determining if we should disable proxying
84 */
85extern char const *rest_no_proxy;
86
87/*
88 * Must be updated (in rest.c) if additional values are added to
89 * http_body_type_t
90 */
92
94
95extern const unsigned long http_curl_auth[REST_HTTP_AUTH_NUM_ENTRIES];
96
98extern size_t http_auth_table_len;
99
101extern size_t http_method_table_len;
102
104extern size_t http_body_type_table_len;
105
107extern size_t http_content_type_table_len;
108
109typedef struct {
110 char const *proxy; //!< Send request via this proxy.
111
112 char const *method_str; //!< The string version of the HTTP method.
113 http_method_t method; //!< What HTTP method should be used, GET, POST etc...
114
115 char const *body_str; //!< The string version of the encoding/content type.
116 http_body_type_t body; //!< What encoding type should be used.
117
118 bool auth_is_set; //!< Whether a value was provided for auth_str.
119
120 http_auth_type_t auth; //!< HTTP auth type.
121
122 bool require_auth; //!< Whether HTTP-Auth is required or not.
123
124 uint32_t chunk; //!< Max chunk-size (mainly for testing the encoders)
126
127typedef struct {
128 bool do_xlat; //!< Section default for the per-attribute "do_xlat"
129 //!< flag in JSON responses. Defaults to false, the
130 //!< API must opt in to expansion.
131 bool is_json; //!< Section default for the per-attribute "is_json"
132 //!< flag in JSON responses. If true, nested JSON data
133 //!< is copied to the attribute in string form.
134 //!< Defaults to false.
136
137typedef struct {
138 bool do_xlat; //!< If true, values in POST responses are xlat
139 //!< expanded before being assigned to attributes.
140 //!< Defaults to false.
142
143typedef struct {
144 char const *force_to_str; //!< Force decoding with this decoder.
145 http_body_type_t force_to; //!< Override the Content-Type header in the response
146 //!< to force decoding as a particular type.
147 bool accept_all; //!< Accept all content types.
148
149 size_t max_body_in; //!< Maximum size of incoming data.
150
151 rlm_rest_section_response_json_t json; //!< Configuration for the JSON decoder.
152 rlm_rest_section_response_post_t post; //!< Configuration for the POST decoder.
154
155/*
156 * Structure for section configuration
157 */
158typedef struct {
159 char const *name; //!< Section name.
160
161 fr_time_delta_t timeout; //!< Timeout timeval.
162 bool binary; //!< Do we expect binary data - so xlat will output octets.
163
164 rlm_rest_section_request_t request; //!< Request configuration.
165 rlm_rest_section_response_t response; //!< Response configuration.
166
169
170/*
171 * Structure for call_env found module calls
172 */
173typedef struct {
174 rlm_rest_section_t section; //!< Parsed section config
175 CONF_SECTION *cs; //!< Conf section found for this call
176 fr_rb_node_t node; //!< In tree of calls
178
179/*
180 * Structure for module configuration
181 */
182typedef struct {
183 char const *connect_proxy; //!< Send request via this proxy.
184
185 int http_negotiation; //!< What HTTP version to negotiate, and how to
186 ///< negotiate it. One or the CURL_HTTP_VERSION_ macros.
187
188 bool multiplex; //!< Whether to perform multiple requests using a single
189 ///< connection.
190
191 fr_curl_conn_config_t conn_config; //!< Configuration of slab allocated connection handles.
192
193 rlm_rest_section_t xlat; //!< Configuration specific to xlat.
194
195 fr_rb_tree_t sections; //!< Tree of sections with module call found by call_env parsing
196 bool sections_init; //!< Has the tree been initialised.
197
198#ifndef NDEBUG
199 bool fail_header_decode; //!< Force header decoding to fail for debugging purposes.
200 bool fail_body_decode; //!< Force body decoding to fail for debugging purposes.
201#endif
202} rlm_rest_t;
203
206
207/** Thread specific rlm_rest instance data
208 *
209 */
210typedef struct {
211 rlm_rest_t const *inst; //!< Instance of rlm_rest.
212 rest_slab_list_t *slab; //!< Slab list for connection handles.
213 fr_curl_handle_t *mhandle; //!< Thread specific multi handle. Serves as the dispatch
214 //!< and coralling structure for REST requests.
216
217/*
218 * States for stream based attribute encoders
219 */
226
227/*
228 * States for the response parser
229 */
236
237/*
238 * Outbound data context (passed to CURLOPT_READFUNCTION as CURLOPT_READDATA)
239 */
240typedef struct {
241 rlm_rest_t const *instance; //!< This instance of rlm_rest.
242 rlm_rest_section_t const *section; //!< Section configuration.
243
244 request_t *request; //!< Current request.
245 read_state_t state; //!< Encoder state
246
247 fr_dcursor_t cursor; //!< Cursor pointing to the start of the list to encode.
248
249 size_t chunk; //!< Chunk size
250
251 void *encoder; //!< Encoder specific data.
253
254/*
255 * Curl inbound data context (passed to CURLOPT_WRITEFUNCTION and
256 * CURLOPT_HEADERFUNCTION as CURLOPT_WRITEDATA and CURLOPT_HEADERDATA)
257 */
258typedef struct {
259 rlm_rest_t const *instance; //!< This instance of rlm_rest.
260 rlm_rest_section_t const *section; //!< Section configuration.
261
262 request_t *request; //!< Current request.
263 write_state_t state; //!< Decoder state.
264
265 char *buffer; //!< Raw incoming HTTP data.
266 size_t alloc; //!< Space allocated for buffer.
267 size_t used; //!< Space used in buffer.
268
269 int code; //!< HTTP Status Code.
270 http_body_type_t type; //!< HTTP Content Type.
271 http_body_type_t force_to; //!< Force decoding the body type as a particular encoding.
272
273 tmpl_t *header; //!< Where to create pairs representing HTTP response headers.
274 ///< If NULL no headers will be parsed other than content-type.
275
276 void *decoder; //!< Decoder specific data.
278
279/*
280 * Curl context data
281 */
282typedef struct {
283 struct curl_slist *headers; //!< Any HTTP headers which will be sent with the
284 //!< request.
285
286 char *body; //!< Pointer to the buffer which contains body data/
287 //!< Only used when not performing chunked encoding.
288
289 rlm_rest_request_t request; //!< Request context data.
290 rlm_rest_response_t response; //!< Response context data.
292
293/** Stores the state of a yielded xlat
294 *
295 */
296typedef struct {
297 rlm_rest_section_t section; //!< Our mutated section config.
298 fr_curl_io_request_t *handle; //!< curl easy handle servicing our request.
300
301typedef struct {
302 rlm_rest_section_conf_t *section; //!< Section config.
303 struct {
304 fr_value_box_t *uri; //!< URI to send HTTP request to.
305 fr_value_box_list_t *header; //!< Headers to place in the request
306 fr_value_box_t *data; //!< Custom data to send in requests.
307 fr_value_box_t *username; //!< Username to use for authentication
308 fr_value_box_t *password; //!< Password to use for authentication
310
311 struct {
312 tmpl_t *header; //!< Where to write response headers
313 } response;
315
316extern HIDDEN fr_dict_t const *dict_freeradius;
317
321
322/*
323 * Function prototype for rest_read_wrapper. Matches CURL's
324 * CURLOPT_READFUNCTION prototype.
325 */
326typedef size_t (*rest_read_t)(void *ptr, size_t size, size_t nmemb,
327 void *userdata);
328
329
330void *rest_mod_conn_create(TALLOC_CTX *ctx, void *instance, fr_time_delta_t timeout);
331
332/*
333 * Request processing API
334 */
335
337 char const *header, bool validate) CC_HINT(nonnull(1,2,3));
338
339int rest_request_config(module_ctx_t const *mctx, rlm_rest_section_t const *section,
342 char const *uri, char const *body_data) CC_HINT(nonnull (1,2,4,7));
343
346 fr_curl_io_request_t *randle);
347
350
351#define rest_get_handle_code(_handle)(((rlm_rest_curl_context_t*)((fr_curl_io_request_t*)(_handle))->uctx)->response.code)
352
353#define rest_get_handle_type(_handle)(((rlm_rest_curl_context_t*)((fr_curl_io_request_t*)(_handle))->uctx)->response.type)
354
355size_t rest_get_handle_data(char const **out, fr_curl_io_request_t *handle);
356
358
359/*
360 * Helper functions
361 */
362size_t rest_uri_escape(UNUSED request_t *request, char *out, size_t outlen, char const *raw, UNUSED void *arg);
364 fr_curl_io_request_t *randle, char const *uri);
365
366/*
367 * Async IO helpers
368 */
static uint8_t request[4]
#define RCSIDH(h, id)
Definition build.h:604
#define HIDDEN
Definition build.h:414
#define UNUSED
Definition build.h:415
A section grouping multiple CONF_PAIR.
Definition cf_priv.h:106
Uctx data for timer and I/O functions.
Definition base.h:89
Structure representing an individual request being passed to curl for processing.
Definition base.h:99
unsigned int uint32_t
long int ssize_t
unsigned char uint8_t
unsigned long int size_t
Temporary structure to hold arguments for module calls.
Definition module_ctx.h:41
The main red black tree structure.
Definition rb.h:71
rlm_rest_t const * instance
This instance of rlm_rest.
Definition rest.h:259
read_state_t state
Encoder state.
Definition rest.h:245
HIDDEN fr_dict_attr_t const * attr_rest_http_header
Definition rlm_rest.c:276
bool is_json
Section default for the per-attribute "is_json" flag in JSON responses.
Definition rest.h:131
http_auth_type_t auth
HTTP auth type.
Definition rest.h:120
size_t rest_get_handle_data(char const **out, fr_curl_io_request_t *handle)
Extracts pointer to buffer containing response data.
Definition rest.c:1634
struct curl_slist * headers
Any HTTP headers which will be sent with the request.
Definition rest.h:283
rlm_rest_section_response_json_t json
Configuration for the JSON decoder.
Definition rest.h:151
tmpl_t * header
Where to create pairs representing HTTP response headers.
Definition rest.h:273
http_method_t
Definition rest.h:41
@ REST_HTTP_METHOD_PATCH
Definition rest.h:46
@ REST_HTTP_METHOD_DELETE
Definition rest.h:47
@ REST_HTTP_METHOD_PUT
Definition rest.h:45
@ REST_HTTP_METHOD_POST
Definition rest.h:44
@ REST_HTTP_METHOD_UNKNOWN
Definition rest.h:42
@ REST_HTTP_METHOD_CUSTOM
Must always come last, should not be in method table.
Definition rest.h:48
@ REST_HTTP_METHOD_GET
Definition rest.h:43
request_t * request
Current request.
Definition rest.h:262
char * buffer
Raw incoming HTTP data.
Definition rest.h:265
fr_table_num_sorted_t const http_auth_table[]
Definition rest.c:162
int code
HTTP Status Code.
Definition rest.h:269
fr_curl_handle_t * mhandle
Thread specific multi handle.
Definition rest.h:213
rlm_rest_section_response_post_t post
Configuration for the POST decoder.
Definition rest.h:152
write_state_t state
Decoder state.
Definition rest.h:263
void rest_io_module_signal(module_ctx_t const *mctx, request_t *request, fr_signal_t action)
bool fail_header_decode
Force header decoding to fail for debugging purposes.
Definition rest.h:199
char const * proxy
Send request via this proxy.
Definition rest.h:110
size_t used
Space used in buffer.
Definition rest.h:267
int rest_response_decode(rlm_rest_t const *instance, UNUSED rlm_rest_section_t const *section, request_t *request, fr_curl_io_request_t *randle)
http_body_type_t type
HTTP Content Type.
Definition rest.h:270
char * body
Pointer to the buffer which contains body data/ Only used when not performing chunked encoding.
Definition rest.h:286
fr_curl_tls_t tls
Definition rest.h:167
fr_rb_tree_t sections
Tree of sections with module call found by call_env parsing.
Definition rest.h:195
bool fail_body_decode
Force body decoding to fail for debugging purposes.
Definition rest.h:200
http_body_type_t force_to
Override the Content-Type header in the response to force decoding as a particular type.
Definition rest.h:145
size_t max_body_in
Maximum size of incoming data.
Definition rest.h:149
fr_dcursor_t cursor
Cursor pointing to the start of the list to encode.
Definition rest.h:247
http_body_type_t force_to
Force decoding the body type as a particular encoding.
Definition rest.h:271
write_state_t
Definition rest.h:230
@ WRITE_STATE_INIT
Definition rest.h:231
@ WRITE_STATE_PARSE_HEADERS
Definition rest.h:232
@ WRITE_STATE_PARSE_CONTENT
Definition rest.h:233
@ WRITE_STATE_DISCARD
Definition rest.h:234
void * rest_mod_conn_create(TALLOC_CTX *ctx, void *instance, fr_time_delta_t timeout)
char const * method_str
The string version of the HTTP method.
Definition rest.h:112
http_body_type_t rest_response_body_type_get(fr_curl_io_request_t *randle)
Return the body type of a HTTP response.
Definition rest.c:1650
http_auth_type_t
Definition rest.h:68
@ REST_HTTP_AUTH_NTLM_WB
Definition rest.h:77
@ REST_HTTP_AUTH_NUM_ENTRIES
Definition rest.h:80
@ REST_HTTP_AUTH_BASIC
Definition rest.h:72
@ REST_HTTP_AUTH_NTLM
Definition rest.h:76
@ REST_HTTP_AUTH_DIGEST
Definition rest.h:73
@ REST_HTTP_AUTH_TLS_SRP
Definition rest.h:71
@ REST_HTTP_AUTH_UNKNOWN
Definition rest.h:69
@ REST_HTTP_AUTH_GSSNEGOTIATE
Definition rest.h:75
@ REST_HTTP_AUTH_ANY
Definition rest.h:78
@ REST_HTTP_AUTH_NONE
Definition rest.h:70
@ REST_HTTP_AUTH_DIGEST_IE
Definition rest.h:74
@ REST_HTTP_AUTH_ANY_SAFE
Definition rest.h:79
void rest_io_xlat_signal(xlat_ctx_t const *xctx, request_t *request, fr_signal_t action)
Handle asynchronous cancellation of a request.
Definition io.c:56
rlm_rest_section_t const * section
Section configuration.
Definition rest.h:260
read_state_t
Definition rest.h:220
@ READ_STATE_ATTR_CONT
Definition rest.h:223
@ READ_STATE_ATTR_BEGIN
Definition rest.h:222
@ READ_STATE_END
Definition rest.h:224
@ READ_STATE_INIT
Definition rest.h:221
fr_table_num_sorted_t const http_body_type_table[]
Conversion table for type config values.
Definition rest.c:146
fr_curl_conn_config_t conn_config
Configuration of slab allocated connection handles.
Definition rest.h:191
int http_negotiation
What HTTP version to negotiate, and how to.
Definition rest.h:185
HIDDEN fr_dict_t const * dict_freeradius
Definition base.c:75
char const * body_str
The string version of the encoding/content type.
Definition rest.h:115
HIDDEN fr_dict_attr_t const * attr_rest_http_body
Definition rlm_rest.c:275
rlm_rest_section_t section
Parsed section config.
Definition rest.h:174
fr_rb_node_t node
In tree of calls.
Definition rest.h:176
fr_table_num_sorted_t const http_method_table[]
Conversion table for method config values.
Definition rest.c:127
ssize_t rest_uri_host_unescape(char **out, UNUSED rlm_rest_t const *mod_inst, request_t *request, fr_curl_io_request_t *randle, char const *uri)
Unescapes the host portion of a URI string.
Definition rest.c:2190
char const * force_to_str
Force decoding with this decoder.
Definition rest.h:144
rlm_rest_section_conf_t * section
Section config.
Definition rest.h:302
rlm_rest_section_request_t request
Request configuration.
Definition rest.h:164
bool binary
Do we expect binary data - so xlat will output octets.
Definition rest.h:162
rlm_rest_response_t response
Response context data.
Definition rest.h:290
size_t(* rest_read_t)(void *ptr, size_t size, size_t nmemb, void *userdata)
Definition rest.h:326
void * decoder
Decoder specific data.
Definition rest.h:276
bool do_xlat
If true, values in POST responses are xlat expanded before being assigned to attributes.
Definition rest.h:138
bool auth_is_set
Whether a value was provided for auth_str.
Definition rest.h:118
int rest_request_config_add_header(request_t *request, fr_curl_io_request_t *randle, char const *header, bool validate))
Adds an additional header to a handle to use in the next reques.
Definition rest.c:1731
rlm_rest_section_t const * section
Section configuration.
Definition rest.h:242
int rest_request_config(module_ctx_t const *mctx, rlm_rest_section_t const *section, request_t *request, fr_curl_io_request_t *randle, http_method_t method, http_body_type_t type, char const *uri, char const *body_data))
Configures request curlopts.
Definition rest.c:1811
void * encoder
Encoder specific data.
Definition rest.h:251
rlm_rest_section_t xlat
Configuration specific to xlat.
Definition rest.h:193
HIDDEN fr_dict_attr_t const * attr_rest_http_status_code
Definition rlm_rest.c:277
void rest_response_debug(request_t *request, fr_curl_io_request_t *handle)
Print out the response text.
Definition rest.c:1577
bool accept_all
Accept all content types.
Definition rest.h:147
rlm_rest_request_t request
Request context data.
Definition rest.h:289
http_method_t method
What HTTP method should be used, GET, POST etc...
Definition rest.h:113
fr_table_num_sorted_t const http_content_type_table[]
Conversion table for "Content-Type" header values.
Definition rest.c:190
const unsigned long http_curl_auth[REST_HTTP_AUTH_NUM_ENTRIES]
Definition rest.c:101
bool sections_init
Has the tree been initialised.
Definition rest.h:196
rlm_rest_section_response_t response
Response configuration.
Definition rest.h:165
rlm_rest_section_t section
Our mutated section config.
Definition rest.h:297
const http_body_type_t http_body_type_supported[REST_HTTP_BODY_NUM_ENTRIES]
Table of encoder/decoder support.
Definition rest.c:44
fr_time_delta_t timeout
Timeout timeval.
Definition rest.h:161
bool do_xlat
Section default for the per-attribute "do_xlat" flag in JSON responses.
Definition rest.h:128
size_t rest_uri_escape(UNUSED request_t *request, char *out, size_t outlen, char const *raw, UNUSED void *arg)
URL encodes a string.
Definition rest.c:2164
bool multiplex
Whether to perform multiple requests using a single connection.
Definition rest.h:188
rlm_rest_t const * inst
Instance of rlm_rest.
Definition rest.h:211
char const * name
Section name.
Definition rest.h:159
void rest_response_error(request_t *request, fr_curl_io_request_t *handle)
Print out the response text as error lines.
Definition rest.c:1552
size_t alloc
Space allocated for buffer.
Definition rest.h:266
rest_slab_list_t * slab
Slab list for connection handles.
Definition rest.h:212
size_t http_body_type_table_len
Definition rest.c:160
char const * connect_proxy
Send request via this proxy.
Definition rest.h:183
size_t http_auth_table_len
Definition rest.c:174
size_t http_content_type_table_len
Definition rest.c:203
request_t * request
Current request.
Definition rest.h:244
http_body_type_t body
What encoding type should be used.
Definition rest.h:116
const bool http_body_type_binary[REST_HTTP_BODY_NUM_ENTRIES]
Table of which known body types are expected to give binary data.
Definition rest.c:66
size_t http_method_table_len
Definition rest.c:135
http_body_type_t
Definition rest.h:51
@ REST_HTTP_BODY_HTML
Definition rest.h:62
@ REST_HTTP_BODY_PLAIN
Definition rest.h:63
@ REST_HTTP_BODY_JSON
Definition rest.h:59
@ REST_HTTP_BODY_INVALID
Definition rest.h:55
@ REST_HTTP_BODY_XML
Definition rest.h:60
@ REST_HTTP_BODY_UNSUPPORTED
Definition rest.h:53
@ REST_HTTP_BODY_YAML
Definition rest.h:61
@ REST_HTTP_BODY_POST
Definition rest.h:58
@ REST_HTTP_BODY_CUSTOM
Definition rest.h:57
@ REST_HTTP_BODY_NUM_ENTRIES
Definition rest.h:65
@ REST_HTTP_BODY_CRL
Definition rest.h:64
@ REST_HTTP_BODY_UNKNOWN
Definition rest.h:52
@ REST_HTTP_BODY_NONE
Definition rest.h:56
@ REST_HTTP_BODY_UNAVAILABLE
Definition rest.h:54
fr_curl_io_request_t * handle
curl easy handle servicing our request.
Definition rest.h:298
rlm_rest_t const * instance
This instance of rlm_rest.
Definition rest.h:241
CONF_SECTION * cs
Conf section found for this call.
Definition rest.h:175
char const * rest_no_proxy
Magic pointer value for determining if we should disable proxying.
Definition rlm_rest.c:78
uint32_t chunk
Max chunk-size (mainly for testing the encoders)
Definition rest.h:124
bool require_auth
Whether HTTP-Auth is required or not.
Definition rest.h:122
size_t chunk
Chunk size.
Definition rest.h:249
Definition rest.h:137
Thread specific rlm_rest instance data.
Definition rest.h:210
Stores the state of a yielded xlat.
Definition rest.h:296
fr_signal_t
Signals that can be generated/processed by request signal handlers.
Definition signal.h:38
#define FR_SLAB_FUNCS(_name, _type)
Define type specific wrapper functions for slabs and slab elements.
Definition slab.h:124
#define FR_SLAB_TYPES(_name, _type)
Define type specific wrapper structs for slabs and slab elements.
Definition slab.h:75
fr_aka_sim_id_type_t type
An element in a lexicographically sorted array of name to num mappings.
Definition table.h:49
A time delta, a difference in time measured in nanoseconds.
Definition time.h:80
static fr_slen_t data
Definition value.h:1366
static fr_sbuff_err_t char ** out
Definition value.h:1061
int nonnull(2, 5))
An xlat calling ctx.
Definition xlat_ctx.h:49