diff options
Diffstat (limited to 'include/radsec/radsec.h')
| -rw-r--r-- | include/radsec/radsec.h | 607 |
1 files changed, 607 insertions, 0 deletions
diff --git a/include/radsec/radsec.h b/include/radsec/radsec.h new file mode 100644 index 0000000..1d718a0 --- /dev/null +++ b/include/radsec/radsec.h @@ -0,0 +1,607 @@ +/** \file radsec.h + \brief Public interface for libradsec. */ + +/* Copyright 2010-2013 NORDUnet A/S. All rights reserved. + See LICENSE for licensing information. */ + +#ifndef _RADSEC_RADSEC_H_ +#define _RADSEC_RADSEC_H_ 1 + +#ifdef HAVE_CONFIG_H +#include <config.h> +#endif +#ifdef HAVE_SYS_TIME_H +#include <sys/time.h> +#endif +#ifdef HAVE_ARPA_INET_H +#include <arpa/inet.h> +#endif +#ifdef HAVE_UNISTD_H +#include <unistd.h> +#endif +#ifdef HAVE_STDINT_H +#include <stdint.h> +#endif + +enum rs_error_code { + RSE_OK = 0, + RSE_NOMEM = 1, + RSE_NOSYS = 2, + RSE_INVALID_CTX = 3, + RSE_INVALID_CONN = 4, + RSE_CONN_TYPE_MISMATCH = 5, + RSE_BADADDR = 7, + RSE_NOPEER = 8, + RSE_EVENT = 9, /* libevent error. */ + RSE_SOCKERR = 10, + RSE_CONFIG = 11, + RSE_BADAUTH = 12, + RSE_INTERNAL = 13, + RSE_SSLERR = 14, /* OpenSSL error. */ + RSE_INVALID_PKT = 15, + RSE_TIMEOUT_CONN = 16, /* Connection timeout. */ + RSE_INVAL = 17, /* Invalid argument. */ + RSE_TIMEOUT_IO = 18, /* I/O timeout. */ + RSE_TIMEOUT = 19, /* High level timeout. */ + RSE_DISCO = 20, + RSE_INUSE = 21, + RSE_PACKET_TOO_SMALL = 22, + RSE_PACKET_TOO_LARGE = 23, + RSE_ATTR_OVERFLOW = 24, + RSE_ATTR_TOO_SMALL = 25, + RSE_ATTR_TOO_LARGE = 26, + RSE_ATTR_UNKNOWN = 27, + RSE_ATTR_BAD_NAME = 28, + RSE_ATTR_VALUE_MALFORMED = 29, + RSE_ATTR_INVALID = 30, + RSE_TOO_MANY_ATTRS = 31, + RSE_ATTR_TYPE_UNKNOWN = 32, + RSE_MSG_AUTH_LEN = 33, + RSE_MSG_AUTH_WRONG = 34, + RSE_REQUEST_REQUIRED = 35, + RSE_INVALID_REQUEST_CODE = 36, + RSE_AUTH_VECTOR_WRONG = 37, + RSE_INVALID_RESPONSE_CODE = 38, + RSE_INVALID_RESPONSE_ID = 39, + RSE_INVALID_RESPONSE_SRC = 40, + RSE_NO_PACKET_DATA = 41, + RSE_VENDOR_UNKNOWN = 42, + RSE_CRED = 43, + RSE_CERT = 44, + RSE_MAX = RSE_CERT +}; + +enum rs_conn_type { + RS_CONN_TYPE_NONE = 0, + RS_CONN_TYPE_UDP, + RS_CONN_TYPE_TCP, + RS_CONN_TYPE_TLS, + RS_CONN_TYPE_DTLS, +}; +typedef unsigned int rs_conn_type_t; + +typedef enum rs_attr_type_t { + RS_TYPE_INVALID = 0, /**< Invalid data type */ + RS_TYPE_STRING, /**< printable-text */ + RS_TYPE_INTEGER, /**< a 32-bit unsigned integer */ + RS_TYPE_IPADDR, /**< an IPv4 address */ + RS_TYPE_DATE, /**< a 32-bit date, of seconds since January 1, 1970 */ + RS_TYPE_OCTETS, /**< a sequence of binary octets */ + RS_TYPE_IFID, /**< an Interface Id */ + RS_TYPE_IPV6ADDR, /**< an IPv6 address */ + RS_TYPE_IPV6PREFIX, /**< an IPv6 prefix */ + RS_TYPE_BYTE, /**< an 8-bit integer */ + RS_TYPE_SHORT, /**< a 16-bit integer */ +} rs_attr_type_t; + +#define PW_ACCESS_REQUEST 1 +#define PW_ACCESS_ACCEPT 2 +#define PW_ACCESS_REJECT 3 +#define PW_ACCOUNTING_REQUEST 4 +#define PW_ACCOUNTING_RESPONSE 5 +#define PW_ACCOUNTING_STATUS 6 +#define PW_PASSWORD_REQUEST 7 +#define PW_PASSWORD_ACK 8 +#define PW_PASSWORD_REJECT 9 +#define PW_ACCOUNTING_MESSAGE 10 +#define PW_ACCESS_CHALLENGE 11 +#define PW_STATUS_SERVER 12 +#define PW_STATUS_CLIENT 13 +#define PW_DISCONNECT_REQUEST 40 +#define PW_DISCONNECT_ACK 41 +#define PW_DISCONNECT_NAK 42 +#define PW_COA_REQUEST 43 +#define PW_COA_ACK 44 +#define PW_COA_NAK 45 + +#if defined (__cplusplus) +extern "C" { +#endif + +/* Data types. */ +struct rs_context; /* radsec-impl.h */ +struct rs_connection; /* radsec-impl.h */ +struct rs_packet; /* radsec-impl.h */ +struct rs_conn; /* radsec-impl.h */ +struct rs_error; /* radsec-impl.h */ +struct rs_peer; /* radsec-impl.h */ +struct radius_packet; /* <radius/client.h> */ +struct value_pair; /* <radius/client.h> */ +struct event_base; /* <event2/event-internal.h> */ + +typedef void *(*rs_calloc_fp) (size_t nmemb, size_t size); +typedef void *(*rs_malloc_fp) (size_t size); +typedef void (*rs_free_fp) (void *ptr); +typedef void *(*rs_realloc_fp) (void *ptr, size_t size); +struct rs_alloc_scheme { + rs_calloc_fp calloc; + rs_malloc_fp malloc; + rs_free_fp free; + rs_realloc_fp realloc; +}; + +typedef void (*rs_conn_connected_cb) (void *user_data /* FIXME: peer? */ ); +typedef void (*rs_conn_disconnected_cb) (void *user_data /* FIXME: reason? */ ); +typedef void (*rs_conn_packet_received_cb) (struct rs_packet *packet, + void *user_data); +typedef void (*rs_conn_packet_sent_cb) (void *user_data); +struct rs_conn_callbacks { + /** Callback invoked when the connection has been established. */ + rs_conn_connected_cb connected_cb; + /** Callback invoked when the connection has been torn down. */ + rs_conn_disconnected_cb disconnected_cb; + /** Callback invoked when a packet was received. */ + rs_conn_packet_received_cb received_cb; + /** Callback invoked when a packet was successfully sent. */ + rs_conn_packet_sent_cb sent_cb; +}; + +typedef struct value_pair rs_avp; +typedef const struct value_pair rs_const_avp; + +/* Function prototypes. */ + +/*************/ +/* Context. */ +/*************/ +/** Create a context. Freed by calling \a rs_context_destroy. Note + that the context must not be freed before all other libradsec + objects have been freed. + + If support for POSIX threads was detected at configure and build + time \a rs_context_create will use mutexes to protect multiple + threads from stomping on each other in OpenSSL. + + \a ctx Address of pointer to a struct rs_context. This is the + output of this function. + + \return RSE_OK (0) on success, RSE_SSLERR on TLS library + initialisation error and RSE_NOMEM on out of memory. */ +int rs_context_create(struct rs_context **ctx); + +/** Free a context. Note that the context must not be freed before + all other libradsec objects have been freed. */ +void rs_context_destroy(struct rs_context *ctx); + +/** Set allocation scheme to use. \a scheme is the allocation scheme + to use, see \a rs_alloc_scheme. \return On success, RSE_OK (0) is + returned. On error, !0 is returned and a struct \a rs_error is + pushed on the error stack for the context. The error can be + accessed using \a rs_err_ctx_pop. */ +int rs_context_set_alloc_scheme(struct rs_context *ctx, + struct rs_alloc_scheme *scheme); + +/** Read configuration file. \a config_file is the path of the + configuration file to read. \return On success, RSE_OK (0) is + returned. On error, !0 is returned and a struct \a rs_error is + pushed on the error stack for the context. The error can be + accessed using \a rs_err_ctx_pop. */ +int rs_context_read_config(struct rs_context *ctx, const char *config_file); + +/****************/ +/* Connection. */ +/****************/ +/** Create a connection. \a conn is the address of a pointer to an \a + rs_connection, the output. Free the connection using \a + rs_conn_destroy. Note that a connection must not be freed before + all packets associated with the connection have been freed. A + packet is associated with a connection when it's created (\a + rs_packet_create) or received (\a rs_conn_receive_packet). + + If \a config is not NULL it should be the name of a configuration + found in the config file read in using \a rs_context_read_config. + \return On success, RSE_OK (0) is returned. On error, !0 is + returned and a struct \a rs_error is pushed on the error stack for + the context. The error can be accessed using \a + rs_err_ctx_pop. */ +int rs_conn_create(struct rs_context *ctx, + struct rs_connection **conn, + const char *config); + +/** Not implemented. */ +int rs_conn_add_listener(struct rs_connection *conn, + rs_conn_type_t type, + const char *hostname, + int port); +/** Disconnect connection \a conn. \return RSE_OK (0) on success, !0 + * on error. On error, errno is set appropriately. */ +int rs_conn_disconnect (struct rs_connection *conn); + +/** Disconnect and free memory allocated for connection \a conn. Note + that a connection must not be freed before all packets associated + with the connection have been freed. A packet is associated with + a connection when it's created (\a rs_packet_create) or received + (\a rs_conn_receive_packet). \return RSE_OK (0) on success, !0 * + on error. On error, errno is set appropriately. */ +int rs_conn_destroy(struct rs_connection *conn); + +/** Set connection type for \a conn. */ +void rs_conn_set_type(struct rs_connection *conn, rs_conn_type_t type); + +/** Not implemented. */ +int rs_conn_set_eventbase(struct rs_connection *conn, struct event_base *eb); + +/** Register callbacks \a cb for connection \a conn. */ +void rs_conn_set_callbacks(struct rs_connection *conn, + struct rs_conn_callbacks *cb); + +/** Remove callbacks for connection \a conn. */ +void rs_conn_del_callbacks(struct rs_connection *conn); + +/** Return callbacks registered for connection \a conn. \return + Installed callbacks are returned. */ +struct rs_conn_callbacks *rs_conn_get_callbacks(struct rs_connection *conn); + +/** Not implemented. */ +int rs_conn_select_peer(struct rs_connection *conn, const char *name); + +/** Not implemented. */ +int rs_conn_get_current_peer(struct rs_connection *conn, + const char *name, + size_t buflen); + +/** Special function used in blocking mode, i.e. with no callbacks + registered. For any other use of libradsec, a \a received_cb + callback should be registered using \a rs_conn_set_callbacks. + + If \a req_msg is not NULL, a successfully received RADIUS message + is verified against it. If \a pkt_out is not NULL it will upon + return contain a pointer to an \a rs_packet containing the new + message. + + \return On error or if the connect (TCP only) or read times out, + \a pkt_out will not be changed and one or more errors are pushed + on \a conn (available through \a rs_err_conn_pop). */ +int rs_conn_receive_packet(struct rs_connection *conn, + struct rs_packet *request, + struct rs_packet **pkt_out); + +/** Get the file descriptor associated with connection \a conn. + * \return File descriptor. */ +int rs_conn_fd(struct rs_connection *conn); + +/** Set the timeout value for connection \a conn. */ +void rs_conn_set_timeout(struct rs_connection *conn, struct timeval *tv); + +/* Peer -- client and server. */ +int rs_peer_create(struct rs_connection *conn, struct rs_peer **peer_out); +int rs_peer_set_address(struct rs_peer *peer, + const char *hostname, + const char *service); +int rs_peer_set_secret(struct rs_peer *peer, const char *secret); +void rs_peer_set_timeout(struct rs_peer *peer, int timeout); +void rs_peer_set_retries(struct rs_peer *peer, int retries); + +/************/ +/* Packet. */ +/************/ +/** Create a packet associated with connection \a conn. */ +int rs_packet_create(struct rs_connection *conn, struct rs_packet **pkt_out); + +/** Free all memory allocated for packet \a pkt. */ +void rs_packet_destroy(struct rs_packet *pkt); + +/** Send packet \a pkt on the connection associated with \a pkt. + \a user_data is passed to the \a rs_conn_packet_received_cb callback + registered with the connection. If no callback is registered with + the connection, the event loop is run by \a rs_packet_send and it + blocks until the full packet has been sent. Note that sending can + fail in several ways, f.ex. if the transmission protocol in use + is connection oriented (\a RS_CONN_TYPE_TCP and \a RS_CONN_TYPE_TLS) + and the connection can not be established. Also note that no + retransmission is done, something that is required for connectionless + transport protocols (\a RS_CONN_TYPE_UDP and \a RS_CONN_TYPE_DTLS). + The "request" API with \a rs_request_send can help with this. + + \return On success, RSE_OK (0) is returned. On error, !0 is + returned and a struct \a rs_error is pushed on the error stack for + the connection. The error can be accessed using \a rs_err_conn_pop. */ +int rs_packet_send(struct rs_packet *pkt, void *user_data); + +/** Create a RADIUS authentication request packet associated with + connection \a conn. Optionally, User-Name and User-Password + attributes are added to the packet using the data in \a user_name + and \a user_pw. */ +int rs_packet_create_authn_request(struct rs_connection *conn, + struct rs_packet **pkt, + const char *user_name, + const char *user_pw); + +/** Add a new attribute-value pair to \a pkt. */ +int rs_packet_add_avp(struct rs_packet *pkt, + unsigned int attr, unsigned int vendor, + const void *data, size_t data_len); + +/** Append a new attribute to packet \a pkt. Note that this function + encodes the attribute and therefore might require the secret + shared with the thought recipient to be set in pkt->rpkt. Note + also that this function marks \a pkt as already encoded and can + not be used on packets with non-encoded value-pairs already + added. */ +int +rs_packet_append_avp(struct rs_packet *pkt, + unsigned int attribute, unsigned int vendor, + const void *data, size_t data_len); + +/*** Get pointer to \a pkt attribute value pairs. */ +void +rs_packet_avps(struct rs_packet *pkt, rs_avp ***vps); + +/*** Get RADIUS packet type of \a pkt. */ +unsigned int +rs_packet_code(struct rs_packet *pkt); + +/*** Get RADIUS AVP from \a pkt. */ +rs_const_avp * +rs_packet_find_avp(struct rs_packet *pkt, unsigned int attr, unsigned int vendor); + +/*** Set packet identifier in \a pkt; returns old identifier */ +int +rs_packet_set_id (struct rs_packet *pkt, int id); + +/************/ +/* Config. */ +/************/ +/** Find the realm named \a name in the configuration file previoiusly + read in using \a rs_context_read_config. */ +struct rs_realm *rs_conf_find_realm(struct rs_context *ctx, const char *name); + +/***********/ +/* Error. */ +/***********/ +/** Create a struct \a rs_error and push it on a FIFO associated with + context \a ctx. Note: The depth of the error stack is one (1) at + the moment. This will change in a future release. */ +int rs_err_ctx_push(struct rs_context *ctx, int code, const char *fmt, ...); +int rs_err_ctx_push_fl(struct rs_context *ctx, + int code, + const char *file, + int line, + const char *fmt, + ...); +/** Pop the first error from the error FIFO associated with context \a + ctx or NULL if there are no errors in the FIFO. */ +struct rs_error *rs_err_ctx_pop(struct rs_context *ctx); + +/** Create a struct \a rs_error and push it on a FIFO associated with + connection \a conn. Note: The depth of the error stack is one (1) + at the moment. This will change in a future release. */ +int rs_err_conn_push(struct rs_connection *conn, + int code, + const char *fmt, + ...); +int rs_err_conn_push_fl(struct rs_connection *conn, + int code, + const char *file, + int line, + const char *fmt, + ...); +/** Pop the first error from the error FIFO associated with connection + \a conn or NULL if there are no errors in the FIFO. */ +struct rs_error *rs_err_conn_pop(struct rs_connection *conn); + +int rs_err_conn_peek_code (struct rs_connection *conn); +void rs_err_free(struct rs_error *err); +char *rs_err_msg(struct rs_error *err); +int rs_err_code(struct rs_error *err, int dofree_flag); + +/************/ +/* AVPs. */ +/************/ +#define rs_avp_is_string(vp) (rs_avp_typeof(vp) == RS_TYPE_STRING) +#define rs_avp_is_integer(vp) (rs_avp_typeof(vp) == RS_TYPE_INTEGER) +#define rs_avp_is_ipaddr(vp) (rs_avp_typeof(vp) == RS_TYPE_IPADDR) +#define rs_avp_is_date(vp) (rs_avp_typeof(vp) == RS_TYPE_DATE) +#define rs_avp_is_octets(vp) (rs_avp_typeof(vp) == RS_TYPE_OCTETS) +#define rs_avp_is_ifid(vp) (rs_avp_typeof(vp) == RS_TYPE_IFID) +#define rs_avp_is_ipv6addr(vp) (rs_avp_typeof(vp) == RS_TYPE_IPV6ADDR) +#define rs_avp_is_ipv6prefix(vp) (rs_avp_typeof(vp) == RS_TYPE_IPV6PREFIX) +#define rs_avp_is_byte(vp) (rs_avp_typeof(vp) == RS_TYPE_BYTE) +#define rs_avp_is_short(vp) (rs_avp_typeof(vp) == RS_TYPE_SHORT) +#define rs_avp_is_tlv(vp) (rs_avp_typeof(vp) == RS_TYPE_TLV) + +/** The maximum length of a RADIUS attribute. + * + * The RFCs require that a RADIUS attribute transport no more than + * 253 octets of data. We add an extra byte for a trailing NUL, so + * that the VALUE_PAIR::vp_strvalue field can be handled as a C + * string. + */ +#define RS_MAX_STRING_LEN 254 + +/** Free the AVP list \a vps */ +void +rs_avp_free(rs_avp **vps); + +/** Return the length of AVP \a vp in bytes */ +size_t +rs_avp_length(rs_const_avp *vp); + +/** Return the type of \a vp */ +rs_attr_type_t +rs_avp_typeof(rs_const_avp *vp); + +/** Retrieve the attribute and vendor ID of \a vp */ +void +rs_avp_attrid(rs_const_avp *vp, unsigned int *attr, unsigned int *vendor); + +/** Add \a vp to the list pointed to by \a head */ +void +rs_avp_append(rs_avp **head, rs_avp *vp); + +/** Find an AVP in \a vp that matches \a attr and \a vendor */ +rs_avp * +rs_avp_find(rs_avp *vp, unsigned int attr, unsigned int vendor); + +/** Find an AVP in \a vp that matches \a attr and \a vendor */ +rs_const_avp * +rs_avp_find_const(rs_const_avp *vp, unsigned int attr, unsigned int vendor); + +/** Alloc a new AVP for \a attr and \a vendor */ +rs_avp * +rs_avp_alloc(unsigned int attr, unsigned int vendor); + +/** Duplicate existing AVP \a vp */ +rs_avp * +rs_avp_dup(rs_const_avp *vp); + +/** Remove matching AVP from list \a vps */ +int +rs_avp_delete(rs_avp **vps, unsigned int attr, unsigned int vendor); + +/** Return next AVP in list */ +rs_avp * +rs_avp_next(rs_avp *vp); + +/** Return next AVP in list */ +rs_const_avp * +rs_avp_next_const(rs_const_avp *avp); + +/** Return string value of \a vp */ +const char * +rs_avp_string_value(rs_const_avp *vp); + +/** Set AVP \a vp to string \a str */ +int +rs_avp_string_set(rs_avp *vp, const char *str); + +/** Return integer value of \a vp */ +uint32_t +rs_avp_integer_value(rs_const_avp *vp); + +/** Set AVP \a vp to integer \a val */ +int +rs_avp_integer_set(rs_avp *vp, uint32_t val); + +/** Return IPv4 value of \a vp */ +uint32_t +rs_avp_ipaddr_value(rs_const_avp *vp); + +/** Set AVP \a vp to IPv4 address \a in */ +int +rs_avp_ipaddr_set(rs_avp *vp, struct in_addr in); + +/** Return POSIX time value of \a vp */ +time_t +rs_avp_date_value(rs_const_avp *vp); + +/** Set AVP \a vp to POSIX time \a date */ +int +rs_avp_date_set(rs_avp *vp, time_t date); + +/** Return constant pointer to octets in \a vp */ +const unsigned char * +rs_avp_octets_value_const_ptr(rs_const_avp *vp); + +/** Return pointer to octets in \a vp */ +unsigned char * +rs_avp_octets_value_ptr(rs_avp *vp); + +/** Retrieve octet pointer \a p and length \a len from \a vp */ +int +rs_avp_octets_value_byref(rs_avp *vp, + unsigned char **p, + size_t *len); + +/** Copy octets from \a vp into \a buf and \a len */ +int +rs_avp_octets_value(rs_const_avp *vp, + unsigned char *buf, + size_t *len); + +/** + * Copy octets possibly fragmented across multiple VPs + * into \a buf and \a len + */ +int +rs_avp_fragmented_value(rs_const_avp *vps, + unsigned char *buf, + size_t *len); + +/** Copy \a len octets in \a buf to AVP \a vp */ +int +rs_avp_octets_set(rs_avp *vp, + const unsigned char *buf, + size_t len); + +/** Return IFID value of \a vp */ +int +rs_avp_ifid_value(rs_const_avp *vp, uint8_t val[8]); + +int +rs_avp_ifid_set(rs_avp *vp, const uint8_t val[8]); + +/** Return byte value of \a vp */ +uint8_t +rs_avp_byte_value(rs_const_avp *vp); + +/** Set AVP \a vp to byte \a val */ +int +rs_avp_byte_set(rs_avp *vp, uint8_t val); + +/** Return short value of \a vp */ +uint16_t +rs_avp_short_value(rs_const_avp *vp); + +/** Set AVP \a vp to short integer \a val */ +int +rs_avp_short_set(rs_avp *vp, uint16_t val); + +/** Display possibly \a canonical attribute name into \a buffer */ +int +rs_attr_display_name (unsigned int attr, + unsigned int vendor, + char *buffer, + size_t bufsize, + int canonical); + +/** Display AVP \a vp into \a buffer */ +size_t +rs_avp_display_value(rs_const_avp *vp, + char *buffer, + size_t buflen); + +int +rs_attr_parse_name (const char *name, + unsigned int *attr, + unsigned int *vendor); + +/** Lookup attribute \a name */ +int +rs_attr_find(const char *name, + unsigned int *attr, + unsigned int *vendor); + +/** Return dictionary name for AVP \a vp */ +const char * +rs_avp_name(rs_const_avp *vp); + +#if defined (__cplusplus) +} +#endif + +#endif /* _RADSEC_RADSEC_H_ */ + +/* Local Variables: */ +/* c-file-style: "stroustrup" */ +/* End: */ |