All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Data Structures | Macros | Typedefs | Functions | Variables
rest.c File Reference

Functions and datatypes for the REST (HTTP) transport. More...

#include <ctype.h>
#include <string.h>
#include <time.h>
#include <freeradius-devel/rad_assert.h>
#include <freeradius-devel/radiusd.h>
#include <freeradius-devel/libradius.h>
#include <freeradius-devel/connection.h>
#include "rest.h"
+ Include dependency graph for rest.c:

Go to the source code of this file.

Data Structures

struct  json_flags
 Flags to control the conversion of JSON values to VALUE_PAIRs. More...
 
struct  rest_custom_data
 

Macros

#define CURLAUTH_BASIC   0
 
#define CURLAUTH_DIGEST   0
 
#define CURLAUTH_DIGEST_IE   0
 
#define CURLAUTH_GSSNEGOTIATE   0
 
#define CURLAUTH_NTLM   0
 
#define CURLAUTH_NTLM_WB   0
 
#define CURLOPT_TLSAUTH_SRP   0
 
#define SET_OPTION(_x, _y)
 

Typedefs

typedef struct json_flags json_flags_t
 Flags to control the conversion of JSON values to VALUE_PAIRs. More...
 
typedef struct rest_custom_data rest_custom_data_t
 

Functions

static int _mod_conn_free (rlm_rest_handle_t *randle)
 Frees a libcurl handle, and any additional memory used by context data. More...
 
static int json_pair_make (rlm_rest_t const *instance, rlm_rest_section_t *section, REQUEST *request, json_object *object, UNUSED int level, int max)
 Processes JSON response and converts it into multiple VALUE_PAIRs. More...
 
static VALUE_PAIRjson_pair_make_leaf (UNUSED rlm_rest_t const *instance, UNUSED rlm_rest_section_t *section, TALLOC_CTX *ctx, REQUEST *request, fr_dict_attr_t const *da, json_flags_t *flags, json_object *leaf)
 Converts JSON "value" key into VALUE_PAIR. More...
 
int mod_conn_alive (void *instance, void *handle)
 Verifies that the last TCP socket associated with a handle is still active. More...
 
void * mod_conn_create (TALLOC_CTX *ctx, void *instance, struct timeval const *timeout)
 Creates a new connection handle for use by the FR connection API. More...
 
void rest_cleanup (void)
 Cleans up after libcurl. More...
 
static int rest_decode_json (rlm_rest_t const *instance, rlm_rest_section_t *section, REQUEST *request, UNUSED void *handle, char *raw, UNUSED size_t rawlen)
 Converts JSON response into VALUE_PAIRs and adds them to the request. More...
 
static int rest_decode_plain (UNUSED rlm_rest_t const *instance, UNUSED rlm_rest_section_t *section, REQUEST *request, UNUSED void *handle, char *raw, size_t rawlen)
 Converts plain response into a single VALUE_PAIR. More...
 
static int rest_decode_post (UNUSED rlm_rest_t const *instance, UNUSED rlm_rest_section_t *section, REQUEST *request, void *handle, char *raw, size_t rawlen)
 Converts POST response into VALUE_PAIRs and adds them to the request. More...
 
static size_t rest_encode_custom (void *out, size_t size, size_t nmemb, void *userdata)
 Copies a pre-expanded xlat string to the output buffer. More...
 
static size_t rest_encode_json (void *out, size_t size, size_t nmemb, void *userdata)
 Encodes VALUE_PAIR linked list in JSON format. More...
 
static size_t rest_encode_post (void *out, size_t size, size_t nmemb, void *userdata)
 Encodes VALUE_PAIR linked list in POST format. More...
 
size_t rest_get_handle_data (char const **out, rlm_rest_handle_t *handle)
 Extracts pointer to buffer containing response data. More...
 
int rest_init (rlm_rest_t *instance)
 Initialises libcurl. More...
 
void rest_request_cleanup (UNUSED rlm_rest_t const *instance, UNUSED rlm_rest_section_t *section, void *handle)
 Cleans up after a REST request. More...
 
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)
 Configures request curlopts. More...
 
static int rest_request_config_body (UNUSED rlm_rest_t const *instance, rlm_rest_section_t *section, REQUEST *request, rlm_rest_handle_t *handle, rest_read_t func)
 Configures body specific curlopts. More...
 
