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

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

#include <freeradius-devel/connection.h>
#include "config.h"
#include <curl/curl.h>
#include "../rlm_json/json.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_curl_context_t
 
struct  rlm_rest_handle_t
 
struct  rlm_rest_request_t
 
struct  rlm_rest_response_t
 
struct  rlm_rest_section_t
 
struct  rlm_rest_t
 

Macros

#define CURL_NO_OLDIES   1
 
#define REST_BODY_INIT   1024
 
#define REST_BODY_MAX_ATTRS   256
 
#define REST_BODY_MAX_LEN   8192
 
#define rest_get_handle_code(_handle)   (((rlm_rest_curl_context_t*)((rlm_rest_handle_t*)_handle)->ctx)->response.code)
 
#define rest_get_handle_type(_handle)   (((rlm_rest_curl_context_t*)((rlm_rest_handle_t*)_handle)->ctx)->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)
 
typedef struct
rlm_rest_curl_context_t 
rlm_rest_curl_context_t
 
typedef struct rlm_rest_handle_t rlm_rest_handle_t
 
typedef struct rlm_rest_request_t rlm_rest_request_t
 
typedef struct rlm_rest_response_t rlm_rest_response_t
 
typedef struct rlm_rest_section_t rlm_rest_section_t
 
typedef struct rlm_rest_t rlm_rest_t
 

Enumerations

enum  http_auth_type_t {
  HTTP_AUTH_UNKNOWN = 0,
  HTTP_AUTH_NONE,
  HTTP_AUTH_TLS_SRP,
  HTTP_AUTH_BASIC,
  HTTP_AUTH_DIGEST,
  HTTP_AUTH_DIGEST_IE,
  HTTP_AUTH_GSSNEGOTIATE,
  HTTP_AUTH_NTLM,
  HTTP_AUTH_NTLM_WB,
  HTTP_AUTH_ANY,
  HTTP_AUTH_ANY_SAFE,
  HTTP_AUTH_NUM_ENTRIES
}
 
enum  http_body_type_t {
  HTTP_BODY_UNKNOWN = 0,
  HTTP_BODY_UNSUPPORTED,
  HTTP_BODY_UNAVAILABLE,
  HTTP_BODY_INVALID,
  HTTP_BODY_NONE,
  HTTP_BODY_CUSTOM_XLAT,
  HTTP_BODY_CUSTOM_LITERAL,
  HTTP_BODY_POST,
  HTTP_BODY_JSON,
  HTTP_BODY_XML,
  HTTP_BODY_YAML,
  HTTP_BODY_HTML,
  HTTP_BODY_PLAIN,
  HTTP_BODY_NUM_ENTRIES
}
 
enum  http_method_t {
  HTTP_METHOD_UNKNOWN = 0,
  HTTP_METHOD_GET,
  HTTP_METHOD_POST,
  HTTP_METHOD_PUT,
  HTTP_METHOD_PATCH,
  HTTP_METHOD_DELETE,
  HTTP_METHOD_CUSTOM
}
 
enum  read_state_t {
  READ_STATE_INIT = 0,
  READ_STATE_ATTR_BEGIN,
  READ_STATE_ATTR_CONT,
  READ_STATE_ATTR_END,
  READ_STATE_END
}
 
enum  write_state_t {
  WRITE_STATE_INIT = 0,
  WRITE_STATE_PARSE_HEADERS,
  WRITE_STATE_PARSE_CONTENT,
  WRITE_STATE_DISCARD
}
 

Functions

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)
 Create a new connection pool handle. More...
 
void rest_cleanup (void)
 Cleans up after libcurl. 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 (rlm_rest_t const *instance, rlm_rest_section_t *section, void *handle)
 
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
 
int int rest_request_perform (rlm_rest_t const *instance, rlm_rest_section_t *section, REQUEST *request, void *handle)
 
int rest_response_decode (rlm_rest_t const *instance, UNUSED rlm_rest_section_t *section, REQUEST *request, void *handle)
 
void rest_response_error (REQUEST *request, rlm_rest_handle_t *handle)
 Print out the response text as error lines. More...
 
ssize_t rest_uri_build (char **out, rlm_rest_t *instance, REQUEST *request, char const *uri)
 
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

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

Id:
3465c8c502f31e738ebb6353260c7d5164cd3dc6

Definition in file rest.h.


Data Structure Documentation

struct rlm_rest_curl_context_t

Definition at line 223 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.
struct rlm_rest_handle_t

Definition at line 237 of file rest.h.

+ Collaboration diagram for rlm_rest_handle_t:
Data Fields
rlm_rest_curl_context_t * ctx Context.
void * handle Real Handle.
struct rlm_rest_request_t

Definition at line 188 of file rest.h.

+ Collaboration diagram for rlm_rest_request_t:
Data Fields
size_t chunk Chunk size.
vp_cursor_t cursor Cursor pointing to the start of the list to encode.
void * encoder Encoder specific data.
rlm_rest_t * instance This instance of rlm_rest.
REQUEST * request Current request.
read_state_t state Encoder state.
struct rlm_rest_response_t

Definition at line 204 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.
rlm_rest_t * instance This instance of rlm_rest.
REQUEST * request Current request.
write_state_t state Decoder state.
http_body_type_t type HTTP Content Type.
size_t used Space used in buffer.
struct rlm_rest_section_t

Definition at line 105 of file rest.h.

