path: root/lib/include/radsec/radsec.h

/** \file radsec.h
    \brief Public interface for libradsec.  */

/* Copyright 2010,2011,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_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_listener;             /* 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;		/* <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_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 an outgoing 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 void (*rs_listener_new_conn_cb) (struct rs_connection *conn,
                                         void *user_data);
struct rs_listener_callbacks {
    rs_listener_new_conn_cb new_conn_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);

int rs_context_print_config (struct rs_context *ctx, char **buf_out);

/*************/
/* Listener. */
/*************/
int rs_listener_create (struct rs_context *ctx,
                        struct rs_listener **listener,
                        const char *config);
void rs_listener_set_callbacks (struct rs_listener *listener,
                                const struct rs_listener_callbacks *cb);
int rs_listener_dispatch (const struct rs_listener *listener);

/****************/
/* 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);

/** Run the dispatcher for the event base associated with \a conn. A
 * wrapper around event_base_dispatch() for not having to hand out the
 * event base. */
int rs_conn_dispatch(struct rs_connection *conn);

#if 0
/** Get the event base associated with connection \a conn.
 * \return struct event_base*. */
struct event_base *rs_conn_get_evb(const struct rs_connection *conn);
#endif

#define rs_conn_fd rs_conn_get_fd /* Old name. */
/** Get the file descriptor associated with connection \a conn.
 * \return File descriptor.  */
int rs_conn_get_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: */