The FreeRADIUS server  $Id: 15bac2a4c627c01d1aa2047687b3418955ac7f00 $
Data Structures | Macros | Typedefs | Enumerations | Functions | Variables
rest.h File Reference

Function prototypes and datatypes for the REST (HTTP) transport. More...

#include <freeradius-devel/curl/base.h>
#include <freeradius-devel/curl/config.h>
#include <freeradius-devel/server/pairmove.h>
#include <freeradius-devel/util/slab.h>
#include <freeradius-devel/json/base.h>
+ Include dependency graph for rest.h:
+ This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  rlm_rest_call_env_t
 
struct  rlm_rest_call_env_t.request
 
struct  rlm_rest_call_env_t.response
 
struct  rlm_rest_curl_context_t
 
struct  rlm_rest_request_t
 
struct  rlm_rest_response_t
 
struct  rlm_rest_section_request_t
 
struct  rlm_rest_section_response_t
 
struct  rlm_rest_section_t
 
struct  rlm_rest_t
 
struct  rlm_rest_thread_t
 Thread specific rlm_rest instance data. More...
 
struct  rlm_rest_xlat_rctx_t
 Stores the state of a yielded xlat. More...
 

Macros

#define REST_BODY_ALLOC_CHUNK   1024
 
#define REST_BODY_MAX_ATTRS   256
 
#define REST_BODY_MAX_LEN   8192
 
#define rest_get_handle_code(_handle)   (((rlm_rest_curl_context_t*)((fr_curl_io_request_t*)(_handle))->uctx)->response.code)
 
#define rest_get_handle_type(_handle)   (((rlm_rest_curl_context_t*)((fr_curl_io_request_t*)(_handle))->uctx)->response.type)
 
#define REST_URI_MAX_LEN   2048
 

Typedefs

typedef size_t(* rest_read_t) (void *ptr, size_t size, size_t nmemb, void *userdata)
 

Enumerations

enum  http_auth_type_t {
  REST_HTTP_AUTH_UNKNOWN = 0 ,
  REST_HTTP_AUTH_NONE ,
  REST_HTTP_AUTH_TLS_SRP ,
  REST_HTTP_AUTH_BASIC ,
  REST_HTTP_AUTH_DIGEST ,
  REST_HTTP_AUTH_DIGEST_IE ,
  REST_HTTP_AUTH_GSSNEGOTIATE ,
  REST_HTTP_AUTH_NTLM ,
  REST_HTTP_AUTH_NTLM_WB ,
  REST_HTTP_AUTH_ANY ,
  REST_HTTP_AUTH_ANY_SAFE ,
  REST_HTTP_AUTH_NUM_ENTRIES
}
 
enum  http_body_type_t {
  REST_HTTP_BODY_UNKNOWN = 0 ,
  REST_HTTP_BODY_UNSUPPORTED ,
  REST_HTTP_BODY_UNAVAILABLE ,
  REST_HTTP_BODY_INVALID ,
  REST_HTTP_BODY_NONE ,
  REST_HTTP_BODY_CUSTOM ,
  REST_HTTP_BODY_POST ,
  REST_HTTP_BODY_JSON ,
  REST_HTTP_BODY_XML ,
  REST_HTTP_BODY_YAML ,
  REST_HTTP_BODY_HTML ,
  REST_HTTP_BODY_PLAIN ,
  REST_HTTP_BODY_NUM_ENTRIES
}
 
enum  http_method_t {
  REST_HTTP_METHOD_UNKNOWN = 0 ,
  REST_HTTP_METHOD_GET ,
  REST_HTTP_METHOD_POST ,
  REST_HTTP_METHOD_PUT ,
  REST_HTTP_METHOD_PATCH ,
  REST_HTTP_METHOD_DELETE ,
  REST_HTTP_METHOD_CUSTOM
}
 
enum  read_state_t {
  READ_STATE_INIT = 0 ,
  READ_STATE_ATTR_BEGIN ,
  READ_STATE_ATTR_CONT ,
  READ_STATE_END
}
 
