src/modules/rlm_rest/rest.h

   1 /** Function prototypes datatypes for the REST (HTTP) transport.
   2  *
   3  * @file rest.h
   4  *
   5  * Version:     $Id$
   6  *
   7  *   This program is free software; you can redistribute it and/or modify
   8  *   it under the terms of the GNU General Public License as published by
   9  *   the Free Software Foundation; either version 2 of the License, or
  10  *   (at your option) any later version.
  11  *
  12  *   This program is distributed in the hope that it will be useful,
  13  *   but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15  *   GNU General Public License for more details.
  16  *
  17  *   You should have received a copy of the GNU General Public License
  18  *   along with this program; if not, write to the Free Software
  19  *   Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA
  20  *
  21  * Copyright 2012  Arran Cudbard-Bell <a.cudbard-bell@freeradius.org>
  22  */
  23 #include <freeradius-devel/ident.h>
  24 #include <freeradius-devel/connection.h>
  25
  26 RCSIDH(other_h, "$Id$")
  27
  28
  29 #define REST_URI_MAX_LEN                2048
  30 #define REST_BODY_MAX_LEN               8192
  31 #define REST_BODY_INCR                  512
  32 #define REST_BODY_MAX_ATTRS             256
  33
  34 typedef enum {
  35         HTTP_METHOD_CUSTOM,
  36         HTTP_METHOD_GET,
  37         HTTP_METHOD_POST,
  38         HTTP_METHOD_PUT,
  39         HTTP_METHOD_DELETE
  40 } http_method_t;
  41
  42 typedef enum {
  43         HTTP_BODY_UNKNOWN = 0,
  44         HTTP_BODY_UNSUPPORTED,
  45         HTTP_BODY_INVALID,
  46         HTTP_BODY_POST,
  47         HTTP_BODY_JSON,
  48         HTTP_BODY_XML,
  49         HTTP_BODY_YAML,
  50         HTTP_BODY_HTML,
  51         HTTP_BODY_PLAIN,
  52         HTTP_BODY_NUM_ENTRIES
  53 } http_body_type_t;
  54
  55 typedef enum {
  56         HTTP_AUTH_UNKNOWN = 0,
  57         HTTP_AUTH_NONE,
  58         HTTP_AUTH_TLS_SRP,
  59         HTTP_AUTH_BASIC,
  60         HTTP_AUTH_DIGEST,
  61         HTTP_AUTH_DIGEST_IE,
  62         HTTP_AUTH_GSSNEGOTIATE,
  63         HTTP_AUTH_NTLM,
  64         HTTP_AUTH_NTLM_WB,
  65         HTTP_AUTH_ANY,
  66         HTTP_AUTH_ANY_SAFE,
  67         HTTP_AUTH_NUM_ENTRIES
  68 } http_auth_type_t;
  69
  70 /*
  71  *      Must be updated (in rest.c) if additional values are added to
  72  *      http_body_type_t
  73  */
  74 extern const http_body_type_t http_body_type_supported[HTTP_BODY_NUM_ENTRIES];
  75
  76 extern const http_body_type_t http_curl_auth[HTTP_AUTH_NUM_ENTRIES];
  77
  78 extern const FR_NAME_NUMBER http_auth_table[];
  79
  80 extern const FR_NAME_NUMBER http_method_table[];
  81
  82 extern const FR_NAME_NUMBER http_body_table[];
  83
  84 extern const FR_NAME_NUMBER http_content_header_table[];
  85
  86 /*
  87  *      Structure for section configuration
  88  */
  89 typedef struct rlm_rest_section_t {
  90         const char *name;
  91         char *uri;
  92
  93         char *method_str;
  94         http_method_t method;
  95
  96         char *body_str;
  97         http_body_type_t body;
  98
  99         char *username;
 100         char *password;
 101         char *auth_str;
 102         http_auth_type_t auth;
 103         int require_auth;
 104
 105         char *certificate_file;
 106         int file_type;
 107         char *private_key_file;
 108         char *private_key_password;
 109         char *ca_file;
 110         char *ca_path;
 111         char *random_file;
 112         int check_cert_cn;
 113
 114         int timeout;
 115         unsigned int chunk;
 116 } rlm_rest_section_t;
 117
 118 /*
 119  *      Structure for module configuration
 120  */
 121 typedef struct rlm_rest_t {
 122         const char *xlat_name;
 123
 124         char *connect_uri;
 125
 126         fr_connection_pool_t *conn_pool;
 127
 128         rlm_rest_section_t authorize;
 129         rlm_rest_section_t authenticate;
 130         rlm_rest_section_t accounting;
 131         rlm_rest_section_t checksimul;
 132         rlm_rest_section_t postauth;
 133 } rlm_rest_t;
 134
 135 /*
 136  *      States for stream based attribute encoders
 137  */
 138 typedef enum {
 139         READ_STATE_INIT = 0,
 140         READ_STATE_ATTR_BEGIN,
 141         READ_STATE_ATTR_CONT,
 142         READ_STATE_END,
 143 } read_state_t;
 144
 145 /*
 146  *      States for the response parser
 147  */
 148 typedef enum {
 149         WRITE_STATE_INIT = 0,
 150         WRITE_STATE_PARSE_HEADERS,
 151         WRITE_STATE_PARSE_CONTENT,
 152         WRITE_STATE_DISCARD,
 153 } write_state_t;
 154
 155 /*
 156  *      Outbound data context (passed to CURLOPT_READFUNCTION as CURLOPT_READDATA)
 157  */
 158 typedef struct rlm_rest_read_t {
 159         rlm_rest_t      *instance;
 160         REQUEST         *request;
 161         read_state_t    state;
 162
 163         VALUE_PAIR      **first;
 164         VALUE_PAIR      **next;
 165
 166         unsigned int    chunk;
 167 } rlm_rest_read_t;
 168
 169 /*
 170  *      Curl inbound data context (passed to CURLOPT_WRITEFUNCTION and
 171  *      CURLOPT_HEADERFUNCTION as CURLOPT_WRITEDATA and CURLOPT_HEADERDATA)
 172  */
 173 typedef struct rlm_rest_write_t {
 174         rlm_rest_t       *instance;
 175         REQUEST          *request;
 176         write_state_t    state;
 177
 178         char             *buffer;       /* HTTP incoming raw data */
 179         size_t           alloc;         /* Space allocated for buffer */
 180         size_t           used;          /* Space used in buffer */
 181
 182         int              code;          /* HTTP Status Code */
 183         http_body_type_t type;          /* HTTP Content Type */
 184 } rlm_rest_write_t;
 185
 186 /*
 187  *      Curl context data
 188  */
 189 typedef struct rlm_rest_curl_context_t {
 190         struct curl_slist       *headers;
 191         char                    *body;
 192         rlm_rest_read_t         read;
 193         rlm_rest_write_t        write;
 194 } rlm_rest_curl_context_t;
 195
 196 /*
 197  *      Connection API handle
 198  */
 199 typedef struct rlm_rest_handle_t {
 200         void    *handle;        /* Real Handle */
 201         void    *ctx;           /* Context */
 202 } rlm_rest_handle_t;
 203
 204 /*
 205  *      Function prototype for rest_read_wrapper. Matches CURL's
 206  *      CURLOPT_READFUNCTION prototype.
 207  */
 208 typedef size_t (*rest_read_t)(void *ptr, size_t size, size_t nmemb,
 209                               void *userdata);
 210
 211 /*
 212  *      Connection API callbacks
 213  */
 214 int rest_init(rlm_rest_t *instance);
 215
 216 void rest_cleanup(void);
 217
 218 void *rest_socket_create(void *instance);
 219
 220 int rest_socket_alive(void *instance, void *handle);
 221
 222 int rest_socket_delete(void *instance, void *handle);
 223
 224 /*
 225  *      Request processing API
 226  */
 227 int rest_request_config(rlm_rest_t *instance,
 228                         rlm_rest_section_t *section, REQUEST *request,
 229                         void *handle, http_method_t method,
 230                         http_body_type_t type, char *uri);
 231
 232 int rest_request_perform(rlm_rest_t *instance, rlm_rest_section_t *section,
 233                          void *handle);
 234
 235 int rest_request_decode(rlm_rest_t *instance,
 236                         UNUSED rlm_rest_section_t *section, REQUEST *request,
 237                         void *handle);
 238
 239 void rest_request_cleanup(rlm_rest_t *instance, rlm_rest_section_t *section,
 240                           void *handle);
 241
 242 #define rest_get_handle_code(handle)(((rlm_rest_curl_context_t*)((rlm_rest_handle_t*)handle)->ctx)->write.code)
 243
 244 #define rest_get_handle_type(handle)(((rlm_rest_curl_context_t*)((rlm_rest_handle_t*)handle)->ctx)->write.type)
 245
 246 /*
 247  *      Helper functions
 248  */
 249 ssize_t rest_uri_build(rlm_rest_t *instance, rlm_rest_section_t *section,
 250                        REQUEST *request, char *buffer, size_t bufsize);