The FreeRADIUS server $Id: 15bac2a4c627c01d1aa2047687b3418955ac7f00 $
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: ec880d6a039b96d63073db8b2d0eebb233a9df9f $
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: ec880d6a039b96d63073db8b2d0eebb233a9df9f $")
27
28#include <freeradius-devel/curl/base.h>
29#include <freeradius-devel/curl/config.h>
30#include <freeradius-devel/server/pairmove.h>
31#include <freeradius-devel/util/slab.h>
32
33/*
34 * The common JSON library (also tells us if we have json-c)
35 */
36#include <freeradius-devel/json/base.h>
37
38#define REST_URI_MAX_LEN 2048
39#define REST_BODY_MAX_LEN 8192
40#define REST_BODY_ALLOC_CHUNK 1024
41#define REST_BODY_MAX_ATTRS 256
42
52
69
84
85/** Magic pointer value for determining if we should disable proxying
86 */
87extern char const *rest_no_proxy;
88
89/*
90 * Must be updated (in rest.c) if additional values are added to
91 * http_body_type_t
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 char const *force_to_str; //!< Force decoding with this decoder.
129 http_body_type_t force_to; //!< Override the Content-Type header in the response
130 //!< to force decoding as a particular type.
131
132 size_t max_body_in; //!< Maximum size of incoming data.
134
135/*
136 * Structure for section configuration
137 */
138typedef struct {
139 char const *name; //!< Section name.
140
141 fr_time_delta_t timeout; //!< Timeout timeval.
142
143 rlm_rest_section_request_t request; //!< Request configuration.
144 rlm_rest_section_response_t response; //!< Response configuration.
145
148
149/*
150 * Structure for call_env found module calls
151 */
152typedef struct {
153 rlm_rest_section_t section; //!< Parsed section config
154 CONF_SECTION *cs; //!< Conf section found for this call
155 fr_rb_node_t node; //!< In tree of calls
157
158/*
159 * Structure for module configuration
160 */
161typedef struct {
162 char const *connect_proxy; //!< Send request via this proxy.
163
164 int http_negotiation; //!< What HTTP version to negotiate, and how to
165 ///< negotiate it. One or the CURL_HTTP_VERSION_ macros.
166
167 bool multiplex; //!< Whether to perform multiple requests using a single
168 ///< connection.
169
170 fr_curl_conn_config_t conn_config; //!< Configuration of slab allocated connection handles.
171
172 rlm_rest_section_t xlat; //!< Configuration specific to xlat.
173
174 fr_rb_tree_t sections; //!< Tree of sections with module call found by call_env parsing
175 bool sections_init; //!< Has the tree been initialised.
176
177#ifndef NDEBUG
178 bool fail_header_decode; //!< Force header decoding to fail for debugging purposes.
179 bool fail_body_decode; //!< Force body decoding to fail for debugging purposes.
180#endif
181} rlm_rest_t;
182
185
186/** Thread specific rlm_rest instance data
187 *
188 */
189typedef struct {
190 rlm_rest_t const *inst; //!< Instance of rlm_rest.
191 rest_slab_list_t *slab; //!< Slab list for connection handles.
192 fr_curl_handle_t *mhandle; //!< Thread specific multi handle. Serves as the dispatch
193 //!< and coralling structure for REST requests.
195
196/*
197 * States for stream based attribute encoders
198 */
205
206/*
207 * States for the response parser
208 */
215
216/*
217 * Outbound data context (passed to CURLOPT_READFUNCTION as CURLOPT_READDATA)
218 */
219typedef struct {
220 rlm_rest_t const *instance; //!< This instance of rlm_rest.
221 rlm_rest_section_t const *section; //!< Section configuration.
222
223 request_t *request; //!< Current request.
224 read_state_t state; //!< Encoder state
225
226 fr_dcursor_t cursor; //!< Cursor pointing to the start of the list to encode.
227
228 size_t chunk; //!< Chunk size
229
230 void *encoder; //!< Encoder specific data.
232
233/*
234 * Curl inbound data context (passed to CURLOPT_WRITEFUNCTION and
235 * CURLOPT_HEADERFUNCTION as CURLOPT_WRITEDATA and CURLOPT_HEADERDATA)
236 */
237typedef struct {
238 rlm_rest_t const *instance; //!< This instance of rlm_rest.
239 rlm_rest_section_t const *section; //!< Section configuration.
240
241 request_t *request; //!< Current request.
242 write_state_t state; //!< Decoder state.
243
244 char *buffer; //!< Raw incoming HTTP data.
245 size_t alloc; //!< Space allocated for buffer.
246 size_t used; //!< Space used in buffer.
247
248 int code; //!< HTTP Status Code.
249 http_body_type_t type; //!< HTTP Content Type.
250 http_body_type_t force_to; //!< Force decoding the body type as a particular encoding.
251
252 tmpl_t *header; //!< Where to create pairs representing HTTP response headers.
253 ///< If NULL no headers will be parsed other than content-type.
254
255 void *decoder; //!< Decoder specific data.
257
258/*
259 * Curl context data
260 */
261typedef struct {
262 struct curl_slist *headers; //!< Any HTTP headers which will be sent with the
263 //!< request.
264
265 char *body; //!< Pointer to the buffer which contains body data/
266 //!< Only used when not performing chunked encoding.
267
268 rlm_rest_request_t request; //!< Request context data.
269 rlm_rest_response_t response; //!< Response context data.
271
272/** Stores the state of a yielded xlat
273 *
274 */
275typedef struct {
276 rlm_rest_section_t section; //!< Our mutated section config.
277 fr_curl_io_request_t *handle; //!< curl easy handle servicing our request.
279
280typedef struct {
281 rlm_rest_section_conf_t *section; //!< Section config.
282 struct {
283 fr_value_box_t *uri; //!< URI to send HTTP request to.
284 fr_value_box_list_t *header; //!< Headers to place in the request
285 fr_value_box_t *data; //!< Custom data to send in requests.
286 fr_value_box_t *username; //!< Username to use for authentication
287 fr_value_box_t *password; //!< Password to use for authentication
288 } request;
289
290 struct {
291 tmpl_t *header; //!< Where to write response headers
292 } response;
294
295extern HIDDEN fr_dict_t const *dict_freeradius;
296
300
301/*
302 * Function prototype for rest_read_wrapper. Matches CURL's
303 * CURLOPT_READFUNCTION prototype.
304 */
305typedef size_t (*rest_read_t)(void *ptr, size_t size, size_t nmemb,
306 void *userdata);
307
308
309void *rest_mod_conn_create(TALLOC_CTX *ctx, void *instance, fr_time_delta_t timeout);
310
311/*
312 * Request processing API
313 */
314
316 char const *header, bool validate) CC_HINT(nonnull(1,2,3));
317
318int rest_request_config(module_ctx_t const *mctx, rlm_rest_section_t const *section,
319 request_t *request, fr_curl_io_request_t *randle, http_method_t method,
321 char const *uri, char const *body_data) CC_HINT(nonnull (1,2,4,7));
322
324 UNUSED rlm_rest_section_t const *section, request_t *request,
325 fr_curl_io_request_t *randle);
326
329
330#define rest_get_handle_code(_handle)(((rlm_rest_curl_context_t*)((fr_curl_io_request_t*)(_handle))->uctx)->response.code)
331
332#define rest_get_handle_type(_handle)(((rlm_rest_curl_context_t*)((fr_curl_io_request_t*)(_handle))->uctx)->response.type)
333
334size_t rest_get_handle_data(char const **out, fr_curl_io_request_t *handle);
335
336/*
337 * Helper functions
338 */
339size_t rest_uri_escape(UNUSED request_t *request, char *out, size_t outlen, char const *raw, UNUSED void *arg);
340ssize_t rest_uri_host_unescape(char **out, UNUSED rlm_rest_t const *mod_inst, request_t *request,
341 fr_curl_io_request_t *randle, char const *uri);
342
343/*
344 * Async IO helpers
345 */
346void rest_io_module_signal(module_ctx_t const *mctx, request_t *request, fr_signal_t action);
347void rest_io_xlat_signal(xlat_ctx_t const *xctx, request_t *request, fr_signal_t action);
#define RCSIDH(h, id)
Definition build.h:486
#define HIDDEN
Definition build.h:316
#define UNUSED
Definition build.h:317
A section grouping multiple CONF_PAIR.
Definition cf_priv.h:101
Uctx data for timer and I/O functions.
Definition base.h:91
Structure representing an individual request being passed to curl for processing.
Definition base.h:101
unsigned int uint32_t
long int ssize_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:73
rlm_rest_t const * instance
This instance of rlm_rest.
Definition rest.h:238
read_state_t state
Encoder state.
Definition rest.h:224
HIDDEN fr_dict_attr_t const * attr_rest_http_header
Definition rlm_rest.c:256
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:1623
struct curl_slist * headers
Any HTTP headers which will be sent with the request.
Definition rest.h:262
tmpl_t * header
Where to create pairs representing HTTP response headers.
Definition rest.h:252
request_t * request
Current request.
Definition rest.h:241
char * buffer
Raw incoming HTTP data.
Definition rest.h:244
fr_table_num_sorted_t const http_auth_table[]
Definition rest.c:163
int code
HTTP Status Code.
Definition rest.h:248
fr_curl_handle_t * mhandle
Thread specific multi handle.
Definition rest.h:192
write_state_t state
Decoder state.
Definition rest.h:242
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:178
char const * proxy
Send request via this proxy.
Definition rest.h:110
size_t used
Space used in buffer.
Definition rest.h:246
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:249
char * body
Pointer to the buffer which contains body data/ Only used when not performing chunked encoding.
Definition rest.h:265
fr_curl_tls_t tls
Definition rest.h:146
fr_rb_tree_t sections
Tree of sections with module call found by call_env parsing.
Definition rest.h:174
bool fail_body_decode
Force body decoding to fail for debugging purposes.
Definition rest.h:179
http_body_type_t force_to
Override the Content-Type header in the response to force decoding as a particular type.
Definition rest.h:129
http_method_t
Definition rest.h:43
@ REST_HTTP_METHOD_PATCH
Definition rest.h:48
@ REST_HTTP_METHOD_DELETE
Definition rest.h:49
@ REST_HTTP_METHOD_PUT
Definition rest.h:47
@ REST_HTTP_METHOD_POST
Definition rest.h:46
@ REST_HTTP_METHOD_UNKNOWN
Definition rest.h:44
@ REST_HTTP_METHOD_CUSTOM
Must always come last, should not be in method table.
Definition rest.h:50
@ REST_HTTP_METHOD_GET
Definition rest.h:45
size_t max_body_in
Maximum size of incoming data.
Definition rest.h:132
fr_dcursor_t cursor
Cursor pointing to the start of the list to encode.
Definition rest.h:226
http_body_type_t force_to
Force decoding the body type as a particular encoding.
Definition rest.h:250
http_body_type_t
Definition rest.h:53
@ REST_HTTP_BODY_HTML
Definition rest.h:64
@ REST_HTTP_BODY_PLAIN
Definition rest.h:65
@ REST_HTTP_BODY_JSON
Definition rest.h:61
@ REST_HTTP_BODY_INVALID
Definition rest.h:57
@ REST_HTTP_BODY_XML
Definition rest.h:62
@ REST_HTTP_BODY_UNSUPPORTED
Definition rest.h:55
@ REST_HTTP_BODY_YAML
Definition rest.h:63
@ REST_HTTP_BODY_POST
Definition rest.h:60
@ REST_HTTP_BODY_CUSTOM
Definition rest.h:59
@ REST_HTTP_BODY_NUM_ENTRIES
Definition rest.h:67
@ REST_HTTP_BODY_CRL
Definition rest.h:66
@ REST_HTTP_BODY_UNKNOWN
Definition rest.h:54
@ REST_HTTP_BODY_NONE
Definition rest.h:58
@ REST_HTTP_BODY_UNAVAILABLE
Definition rest.h:56
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
read_state_t
Definition rest.h:199
@ READ_STATE_ATTR_CONT
Definition rest.h:202
@ READ_STATE_ATTR_BEGIN
Definition rest.h:201
@ READ_STATE_END
Definition rest.h:203
@ READ_STATE_INIT
Definition rest.h:200
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:239
fr_table_num_sorted_t const http_body_type_table[]
Conversion table for type config values.
Definition rest.c:147
fr_curl_conn_config_t conn_config
Configuration of slab allocated connection handles.
Definition rest.h:170
int http_negotiation
What HTTP version to negotiate, and how to.
Definition rest.h:164
HIDDEN fr_dict_t const * dict_freeradius
Definition base.c:77
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:255
rlm_rest_section_t section
Parsed section config.
Definition rest.h:153
fr_rb_node_t node
In tree of calls.
Definition rest.h:155
fr_table_num_sorted_t const http_method_table[]
Conversion table for method config values.
Definition rest.c:128
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:2166
char const * force_to_str
Force decoding with this decoder.
Definition rest.h:128
rlm_rest_section_conf_t * section
Section config.
Definition rest.h:281
rlm_rest_section_request_t request
Request configuration.
Definition rest.h:143
rlm_rest_response_t response
Response context data.
Definition rest.h:269
size_t(* rest_read_t)(void *ptr, size_t size, size_t nmemb, void *userdata)
Definition rest.h:305
void * decoder
Decoder specific data.
Definition rest.h:255
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:1707
rlm_rest_section_t const * section
Section configuration.
Definition rest.h:221
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:1787
void * encoder
Encoder specific data.
Definition rest.h:230
rlm_rest_section_t xlat
Configuration specific to xlat.
Definition rest.h:172
HIDDEN fr_dict_attr_t const * attr_rest_http_status_code
Definition rlm_rest.c:257
void rest_response_debug(request_t *request, fr_curl_io_request_t *handle)
Print out the response text.
Definition rest.c:1566
rlm_rest_request_t request
Request context data.
Definition rest.h:268
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:191
const unsigned long http_curl_auth[REST_HTTP_AUTH_NUM_ENTRIES]
Definition rest.c:102
bool sections_init
Has the tree been initialised.
Definition rest.h:175
rlm_rest_section_response_t response
Response configuration.
Definition rest.h:144
rlm_rest_section_t section
Our mutated section config.
Definition rest.h:276
const http_body_type_t http_body_type_supported[REST_HTTP_BODY_NUM_ENTRIES]
Table of encoder/decoder support.
Definition rest.c:52
fr_time_delta_t timeout
Timeout timeval.
Definition rest.h:141
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:2140
write_state_t
Definition rest.h:209
@ WRITE_STATE_INIT
Definition rest.h:210
@ WRITE_STATE_PARSE_HEADERS
Definition rest.h:211
@ WRITE_STATE_PARSE_CONTENT
Definition rest.h:212
@ WRITE_STATE_DISCARD
Definition rest.h:213
bool multiplex
Whether to perform multiple requests using a single connection.
Definition rest.h:167
rlm_rest_t const * inst
Instance of rlm_rest.
Definition rest.h:190
char const * name
Section name.
Definition rest.h:139
http_auth_type_t
Definition rest.h:70
@ REST_HTTP_AUTH_NTLM_WB
Definition rest.h:79
@ REST_HTTP_AUTH_NUM_ENTRIES
Definition rest.h:82
@ REST_HTTP_AUTH_BASIC
Definition rest.h:74
@ REST_HTTP_AUTH_NTLM
Definition rest.h:78
@ REST_HTTP_AUTH_DIGEST
Definition rest.h:75
@ REST_HTTP_AUTH_TLS_SRP
Definition rest.h:73
@ REST_HTTP_AUTH_UNKNOWN
Definition rest.h:71
@ REST_HTTP_AUTH_GSSNEGOTIATE
Definition rest.h:77
@ REST_HTTP_AUTH_ANY
Definition rest.h:80
@ REST_HTTP_AUTH_NONE
Definition rest.h:72
@ REST_HTTP_AUTH_DIGEST_IE
Definition rest.h:76
@ REST_HTTP_AUTH_ANY_SAFE
Definition rest.h:81
void rest_response_error(request_t *request, fr_curl_io_request_t *handle)
Print out the response text as error lines.
Definition rest.c:1541
size_t alloc
Space allocated for buffer.
Definition rest.h:245
rest_slab_list_t * slab
Slab list for connection handles.
Definition rest.h:191
size_t http_body_type_table_len
Definition rest.c:161
char const * connect_proxy
Send request via this proxy.
Definition rest.h:162
size_t http_auth_table_len
Definition rest.c:175
size_t http_content_type_table_len
Definition rest.c:204
request_t * request
Current request.
Definition rest.h:223
http_body_type_t body
What encoding type should be used.
Definition rest.h:116
size_t http_method_table_len
Definition rest.c:136
fr_curl_io_request_t * handle
curl easy handle servicing our request.
Definition rest.h:277
rlm_rest_t const * instance
This instance of rlm_rest.
Definition rest.h:220
CONF_SECTION * cs
Conf section found for this call.
Definition rest.h:154
char const * rest_no_proxy
Magic pointer value for determining if we should disable proxying.
Definition rlm_rest.c:82
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:228
Thread specific rlm_rest instance data.
Definition rest.h:189
Stores the state of a yielded xlat.
Definition rest.h:275
username
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:120
#define FR_SLAB_TYPES(_name, _type)
Define type specific wrapper structs for slabs and slab elements.
Definition slab.h:72
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:1288
int nonnull(2, 5))
static size_t char ** out
Definition value.h:1020
An xlat calling ctx.
Definition xlat_ctx.h:49