lib/include/radsec/radsec.h

   1 /** \file radsec.h
   2     \brief Public interface for libradsec.  */
   3
   4 /* See the file COPYING for licensing information.  */
   5
   6 #ifndef _RADSEC_RADSEC_H_
   7 #define _RADSEC_RADSEC_H_ 1
   8
   9 #include <unistd.h>
  10 #include <stdint.h>
  11
  12 #include <arpa/inet.h>
  13 #include <sys/time.h>
  14
  15 enum rs_error_code {
  16     RSE_OK = 0,
  17     RSE_NOMEM = 1,
  18     RSE_NOSYS = 2,
  19     RSE_INVALID_CTX = 3,
  20     RSE_INVALID_CONN = 4,
  21     RSE_CONN_TYPE_MISMATCH = 5,
  22     RSE_FR = 6,
  23     RSE_BADADDR = 7,
  24     RSE_NOPEER = 8,
  25     RSE_EVENT = 9,              /* libevent error.  */
  26     RSE_SOCKERR = 10,
  27     RSE_CONFIG = 11,
  28     RSE_BADAUTH = 12,
  29     RSE_INTERNAL = 13,
  30     RSE_SSLERR = 14,            /* OpenSSL error.  */
  31     RSE_INVALID_PKT = 15,
  32     RSE_TIMEOUT_CONN = 16,      /* Connection timeout.  */
  33     RSE_INVAL = 17,             /* Invalid argument.  */
  34     RSE_TIMEOUT_IO = 18,        /* I/O timeout.  */
  35     RSE_TIMEOUT= 19,            /* High level timeout.  */
  36     RSE_DISCO = 20,
  37     RSE_INUSE = 21,
  38     RSE_PACKET_TOO_SMALL = 22,
  39     RSE_PACKET_TOO_LARGE = 23,
  40     RSE_ATTR_OVERFLOW = 24,
  41     RSE_ATTR_TOO_SMALL = 25,
  42     RSE_ATTR_TOO_LARGE = 26,
  43     RSE_ATTR_UNKNOWN = 27,
  44     RSE_ATTR_BAD_NAME = 28,
  45     RSE_ATTR_VALUE_MALFORMED = 29,
  46     RSE_ATTR_INVALID = 30,
  47     RSE_TOO_MANY_ATTRS = 31,
  48     RSE_ATTR_TYPE_UNKNOWN = 32,
  49     RSE_MSG_AUTH_LEN = 33,
  50     RSE_MSG_AUTH_WRONG = 34,
  51     RSE_REQUEST_REQUIRED = 35,
  52     RSE_INVALID_REQUEST_CODE = 36,
  53     RSE_AUTH_VECTOR_WRONG = 37,
  54     RSE_INVALID_RESPONSE_CODE = 38,
  55     RSE_INVALID_RESPONSE_ID = 39,
  56     RSE_INVALID_RESPONSE_SRC = 40,
  57     RSE_NO_PACKET_DATA = 41,
  58     RSE_VENDOR_UNKNOWN = 42,
  59     RSE_MAX = RSE_VENDOR_UNKNOWN
  60 };
  61
  62 enum rs_conn_type {
  63     RS_CONN_TYPE_NONE = 0,
  64     RS_CONN_TYPE_UDP,
  65     RS_CONN_TYPE_TCP,
  66     RS_CONN_TYPE_TLS,
  67     RS_CONN_TYPE_DTLS,
  68 };
  69 typedef unsigned int rs_conn_type_t;
  70
  71 typedef enum rs_attr_type_t {
  72     RS_TYPE_INVALID = 0,                /**< Invalid data type */
  73     RS_TYPE_STRING,                     /**< printable-text */
  74     RS_TYPE_INTEGER,                    /**< a 32-bit unsigned integer */
  75     RS_TYPE_IPADDR,                     /**< an IPv4 address */
  76     RS_TYPE_DATE,                       /**< a 32-bit date, of seconds since January 1, 1970 */
  77     RS_TYPE_OCTETS,                     /**< a sequence of binary octets */
  78     RS_TYPE_IFID,                       /**< an Interface Id */
  79     RS_TYPE_IPV6ADDR,                   /**< an IPv6 address */
  80     RS_TYPE_IPV6PREFIX,                 /**< an IPv6 prefix */
  81     RS_TYPE_BYTE,                       /**< an 8-bit integer */
  82     RS_TYPE_SHORT,                      /**< a 16-bit integer */
  83 } rs_attr_type_t;
  84
  85 #define PW_ACCESS_REQUEST               1
  86 #define PW_ACCESS_ACCEPT                2
  87 #define PW_ACCESS_REJECT                3
  88 #define PW_ACCOUNTING_REQUEST           4
  89 #define PW_ACCOUNTING_RESPONSE          5
  90 #define PW_ACCOUNTING_STATUS            6
  91 #define PW_PASSWORD_REQUEST             7
  92 #define PW_PASSWORD_ACK                 8
  93 #define PW_PASSWORD_REJECT              9
  94 #define PW_ACCOUNTING_MESSAGE           10
  95 #define PW_ACCESS_CHALLENGE             11
  96 #define PW_STATUS_SERVER                12
  97 #define PW_STATUS_CLIENT                13
  98 #define PW_DISCONNECT_REQUEST           40
  99 #define PW_DISCONNECT_ACK               41
 100 #define PW_DISCONNECT_NAK               42
 101 #define PW_COA_REQUEST                  43
 102 #define PW_COA_ACK                      44
 103 #define PW_COA_NAK                      45
 104
 105 #if defined (__cplusplus)
 106 extern "C" {
 107 #endif
 108
 109 /* Data types.  */
 110 struct rs_context;              /* radsec-impl.h */
 111 struct rs_connection;           /* radsec-impl.h */
 112 struct rs_packet;               /* radsec-impl.h */
 113 struct rs_conn;                 /* radsec-impl.h */
 114 struct rs_error;                /* radsec-impl.h */
 115 struct rs_peer;                 /* radsec-impl.h */
 116 struct radius_packet;           /* <radius/client.h> */
 117 struct value_pair;              /* <radius/client.h> */
 118 struct event_base;              /* <event2/event-internal.h> */
 119
 120 typedef void *(*rs_calloc_fp) (size_t nmemb, size_t size);
 121 typedef void *(*rs_malloc_fp) (size_t size);
 122 typedef void (*rs_free_fp) (void *ptr);
 123 typedef void *(*rs_realloc_fp) (void *ptr, size_t size);
 124 struct rs_alloc_scheme {
 125     rs_calloc_fp calloc;
 126     rs_malloc_fp malloc;
 127     rs_free_fp free;
 128     rs_realloc_fp realloc;
 129 };
 130
 131 typedef void (*rs_conn_connected_cb) (void *user_data /* FIXME: peer? */ );
 132 typedef void (*rs_conn_disconnected_cb) (void *user_data /* FIXME: reason? */ );
 133 typedef void (*rs_conn_packet_received_cb) (struct rs_packet *packet,
 134                                             void *user_data);
 135 typedef void (*rs_conn_packet_sent_cb) (void *user_data);
 136 struct rs_conn_callbacks {
 137     /** Callback invoked when the connection has been established.  */
 138     rs_conn_connected_cb connected_cb;
 139     /** Callback invoked when the connection has been torn down.  */
 140     rs_conn_disconnected_cb disconnected_cb;
 141     /** Callback invoked when a packet was received.  */
 142     rs_conn_packet_received_cb received_cb;
 143     /** Callback invoked when a packet was successfully sent.  */
 144     rs_conn_packet_sent_cb sent_cb;
 145 };
 146
 147 typedef struct value_pair rs_avp;
 148 typedef const struct value_pair rs_const_avp;
 149
 150 /* Function prototypes.  */
 151
 152 /*************/
 153 /* Context.  */
 154 /*************/
 155 /** Create a context.  Freed by calling \a rs_context_destroy.  Note
 156     that the context must not be freed before all other libradsec
 157     objects have been freed.
 158
 159     \a ctx Address of pointer to a struct rs_context.  This is the
 160     output of this function.
 161
 162     \return RSE_OK (0) on success or RSE_NOMEM on out of memory.  */
 163 int rs_context_create(struct rs_context **ctx);
 164
 165 /** Free a context.  Note that the context must not be freed before
 166     all other libradsec objects have been freed.  */
 167 void rs_context_destroy(struct rs_context *ctx);
 168
 169 /** Set allocation scheme to use.  \a scheme is the allocation scheme
 170     to use, see \a rs_alloc_scheme.  \return On success, RSE_OK (0) is
 171     returned.  On error, !0 is returned and a struct \a rs_error is
 172     pushed on the error stack for the context.  The error can be
 173     accessed using \a rs_err_ctx_pop.  */
 174 int rs_context_set_alloc_scheme(struct rs_context *ctx,
 175                                 struct rs_alloc_scheme *scheme);
 176
 177 /** Read configuration file. \a config_file is the path of the
 178     configuration file to read.  \return On success, RSE_OK (0) is
 179     returned.  On error, !0 is returned and a struct \a rs_error is
 180     pushed on the error stack for the context.  The error can be
 181     accessed using \a rs_err_ctx_pop.  */
 182 int rs_context_read_config(struct rs_context *ctx, const char *config_file);
 183
 184 /****************/
 185 /* Connection.  */
 186 /****************/
 187 /** Create a connection.  \a conn is the address of a pointer to an \a
 188     rs_connection, the output.  Free the connection using \a
 189     rs_conn_destroy.  Note that a connection must not be freed before
 190     all packets associated with the connection have been freed.  A
 191     packet is associated with a connection when it's created (\a
 192     rs_packet_create) or received (\a rs_conn_receive_packet).
 193
 194     If \a config is not NULL it should be the name of a configuration
 195     found in the config file read in using \a rs_context_read_config.
 196     \return On success, RSE_OK (0) is returned.  On error, !0 is
 197     returned and a struct \a rs_error is pushed on the error stack for
 198     the context.  The error can be accessed using \a
 199     rs_err_ctx_pop.  */
 200 int rs_conn_create(struct rs_context *ctx,
 201                    struct rs_connection **conn,
 202                    const char *config);
 203
 204 /** Not implemented.  */
 205 int rs_conn_add_listener(struct rs_connection *conn,
 206                          rs_conn_type_t type,
 207                          const char *hostname,
 208                          int port);
 209 /** Disconnect connection \a conn.  \return RSE_OK (0) on success, !0
 210  * on error.  On error, errno is set appropriately.  */
 211 int rs_conn_disconnect (struct rs_connection *conn);
 212
 213 /** Disconnect and free memory allocated for connection \a conn.  Note
 214     that a connection must not be freed before all packets associated
 215     with the connection have been freed.  A packet is associated with
 216     a connection when it's created (\a rs_packet_create) or received
 217     (\a rs_conn_receive_packet).  \return RSE_OK (0) on success, !0 *
 218     on error.  On error, errno is set appropriately. */
 219 int rs_conn_destroy(struct rs_connection *conn);
 220
 221 /** Set connection type for \a conn.  */
 222 void rs_conn_set_type(struct rs_connection *conn, rs_conn_type_t type);
 223
 224 /** Not implemented.  */
 225 int rs_conn_set_eventbase(struct rs_connection *conn, struct event_base *eb);
 226
 227 /** Register callbacks \a cb for connection \a conn.  */
 228 void rs_conn_set_callbacks(struct rs_connection *conn,
 229                            struct rs_conn_callbacks *cb);
 230
 231 /** Remove callbacks for connection \a conn.  */
 232 void rs_conn_del_callbacks(struct rs_connection *conn);
 233
 234 /** Return callbacks registered for connection \a conn.  \return
 235     Installed callbacks are returned.  */
 236 struct rs_conn_callbacks *rs_conn_get_callbacks(struct rs_connection *conn);
 237
 238 /** Not implemented.  */
 239 int rs_conn_select_peer(struct rs_connection *conn, const char *name);
 240
 241 /** Not implemented.  */
 242 int rs_conn_get_current_peer(struct rs_connection *conn,
 243                              const char *name,
 244                              size_t buflen);
 245
 246 /** Special function used in blocking mode, i.e. with no callbacks
 247     registered.  For any other use of libradsec, a \a received_cb
 248     callback should be registered using \a rs_conn_set_callbacks.
 249
 250     If \a req_msg is not NULL, a successfully received RADIUS message
 251     is verified against it.  If \a pkt_out is not NULL it will upon
 252     return contain a pointer to an \a rs_packet containing the new
 253     message.
 254
 255     \return On error or if the connect (TCP only) or read times out,
 256     \a pkt_out will not be changed and one or more errors are pushed
 257     on \a conn (available through \a rs_err_conn_pop).  */
 258 int rs_conn_receive_packet(struct rs_connection *conn,
 259                            struct rs_packet *request,
 260                            struct rs_packet **pkt_out);
 261
 262 /** Get the file descriptor associated with connection \a conn.
 263  * \return File descriptor.  */
 264 int rs_conn_fd(struct rs_connection *conn);
 265
 266 /** Set the timeout value for connection \a conn.  */
 267 void rs_conn_set_timeout(struct rs_connection *conn, struct timeval *tv);
 268
 269 /* Peer -- client and server.  */
 270 int rs_peer_create(struct rs_connection *conn, struct rs_peer **peer_out);
 271 int rs_peer_set_address(struct rs_peer *peer,
 272                         const char *hostname,
 273                         const char *service);
 274 int rs_peer_set_secret(struct rs_peer *peer, const char *secret);
 275 void rs_peer_set_timeout(struct rs_peer *peer, int timeout);
 276 void rs_peer_set_retries(struct rs_peer *peer, int retries);
 277
 278 /************/
 279 /* Packet.  */
 280 /************/
 281 /** Create a packet associated with connection \a conn.  */
 282 int rs_packet_create(struct rs_connection *conn, struct rs_packet **pkt_out);
 283
 284 /** Free all memory allocated for packet \a pkt.  */
 285 void rs_packet_destroy(struct rs_packet *pkt);
 286
 287 /** Send packet \a pkt on the connection associated with \a pkt.  \a
 288     user_data is sent to the \a rs_conn_packet_received_cb callback
 289     registered with the connection.  If no callback is registered with
 290     the connection, the event loop is run by \a rs_packet_send and it
 291     blocks until the packet has been succesfully sent.
 292
 293     \return On success, RSE_OK (0) is returned.  On error, !0 is
 294     returned and a struct \a rs_error is pushed on the error stack for
 295     the connection.  The error can be accessed using \a
 296     rs_err_conn_pop.  */
 297 int rs_packet_send(struct rs_packet *pkt, void *user_data);
 298
 299 /** Create a RADIUS authentication request packet associated with
 300     connection \a conn.  Optionally, User-Name and User-Password
 301     attributes are added to the packet using the data in \a user_name
 302     and \a user_pw.  */
 303 int rs_packet_create_authn_request(struct rs_connection *conn,
 304                                    struct rs_packet **pkt,
 305                                    const char *user_name,
 306                                    const char *user_pw);
 307
 308 /*** Append \a tail to packet \a pkt.  */
 309 int
 310 rs_packet_append_avp(struct rs_packet *pkt,
 311                      unsigned int attribute, unsigned int vendor,
 312                      const void *data, size_t data_len);
 313
 314 /*** Get pointer to \a pkt attribute value pairs. */
 315 void
 316 rs_packet_avps(struct rs_packet *pkt, rs_avp ***vps);
 317
 318 /*** Get RADIUS packet type of \a pkt. */
 319 unsigned int
 320 rs_packet_code(struct rs_packet *pkt);
 321
 322 /*** Get RADIUS AVP from \a pkt. */
 323 rs_const_avp *
 324 rs_packet_find_avp(struct rs_packet *pkt, unsigned int attr, unsigned int vendor);
 325
 326 /*** Set packet identifier in \a pkt; returns old identifier */
 327 int
 328 rs_packet_set_id (struct rs_packet *pkt, int id);
 329
 330 /************/
 331 /* Config.  */
 332 /************/
 333 /** Find the realm named \a name in the configuration file previoiusly
 334     read in using \a rs_context_read_config.  */
 335 struct rs_realm *rs_conf_find_realm(struct rs_context *ctx, const char *name);
 336
 337 /***********/
 338 /* Error.  */
 339 /***********/
 340 /** Create a struct \a rs_error and push it on a FIFO associated with
 341     context \a ctx.  Note: The depth of the error stack is one (1) at
 342     the moment.  This will change in a future release.  */
 343 int rs_err_ctx_push(struct rs_context *ctx, int code, const char *fmt, ...);
 344 int rs_err_ctx_push_fl(struct rs_context *ctx,
 345                        int code,
 346                        const char *file,
 347                        int line,
 348                        const char *fmt,
 349                        ...);
 350 /** Pop the first error from the error FIFO associated with context \a
 351     ctx or NULL if there are no errors in the FIFO.  */
 352 struct rs_error *rs_err_ctx_pop(struct rs_context *ctx);
 353
 354 /** Create a struct \a rs_error and push it on a FIFO associated with
 355     connection \a conn.  Note: The depth of the error stack is one (1)
 356     at the moment.  This will change in a future release.  */
 357 int rs_err_conn_push(struct rs_connection *conn,
 358                      int code,
 359                      const char *fmt,
 360                      ...);
 361 int rs_err_conn_push_fl(struct rs_connection *conn,
 362                         int code,
 363                         const char *file,
 364                         int line,
 365                         const char *fmt,
 366                         ...);
 367 /** Pop the first error from the error FIFO associated with connection
 368     \a conn or NULL if there are no errors in the FIFO.  */
 369 struct rs_error *rs_err_conn_pop(struct rs_connection *conn);
 370
 371 int rs_err_conn_peek_code (struct rs_connection *conn);
 372 void rs_err_free(struct rs_error *err);
 373 char *rs_err_msg(struct rs_error *err);
 374 int rs_err_code(struct rs_error *err, int dofree_flag);
 375
 376 /************/
 377 /* AVPs.    */
 378 /************/
 379 #define rs_avp_is_string(vp)      (rs_avp_typeof(vp) == RS_TYPE_STRING)
 380 #define rs_avp_is_integer(vp)     (rs_avp_typeof(vp) == RS_TYPE_INTEGER)
 381 #define rs_avp_is_ipaddr(vp)      (rs_avp_typeof(vp) == RS_TYPE_IPADDR)
 382 #define rs_avp_is_date(vp)        (rs_avp_typeof(vp) == RS_TYPE_DATE)
 383 #define rs_avp_is_octets(vp)      (rs_avp_typeof(vp) == RS_TYPE_OCTETS)
 384 #define rs_avp_is_ifid(vp)        (rs_avp_typeof(vp) == RS_TYPE_IFID)
 385 #define rs_avp_is_ipv6addr(vp)    (rs_avp_typeof(vp) == RS_TYPE_IPV6ADDR)
 386 #define rs_avp_is_ipv6prefix(vp)  (rs_avp_typeof(vp) == RS_TYPE_IPV6PREFIX)
 387 #define rs_avp_is_byte(vp)        (rs_avp_typeof(vp) == RS_TYPE_BYTE)
 388 #define rs_avp_is_short(vp)       (rs_avp_typeof(vp) == RS_TYPE_SHORT)
 389 #define rs_avp_is_tlv(vp)         (rs_avp_typeof(vp) == RS_TYPE_TLV)
 390
 391 /**  The maximum length of a RADIUS attribute.
 392  *
 393  *  The RFCs require that a RADIUS attribute transport no more than
 394  *  253 octets of data.  We add an extra byte for a trailing NUL, so
 395  *  that the VALUE_PAIR::vp_strvalue field can be handled as a C
 396  *  string.
 397  */
 398 #define RS_MAX_STRING_LEN         254
 399
 400 void
 401 rs_avp_free(rs_avp **vps);
 402
 403 size_t
 404 rs_avp_length(rs_const_avp *vp);
 405
 406 rs_attr_type_t
 407 rs_avp_typeof(rs_const_avp *vp);
 408
 409 void
 410 rs_avp_attrid(rs_const_avp *vp, unsigned int *attr, unsigned int *vendor);
 411
 412
 413 void
 414 rs_avp_append(rs_avp **head, rs_avp *tail);
 415
 416 rs_avp *
 417 rs_avp_find(rs_avp *vp, unsigned int attr, unsigned int vendor);
 418
 419 rs_const_avp *
 420 rs_avp_find_const(rs_const_avp *vp, unsigned int attr, unsigned int vendor);
 421
 422 rs_avp *
 423 rs_avp_alloc(unsigned int attr, unsigned int vendor);
 424
 425 rs_avp *
 426 rs_avp_dup(rs_const_avp *vp);
 427
 428 int
 429 rs_avp_delete(rs_avp **first, unsigned int attr, unsigned int vendor);
 430
 431 rs_avp *
 432 rs_avp_next(rs_avp *avp);
 433
 434 rs_const_avp *
 435 rs_avp_next_const(rs_const_avp *avp);
 436
 437 const char *
 438 rs_avp_string_value(rs_const_avp *vp);
 439
 440 int
 441 rs_avp_string_set(rs_avp *vp, const char *str);
 442
 443 uint32_t
 444 rs_avp_integer_value(rs_const_avp *vp);
 445
 446 int
 447 rs_avp_integer_set(rs_avp *vp, uint32_t val);
 448
 449 uint32_t
 450 rs_avp_ipaddr_value(rs_const_avp *vp);
 451
 452 int
 453 rs_avp_ipaddr_set(rs_avp *vp, struct in_addr in);
 454
 455 time_t
 456 rs_avp_date_value(rs_const_avp *vp);
 457
 458 int
 459 rs_avp_date_set(rs_avp *vp, time_t date);
 460
 461 const unsigned char *
 462 rs_avp_octets_value_const_ptr(rs_const_avp *vp);
 463
 464 unsigned char *
 465 rs_avp_octets_value_ptr(rs_avp *vp);
 466
 467 int
 468 rs_avp_octets_value_byref(rs_avp *vp,
 469                           unsigned char **p,
 470                           size_t *len);
 471
 472 int
 473 rs_avp_octets_value(rs_const_avp *vp,
 474                     unsigned char *buf,
 475                     size_t *len);
 476
 477 int
 478 rs_avp_fragmented_value(rs_const_avp *vps,
 479                         unsigned char *buf,
 480                         size_t *len);
 481
 482 int
 483 rs_avp_octets_set(rs_avp *vp,
 484                   const unsigned char *buf,
 485                   size_t len);
 486
 487 int
 488 rs_avp_ifid_value(rs_const_avp *vp, uint8_t val[8]);
 489
 490 int
 491 rs_avp_ifid_set(rs_avp *vp, const uint8_t val[8]);
 492
 493 uint8_t
 494 rs_avp_byte_value(rs_const_avp *vp);
 495
 496 int
 497 rs_avp_byte_set(rs_avp *vp, uint8_t val);
 498
 499 uint16_t
 500 rs_avp_short_value(rs_const_avp *vp);
 501
 502 int
 503 rs_avp_short_set(rs_avp *vp, uint16_t val);
 504
 505 size_t
 506 rs_avp_display_value(rs_const_avp *vp,
 507                      char *buffer,
 508                      size_t buflen);
 509
 510 int
 511 rs_attr_find(const char *name,
 512              unsigned int *attr,
 513              unsigned int *vendor);
 514
 515 const char *
 516 rs_avp_name(rs_const_avp *vp);
 517
 518 #if defined (__cplusplus)
 519 }
 520 #endif
 521
 522 #endif /* _RADSEC_RADSEC_H_ */
 523
 524 /* Local Variables: */
 525 /* c-file-style: "stroustrup" */
 526 /* End: */