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