enum  write_state_t {
  WRITE_STATE_INIT = 0 ,
  WRITE_STATE_PARSE_HEADERS ,
  WRITE_STATE_PARSE_CONTENT ,
  WRITE_STATE_DISCARD
}
 

Functions

size_t rest_get_handle_data (char const **out, fr_curl_io_request_t *handle)
 Extracts pointer to buffer containing response data. More...
 
void rest_io_module_signal (module_ctx_t const *mctx, request_t *request, fr_signal_t action)
 
void rest_io_xlat_signal (xlat_ctx_t const *xctx, request_t *request, fr_signal_t action)
 Handle asynchronous cancellation of a request. More...
 
void * rest_mod_conn_create (TALLOC_CTX *ctx, void *instance, fr_time_delta_t timeout)
 
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. More...
 
void rest_response_debug (request_t *request, fr_curl_io_request_t *handle)
 Print out the response text. More...
 
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)
 
void rest_response_error (request_t *request, fr_curl_io_request_t *handle)
 Print out the response text as error lines. More...
 
size_t rest_uri_escape (UNUSED request_t *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_t *request, fr_curl_io_request_t *randle, char const *uri)
 Unescapes the host portion of a URI string. More...
 

Variables

HIDDEN fr_dict_attr_t const * attr_rest_http_body
 
HIDDEN fr_dict_attr_t const * attr_rest_http_header
 
HIDDEN fr_dict_attr_t const * attr_rest_http_status_code
 
HIDDEN fr_dict_t const * dict_freeradius
 
fr_table_num_sorted_t const http_auth_table []
 
size_t http_auth_table_len
 
const http_body_type_t http_body_type_supported [REST_HTTP_BODY_NUM_ENTRIES]
 Table of encoder/decoder support. More...
 
fr_table_num_sorted_t const http_body_type_table []
 Conversion table for type config values. More...
 
size_t http_body_type_table_len
 
fr_table_num_sorted_t const http_content_type_table []
 Conversion table for "Content-Type" header values. More...
 
size_t http_content_type_table_len
 
const unsigned long http_curl_auth [REST_HTTP_AUTH_NUM_ENTRIES]
 
fr_table_num_sorted_t const http_method_table []
 Conversion table for method config values. More...
 
size_t http_method_table_len
 
char const * rest_no_proxy
 Magic pointer value for determining if we should disable proxying. More...
 

Detailed Description

Function prototypes and datatypes for the REST (HTTP) transport.

Id
2e6b27549bff96c1e759cf24245aff02f629bb54

Definition in file rest.h.


Data Structure Documentation

◆ rlm_rest_call_env_t

struct rlm_rest_call_env_t

Definition at line 271 of file rest.h.

Data Fields
struct rlm_rest_call_env_t request
struct rlm_rest_call_env_t response

◆ rlm_rest_call_env_t.request

struct rlm_rest_call_env_t.request

Definition at line 272 of file rest.h.

Data Fields
fr_value_box_t * data Custom data to send in requests.
fr_value_box_list_t * header Headers to place in the request.
fr_value_box_t * password Password to use for authentication.
fr_value_box_t * uri URI to send HTTP request to.
fr_value_box_t * username Username to use for authentication.

◆ rlm_rest_call_env_t.response

struct rlm_rest_call_env_t.response

Definition at line 280 of file rest.h.

Data Fields
tmpl_t * header Where to write response headers.

◆ rlm_rest_curl_context_t

struct rlm_rest_curl_context_t

Definition at line 252 of file rest.h.

+ Collaboration diagram for rlm_rest_curl_context_t:
Data Fields
char * body Pointer to the buffer which contains body data/ Only used when not performing chunked encoding.
struct curl_slist * headers Any HTTP headers which will be sent with the request.
rlm_rest_request_t request Request context data.
rlm_rest_response_t response Response context data.

◆ rlm_rest_request_t

struct rlm_rest_request_t

Definition at line 210 of file rest.h.

+ Collaboration diagram for rlm_rest_request_t:
Data Fields
size_t chunk Chunk size.
fr_dcursor_t cursor Cursor pointing to the start of the list to encode.
void * encoder Encoder specific data.
rlm_rest_t const * instance This instance of rlm_rest.
request_t * request Current request.
rlm_rest_section_t const * section Section configuration.
read_state_t state Encoder state.

