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