static ssize_t rest_request_encode_wrapper (char **out, rest_read_t func, size_t limit, void *userdata)
 Emulates successive libcurl calls to an encoding function. More...
 
static void rest_request_init (REQUEST *request, rlm_rest_request_t *ctx, bool sort)
 (Re-)Initialises the data in a rlm_rest_request_t. More...
 
int rest_request_perform (UNUSED rlm_rest_t const *instance, UNUSED rlm_rest_section_t *section, REQUEST *request, void *handle)
 Sends a REST (HTTP) request. More...
 
static size_t rest_response_body (void *ptr, size_t size, size_t nmemb, void *userdata)
 Processes incoming HTTP body data from libcurl. More...
 
int rest_response_decode (rlm_rest_t const *instance, rlm_rest_section_t *section, REQUEST *request, void *handle)
 Sends the response to the correct decode function. More...
 
void rest_response_error (REQUEST *request, rlm_rest_handle_t *handle)
 Print out the response text as error lines. More...
 
static size_t rest_response_header (void *in, size_t size, size_t nmemb, void *userdata)
 Processes incoming HTTP header data from libcurl. More...
 
static void rest_response_init (REQUEST *request, rlm_rest_response_t *ctx, http_body_type_t type)
 (Re-)Initialises the data in a rlm_rest_response_t. More...
 
ssize_t rest_uri_build (char **out, UNUSED rlm_rest_t *instance, REQUEST *request, char const *uri)
 Builds URI; performs XLAT expansions and encoding. More...
 
size_t rest_uri_escape (UNUSED REQUEST *request, char *out, size_t outlen, char const *raw, UNUSED void *arg)
 URL encodes a string. More...
 
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. More...
 

Variables

const FR_NAME_NUMBER http_auth_table []
 
const http_body_type_t http_body_type_supported [HTTP_BODY_NUM_ENTRIES]
 Table of encoder/decoder support. More...
 
const FR_NAME_NUMBER http_body_type_table []
 Conversion table for type config values. More...
 
const FR_NAME_NUMBER http_content_type_table []
 Conversion table for "Content-Type" header values. More...
 
const unsigned long http_curl_auth [HTTP_AUTH_NUM_ENTRIES]
 
const FR_NAME_NUMBER http_method_table []
 Conversion table for method config values. More...
 

Detailed Description

Functions and datatypes for the REST (HTTP) transport.

Id:
5c4810ac4606eba6928ea5d90565d4975ed15989

Definition in file rest.c.


Data Structure Documentation

struct json_flags

Flags to control the conversion of JSON values to VALUE_PAIRs.

These fields are set when parsing the expanded format for value pairs in JSON, and control how json_pair_make_leaf and json_pair_make convert the JSON value, and move the new VALUE_PAIR into an attribute list.

See Also
json_pair_make
json_pair_make_leaf

Definition at line 232 of file rest.c.

Data Fields
int do_xlat If true value will be expanded with xlat.
int is_json If true value will be inserted as raw JSON.
FR_TOKEN op The operator that determines how the new VP.
struct rest_custom_data

Definition at line 216 of file rest.c.

Data Fields
size_t len Length of data.
char const * p how much text we've sent so far.
char const * start Start of the buffer.

Macro Definition Documentation

#define CURLAUTH_BASIC   0

Definition at line 73 of file rest.c.

#define CURLAUTH_DIGEST   0

Definition at line 76 of file rest.c.

#define CURLAUTH_DIGEST_IE   0

Definition at line 79 of file rest.c.

#define CURLAUTH_GSSNEGOTIATE   0

Definition at line 82 of file rest.c.

#define CURLAUTH_NTLM   0

Definition at line 85 of file rest.c.

#define CURLAUTH_NTLM_WB   0

Definition at line 88 of file rest.c.

#define CURLOPT_TLSAUTH_SRP   0

Definition at line 70 of file rest.c.

#define SET_OPTION (   _x,
  _y 
)
Value:
do {\
if ((ret = curl_easy_setopt(candle, _x, _y)) != CURLE_OK) {\
option = STRINGIFY(_x);\
goto error;\
}\
} while (0)
#define STRINGIFY(x)
Definition: build.h:34

Definition at line 98 of file rest.c.