◆ rlm_rest_response_t

struct rlm_rest_response_t

Definition at line 228 of file rest.h.

+ Collaboration diagram for rlm_rest_response_t:
Data Fields
size_t alloc Space allocated for buffer.
char * buffer Raw incoming HTTP data.
int code HTTP Status Code.
void * decoder Decoder specific data.
http_body_type_t force_to Force decoding the body type as a particular encoding.
tmpl_t * header Where to create pairs representing HTTP response headers.

If NULL no headers will be parsed other than content-type.

rlm_rest_t const * instance This instance of rlm_rest.
request_t * request Current request.
rlm_rest_section_t const * section Section configuration.
write_state_t state Decoder state.
http_body_type_t type HTTP Content Type.
size_t used Space used in buffer.

◆ rlm_rest_section_request_t

struct rlm_rest_section_request_t

Definition at line 108 of file rest.h.

Data Fields
http_auth_type_t auth HTTP auth type.
bool auth_is_set Whether a value was provided for auth_str.
http_body_type_t body What encoding type should be used.
char const * body_str The string version of the encoding/content type.
uint32_t chunk Max chunk-size (mainly for testing the encoders)
http_method_t method What HTTP method should be used, GET, POST etc...
char const * method_str The string version of the HTTP method.
char const * proxy Send request via this proxy.
bool require_auth Whether HTTP-Auth is required or not.

◆ rlm_rest_section_response_t

struct rlm_rest_section_response_t

Definition at line 126 of file rest.h.

Data Fields
http_body_type_t force_to Override the Content-Type header in the response to force decoding as a particular type.
char const * force_to_str Force decoding with this decoder.
size_t max_body_in Maximum size of incoming data.

◆ rlm_rest_section_t

struct rlm_rest_section_t

Definition at line 137 of file rest.h.

+ Collaboration diagram for rlm_rest_section_t:
Data Fields
char const * name Section name.
rlm_rest_section_request_t request Request configuration.
rlm_rest_section_response_t response Response configuration.
fr_time_delta_t timeout Timeout timeval.
fr_curl_tls_t tls

◆ rlm_rest_t

struct rlm_rest_t

Definition at line 151 of file rest.h.

+ Collaboration diagram for rlm_rest_t:
Data Fields
rlm_rest_section_t accounting Configuration specific to accounting.
rlm_rest_section_t authenticate Configuration specific to authentication.
rlm_rest_section_t authorize Configuration specific to authorisation.
fr_curl_conn_config_t conn_config Configuration of slab allocated connection handles.
char const * connect_proxy Send request via this proxy.
bool fail_body_decode Force body decoding to fail for debugging purposes.
bool fail_header_decode Force header decoding to fail for debugging purposes.
int http_negotiation What HTTP version to negotiate, and how to.

negotiate it. One or the CURL_HTTP_VERSION_ macros.

bool multiplex Whether to perform multiple requests using a single connection.
rlm_rest_section_t post_auth Configuration specific to Post-auth.
rlm_rest_section_t xlat Configuration specific to xlat.

◆ rlm_rest_thread_t

struct rlm_rest_thread_t

Thread specific rlm_rest instance data.

Definition at line 180 of file rest.h.

+ Collaboration diagram for rlm_rest_thread_t:
Data Fields
rlm_rest_t const * inst Instance of rlm_rest.
fr_curl_handle_t * mhandle Thread specific multi handle.

Serves as the dispatch and coralling structure for REST requests.

rest_slab_list_t * slab Slab list for connection handles.

◆ rlm_rest_xlat_rctx_t

struct rlm_rest_xlat_rctx_t

Stores the state of a yielded xlat.

Definition at line 266 of file rest.h.

+ Collaboration diagram for rlm_rest_xlat_rctx_t:
Data Fields
fr_curl_io_request_t * handle curl easy handle servicing our request.
rlm_rest_section_t section Our mutated section config.

Macro Definition Documentation

◆ REST_BODY_ALLOC_CHUNK

#define REST_BODY_ALLOC_CHUNK   1024

Definition at line 40 of file rest.h.

