/** \file radsec.h \brief Public interface for libradsec. */ /* See LICENSE for licensing information. */ #ifndef _RADSEC_RADSEC_H_ #define _RADSEC_RADSEC_H_ 1 #ifdef HAVE_CONFIG_H #include #endif #ifdef HAVE_SYS_TIME_H #include #endif #ifdef HAVE_ARPA_INET_H #include #endif #ifdef HAVE_UNISTD_H #include #endif #ifdef HAVE_STDINT_H #include #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_FR = 6, 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_MSG = 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 /* Backwards compatible with 0.0.2. */ #define RSE_INVALID_PKT RSE_INVALID_MSG #define rs_packet rs_message #define rs_conn_packet_received_cb rs_conn_message_received_cb #define rs_conn_packet_sent_cb rs_conn_message_sent_cb #define rs_conn_receive_packet rs_conn_receive_message #define rs_dump_packet rs_dump_message #define rs_packet_append_avp rs_message_append_avp #define rs_packet_avps rs_message_avps #define rs_packet_code rs_message_code #define rs_packet_create rs_message_create #define rs_packet_create_authn_request rs_message_create_authn_request #define rs_packet_destroy rs_message_destroy #define rs_packet_send rs_message_send /* Data types. */ struct rs_context; /* radsec-impl.h */ struct rs_connection; /* radsec-impl.h */ struct rs_message; /* radsec-impl.h */ struct rs_conn; /* radsec-impl.h */ struct rs_error; /* radsec-impl.h */ struct rs_peer; /* radsec-impl.h */ struct radius_packet; /* */ struct value_pair; /* */ struct event_base; /* */ 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_message_received_cb) (struct rs_message *message, void *user_data); typedef void (*rs_conn_message_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 message was received. */ rs_conn_message_received_cb received_cb; /** Callback invoked when a message was successfully sent. */ rs_conn_message_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. \a ctx Address of pointer to a struct rs_context. This is the output of this function. \return RSE_OK (0) on success or 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 messages associated with the connection have been freed. A message is associated with a connection when it's created (\a rs_message_create) or received (\a rs_conn_receive_message). If \a config is not NULL it should be the name of a realm found in a config file that has already been read 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 messages associated with the connection have been freed. A message is associated with a connection when it's created (\a rs_message_create) or received (\a rs_conn_receive_message). \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_message 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_message(struct rs_connection *conn, struct rs_message *request, struct rs_message **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); /************/ /* Message. */ /************/ /** Create a message associated with connection \a conn. */ int rs_message_create(struct rs_connection *conn, struct rs_message **pkt_out); /** Free all memory allocated for message \a msg. */ void rs_message_destroy(struct rs_message *msg); /** Send message \a msg on the connection associated with \a msg. \a user_data is sent to the \a rs_conn_message_received_cb callback registered with the connection. If no callback is registered with the connection, the event loop is run by \a rs_message_send and it blocks until the message has been succesfully sent. \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_message_send(struct rs_message *msg, void *user_data); /** Create a RADIUS authentication request message associated with connection \a conn. Optionally, User-Name and User-Password attributes are added to the message using the data in \a user_name, \a user_pw and \a secret where \secret is the RADIUS shared secret. */ int rs_message_create_authn_request(struct rs_connection *conn, struct rs_message **msg, const char *user_name, const char *user_pw, const char *secret); /*** Append \a tail to message \a msg. */ int rs_message_append_avp(struct rs_message *msg, unsigned int attribute, unsigned int vendor, const void *data, size_t data_len); /*** Get pointer to \a msg attribute value pairs. */ void rs_message_avps(struct rs_message *msg, rs_avp ***vps); /*** Get RADIUS message type of \a msg. */ unsigned int rs_message_code(struct rs_message *msg); /*** Get RADIUS AVP from \a msg. */ rs_const_avp * rs_message_find_avp(struct rs_message *msg, unsigned int attr, unsigned int vendor); /*** Set packet identifier in \a msg; returns old identifier */ int rs_message_set_id (struct rs_message *msg, 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: */