2 \brief Public interface for libradsec. */
4 /* See the file COPYING for licensing information. */
15 RSE_CONN_TYPE_MISMATCH = 5,
16 RSE_FR = 6, /* FreeRADIUS error. */
19 RSE_EVENT = 9, /* libevent error. */
24 RSE_SSLERR = 14, /* OpenSSL error. */
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. */
34 RS_CONN_TYPE_NONE = 0,
40 typedef unsigned int rs_conn_type_t;
43 #if defined (__cplusplus)
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> */
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 {
66 rs_realloc_fp realloc;
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,
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;
86 /* Function prototypes. */
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.
95 \a ctx Address of pointer to a struct rs_context. This is the output.
97 \a dict Name of a FreeRADIUS dictionary.
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);
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);
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);
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);
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).
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
138 int rs_conn_create(struct rs_context *ctx,
139 struct rs_connection **conn,
142 /** Not implemented. */
143 int rs_conn_add_listener(struct rs_connection *conn,
145 const char *hostname,
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);
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);
159 /** Set connection type for \a conn. */
160 void rs_conn_set_type(struct rs_connection *conn, rs_conn_type_t type);
162 /** Not implemented. */
163 int rs_conn_set_eventbase(struct rs_connection *conn, struct event_base *eb);
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);
169 /** Remove callbacks for connection \a conn. */
170 void rs_conn_del_callbacks(struct rs_connection *conn);
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);
176 /** Not implemented. */
177 int rs_conn_select_peer(struct rs_connection *conn, const char *name);
179 /** Not implemented. */
180 int rs_conn_get_current_peer(struct rs_connection *conn,
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.
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
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);
200 /** Get the file descriptor associated with connection \a conn.
201 * \return File descriptor. */
202 int rs_conn_fd(struct rs_connection *conn);
204 /** Set the timeout value for connection \a conn. */
205 void rs_conn_set_timeout(struct rs_connection *conn, struct timeval *tv);
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);
219 /** Create a packet associated with connection \a conn. */
220 int rs_packet_create(struct rs_connection *conn, struct rs_packet **pkt_out);
222 /** Free all memory allocated for packet \a pkt. */
223 void rs_packet_destroy(struct rs_packet *pkt);
225 /** Add attribute \a attr to packet \a pkt. */
226 void rs_packet_add_attr(struct rs_packet *pkt, struct rs_attr *attr);
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.
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
238 int rs_packet_send(struct rs_packet *pkt, void *user_data);
240 /** Return the FreeRADIUS packet associated with packet \a pkt. */
241 struct radius_packet *rs_packet_frpkt(struct rs_packet *pkt);
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
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);
255 /* FIXME: Replace (or complement) with a wrapper for paircreate(). */
256 /** Create a RADIUS attribute of type \a type and with the value \a
258 int rs_attr_create(struct rs_connection *conn,
259 struct rs_attr **attr,
262 /** Free memory for RADIUS attribute \a attr. */
263 void rs_attr_destroy(struct rs_attr *attr);
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);
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,
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);
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,
296 int rs_err_conn_push_fl(struct rs_connection *conn,
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);
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);
311 #if defined (__cplusplus)
315 /* Local Variables: */
316 /* c-file-style: "stroustrup" */