◆ REST_BODY_MAX_ATTRS

#define REST_BODY_MAX_ATTRS   256

Definition at line 41 of file rest.h.

◆ REST_BODY_MAX_LEN

#define REST_BODY_MAX_LEN   8192

Definition at line 39 of file rest.h.

◆ rest_get_handle_code

#define rest_get_handle_code (   _handle)    (((rlm_rest_curl_context_t*)((fr_curl_io_request_t*)(_handle))->uctx)->response.code)

Definition at line 316 of file rest.h.

◆ rest_get_handle_type

#define rest_get_handle_type (   _handle)    (((rlm_rest_curl_context_t*)((fr_curl_io_request_t*)(_handle))->uctx)->response.type)

Definition at line 318 of file rest.h.

◆ REST_URI_MAX_LEN

#define REST_URI_MAX_LEN   2048

Definition at line 38 of file rest.h.

Typedef Documentation

◆ rest_read_t

typedef size_t(* rest_read_t) (void *ptr, size_t size, size_t nmemb, void *userdata)

Definition at line 295 of file rest.h.

Enumeration Type Documentation

◆ http_auth_type_t

Enumerator
REST_HTTP_AUTH_UNKNOWN 
REST_HTTP_AUTH_NONE 
REST_HTTP_AUTH_TLS_SRP 
REST_HTTP_AUTH_BASIC 
REST_HTTP_AUTH_DIGEST 
REST_HTTP_AUTH_DIGEST_IE 
REST_HTTP_AUTH_GSSNEGOTIATE 
REST_HTTP_AUTH_NTLM 
REST_HTTP_AUTH_NTLM_WB 
REST_HTTP_AUTH_ANY 
REST_HTTP_AUTH_ANY_SAFE 
REST_HTTP_AUTH_NUM_ENTRIES 

Definition at line 69 of file rest.h.

◆ http_body_type_t

Enumerator
REST_HTTP_BODY_UNKNOWN 
REST_HTTP_BODY_UNSUPPORTED 
REST_HTTP_BODY_UNAVAILABLE 
REST_HTTP_BODY_INVALID 
REST_HTTP_BODY_NONE 
REST_HTTP_BODY_CUSTOM 
REST_HTTP_BODY_POST 
REST_HTTP_BODY_JSON 
REST_HTTP_BODY_XML 
REST_HTTP_BODY_YAML 
REST_HTTP_BODY_HTML 
REST_HTTP_BODY_PLAIN 
REST_HTTP_BODY_NUM_ENTRIES 

Definition at line 53 of file rest.h.

◆ http_method_t

Enumerator
REST_HTTP_METHOD_UNKNOWN 
REST_HTTP_METHOD_GET 
REST_HTTP_METHOD_POST 
REST_HTTP_METHOD_PUT 
REST_HTTP_METHOD_PATCH 
REST_HTTP_METHOD_DELETE 
REST_HTTP_METHOD_CUSTOM 

Must always come last, should not be in method table.

Definition at line 43 of file rest.h.

◆ read_state_t

Enumerator
READ_STATE_INIT 
READ_STATE_ATTR_BEGIN 
READ_STATE_ATTR_CONT 
READ_STATE_END 

Definition at line 190 of file rest.h.

◆ write_state_t

Enumerator
WRITE_STATE_INIT 
WRITE_STATE_PARSE_HEADERS 
WRITE_STATE_PARSE_CONTENT 
WRITE_STATE_DISCARD 

Definition at line 200 of file rest.h.

Function Documentation

◆ rest_get_handle_data()

size_t rest_get_handle_data ( char const **  out,
fr_curl_io_request_t randle 
)

Extracts pointer to buffer containing response data.

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

Definition at line 1625 of file rest.c.

+ Here is the caller graph for this function:

◆ rest_io_module_signal()

void rest_io_module_signal ( module_ctx_t const *  mctx,
request_t request,
fr_signal_t  action 
)

◆ rest_io_xlat_signal()

void rest_io_xlat_signal ( xlat_ctx_t const *  xctx,
request_t request,
fr_signal_t  action 
)

Handle asynchronous cancellation of a request.