Typedef Documentation

typedef struct json_flags json_flags_t

Flags to control the conversion of JSON values to VALUE_PAIRs.

These fields are set when parsing the expanded format for value pairs in JSON, and control how json_pair_make_leaf and json_pair_make convert the JSON value, and move the new VALUE_PAIR into an attribute list.

See Also
json_pair_make
json_pair_make_leaf

Function Documentation

static int _mod_conn_free ( rlm_rest_handle_t randle)
static

Frees a libcurl handle, and any additional memory used by context data.

Parameters
[in]randlerlm_rest_handle_t to close and free.
Returns
returns true.

Definition at line 308 of file rest.c.

+ Here is the caller graph for this function:

static int json_pair_make ( rlm_rest_t const *  instance,
rlm_rest_section_t section,
REQUEST request,
json_object *  object,
UNUSED int  level,
int  max 
)
static

Processes JSON response and converts it into multiple VALUE_PAIRs.

Processes JSON attribute declarations in the format below. Will recurse when processing nested attributes. When processing nested attributes flags and operators from previous attributes are not inherited.

JSON response format is:

{
        "<attribute0>":{
                "do_xlat":<bool>,
                "is_json":<bool>,
                "op":"<operator>",
                "value":[<value0>,<value1>,<valueN>]
        },
        "<attribute1>":{
                "value":{
                        "<nested-attribute0>":{
                                "op":"<operator>",
                                "value":<value0>
                        }
                }
        },
        "<attribute2>":"<value0>",
        "<attributeN>":[<value0>,<value1>,<valueN>]
}

JSON valuepair flags:

  • do_xlat (optional) Controls xlat expansion of values. Defaults to true.
  • is_json (optional) If true, any nested JSON data will be copied to the VALUE_PAIR in string form. Defaults to true.
  • op (optional) Controls how the attribute is inserted into the target list. Defaults to ':=' (T_OP_SET).

If "op" is ':=' or '=', it will be automagically changed to '+=' for the second and subsequent values in multivalued attributes. This does not work between multiple attribute declarations.

See Also
fr_tokens_table
Parameters
[in]instanceconfiguration data.
[in]sectionconfiguration data.
[in]requestCurrent request.
[in]objectcontaining root node, or parent node.
[in]levelCurrent nesting level.
[in]maxcounter, decremented after each VALUE_PAIR is created, when 0 no more attributes will be processed.
Returns
  • Number of attributes created.
  • < 0 on error.

Definition at line 1307 of file rest.c.

+ Here is the call graph for this function:

+ Here is the caller graph for this function:

static VALUE_PAIR* json_pair_make_leaf ( UNUSED rlm_rest_t const *  instance,
UNUSED rlm_rest_section_t section,
TALLOC_CTX *  ctx,
REQUEST request,
fr_dict_attr_t const *  da,
json_flags_t flags,
json_object *  leaf 
)
static

Converts JSON "value" key into VALUE_PAIR.

If leaf is not in fact a leaf node, but contains JSON data, the data will written to the attribute in JSON string format.

Parameters
[in]instanceconfiguration data.
[in]sectionconfiguration data.
[in]ctxto allocate new VALUE_PAIRs in.
[in]requestCurrent request.
[in]daAttribute to create.
[in]flagscontaining the operator other flags controlling value expansion.
[in]leafobject containing the VALUE_PAIR value.
Returns

Definition at line 1189 of file rest.c.

+ Here is the call graph for this function:

+ Here is the caller graph for this function:

int mod_conn_alive ( void *  instance,
void *  handle 
)

Verifies that the last TCP socket associated with a handle is still active.

Quieries libcurl to try and determine if the TCP socket associated with a connection handle is still viable.

Parameters
[in]instanceconfiguration data.
[in]handleto check.
Returns
  • False if the last socket is dead, or if the socket state couldn't be determined.
  • True if TCP socket is still alive.

Definition at line 426 of file rest.c.

void* mod_conn_create ( TALLOC_CTX *  ctx,
void *  instance,
struct timeval const *  timeout 
)

Creates a new connection handle for use by the FR connection API.

Create a new connection pool handle.

Matches the fr_connection_create_t function prototype, is passed to fr_connection_pool_init, and called when a new connection is required by the connection pool API.

