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 #include <unistd.h>
   7 #include <sys/time.h>
   8
   9 enum rs_error_code {
  10     RSE_OK = 0,
  11     RSE_NOMEM = 1,
  12     RSE_NOSYS = 2,
  13     RSE_INVALID_CTX = 3,
  14     RSE_INVALID_CONN = 4,
  15     RSE_CONN_TYPE_MISMATCH = 5,
  16     RSE_FR = 6,                 /* FreeRADIUS error.  */
  17     RSE_BADADDR = 7,
  18     RSE_NOPEER = 8,
  19     RSE_EVENT = 9,              /* libevent error.  */
  20     RSE_SOCKERR = 10,
  21     RSE_CONFIG = 11,
  22     RSE_BADAUTH = 12,
  23     RSE_INTERNAL = 13,
  24     RSE_SSLERR = 14,            /* OpenSSL error.  */
  25     RSE_INVALID_PKT = 15,
  26     RSE_TIMEOUT_CONN = 16,      /* Connection timeout.  */
  27     RSE_INVAL = 17,             /* Invalid argument.  */
  28     RSE_TIMEOUT_IO = 18,        /* I/O timeout.  */
  29     RSE_TIMEOUT = 19,           /* High level timeout.  */
  30     RSE_DISCO = 20,
  31 };
  32
  33 enum rs_conn_type {
  34     RS_CONN_TYPE_NONE = 0,
  35     RS_CONN_TYPE_UDP,
  36     RS_CONN_TYPE_TCP,
  37     RS_CONN_TYPE_TLS,
  38     RS_CONN_TYPE_DTLS,
  39 };
  40 typedef unsigned int rs_conn_type_t;
  41
  42
  43 #if defined (__cplusplus)
  44 extern "C" {
  45 #endif
  46
  47 /* Data types.  */
  48 struct rs_context;              /* radsec-impl.h */
  49 struct rs_connection;           /* radsec-impl.h */
  50 struct rs_packet;               /* radsec-impl.h */
  51 struct rs_conn;                 /* radsec-impl.h */
  52 struct rs_attr;                 /* radsec-impl.h */
  53 struct rs_error;                /* radsec-impl.h */
  54 struct rs_peer;                 /* radsec-impl.h */
  55 struct radius_packet;           /* <freeradius/libradius.h> */
  56 struct event_base;              /* <event2/event-internal.h> */
  57
  58 typedef void *(*rs_calloc_fp) (size_t nmemb, size_t size);
  59 typedef void *(*rs_malloc_fp) (size_t size);
  60 typedef void (*rs_free_fp) (void *ptr);
  61 typedef void *(*rs_realloc_fp) (void *ptr, size_t size);
  62 struct rs_alloc_scheme {
  63     rs_calloc_fp calloc;
  64     rs_malloc_fp malloc;
  65     rs_free_fp free;
  66     rs_realloc_fp realloc;
  67 };
  68
  69 typedef void (*rs_conn_connected_cb) (void *user_data /* FIXME: peer? */ );
  70 typedef void (*rs_conn_disconnected_cb) (void *user_data /* FIXME: reason? */ );
  71 typedef void (*rs_conn_packet_received_cb) (struct rs_packet *packet,
  72                                             void *user_data);
  73 typedef void (*rs_conn_packet_sent_cb) (void *user_data);
  74 struct rs_conn_callbacks {
  75     /** Callback invoked when the connection has been established.  */
  76     rs_conn_connected_cb connected_cb;
  77     /** Callback invoked when the connection has been torn down.  */
  78     rs_conn_disconnected_cb disconnected_cb;
  79     /** Callback invoked when a packet was received.  */
  80     rs_conn_packet_received_cb received_cb;
  81     /** Callback invoked when a packet was successfully sent.  */
  82     rs_conn_packet_sent_cb sent_cb;
  83 };
  84
  85
  86 /* Function prototypes.  */
  87
  88 /*************/
  89 /* Context.  */
  90 /*************/
  91 /** Create a context.  Freed by calling \a rs_context_destroy.  Note
  92     that the context must not be freed before all other libradsec
  93     objects have been freed.
  94
  95     \a ctx Address of pointer to a struct rs_context.  This is the output.
  96
  97     \a dict Name of a FreeRADIUS dictionary.
  98
  99     \return RSE_OK (0) on success, RSE_NOMEM on out of memory or
 100     RSE_FR on FreeRADIUS initialization error.  */
 101 int rs_context_create(struct rs_context **ctx, const char *dict);
 102
 103 /** Free a context.  Note that the context must not be freed before
 104     all other libradsec objects have been freed.  */
 105 void rs_context_destroy(struct rs_context *ctx);
 106
 107 /** Set allocation scheme to use.  \a scheme is the allocation scheme
 108     to use, see \a rs_alloc_scheme.  \return On success, RSE_OK (0) is
 109     returned.  On error, !0 is returned and a struct \a rs_error is
 110     pushed on the error stack for the context.  The error can be
 111     accessed using \a rs_err_ctx_pop.  */
 112 int rs_context_set_alloc_scheme(struct rs_context *ctx,
 113                                 struct rs_alloc_scheme *scheme);
 114
 115 /** Read configuration file. \a config_file is the path of the
 116     configuration file to read.  \return On success, RSE_OK (0) is
 117     returned.  On error, !0 is returned and a struct \a rs_error is
 118     pushed on the error stack for the context.  The error can be
 119     accessed using \a rs_err_ctx_pop.  */
 120 int rs_context_read_config(struct rs_context *ctx, const char *config_file);
 121
 122 /****************/
 123 /* Connection.  */
 124 /****************/
 125 /** Create a connection.  \a conn is the address of a pointer to an \a
 126     rs_connection, the output.  Free the connection using \a
 127     rs_conn_destroy.  Note that a connection must not be freed before
 128     all packets associated with the connection have been freed.  A
 129     packet is associated with a connection when it's created (\a
 130     rs_packet_create) or received (\a rs_conn_receive_packet).
 131
 132     If \a config is not NULL it should be the name of a configuration
 133     found in the config file read in using \a rs_context_read_config.
 134     \return On success, RSE_OK (0) is returned.  On error, !0 is
 135     returned and a struct \a rs_error is pushed on the error stack for
 136     the context.  The error can be accessed using \a
 137     rs_err_ctx_pop.  */
 138 int rs_conn_create(struct rs_context *ctx,
 139                    struct rs_connection **conn,
 140                    const char *config);
 141
 142 /** Not implemented.  */
 143 int rs_conn_add_listener(struct rs_connection *conn,
 144                          rs_conn_type_t type,
 145                          const char *hostname,
 146                          int port);
 147 /** Disconnect connection \a conn.  \return RSE_OK (0) on success, !0
 148  * on error.  On error, errno is set appropriately.  */
 149 int rs_conn_disconnect (struct rs_connection *conn);
 150
 151 /** Disconnect and free memory allocated for connection \a conn.  Note
 152     that a connection must not be freed before all packets associated
 153     with the connection have been freed.  A packet is associated with
 154     a connection when it's created (\a rs_packet_create) or received
 155     (\a rs_conn_receive_packet).  \return RSE_OK (0) on success, !0 *
 156     on error.  On error, errno is set appropriately. */
 157 int rs_conn_destroy(struct rs_connection *conn);
 158
 159 /** Set connection type for \a conn.  */
 160 void rs_conn_set_type(struct rs_connection *conn, rs_conn_type_t type);
 161
 162 /** Not implemented.  */
 163 int rs_conn_set_eventbase(struct rs_connection *conn, struct event_base *eb);
 164
 165 /** Register callbacks \a cb for connection \a conn.  */
 166 void rs_conn_set_callbacks(struct rs_connection *conn,
 167                            struct rs_conn_callbacks *cb);
 168
 169 /** Remove callbacks for connection \a conn.  */
 170 void rs_conn_del_callbacks(struct rs_connection *conn);
 171
 172 /** Return callbacks registered for connection \a conn.  \return
 173     Installed callbacks are returned.  */
 174 struct rs_conn_callbacks *rs_conn_get_callbacks(struct rs_connection *conn);
 175
 176 /** Not implemented.  */
 177 int rs_conn_select_peer(struct rs_connection *conn, const char *name);
 178
 179 /** Not implemented.  */
 180 int rs_conn_get_current_peer(struct rs_connection *conn,
 181                              const char *name,
 182                              size_t buflen);
 183
 184 /** Special function used in blocking mode, i.e. with no callbacks
 185     registered.  For any other use of libradsec, a \a received_cb
 186     callback should be registered using \a rs_conn_set_callbacks.
 187
 188     If \a req_msg is not NULL, a successfully received RADIUS message
 189     is verified against it.  If \a pkt_out is not NULL it will upon
 190     return contain a pointer to an \a rs_packet containing the new
 191     message.
 192
 193     \return On error or if the connect (TCP only) or read times out,
 194     \a pkt_out will not be changed and one or more errors are pushed
 195     on \a conn (available through \a rs_err_conn_pop).  */
 196 int rs_conn_receive_packet(struct rs_connection *conn,
 197                            struct rs_packet *request,
 198                            struct rs_packet **pkt_out);
 199
 200 /** Get the file descriptor associated with connection \a conn.
 201  * \return File descriptor.  */
 202 int rs_conn_fd(struct rs_connection *conn);
 203
 204 /** Set the timeout value for connection \a conn.  */
 205 void rs_conn_set_timeout(struct rs_connection *conn, struct timeval *tv);
 206
 207 /* Peer -- client and server.  */
 208 int rs_peer_create(struct rs_connection *conn, struct rs_peer **peer_out);
 209 int rs_peer_set_address(struct rs_peer *peer,
 210                         const char *hostname,
 211                         const char *service);
 212 int rs_peer_set_secret(struct rs_peer *peer, const char *secret);
 213 void rs_peer_set_timeout(struct rs_peer *peer, int timeout);
 214 void rs_peer_set_retries(struct rs_peer *peer, int retries);
 215
 216 /************/
 217 /* Packet.  */
 218 /************/
 219 /** Create a packet associated with connection \a conn.  */
 220 int rs_packet_create(struct rs_connection *conn, struct rs_packet **pkt_out);
 221
 222 /** Free all memory allocated for packet \a pkt.  */
 223 void rs_packet_destroy(struct rs_packet *pkt);
 224
 225 /** Add attribute \a attr to packet \a pkt.  */
 226 void rs_packet_add_attr(struct rs_packet *pkt, struct rs_attr *attr);
 227
 228 /** Send packet \a pkt on the connection associated with \a pkt.  \a
 229     user_data is sent to the \a rs_conn_packet_received_cb callback
 230     registered with the connection.  If no callback is registered with
 231     the connection, the event loop is run by \a rs_packet_send and it
 232     blocks until the packet has been succesfully sent.
 233
 234     \return On success, RSE_OK (0) is returned.  On error, !0 is
 235     returned and a struct \a rs_error is pushed on the error stack for
 236     the connection.  The error can be accessed using \a
 237     rs_err_conn_pop.  */
 238 int rs_packet_send(struct rs_packet *pkt, void *user_data);
 239
 240 /** Return the FreeRADIUS packet associated with packet \a pkt.  */
 241 struct radius_packet *rs_packet_frpkt(struct rs_packet *pkt);
 242
 243 /** Create a RADIUS authentication request packet associated with
 244     connection \a conn.  Optionally, User-Name and User-Password
 245     attributes are added to the packet using the data in \a user_name
 246     and \a user_pw.  */
 247 int rs_packet_create_authn_request(struct rs_connection *conn,
 248                                    struct rs_packet **pkt,
 249                                    const char *user_name,
 250                                    const char *user_pw);
 251
 252 /***************/
 253 /* Attribute.  */
 254 /***************/
 255 /* FIXME: Replace (or complement) with a wrapper for paircreate().  */
 256 /** Create a RADIUS attribute of type \a type and with the value \a
 257     val.  */
 258 int rs_attr_create(struct rs_connection *conn,
 259                    struct rs_attr **attr,
 260                    const char *type,
 261                    const char *val);
 262 /** Free memory for RADIUS attribute \a attr.  */
 263 void rs_attr_destroy(struct rs_attr *attr);
 264
 265 /************/
 266 /* Config.  */
 267 /************/
 268 /** Find the realm named \a name in the configuration file previoiusly
 269     read in using \a rs_context_read_config.  */
 270 struct rs_realm *rs_conf_find_realm(struct rs_context *ctx, const char *name);
 271
 272 /***********/
 273 /* Error.  */
 274 /***********/
 275 /** Create a struct \a rs_error and push it on a FIFO associated with
 276     context \a ctx.  Note: The depth of the error stack is one (1) at
 277     the moment.  This will change in a future release.  */
 278 int rs_err_ctx_push(struct rs_context *ctx, int code, const char *fmt, ...);
 279 int rs_err_ctx_push_fl(struct rs_context *ctx,
 280                        int code,
 281                        const char *file,
 282                        int line,
 283                        const char *fmt,
 284                        ...);
 285 /** Pop the first error from the error FIFO associated with context \a
 286     ctx or NULL if there are no errors in the FIFO.  */
 287 struct rs_error *rs_err_ctx_pop(struct rs_context *ctx);
 288
 289 /** Create a struct \a rs_error and push it on a FIFO associated with
 290     connection \a conn.  Note: The depth of the error stack is one (1)
 291     at the moment.  This will change in a future release.  */
 292 int rs_err_conn_push(struct rs_connection *conn,
 293                      int code,
 294                      const char *fmt,
 295                      ...);
 296 int rs_err_conn_push_fl(struct rs_connection *conn,
 297                         int code,
 298                         const char *file,
 299                         int line,
 300                         const char *fmt,
 301                         ...);
 302 /** Pop the first error from the error FIFO associated with connection
 303     \a conn or NULL if there are no errors in the FIFO.  */
 304 struct rs_error *rs_err_conn_pop(struct rs_connection *conn);
 305
 306 int rs_err_conn_peek_code (struct rs_connection *conn);
 307 void rs_err_free(struct rs_error *err);
 308 char *rs_err_msg(struct rs_error *err);
 309 int rs_err_code(struct rs_error *err, int dofree_flag);
 310
 311 #if defined (__cplusplus)
 312 }
 313 #endif
 314
 315 /* Local Variables: */
 316 /* c-file-style: "stroustrup" */
 317 /* End: */