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>
Go to the source code of this file.
|  | 
| 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_CRL
,
 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
 }
 | 
|  | 
|  | 
| size_t | rest_get_handle_data (char const **out, fr_curl_io_request_t *handle) | 
|  | Extracts pointer to buffer containing response data. 
 | 
|  | 
| 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. 
 | 
|  | 
| 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. 
 | 
|  | 
| 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. 
 | 
|  | 
| void | rest_response_debug (request_t *request, fr_curl_io_request_t *handle) | 
|  | Print out the response text. 
 | 
|  | 
| 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. 
 | 
|  | 
| size_t | rest_uri_escape (UNUSED request_t *request, char *out, size_t outlen, char const *raw, UNUSED void *arg) | 
|  | URL encodes a string. 
 | 
|  | 
| 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. 
 | 
|  | 
Function prototypes and datatypes for the REST (HTTP) transport. 
- Id
- ec880d6a039b96d63073db8b2d0eebb233a9df9f 
- Copyright
- 2012-2016 Arran Cudbard-Bell (a.cud.nosp@m.bard.nosp@m.b@fre.nosp@m.erad.nosp@m.ius.o.nosp@m.rg) 
Definition in file rest.h.
◆ rlm_rest_call_env_t
      
        
          | struct rlm_rest_call_env_t | 
      
 
 
◆ rlm_rest_call_env_t.request
      
        
          | struct rlm_rest_call_env_t.request | 
      
 
Definition at line 282 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 290 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 261 of file rest.h.
 
| 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 | 
      
 
 
◆ rlm_rest_response_t
      
        
          | struct rlm_rest_response_t | 
      
 
Definition at line 237 of file rest.h.
 
| 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_conf_t
      
        
          | struct rlm_rest_section_conf_t | 
      
 
 
◆ rlm_rest_section_request_t
      
        
          | struct rlm_rest_section_request_t | 
      
 
Definition at line 109 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 127 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 | 
      
 
 
◆ rlm_rest_t
Definition at line 161 of file rest.h.
 
| Data Fields | 
|---|
| 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. | 
| fr_rb_tree_t | sections | Tree of sections with module call found by call_env parsing. | 
| bool | sections_init | Has the tree been initialised. | 
| rlm_rest_section_t | xlat | Configuration specific to xlat. | 
 
 
◆ rlm_rest_thread_t
Thread specific rlm_rest instance data. 
Definition at line 189 of file rest.h.
| 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 275 of file rest.h.
 
 
◆ REST_BODY_ALLOC_CHUNK
      
        
          | #define REST_BODY_ALLOC_CHUNK   1024 | 
      
 
 
◆ REST_BODY_MAX_ATTRS
      
        
          | #define REST_BODY_MAX_ATTRS   256 | 
      
 
 
◆ REST_BODY_MAX_LEN
      
        
          | #define REST_BODY_MAX_LEN   8192 | 
      
 
 
◆ rest_get_handle_code
◆ rest_get_handle_type
◆ REST_URI_MAX_LEN
◆ rest_read_t
◆ 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 70 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_CRL |  | 
| 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 199 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 209 of file rest.h.
 
 
◆ rest_get_handle_data()
Extracts pointer to buffer containing response data. 
- Parameters
- 
  
    | [out] | out | Where to write the pointer to the buffer. |  | [in] | randle | used for the last request. |  
 
- Returns
- 
- 0 if no data i available.
- > 0 if data is available. 
 
Definition at line 1623 of file rest.c.
 
 
◆ rest_io_module_signal()
◆ rest_io_xlat_signal()
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.
 
 
◆ rest_mod_conn_create()
      
        
          | void * rest_mod_conn_create | ( | TALLOC_CTX * | ctx, | 
        
          |  |  | void * | instance, | 
        
          |  |  | fr_time_delta_t | timeout | 
        
          |  | ) |  |  | 
      
 
 
◆ rest_request_config()
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] | mctx | call data. |  | [in] | section | configuration data. |  | [in] | randle | to configure. |  | [in] | request | Current request. |  | [in] | method | to use (HTTP verbs PUT, POST, DELETE etc...). |  | [in] | type | Content-Type for request encoding, also sets the default for decoding. |  | [in] | uri | buffer 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 1787 of file rest.c.
 
 
◆ rest_request_config_add_header()
Adds an additional header to a handle to use in the next reques. 
- Parameters
- 
  
    | [in] | request | Current request. |  | [in] | randle | used for the next request. |  | [in] | header | to add. |  | [in] | validate | whether to perform basic checks on the header |  
 
- Returns
- 
- 0 on success.
- -1 on failure. 
 
Definition at line 1707 of file rest.c.
 
 
◆ rest_response_debug()
Print out the response text. 
- Parameters
- 
  
  
Definition at line 1566 of file rest.c.
 
 
◆ rest_response_decode()
◆ rest_response_error()
Print out the response text as error lines. 
- Parameters
- 
  
  
Definition at line 1541 of file rest.c.
 
 
◆ rest_uri_escape()
URL encodes a string. 
Encode special chars as per RFC 3986 section 4.
- Parameters
- 
  
    | [in] | request | Current request. |  | [out] | out | Where to write escaped string. |  | [in] | outlen | Size of out buffer. |  | [in] | raw | string to be urlencoded. |  | [in] | arg | pointer, gives context for escaping. |  
 
- Returns
- length of data written to out (excluding NULL). 
Definition at line 2140 of file rest.c.
 
 
◆ rest_uri_host_unescape()
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] | out | Where to write the pointer to the new buffer containing the escaped URI. |  | [in] | inst | of rlm_rest. |  | [in] | request | Current request |  | [in] | randle | to use. |  | [in] | uri | configuration data. |  
 
- Returns
- 
- Length of data written to buffer (excluding NULL).
- < 0 if an error occurred. 
 
Definition at line 2166 of file rest.c.
 
 
◆ attr_rest_http_body
◆ attr_rest_http_header
◆ attr_rest_http_status_code
◆ dict_freeradius
◆ http_auth_table
◆ http_auth_table_len
◆ http_body_type_supported
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 52 of file rest.c.
 
 
◆ http_body_type_table
◆ http_body_type_table_len
  
  | 
        
          | size_t http_body_type_table_len |  | extern | 
 
 
◆ 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_table_value_by_str 
- 
fr_table_str_by_value 
Definition at line 191 of file rest.c.
 
 
◆ http_content_type_table_len
  
  | 
        
          | size_t http_content_type_table_len |  | extern | 
 
 
◆ http_curl_auth
◆ 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_table_value_by_str 
- 
fr_table_str_by_value 
Definition at line 128 of file rest.c.
 
 
◆ http_method_table_len
◆ 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 82 of file rlm_rest.c.