Creates an instances of rlm_rest_handle_t, and rlm_rest_curl_context_t which hold the context data required for generating requests and parsing responses.

If instance->connect_uri is not NULL libcurl will attempt to open a TCP socket to the server specified in the URI. This is done so that when the socket is first used, there will already be a cached TCP connection to the REST server associated with the curl handle.

See Also
fr_connection_pool_init
fr_connection_create_t
connection.c

Definition at line 334 of file rest.c.

+ Here is the call graph for this function:

void rest_cleanup ( void  )

Cleans up after libcurl.

Wrapper around curl_global_cleanup, frees any memory allocated by rest_init. Must only be called once per call of rest_init.

See Also
rest_init

Definition at line 297 of file rest.c.

+ Here is the caller graph for this function:

static int rest_decode_json ( rlm_rest_t const *  instance,
rlm_rest_section_t section,
REQUEST request,
UNUSED void *  handle,
char *  raw,
UNUSED size_t  rawlen 
)
static

Converts JSON response into VALUE_PAIRs and adds them to the request.

Converts the raw JSON string into a json-c object tree and passes it to json_pair_make. After the tree has been parsed json_object_put is called which decrements the reference count of the root node by one, and frees the entire tree.

See Also
rest_encode_json
json_pair_make
Parameters
[in]instanceconfiguration data.
[in]sectionconfiguration data.
[in,out]requestCurrent request.
[in]handleREST handle.
[in]rawbuffer containing JSON data.
[in]rawlenLength of data in raw buffer.
Returns
  • The number of VALUE_PAIR processed.
  • -1 on unrecoverable error.

Definition at line 1497 of file rest.c.

+ Here is the call graph for this function:

+ Here is the caller graph for this function:

static int rest_decode_plain ( UNUSED rlm_rest_t const *  instance,
UNUSED rlm_rest_section_t section,
REQUEST request,
UNUSED void *  handle,
char *  raw,
size_t  rawlen 
)
static

Converts plain response into a single VALUE_PAIR.

Parameters
[in]instanceconfiguration data.
[in]sectionconfiguration data.
[in]handlerlm_rest_handle_t to use.
[in]requestCurrent request.
[in]rawbuffer containing POST data.
[in]rawlenLength of data in raw buffer.
Returns
  • Number of VALUE_PAIR processed.
  • -1 on unrecoverable error.

Definition at line 974 of file rest.c.

+ Here is the call graph for this function:

+ Here is the caller graph for this function:

static int rest_decode_post ( UNUSED rlm_rest_t const *  instance,
UNUSED rlm_rest_section_t section,
REQUEST request,
void *  handle,
char *  raw,
size_t  rawlen 
)
static

Converts POST response into VALUE_PAIRs and adds them to the request.

Accepts VALUE_PAIRS in the same format as rest_encode_post, but with the addition of optional attribute list qualifiers as part of the attribute name string.

If no qualifiers are specified, will default to the request list.

POST response format is:

[outer.][<list>:]<attribute0>=<value0>&[outer.][<list>:]<attribute1>=<value1>&[outer.][<list>:]<attributeN>=<valueN> 
See Also
rest_encode_post
Parameters
[in]instanceconfiguration data.
[in]sectionconfiguration data.
[in]handlerlm_rest_handle_t to use.
[in]requestCurrent request.
[in]rawbuffer containing POST data.
[in]rawlenLength of data in raw buffer.
Returns
  • Number of VALUE_PAIRs processed.
  • -1 on unrecoverable error.

Definition at line 1018 of file rest.c.

+ Here is the call graph for this function:

+ Here is the caller graph for this function:

static size_t rest_encode_custom ( void *  out,
size_t  size,
size_t  nmemb,
void *  userdata 
)
static

Copies a pre-expanded xlat string to the output buffer.

Parameters
[out]outChar buffer to write encoded data to.
[in]sizeMultiply by nmemb to get the length of ptr.
[in]nmembMultiply by size to get the length of ptr.
[in]userdatarlm_rest_request_t to keep encoding state between calls.
Returns
  • Length of data (including NULL) written to ptr.
  • 0 if no more data to write.

Definition at line 460 of file rest.c.

+ Here is the caller graph for this function:

static size_t rest_encode_json ( void *  out,
size_t  size,
size_t  nmemb,
void *  userdata 
)
static

