All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
rest.h
Go to the documentation of this file.
1 /*
2  * This program is free software; you can redistribute it and/or modify
3  * it under the terms of the GNU General Public License as published by
4  * the Free Software Foundation; either version 2 of the License, or
5  * (at your option) any later version.
6  *
7  * This program is distributed in the hope that it will be useful,
8  * but WITHOUT ANY WARRANTY; without even the implied warranty of
9  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
10  * GNU General Public License for more details.
11  *
12  * You should have received a copy of the GNU General Public License
13  * along with this program; if not, write to the Free Software
14  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA
15  */
16 
17 /**
18  * $Id: 3465c8c502f31e738ebb6353260c7d5164cd3dc6 $
19  *
20  * @brief Function prototypes and datatypes for the REST (HTTP) transport.
21  * @file rest.h
22  *
23  * @copyright 2012-2014 Arran Cudbard-Bell <a.cudbard-bell@freeradius.org>
24  */
25 
26 RCSIDH(other_h, "$Id: 3465c8c502f31e738ebb6353260c7d5164cd3dc6 $")
27 
28 #include <freeradius-devel/connection.h>
29 #include "config.h"
30 
31 #define CURL_NO_OLDIES 1
32 #include <curl/curl.h>
33 
34 /*
35  * The common JSON library (also tells us if we have json-c)
36  */
37 #include "../rlm_json/json.h"
38 
39 #define REST_URI_MAX_LEN 2048
40 #define REST_BODY_MAX_LEN 8192
41 #define REST_BODY_INIT 1024
42 #define REST_BODY_MAX_ATTRS 256
43 
44 typedef enum {
51  HTTP_METHOD_CUSTOM //!< Must always come last, should not be in method table
53 
54 typedef enum {
70 
71 typedef enum {
85 
86 /*
87  * Must be updated (in rest.c) if additional values are added to
88  * http_body_type_t
89  */
91 
92 extern const unsigned long http_curl_auth[HTTP_AUTH_NUM_ENTRIES];
93 
94 extern const FR_NAME_NUMBER http_auth_table[];
95 
96 extern const FR_NAME_NUMBER http_method_table[];
97 
99 
101 
102 /*
103  * Structure for section configuration
104  */
105 typedef struct rlm_rest_section_t {
106  char const *name; //!< Section name.
107  char const *uri; //!< URI to send HTTP request to.
108 
109  char const *proxy; //!< Send request via this proxy.
110 
111  char const *method_str; //!< The string version of the HTTP method.
112  http_method_t method; //!< What HTTP method should be used, GET, POST etc...
113 
114  char const *body_str; //!< The string version of the encoding/content type.
115  http_body_type_t body; //!< What encoding type should be used.
116 
117  char const *force_to_str; //!< Force decoding with this decoder.
118  http_body_type_t force_to; //!< Override the Content-Type header in the response
119  //!< to force decoding as a particular type.
120 
121  char const *data; //!< Custom body data (optional).
122 
123  char const *auth_str; //!< The string version of the Auth-Type.
124  http_auth_type_t auth; //!< HTTP auth type.
125  bool require_auth; //!< Whether HTTP-Auth is required or not.
126  char const *username; //!< Username used for HTTP-Auth
127  char const *password; //!< Password used for HTTP-Auth
128 
129  char const *tls_certificate_file;
130  char const *tls_private_key_file;
132  char const *tls_ca_file;
133  char const *tls_ca_path;
134  char const *tls_random_file;
137 
138  struct timeval timeout_tv; //!< Timeout timeval.
139  long timeout; //!< Timeout in ms.
140  uint32_t chunk; //!< Max chunk-size (mainly for testing the encoders)
142 
143 /*
144  * Structure for module configuration
145  */
146 typedef struct rlm_rest_t {
147  char const *xlat_name; //!< Instance name.
148 
149  char const *connect_uri; //!< URI we attempt to connect to, to pre-establish
150  //!< TCP connections.
151 
152  char const *connect_proxy; //!< Send request via this proxy.
153 
154  fr_connection_pool_t *pool; //!< Pointer to the connection pool.
155 
156  rlm_rest_section_t authorize; //!< Configuration specific to authorisation.
157  rlm_rest_section_t authenticate; //!< Configuration specific to authentication.
158  rlm_rest_section_t accounting; //!< Configuration specific to accounting.
159  rlm_rest_section_t checksimul; //!< Configuration specific to simultaneous session
160  //!< checking.
161  rlm_rest_section_t post_auth; //!< Configuration specific to Post-auth
162 } rlm_rest_t;
163 
164 /*
165  * States for stream based attribute encoders
166  */
167 typedef enum {
173 } read_state_t;
174 
175 /*
176  * States for the response parser
177  */
178 typedef enum {
183 } write_state_t;
184 
185 /*
186  * Outbound data context (passed to CURLOPT_READFUNCTION as CURLOPT_READDATA)
187  */
188 typedef struct rlm_rest_request_t {
189  rlm_rest_t *instance; //!< This instance of rlm_rest.
190  REQUEST *request; //!< Current request.
191  read_state_t state; //!< Encoder state
192 
193  vp_cursor_t cursor; //!< Cursor pointing to the start of the list to encode.
194 
195  size_t chunk; //!< Chunk size
196 
197  void *encoder; //!< Encoder specific data.
199 
200 /*
201  * Curl inbound data context (passed to CURLOPT_WRITEFUNCTION and
202  * CURLOPT_HEADERFUNCTION as CURLOPT_WRITEDATA and CURLOPT_HEADERDATA)
203  */
204 typedef struct rlm_rest_response_t {
205  rlm_rest_t *instance; //!< This instance of rlm_rest.
206  REQUEST *request; //!< Current request.
207  write_state_t state; //!< Decoder state.
208 
209  char *buffer; //!< Raw incoming HTTP data.
210  size_t alloc; //!< Space allocated for buffer.
211  size_t used; //!< Space used in buffer.
212 
213  int code; //!< HTTP Status Code.
214  http_body_type_t type; //!< HTTP Content Type.
215  http_body_type_t force_to; //!< Force decoding the body type as a particular encoding.
216 
217  void *decoder; //!< Decoder specific data.
219 
220 /*
221  * Curl context data
222  */
223 typedef struct rlm_rest_curl_context_t {
224  struct curl_slist *headers; //!< Any HTTP headers which will be sent with the
225  //!< request.
226 
227  char *body; //!< Pointer to the buffer which contains body data/
228  //!< Only used when not performing chunked encoding.
229 
230  rlm_rest_request_t request; //!< Request context data.
231  rlm_rest_response_t response; //!< Response context data.
233 
234 /*
235  * Connection API handle
236  */
237 typedef struct rlm_rest_handle_t {
238  void *handle; //!< Real Handle.
239  rlm_rest_curl_context_t *ctx; //!< Context.
241 
242 /*
243  * Function prototype for rest_read_wrapper. Matches CURL's
244  * CURLOPT_READFUNCTION prototype.
245  */
246 typedef size_t (*rest_read_t)(void *ptr, size_t size, size_t nmemb,
247  void *userdata);
248 
249 /*
250  * Connection API callbacks
251  */
252 int rest_init(rlm_rest_t *instance);
253 
254 void rest_cleanup(void);
255 
256 void *mod_conn_create(TALLOC_CTX *ctx, void *instance, struct timeval const *timeout);
257 
258 int mod_conn_alive(void *instance, void *handle);
259 
260 /*
261  * Request processing API
262  */
263 int rest_request_config(rlm_rest_t const *instance,
264  rlm_rest_section_t *section, REQUEST *request,
265  void *handle, http_method_t method,
266  http_body_type_t type, char const *uri,
267  char const *username, char const *password) CC_HINT(nonnull (1,2,3,4,7));
268 
269 int rest_request_perform(rlm_rest_t const *instance,
270  rlm_rest_section_t *section, REQUEST *request,
271  void *handle);
272 
273 int rest_response_decode(rlm_rest_t const *instance,
274  UNUSED rlm_rest_section_t *section, REQUEST *request,
275  void *handle);
276 
277 void rest_response_error(REQUEST *request, rlm_rest_handle_t *handle);
278 
279 void rest_request_cleanup(rlm_rest_t const *instance, rlm_rest_section_t *section,
280  void *handle);
281 
282 #define rest_get_handle_code(_handle)(((rlm_rest_curl_context_t*)((rlm_rest_handle_t*)_handle)->ctx)->response.code)
283 
284 #define rest_get_handle_type(_handle)(((rlm_rest_curl_context_t*)((rlm_rest_handle_t*)_handle)->ctx)->response.type)
285 
286 size_t rest_get_handle_data(char const **out, rlm_rest_handle_t *handle);
287 
288 /*
289  * Helper functions
290  */
291 size_t rest_uri_escape(UNUSED REQUEST *request, char *out, size_t outlen, char const *raw, UNUSED void *arg);
292 ssize_t rest_uri_build(char **out, rlm_rest_t *instance, REQUEST *request, char const *uri);
293 ssize_t rest_uri_host_unescape(char **out, UNUSED rlm_rest_t const *mod_inst, REQUEST *request,
294  void *handle, char const *uri);
char const * name
Section name.
Definition: rest.h:106
read_state_t
Definition: rest.h:167
size_t used
Space used in buffer.
Definition: rest.h:211
#define RCSIDH(h, id)
Definition: build.h:136
http_body_type_t
Definition: rest.h:54
rlm_rest_section_t post_auth
Configuration specific to Post-auth.
Definition: rest.h:161
struct rlm_rest_response_t rlm_rest_response_t
uint32_t chunk
Max chunk-size (mainly for testing the encoders)
Definition: rest.h:140
const FR_NAME_NUMBER http_content_type_table[]
Conversion table for "Content-Type" header values.
Definition: rest.c:198
char const * tls_ca_path
Definition: rest.h:133
struct rlm_rest_request_t rlm_rest_request_t
void * decoder
Decoder specific data.
Definition: rest.h:217
http_body_type_t force_to
Override the Content-Type header in the response to force decoding as a particular type...
Definition: rest.h:118
fr_connection_pool_t * pool
Pointer to the connection pool.
Definition: rest.h:154
const FR_NAME_NUMBER http_auth_table[]
Definition: rest.c:169
#define CC_HINT(_x)
Definition: build.h:71
#define UNUSED
Definition: libradius.h:134
char const * password
Password used for HTTP-Auth.
Definition: rest.h:127
const FR_NAME_NUMBER http_method_table[]
Conversion table for method config values.
Definition: rest.c:133
rlm_rest_t * instance
This instance of rlm_rest.
Definition: rest.h:205
rlm_rest_curl_context_t * ctx
Context.
Definition: rest.h:239
const FR_NAME_NUMBER http_body_type_table[]
Conversion table for type config values.
Definition: rest.c:153
static float timeout
Definition: radclient.c:43
http_body_type_t body
What encoding type should be used.
Definition: rest.h:115
REQUEST * request
Current request.
Definition: rest.h:206
void rest_cleanup(void)
Cleans up after libcurl.
Definition: rest.c:297
vp_cursor_t cursor
Cursor pointing to the start of the list to encode.
Definition: rest.h:193
Abstraction to allow iterating over different configurations of VALUE_PAIRs.
Definition: pair.h:144
rlm_rest_section_t accounting
Configuration specific to accounting.
Definition: rest.h:158
int mod_conn_alive(void *instance, void *handle)
Verifies that the last TCP socket associated with a handle is still active.
Definition: rest.c:426
size_t(* rest_read_t)(void *ptr, size_t size, size_t nmemb, void *userdata)
Definition: rest.h:246
http_auth_type_t auth
HTTP auth type.
Definition: rest.h:124
char const * tls_private_key_file
Definition: rest.h:130
int int rest_request_perform(rlm_rest_t const *instance, rlm_rest_section_t *section, REQUEST *request, void *handle)
struct curl_slist * headers
Any HTTP headers which will be sent with the request.
Definition: rest.h:224
struct rlm_rest_handle_t rlm_rest_handle_t
struct rlm_rest_t rlm_rest_t
rlm_rest_section_t authenticate
Configuration specific to authentication.
Definition: rest.h:157
bool tls_check_cert
Definition: rest.h:135
char const * proxy
Send request via this proxy.
Definition: rest.h:109
char const * data
Custom body data (optional).
Definition: rest.h:121
char const * connect_proxy
Send request via this proxy.
Definition: rest.h:152
void * handle
Real Handle.
Definition: rest.h:238
http_auth_type_t
Definition: rest.h:71
Must always come last, should not be in method table.
Definition: rest.h:51
size_t chunk
Chunk size.
Definition: rest.h:195
ssize_t rest_uri_host_unescape(char **out, UNUSED rlm_rest_t const *mod_inst, REQUEST *request, void *handle, char const *uri)
Unescapes the host portion of a URI string.
Definition: rest.c:2565
const unsigned long http_curl_auth[HTTP_AUTH_NUM_ENTRIES]
Definition: rest.c:106
char const * tls_random_file
Definition: rest.h:134
bool require_auth
Whether HTTP-Auth is required or not.
Definition: rest.h:125
char const * uri
URI to send HTTP request to.
Definition: rest.h:107
rlm_rest_response_t response
Response context data.
Definition: rest.h:231
void * mod_conn_create(TALLOC_CTX *ctx, void *instance, struct timeval const *timeout)
Create a new connection pool handle.
Definition: mod.c:68
char * body
Pointer to the buffer which contains body data/ Only used when not performing chunked encoding...
Definition: rest.h:227
size_t rest_get_handle_data(char const **out, rlm_rest_handle_t *handle)
Extracts pointer to buffer containing response data.
Definition: rest.c:1871
REQUEST * request
Current request.
Definition: rest.h:190
char const * auth_str
The string version of the Auth-Type.
Definition: rest.h:123
int rest_request_config(rlm_rest_t const *instance, rlm_rest_section_t *section, REQUEST *request, void *handle, http_method_t method, http_body_type_t type, char const *uri, char const *username, char const *password) CC_HINT(nonnull(1
char * buffer
Raw incoming HTTP data.
Definition: rest.h:209
size_t rest_uri_escape(UNUSED REQUEST *request, char *out, size_t outlen, char const *raw, UNUSED void *arg)
URL encodes a string.
Definition: rest.c:2469
long timeout
Timeout in ms.
Definition: rest.h:139
size_t alloc
Space allocated for buffer.
Definition: rest.h:210
int code
HTTP Status Code.
Definition: rest.h:213
void rest_response_error(REQUEST *request, rlm_rest_handle_t *handle)
Print out the response text as error lines.
Definition: rest.c:1823
http_body_type_t force_to
Force decoding the body type as a particular encoding.
Definition: rest.h:215
int rest_response_decode(rlm_rest_t const *instance, UNUSED rlm_rest_section_t *section, REQUEST *request, void *handle)
char const * method_str
The string version of the HTTP method.
Definition: rest.h:111
rlm_rest_section_t checksimul
Configuration specific to simultaneous session checking.
Definition: rest.h:159
void rest_request_cleanup(rlm_rest_t const *instance, rlm_rest_section_t *section, void *handle)
rlm_rest_section_t authorize
Configuration specific to authorisation.
Definition: rest.h:156
http_method_t
Definition: rest.h:44
A connection pool.
Definition: connection.c:85
char const * username
Username used for HTTP-Auth.
Definition: rest.h:126
char const * tls_certificate_file
Definition: rest.h:129
char const * body_str
The string version of the encoding/content type.
Definition: rest.h:114
bool tls_check_cert_cn
Definition: rest.h:136
ssize_t rest_uri_build(char **out, rlm_rest_t *instance, REQUEST *request, char const *uri)
char const * tls_ca_file
Definition: rest.h:132
const http_body_type_t http_body_type_supported[HTTP_BODY_NUM_ENTRIES]
Table of encoder/decoder support.
Definition: rest.c:46
char const * xlat_name
Instance name.
Definition: rest.h:147
rlm_rest_request_t request
Request context data.
Definition: rest.h:230
char const * tls_private_key_password
Definition: rest.h:131
rlm_rest_t * instance
This instance of rlm_rest.
Definition: rest.h:189
write_state_t
Definition: rest.h:178
struct rlm_rest_curl_context_t rlm_rest_curl_context_t
char const * connect_uri
URI we attempt to connect to, to pre-establish TCP connections.
Definition: rest.h:149
char const * force_to_str
Force decoding with this decoder.
Definition: rest.h:117
http_method_t method
What HTTP method should be used, GET, POST etc...
Definition: rest.h:112
write_state_t state
Decoder state.
Definition: rest.h:207
read_state_t state
Encoder state.
Definition: rest.h:191
http_body_type_t type
HTTP Content Type.
Definition: rest.h:214
struct timeval timeout_tv
Timeout timeval.
Definition: rest.h:138
int rest_init(rlm_rest_t *instance)
Initialises libcurl.
Definition: rest.c:255
struct rlm_rest_section_t rlm_rest_section_t
void * encoder
Encoder specific data.
Definition: rest.h:197