2 \brief Public interface for libradsec. */
4 /* Copyright 2010-2013 NORDUnet A/S. All rights reserved.
5 See LICENSE for licensing information. */
7 #ifndef _RADSEC_RADSEC_H_
8 #define _RADSEC_RADSEC_H_ 1
13 #ifdef HAVE_SYS_TIME_H
16 #ifdef HAVE_ARPA_INET_H
17 #include <arpa/inet.h>
32 RSE_CONN_TYPE_MISMATCH = 5,
35 RSE_EVENT = 9, /* libevent error. */
40 RSE_SSLERR = 14, /* OpenSSL error. */
42 RSE_TIMEOUT_CONN = 16, /* Connection timeout. */
43 RSE_INVAL = 17, /* Invalid argument. */
44 RSE_TIMEOUT_IO = 18, /* I/O timeout. */
45 RSE_TIMEOUT = 19, /* High level timeout. */
48 RSE_PACKET_TOO_SMALL = 22,
49 RSE_PACKET_TOO_LARGE = 23,
50 RSE_ATTR_OVERFLOW = 24,
51 RSE_ATTR_TOO_SMALL = 25,
52 RSE_ATTR_TOO_LARGE = 26,
53 RSE_ATTR_UNKNOWN = 27,
54 RSE_ATTR_BAD_NAME = 28,
55 RSE_ATTR_VALUE_MALFORMED = 29,
56 RSE_ATTR_INVALID = 30,
57 RSE_TOO_MANY_ATTRS = 31,
58 RSE_ATTR_TYPE_UNKNOWN = 32,
59 RSE_MSG_AUTH_LEN = 33,
60 RSE_MSG_AUTH_WRONG = 34,
61 RSE_REQUEST_REQUIRED = 35,
62 RSE_INVALID_REQUEST_CODE = 36,
63 RSE_AUTH_VECTOR_WRONG = 37,
64 RSE_INVALID_RESPONSE_CODE = 38,
65 RSE_INVALID_RESPONSE_ID = 39,
66 RSE_INVALID_RESPONSE_SRC = 40,
67 RSE_NO_PACKET_DATA = 41,
68 RSE_VENDOR_UNKNOWN = 42,
75 RS_CONN_TYPE_NONE = 0,
81 typedef unsigned int rs_conn_type_t;
83 typedef enum rs_attr_type_t {
84 RS_TYPE_INVALID = 0, /**< Invalid data type */
85 RS_TYPE_STRING, /**< printable-text */
86 RS_TYPE_INTEGER, /**< a 32-bit unsigned integer */
87 RS_TYPE_IPADDR, /**< an IPv4 address */
88 RS_TYPE_DATE, /**< a 32-bit date, of seconds since January 1, 1970 */
89 RS_TYPE_OCTETS, /**< a sequence of binary octets */
90 RS_TYPE_IFID, /**< an Interface Id */
91 RS_TYPE_IPV6ADDR, /**< an IPv6 address */
92 RS_TYPE_IPV6PREFIX, /**< an IPv6 prefix */
93 RS_TYPE_BYTE, /**< an 8-bit integer */
94 RS_TYPE_SHORT, /**< a 16-bit integer */
97 #define PW_ACCESS_REQUEST 1
98 #define PW_ACCESS_ACCEPT 2
99 #define PW_ACCESS_REJECT 3
100 #define PW_ACCOUNTING_REQUEST 4
101 #define PW_ACCOUNTING_RESPONSE 5
102 #define PW_ACCOUNTING_STATUS 6
103 #define PW_PASSWORD_REQUEST 7
104 #define PW_PASSWORD_ACK 8
105 #define PW_PASSWORD_REJECT 9
106 #define PW_ACCOUNTING_MESSAGE 10
107 #define PW_ACCESS_CHALLENGE 11
108 #define PW_STATUS_SERVER 12
109 #define PW_STATUS_CLIENT 13
110 #define PW_DISCONNECT_REQUEST 40
111 #define PW_DISCONNECT_ACK 41
112 #define PW_DISCONNECT_NAK 42
113 #define PW_COA_REQUEST 43
114 #define PW_COA_ACK 44
115 #define PW_COA_NAK 45
117 #if defined (__cplusplus)
122 struct rs_context; /* radsec-impl.h */
123 struct rs_connection; /* radsec-impl.h */
124 struct rs_packet; /* radsec-impl.h */
125 struct rs_conn; /* radsec-impl.h */
126 struct rs_error; /* radsec-impl.h */
127 struct rs_peer; /* radsec-impl.h */
128 struct radius_packet; /* <radius/client.h> */
129 struct value_pair; /* <radius/client.h> */
130 struct event_base; /* <event2/event-internal.h> */
132 typedef void *(*rs_calloc_fp) (size_t nmemb, size_t size);
133 typedef void *(*rs_malloc_fp) (size_t size);
134 typedef void (*rs_free_fp) (void *ptr);
135 typedef void *(*rs_realloc_fp) (void *ptr, size_t size);
136 struct rs_alloc_scheme {
140 rs_realloc_fp realloc;
143 typedef void (*rs_conn_connected_cb) (void *user_data /* FIXME: peer? */ );
144 typedef void (*rs_conn_disconnected_cb) (void *user_data /* FIXME: reason? */ );
145 typedef void (*rs_conn_packet_received_cb) (struct rs_packet *packet,
147 typedef void (*rs_conn_packet_sent_cb) (void *user_data);
148 struct rs_conn_callbacks {
149 /** Callback invoked when the connection has been established. */
150 rs_conn_connected_cb connected_cb;
151 /** Callback invoked when the connection has been torn down. */
152 rs_conn_disconnected_cb disconnected_cb;
153 /** Callback invoked when a packet was received. */
154 rs_conn_packet_received_cb received_cb;
155 /** Callback invoked when a packet was successfully sent. */
156 rs_conn_packet_sent_cb sent_cb;
159 typedef struct value_pair rs_avp;
160 typedef const struct value_pair rs_const_avp;
162 /* Function prototypes. */
167 /** Create a context. Freed by calling \a rs_context_destroy. Note
168 that the context must not be freed before all other libradsec
169 objects have been freed.
171 If support for POSIX threads was detected at configure and build
172 time \a rs_context_create will use mutexes to protect multiple
173 threads from stomping on each other in OpenSSL.
175 \a ctx Address of pointer to a struct rs_context. This is the
176 output of this function.
178 \return RSE_OK (0) on success, RSE_SSLERR on TLS library
179 initialisation error and RSE_NOMEM on out of memory. */
180 int rs_context_create(struct rs_context **ctx);
182 /** Free a context. Note that the context must not be freed before
183 all other libradsec objects have been freed. */
184 void rs_context_destroy(struct rs_context *ctx);
186 /** Set allocation scheme to use. \a scheme is the allocation scheme
187 to use, see \a rs_alloc_scheme. \return On success, RSE_OK (0) is
188 returned. On error, !0 is returned and a struct \a rs_error is
189 pushed on the error stack for the context. The error can be
190 accessed using \a rs_err_ctx_pop. */
191 int rs_context_set_alloc_scheme(struct rs_context *ctx,
192 struct rs_alloc_scheme *scheme);
194 /** Read configuration file. \a config_file is the path of the
195 configuration file to read. \return On success, RSE_OK (0) is
196 returned. On error, !0 is returned and a struct \a rs_error is
197 pushed on the error stack for the context. The error can be
198 accessed using \a rs_err_ctx_pop. */
199 int rs_context_read_config(struct rs_context *ctx, const char *config_file);
204 /** Create a connection. \a conn is the address of a pointer to an \a
205 rs_connection, the output. Free the connection using \a
206 rs_conn_destroy. Note that a connection must not be freed before
207 all packets associated with the connection have been freed. A
208 packet is associated with a connection when it's created (\a
209 rs_packet_create) or received (\a rs_conn_receive_packet).
211 If \a config is not NULL it should be the name of a configuration
212 found in the config file read in using \a rs_context_read_config.
213 \return On success, RSE_OK (0) is returned. On error, !0 is
214 returned and a struct \a rs_error is pushed on the error stack for
215 the context. The error can be accessed using \a
217 int rs_conn_create(struct rs_context *ctx,
218 struct rs_connection **conn,
221 /** Not implemented. */
222 int rs_conn_add_listener(struct rs_connection *conn,
224 const char *hostname,
226 /** Disconnect connection \a conn. \return RSE_OK (0) on success, !0
227 * on error. On error, errno is set appropriately. */
228 int rs_conn_disconnect (struct rs_connection *conn);
230 /** Disconnect and free memory allocated for connection \a conn. Note
231 that a connection must not be freed before all packets associated
232 with the connection have been freed. A packet is associated with
233 a connection when it's created (\a rs_packet_create) or received
234 (\a rs_conn_receive_packet). \return RSE_OK (0) on success, !0 *
235 on error. On error, errno is set appropriately. */
236 int rs_conn_destroy(struct rs_connection *conn);
238 /** Set connection type for \a conn. */
239 void rs_conn_set_type(struct rs_connection *conn, rs_conn_type_t type);
241 /** Not implemented. */
242 int rs_conn_set_eventbase(struct rs_connection *conn, struct event_base *eb);
244 /** Register callbacks \a cb for connection \a conn. */
245 void rs_conn_set_callbacks(struct rs_connection *conn,
246 struct rs_conn_callbacks *cb);
248 /** Remove callbacks for connection \a conn. */
249 void rs_conn_del_callbacks(struct rs_connection *conn);
251 /** Return callbacks registered for connection \a conn. \return
252 Installed callbacks are returned. */
253 struct rs_conn_callbacks *rs_conn_get_callbacks(struct rs_connection *conn);
255 /** Not implemented. */
256 int rs_conn_select_peer(struct rs_connection *conn, const char *name);
258 /** Not implemented. */
259 int rs_conn_get_current_peer(struct rs_connection *conn,
263 /** Special function used in blocking mode, i.e. with no callbacks
264 registered. For any other use of libradsec, a \a received_cb
265 callback should be registered using \a rs_conn_set_callbacks.
267 If \a req_msg is not NULL, a successfully received RADIUS message
268 is verified against it. If \a pkt_out is not NULL it will upon
269 return contain a pointer to an \a rs_packet containing the new
272 \return On error or if the connect (TCP only) or read times out,
273 \a pkt_out will not be changed and one or more errors are pushed
274 on \a conn (available through \a rs_err_conn_pop). */
275 int rs_conn_receive_packet(struct rs_connection *conn,
276 struct rs_packet *request,
277 struct rs_packet **pkt_out);
279 /** Get the file descriptor associated with connection \a conn.
280 * \return File descriptor. */
281 int rs_conn_fd(struct rs_connection *conn);
283 /** Set the timeout value for connection \a conn. */
284 void rs_conn_set_timeout(struct rs_connection *conn, struct timeval *tv);
286 /* Peer -- client and server. */
287 int rs_peer_create(struct rs_connection *conn, struct rs_peer **peer_out);
288 int rs_peer_set_address(struct rs_peer *peer,
289 const char *hostname,
290 const char *service);
291 int rs_peer_set_secret(struct rs_peer *peer, const char *secret);
292 void rs_peer_set_timeout(struct rs_peer *peer, int timeout);
293 void rs_peer_set_retries(struct rs_peer *peer, int retries);
298 /** Create a packet associated with connection \a conn. */
299 int rs_packet_create(struct rs_connection *conn, struct rs_packet **pkt_out);
301 /** Free all memory allocated for packet \a pkt. */
302 void rs_packet_destroy(struct rs_packet *pkt);
304 /** Send packet \a pkt on the connection associated with \a pkt.
305 \a user_data is passed to the \a rs_conn_packet_received_cb callback
306 registered with the connection. If no callback is registered with
307 the connection, the event loop is run by \a rs_packet_send and it
308 blocks until the full packet has been sent. Note that sending can
309 fail in several ways, f.ex. if the transmission protocol in use
310 is connection oriented (\a RS_CONN_TYPE_TCP and \a RS_CONN_TYPE_TLS)
311 and the connection can not be established. Also note that no
312 retransmission is done, something that is required for connectionless
313 transport protocols (\a RS_CONN_TYPE_UDP and \a RS_CONN_TYPE_DTLS).
314 The "request" API with \a rs_request_send can help with this.
316 \return On success, RSE_OK (0) is returned. On error, !0 is
317 returned and a struct \a rs_error is pushed on the error stack for
318 the connection. The error can be accessed using \a rs_err_conn_pop. */
319 int rs_packet_send(struct rs_packet *pkt, void *user_data);
321 /** Create a RADIUS authentication request packet associated with
322 connection \a conn. Optionally, User-Name and User-Password
323 attributes are added to the packet using the data in \a user_name
325 int rs_packet_create_authn_request(struct rs_connection *conn,
326 struct rs_packet **pkt,
327 const char *user_name,
328 const char *user_pw);
330 /** Add a new attribute-value pair to \a pkt. */
331 int rs_packet_add_avp(struct rs_packet *pkt,
332 unsigned int attr, unsigned int vendor,
333 const void *data, size_t data_len);
335 /** Append a new attribute to packet \a pkt. Note that this function
336 encodes the attribute and therefore might require the secret
337 shared with the thought recipient to be set in pkt->rpkt. Note
338 also that this function marks \a pkt as already encoded and can
339 not be used on packets with non-encoded value-pairs already
342 rs_packet_append_avp(struct rs_packet *pkt,
343 unsigned int attribute, unsigned int vendor,
344 const void *data, size_t data_len);
346 /*** Get pointer to \a pkt attribute value pairs. */
348 rs_packet_avps(struct rs_packet *pkt, rs_avp ***vps);
350 /*** Get RADIUS packet type of \a pkt. */
352 rs_packet_code(struct rs_packet *pkt);
354 /*** Get RADIUS AVP from \a pkt. */
356 rs_packet_find_avp(struct rs_packet *pkt, unsigned int attr, unsigned int vendor);
358 /*** Set packet identifier in \a pkt; returns old identifier */
360 rs_packet_set_id (struct rs_packet *pkt, int id);
365 /** Find the realm named \a name in the configuration file previoiusly
366 read in using \a rs_context_read_config. */
367 struct rs_realm *rs_conf_find_realm(struct rs_context *ctx, const char *name);
372 /** Create a struct \a rs_error and push it on a FIFO associated with
373 context \a ctx. Note: The depth of the error stack is one (1) at
374 the moment. This will change in a future release. */
375 int rs_err_ctx_push(struct rs_context *ctx, int code, const char *fmt, ...);
376 int rs_err_ctx_push_fl(struct rs_context *ctx,
382 /** Pop the first error from the error FIFO associated with context \a
383 ctx or NULL if there are no errors in the FIFO. */
384 struct rs_error *rs_err_ctx_pop(struct rs_context *ctx);
386 /** Create a struct \a rs_error and push it on a FIFO associated with
387 connection \a conn. Note: The depth of the error stack is one (1)
388 at the moment. This will change in a future release. */
389 int rs_err_conn_push(struct rs_connection *conn,
393 int rs_err_conn_push_fl(struct rs_connection *conn,
399 /** Pop the first error from the error FIFO associated with connection
400 \a conn or NULL if there are no errors in the FIFO. */
401 struct rs_error *rs_err_conn_pop(struct rs_connection *conn);
403 int rs_err_conn_peek_code (struct rs_connection *conn);
404 void rs_err_free(struct rs_error *err);
405 char *rs_err_msg(struct rs_error *err);
406 int rs_err_code(struct rs_error *err, int dofree_flag);
411 #define rs_avp_is_string(vp) (rs_avp_typeof(vp) == RS_TYPE_STRING)
412 #define rs_avp_is_integer(vp) (rs_avp_typeof(vp) == RS_TYPE_INTEGER)
413 #define rs_avp_is_ipaddr(vp) (rs_avp_typeof(vp) == RS_TYPE_IPADDR)
414 #define rs_avp_is_date(vp) (rs_avp_typeof(vp) == RS_TYPE_DATE)
415 #define rs_avp_is_octets(vp) (rs_avp_typeof(vp) == RS_TYPE_OCTETS)
416 #define rs_avp_is_ifid(vp) (rs_avp_typeof(vp) == RS_TYPE_IFID)
417 #define rs_avp_is_ipv6addr(vp) (rs_avp_typeof(vp) == RS_TYPE_IPV6ADDR)
418 #define rs_avp_is_ipv6prefix(vp) (rs_avp_typeof(vp) == RS_TYPE_IPV6PREFIX)
419 #define rs_avp_is_byte(vp) (rs_avp_typeof(vp) == RS_TYPE_BYTE)
420 #define rs_avp_is_short(vp) (rs_avp_typeof(vp) == RS_TYPE_SHORT)
421 #define rs_avp_is_tlv(vp) (rs_avp_typeof(vp) == RS_TYPE_TLV)
423 /** The maximum length of a RADIUS attribute.
425 * The RFCs require that a RADIUS attribute transport no more than
426 * 253 octets of data. We add an extra byte for a trailing NUL, so
427 * that the VALUE_PAIR::vp_strvalue field can be handled as a C
430 #define RS_MAX_STRING_LEN 254
432 /** Free the AVP list \a vps */
434 rs_avp_free(rs_avp **vps);
436 /** Return the length of AVP \a vp in bytes */
438 rs_avp_length(rs_const_avp *vp);
440 /** Return the type of \a vp */
442 rs_avp_typeof(rs_const_avp *vp);
444 /** Retrieve the attribute and vendor ID of \a vp */
446 rs_avp_attrid(rs_const_avp *vp, unsigned int *attr, unsigned int *vendor);
448 /** Add \a vp to the list pointed to by \a head */
450 rs_avp_append(rs_avp **head, rs_avp *vp);
452 /** Find an AVP in \a vp that matches \a attr and \a vendor */
454 rs_avp_find(rs_avp *vp, unsigned int attr, unsigned int vendor);
456 /** Find an AVP in \a vp that matches \a attr and \a vendor */
458 rs_avp_find_const(rs_const_avp *vp, unsigned int attr, unsigned int vendor);
460 /** Alloc a new AVP for \a attr and \a vendor */
462 rs_avp_alloc(unsigned int attr, unsigned int vendor);
464 /** Duplicate existing AVP \a vp */
466 rs_avp_dup(rs_const_avp *vp);
468 /** Remove matching AVP from list \a vps */
470 rs_avp_delete(rs_avp **vps, unsigned int attr, unsigned int vendor);
472 /** Return next AVP in list */
474 rs_avp_next(rs_avp *vp);
476 /** Return next AVP in list */
478 rs_avp_next_const(rs_const_avp *avp);
480 /** Return string value of \a vp */
482 rs_avp_string_value(rs_const_avp *vp);
484 /** Set AVP \a vp to string \a str */
486 rs_avp_string_set(rs_avp *vp, const char *str);
488 /** Return integer value of \a vp */
490 rs_avp_integer_value(rs_const_avp *vp);
492 /** Set AVP \a vp to integer \a val */
494 rs_avp_integer_set(rs_avp *vp, uint32_t val);
496 /** Return IPv4 value of \a vp */
498 rs_avp_ipaddr_value(rs_const_avp *vp);
500 /** Set AVP \a vp to IPv4 address \a in */
502 rs_avp_ipaddr_set(rs_avp *vp, struct in_addr in);
504 /** Return POSIX time value of \a vp */
506 rs_avp_date_value(rs_const_avp *vp);
508 /** Set AVP \a vp to POSIX time \a date */
510 rs_avp_date_set(rs_avp *vp, time_t date);
512 /** Return constant pointer to octets in \a vp */
513 const unsigned char *
514 rs_avp_octets_value_const_ptr(rs_const_avp *vp);
516 /** Return pointer to octets in \a vp */
518 rs_avp_octets_value_ptr(rs_avp *vp);
520 /** Retrieve octet pointer \a p and length \a len from \a vp */
522 rs_avp_octets_value_byref(rs_avp *vp,
526 /** Copy octets from \a vp into \a buf and \a len */
528 rs_avp_octets_value(rs_const_avp *vp,
533 * Copy octets possibly fragmented across multiple VPs
534 * into \a buf and \a len
537 rs_avp_fragmented_value(rs_const_avp *vps,
541 /** Copy \a len octets in \a buf to AVP \a vp */
543 rs_avp_octets_set(rs_avp *vp,
544 const unsigned char *buf,
547 /** Return IFID value of \a vp */
549 rs_avp_ifid_value(rs_const_avp *vp, uint8_t val[8]);
552 rs_avp_ifid_set(rs_avp *vp, const uint8_t val[8]);
554 /** Return byte value of \a vp */
556 rs_avp_byte_value(rs_const_avp *vp);
558 /** Set AVP \a vp to byte \a val */
560 rs_avp_byte_set(rs_avp *vp, uint8_t val);
562 /** Return short value of \a vp */
564 rs_avp_short_value(rs_const_avp *vp);
566 /** Set AVP \a vp to short integer \a val */
568 rs_avp_short_set(rs_avp *vp, uint16_t val);
570 /** Display possibly \a canonical attribute name into \a buffer */
572 rs_attr_display_name (unsigned int attr,
578 /** Display AVP \a vp into \a buffer */
580 rs_avp_display_value(rs_const_avp *vp,
585 rs_attr_parse_name (const char *name,
587 unsigned int *vendor);
589 /** Lookup attribute \a name */
591 rs_attr_find(const char *name,
593 unsigned int *vendor);
595 /** Return dictionary name for AVP \a vp */
597 rs_avp_name(rs_const_avp *vp);
599 #if defined (__cplusplus)
603 #endif /* _RADSEC_RADSEC_H_ */
605 /* Local Variables: */
606 /* c-file-style: "stroustrup" */