If we're signalled that the request has been cancelled (FR_SIGNAL_CANCEL). Cleanup any pending state and release the connection handle back into the pool.

Definition at line 56 of file io.c.

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ rest_mod_conn_create()

void* rest_mod_conn_create ( TALLOC_CTX *  ctx,
void *  instance,
fr_time_delta_t  timeout 
)

◆ rest_request_config()

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.

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_t is passing through.

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

Parameters
[in]mctxcall data.
[in]sectionconfiguration data.
[in]randleto 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]uribuffer containing the expanded URI to send the request to.
[in]body_data(optional) custom body data. Must persist whilst we're writing data out to the socket. Must be a talloced buffer which is \0 terminated.
Returns
  • 0 on success (all opts configured).
  • -1 on failure.

Definition at line 1726 of file rest.c.

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ rest_response_debug()

void rest_response_debug ( request_t request,
fr_curl_io_request_t handle 
)

Print out the response text.

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

Definition at line 1568 of file rest.c.

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ rest_response_decode()

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 
)

◆ rest_response_error()

void rest_response_error ( request_t request,
fr_curl_io_request_t handle 
)

Print out the response text as error lines.

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

Definition at line 1543 of file rest.c.

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ rest_uri_escape()

size_t rest_uri_escape ( UNUSED request_t 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 2125 of file rest.c.

+ Here is the call graph for this function:

◆ rest_uri_host_unescape()

ssize_t rest_uri_host_unescape ( char **  out,
UNUSED rlm_rest_t const *  inst,
request_t request,
fr_curl_io_request_t randle,
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]instof rlm_rest.
[in]requestCurrent request
[in]randleto use.
[in]uriconfiguration data.
Returns
  • Length of data written to buffer (excluding NULL).
  • < 0 if an error occurred.

Definition at line 2151 of file rest.c.

+ Here is the call graph for this function:

Variable Documentation

◆ attr_rest_http_body

HIDDEN fr_dict_attr_t const* attr_rest_http_body
extern

Definition at line 279 of file rlm_rest.c.

◆ attr_rest_http_header

HIDDEN fr_dict_attr_t const* attr_rest_http_header
extern

Definition at line 280 of file rlm_rest.c.

◆ attr_rest_http_status_code

HIDDEN fr_dict_attr_t const* attr_rest_http_status_code
extern

Definition at line 281 of file rlm_rest.c.

◆ dict_freeradius

HIDDEN fr_dict_t const* dict_freeradius
extern

Definition at line 73 of file base.c.

◆ http_auth_table

fr_table_num_sorted_t const http_auth_table[]
extern

Definition at line 160 of file rest.c.

◆ http_auth_table_len

size_t http_auth_table_len
extern

Definition at line 172 of file rest.c.

◆ http_body_type_supported

const http_body_type_t http_body_type_supported[REST_HTTP_BODY_NUM_ENTRIES]
extern

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 51 of file rest.c.

◆ http_body_type_table

fr_table_num_sorted_t const http_body_type_table[]
extern

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_table_value_by_str
fr_table_str_by_value

Definition at line 145 of file rest.c.

◆ http_body_type_table_len

size_t http_body_type_table_len
extern

Definition at line 158 of file rest.c.

◆ http_content_type_table

fr_table_num_sorted_t const http_content_type_table[]
extern

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_table_value_by_str
fr_table_str_by_value

Definition at line 188 of file rest.c.

◆ http_content_type_table_len

size_t http_content_type_table_len
extern

Definition at line 199 of file rest.c.

◆ http_curl_auth

const unsigned long http_curl_auth[REST_HTTP_AUTH_NUM_ENTRIES]
extern

Definition at line 100 of file rest.c.

◆ http_method_table

fr_table_num_sorted_t const http_method_table[]
extern

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_table_value_by_str
fr_table_str_by_value

Definition at line 126 of file rest.c.

◆ http_method_table_len

size_t http_method_table_len
extern

Definition at line 134 of file rest.c.

◆ rest_no_proxy

char const* rest_no_proxy
extern

Magic pointer value for determining if we should disable proxying.

Magic pointer value for determining if we should disable proxying.

Definition at line 93 of file rlm_rest.c.