Encodes VALUE_PAIR linked list in JSON format.

This is a stream function matching the rest_read_t prototype. Multiple successive calls will return additional encoded VALUE_PAIRs.

Only complete attribute headers

"<name>":{"type":"<type>","value":[' 

and complete attribute values will be written to ptr.

If an attribute occurs multiple times in the request the attribute values will be concatenated into a single value array.

JSON request format is:

{
        "<attribute0>":{
                "type":"<type0>",
                "value":[<value0>,<value1>,<valueN>]
        },
        "<attribute1>":{
                "type":"<type1>",
                "value":[...]
        },
        "<attributeN>":{
                "type":"<typeN>",
                "value":[...]
        },
}
Parameters
[out]outChar buffer to write encoded data to.
[in]sizeMultiply by nmemb to get the length of ptr.
[in]nmembMultiply by size to get the length of ptr.
[in]userdatarlm_rest_request_t to keep encoding state between calls.
Returns
  • Length of data (including NULL) written to ptr.
  • 0 if no more data to write.

Definition at line 698 of file rest.c.

+ Here is the call graph for this function:

+ Here is the caller graph for this function:

static size_t rest_encode_post ( void *  out,
size_t  size,
size_t  nmemb,
void *  userdata 
)
static

Encodes VALUE_PAIR linked list in POST format.

This is a stream function matching the rest_read_t prototype. Multiple successive calls will return additional encoded VALUE_PAIRs. Only complete attribute headers

'<name>=' 

and values will be written to the ptr buffer.

POST request format is:

<attribute0>=<value0>&<attribute1>=<value1>&<attributeN>=<valueN>

All attributes and values are url encoded. There is currently no support for nested attributes, or attribute qualifiers.

Nested attributes may be added in the future using

<attribute-outer>:<attribute-inner>

to denotate nesting.

Requires libcurl for url encoding.

See Also
rest_decode_post
Parameters
[out]outChar buffer to write encoded data to.
[in]sizeMultiply by nmemb to get the length of ptr.
[in]nmembMultiply by size to get the length of ptr.
[in]userdatarlm_rest_request_t to keep encoding state between calls.
Returns
  • Length of data (including NULL) written to ptr.
  • 0 if no more data to write.

Definition at line 519 of file rest.c.

+ Here is the call graph for this function:

+ Here is the caller graph for this function:

size_t rest_get_handle_data ( char const **  out,
rlm_rest_handle_t handle 
)

Extracts pointer to buffer containing response data.

Parameters
[out]outWhere to write the pointer to the buffer.
[in]handleused for the last request.
Returns
> 0 if data is available.

Definition at line 1871 of file rest.c.

+ Here is the caller graph for this function:

int rest_init ( rlm_rest_t instance)

Initialises libcurl.

Allocates global variables and memory required for libcurl to function. MUST only be called once per module instance.

rest_cleanup must not be called if rest_init fails.

See Also
rest_cleanup
Parameters
[in]instanceconfiguration data.
Returns
  • 0 if init succeeded.
  • -1 if it failed.

Definition at line 255 of file rest.c.

+ Here is the caller graph for this function:

void rest_request_cleanup ( UNUSED rlm_rest_t const *  instance,
UNUSED rlm_rest_section_t section,
void *  handle 
)

Cleans up after a REST request.

Resets all options associated with a CURL handle, and frees any headers associated with it.

Calls rest_read_ctx_free and rest_response_free to free any memory used by context data.

Parameters
[in]instanceconfiguration data.
[in]sectionconfiguration data.
[in]handleto cleanup.

Definition at line 2422 of file rest.c.

+ Here is the caller graph for this function:

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 
)

Configures request curlopts.

Configures libcurl handle setting various curlopts for things like local client time, Content-Type, and other FreeRADIUS custom headers.

Current FreeRADIUS custom headers are:

  • X-FreeRADIUS-Section The module section being processed.
  • X-FreeRADIUS-Server The current virtual server the REQUEST is passing through.

Sets up callbacks for all response processing (buffers and body data).

Parameters
[in]instanceconfiguration data.
[in]sectionconfiguration data.
[in]handleto configure.
[in]requestCurrent request.
[in]methodto use (HTTP verbs PUT, POST, DELETE etc...).
[in]typeContent-Type for request encoding, also sets the default for decoding.
[in]usernameto use for HTTP authentication, may be NULL in which case configured defaults will be used.
[in]passwordto use for HTTP authentication, may be NULL in which case configured defaults will be used.
[in]uribuffer containing the expanded URI to send the request to.
Returns
  • 0 on success (all opts configured).
  • -1 on failure.

Definition at line 1976 of file rest.c.

+ Here is the call graph for this function:

+ Here is the caller graph for this function:

static int rest_request_config_body ( UNUSED rlm_rest_t const *  instance,
rlm_rest_section_t section,
REQUEST request,
rlm_rest_handle_t handle,
rest_read_t  func 
)
static

Configures body specific curlopts.

Configures libcurl handle to use either chunked mode, where the request data will be sent using multiple HTTP requests, or contiguous mode where the request data will be sent in a single HTTP request.

Parameters
[in]instanceconfiguration data.
[in]sectionconfiguration data.
[in]requestCurrent request.
[in]handlerlm_rest_handle_t to configure.
[in]functo pass to libcurl for chunked. transfers (NULL if not using chunked mode).
Returns
  • 0 on success.
  • -1 on failure.

Definition at line 1897 of file rest.c.

+ Here is the call graph for this function:

+ Here is the caller graph for this function:

static ssize_t rest_request_encode_wrapper ( char **  out,
rest_read_t  func,
size_t  limit,
void *  userdata 
)
static

Emulates successive libcurl calls to an encoding function.

This function is used when the request will be sent to the HTTP server as one contiguous entity. A buffer of REST_BODY_INIT bytes is allocated and passed to the stream encoding function.

If the stream function does not return 0, a new buffer is allocated which is the size of the previous buffer + REST_BODY_INIT bytes, the data from the previous buffer is copied, and freed, and another call is made to the stream function, passing a pointer into the new buffer at the end of the previously written data.

This process continues until the stream function signals (by returning 0) that it has no more data to write.

Parameters
[out]outwhere the pointer to the alloced buffer should be written.
[in]funcStream function.
[in]limitMaximum buffer size to alloc.
[in]userdatarlm_rest_request_t to keep encoding state between calls to stream function.
Returns
  • Length of the data written to the buffer (excluding NULL).
  • -1 if alloc >= limit.

Definition at line 907 of file rest.c.

+ Here is the caller graph for this function:

static void rest_request_init ( REQUEST request,
rlm_rest_request_t ctx,
bool  sort 
)
static

(Re-)Initialises the data in a rlm_rest_request_t.

Resets the values of a rlm_rest_request_t to their defaults.

Parameters
[in]requestCurrent request.
[in]ctxto initialise.
[in]sortIf true VALUE_PAIRs will be sorted within the VALUE_PAIR pointer array.

Definition at line 945 of file rest.c.

+ Here is the call graph for this function:

+ Here is the caller graph for this function:

int rest_request_perform ( UNUSED rlm_rest_t const *  instance,
UNUSED rlm_rest_section_t section,
REQUEST request,
void *  handle 
)

Sends a REST (HTTP) request.

Send the actual REST request to the server. The response will be handled by the numerous callbacks configured in rest_request_config.

Parameters
[in]instanceconfiguration data.
[in]sectionconfiguration data.
[in]requestCurrent request.
[in]handleto use.
Returns
  • 0 on success.
  • -1 on failure.

Definition at line 2337 of file rest.c.

+ Here is the caller graph for this function:

static size_t rest_response_body ( void *  ptr,
size_t  size,
size_t  nmemb,
void *  userdata 
)
static

Processes incoming HTTP body data from libcurl.

Writes incoming body data to an intermediary buffer for later parsing by one of the decode functions.

Parameters
[in]ptrChar buffer where inbound header data is written
[in]sizeMultiply by nmemb to get the length of ptr.
[in]nmembMultiply by size to get the length of ptr.
[in]userdatarlm_rest_response_t to keep parsing state between calls.
Returns
  • Length of data processed.
  • 0 on error.

Definition at line 1749 of file rest.c.

+ Here is the call graph for this function:

+ Here is the caller graph for this function:

int rest_response_decode ( rlm_rest_t const *  instance,
rlm_rest_section_t section,
REQUEST request,
void *  handle 
)

Sends the response to the correct decode function.

Uses the Content-Type information written in rest_response_header to determine the correct decode function to use. The decode function will then convert the raw received data into VALUE_PAIRs.

Parameters
[in]instanceconfiguration data.
[in]sectionconfiguration data.
[in]requestCurrent request.
[in]handleto use.
Returns
  • 0 on success.
  • -1 on failure.

Definition at line 2368 of file rest.c.

+ Here is the call graph for this function:

+ Here is the caller graph for this function:

void rest_response_error ( REQUEST request,
rlm_rest_handle_t handle 
)

Print out the response text as error lines.

Parameters
requestThe Current request.
handlerlm_rest_handle_t used to execute the previous request.

Definition at line 1823 of file rest.c.

+ Here is the call graph for this function:

+ Here is the caller graph for this function:

static size_t rest_response_header ( void *  in,
size_t  size,
size_t  nmemb,
void *  userdata 
)
static

Processes incoming HTTP header data from libcurl.

Processes the status line, and Content-Type headers from the incoming HTTP response.

Matches prototype for CURLOPT_HEADERFUNCTION, and will be called directly by libcurl.

Parameters
[in]inChar buffer where inbound header data is written.
[in]sizeMultiply by nmemb to get the length of ptr.
[in]nmembMultiply by size to get the length of ptr.
[in]userdatarlm_rest_response_t to keep parsing state between calls.
Returns
  • Length of data processed.
  • 0 on error.

Definition at line 1545 of file rest.c.

+ Here is the call graph for this function:

+ Here is the caller graph for this function:

static void rest_response_init ( REQUEST request,
rlm_rest_response_t ctx,
http_body_type_t  type 
)
static

(Re-)Initialises the data in a rlm_rest_response_t.

This resets the values of the a rlm_rest_response_t to their defaults. Must be called between encoding sessions.

See Also
rest_response_body
rest_response_header
Parameters
[in]requestCurrent request.
[in]ctxdata to initialise.
[in]typeDefault http_body_type to use when decoding raw data, may be overwritten by rest_response_header.

Definition at line 1855 of file rest.c.

+ Here is the caller graph for this function:

ssize_t rest_uri_build ( char **  out,
UNUSED rlm_rest_t instance,
REQUEST request,
char const *  uri 
)

Builds URI; performs XLAT expansions and encoding.

Splits the URI into "http://example.org" and "/%{xlat}/query/?bar=foo" Both components are expanded, but values expanded for the second component are also url encoded.

Parameters
[out]outWhere to write the pointer to the new buffer containing the escaped URI.
[in]instanceconfiguration data.
[in]uriconfiguration data.
[in]requestCurrent request
Returns
  • Length of data written to buffer (excluding NULL).
  • < 0 if an error occurred.

Definition at line 2494 of file rest.c.

+ Here is the call graph for this function:

+ Here is the caller graph for this function:

size_t rest_uri_escape ( UNUSED REQUEST request,
char *  out,
size_t  outlen,
char const *  raw,
UNUSED void *  arg 
)

URL encodes a string.

Encode special chars as per RFC 3986 section 4.

Parameters
[in]requestCurrent request.
[out]outWhere to write escaped string.
[in]outlenSize of out buffer.
[in]rawstring to be urlencoded.
[in]argpointer, gives context for escaping.
Returns
length of data written to out (excluding NULL).

Definition at line 2469 of file rest.c.

+ Here is the call graph for this function:

+ Here is the caller graph for this function:

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.

This is required because the xlat functions which operate on the input string cannot distinguish between host and path components.

Parameters
[out]outWhere to write the pointer to the new buffer containing the escaped URI.
[in]mod_instconfiguration data.
[in]requestCurrent request
[in]handleto use.
[in]uriconfiguration data.
Returns
  • Length of data written to buffer (excluding NULL).
  • < 0 if an error occurred.

Definition at line 2565 of file rest.c.

+ Here is the call graph for this function:

+ Here is the caller graph for this function:

Variable Documentation

const FR_NAME_NUMBER http_auth_table[]
Initial value:
= {
{ "none", HTTP_AUTH_NONE },
{ "srp", HTTP_AUTH_TLS_SRP },
{ "basic", HTTP_AUTH_BASIC },
{ "digest", HTTP_AUTH_DIGEST },
{ "digest-ie", HTTP_AUTH_DIGEST_IE },
{ "gss-negotiate", HTTP_AUTH_GSSNEGOTIATE },
{ "ntlm", HTTP_AUTH_NTLM },
{ "ntlm-winbind", HTTP_AUTH_NTLM_WB },
{ "any", HTTP_AUTH_ANY },
{ "safe", HTTP_AUTH_ANY_SAFE },
{ NULL , -1 }
}

Definition at line 169 of file rest.c.

const http_body_type_t http_body_type_supported[HTTP_BODY_NUM_ENTRIES]
Initial value:

Table of encoder/decoder support.

Indexes in this table match the http_body_type_t enum, and should be updated if additional enum values are added.

See Also
http_body_type_t

Definition at line 46 of file rest.c.

const FR_NAME_NUMBER http_body_type_table[]
Initial value:
= {
{ "unknown", HTTP_BODY_UNKNOWN },
{ "unsupported", HTTP_BODY_UNSUPPORTED },
{ "unavailable", HTTP_BODY_UNAVAILABLE },
{ "invalid", HTTP_BODY_INVALID },
{ "none", HTTP_BODY_NONE },
{ "post", HTTP_BODY_POST },
{ "json", HTTP_BODY_JSON },
{ "xml", HTTP_BODY_XML },
{ "yaml", HTTP_BODY_YAML },
{ "html", HTTP_BODY_HTML },
{ "plain", HTTP_BODY_PLAIN },
{ NULL , -1 }
}

Conversion table for type config values.

Textual names for http_body_type_t enum values, used by the configuration parser.

See Also
http_body_Type_t
fr_str2int
fr_int2str

Definition at line 153 of file rest.c.

const FR_NAME_NUMBER http_content_type_table[]
Initial value:
= {
{ "application/x-www-form-urlencoded", HTTP_BODY_POST },
{ "application/json", HTTP_BODY_JSON },
{ "text/html", HTTP_BODY_HTML },
{ "text/plain", HTTP_BODY_PLAIN },
{ "text/xml", HTTP_BODY_XML },
{ "text/yaml", HTTP_BODY_YAML },
{ "text/x-yaml", HTTP_BODY_YAML },
{ "application/yaml", HTTP_BODY_YAML },
{ "application/x-yaml", HTTP_BODY_YAML },
{ NULL , -1 }
}

Conversion table for "Content-Type" header values.

Used by rest_response_header for parsing incoming headers.

Values we expect to see in the 'Content-Type:' header of the incoming response.

Some data types (like YAML) do no have standard MIME types defined, so multiple types, are listed here.

See Also
http_body_Type_t
fr_str2int
fr_int2str

Definition at line 198 of file rest.c.

const unsigned long http_curl_auth[HTTP_AUTH_NUM_ENTRIES]
Initial value:
= {
0,
0,
CURLAUTH_ANY,
CURLAUTH_ANYSAFE
}
#define CURLAUTH_BASIC
Definition: rest.c:73
#define CURLAUTH_DIGEST
Definition: rest.c:76
#define CURLAUTH_NTLM
Definition: rest.c:85
#define CURLAUTH_NTLM_WB
Definition: rest.c:88
#define CURLAUTH_GSSNEGOTIATE
Definition: rest.c:82
#define CURLAUTH_DIGEST_IE
Definition: rest.c:79
#define CURLOPT_TLSAUTH_SRP
Definition: rest.c:70

Definition at line 106 of file rest.c.

const FR_NAME_NUMBER http_method_table[]
Initial value:
= {
{ "UNKNOWN", HTTP_METHOD_UNKNOWN },
{ "GET", HTTP_METHOD_GET },
{ "POST", HTTP_METHOD_POST },
{ "PUT", HTTP_METHOD_PUT },
{ "PATCH", HTTP_METHOD_PATCH },
{ "DELETE", HTTP_METHOD_DELETE },
{ NULL , -1 }
}

Conversion table for method config values.

HTTP verb strings for http_method_t enum values. Used by libcurl in the status line of the outgoing HTTP header, by rest_response_header for decoding incoming HTTP responses, and by the configuration parser.

Note
must be kept in sync with http_method_t enum.
See Also
http_method_t
fr_str2int
fr_int2str

Definition at line 133 of file rest.c.