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