Data Fields
http_auth_type_t auth HTTP auth type.
char const * auth_str The string version of the Auth-Type.
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)
char const * data Custom body data (optional).
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.
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 * name Section name.
char const * password Password used for HTTP-Auth.
char const * proxy Send request via this proxy.
bool require_auth Whether HTTP-Auth is required or not.
long timeout Timeout in ms.
struct timeval timeout_tv Timeout timeval.
char const * tls_ca_file
char const * tls_ca_path
char const * tls_certificate_file
bool tls_check_cert
bool tls_check_cert_cn
char const * tls_private_key_file
char const * tls_private_key_password
char const * tls_random_file
char const * uri URI to send HTTP request to.
char const * username Username used for HTTP-Auth.
struct rlm_rest_t

Definition at line 146 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.
rlm_rest_section_t checksimul Configuration specific to simultaneous session checking.
char const * connect_proxy Send request via this proxy.
char const * connect_uri URI we attempt to connect to, to pre-establish TCP connections.
fr_connection_pool_t * pool Pointer to the connection pool.
rlm_rest_section_t post_auth Configuration specific to Post-auth.
char const * xlat_name Instance name.

Macro Definition Documentation

#define CURL_NO_OLDIES   1

Definition at line 31 of file rest.h.

#define REST_BODY_INIT   1024

Definition at line 41 of file rest.h.

#define REST_BODY_MAX_ATTRS   256

Definition at line 42 of file rest.h.

#define REST_BODY_MAX_LEN   8192

Definition at line 40 of file rest.h.

#define rest_get_handle_code (   _handle)    (((rlm_rest_curl_context_t*)((rlm_rest_handle_t*)_handle)->ctx)->response.code)

Definition at line 282 of file rest.h.

#define rest_get_handle_type (   _handle)    (((rlm_rest_curl_context_t*)((rlm_rest_handle_t*)_handle)->ctx)->response.type)

Definition at line 284 of file rest.h.

#define REST_URI_MAX_LEN   2048

Definition at line 39 of file rest.h.

Typedef Documentation

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

Definition at line 246 of file rest.h.

typedef struct rlm_rest_t rlm_rest_t

Enumeration Type Documentation

Enumerator
HTTP_AUTH_UNKNOWN 
HTTP_AUTH_NONE 
HTTP_AUTH_TLS_SRP 
HTTP_AUTH_BASIC 
HTTP_AUTH_DIGEST 
HTTP_AUTH_DIGEST_IE 
HTTP_AUTH_GSSNEGOTIATE 
HTTP_AUTH_NTLM 
HTTP_AUTH_NTLM_WB 
HTTP_AUTH_ANY 
HTTP_AUTH_ANY_SAFE 
HTTP_AUTH_NUM_ENTRIES 

Definition at line 71 of file rest.h.

Enumerator
HTTP_BODY_UNKNOWN 
HTTP_BODY_UNSUPPORTED 
HTTP_BODY_UNAVAILABLE 
HTTP_BODY_INVALID 
HTTP_BODY_NONE 
HTTP_BODY_CUSTOM_XLAT 
HTTP_BODY_CUSTOM_LITERAL 
HTTP_BODY_POST 
HTTP_BODY_JSON 
HTTP_BODY_XML 
HTTP_BODY_YAML 
HTTP_BODY_HTML 
HTTP_BODY_PLAIN 
HTTP_BODY_NUM_ENTRIES 

Definition at line 54 of file rest.h.

Enumerator
HTTP_METHOD_UNKNOWN 
HTTP_METHOD_GET 
HTTP_METHOD_POST 
HTTP_METHOD_PUT 
HTTP_METHOD_PATCH 
HTTP_METHOD_DELETE 
HTTP_METHOD_CUSTOM 

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

Definition at line 44 of file rest.h.

Enumerator
READ_STATE_INIT 
READ_STATE_ATTR_BEGIN 
READ_STATE_ATTR_CONT 
READ_STATE_ATTR_END 
READ_STATE_END 

Definition at line 167 of file rest.h.

Enumerator
WRITE_STATE_INIT 
WRITE_STATE_PARSE_HEADERS 
WRITE_STATE_PARSE_CONTENT 
WRITE_STATE_DISCARD 

Definition at line 178 of file rest.h.

Function Documentation

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 
)

Create a new connection pool handle.

Create a new connection to Couchbase within the pool and initialize information associated with the connection instance.

Parameters
ctxThe connection parent context.
instanceThe module instance.
timeoutMaximum time to establish the connection.
Returns
  • New connection handle.
  • NULL on error.

Create a new connection pool handle.

Create a new ldap connection and allocate memory for a new rlm_handle_t

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

Create a new connection to Couchbase within the pool and initialize information associated with the connection instance.

Parameters
ctxThe connection parent context.
instanceThe module instance.
timeoutMaximum time to establish the connection.
Returns
  • New connection handle.
  • NULL on error.

Create a new connection pool handle.

Create a new ldap connection and allocate memory for a new rlm_handle_t

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 68 of file mod.c.

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:

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 ( rlm_rest_t const *  instance,
rlm_rest_section_t section,
void *  handle 
)
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 
)
int int rest_request_perform ( rlm_rest_t const *  instance,
rlm_rest_section_t section,
REQUEST request,
void *  handle 
)
int rest_response_decode ( rlm_rest_t const *  instance,
UNUSED rlm_rest_section_t section,
REQUEST request,
void *  handle 
)
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:

ssize_t rest_uri_build ( char **  out,
rlm_rest_t instance,
REQUEST request,
char const *  uri 
)
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[]

Definition at line 169 of file rest.c.

const http_body_type_t http_body_type_supported[HTTP_BODY_NUM_ENTRIES]

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[]

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[]

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]

Definition at line 106 of file rest.c.

const FR_NAME_NUMBER http_method_table[]

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.