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