Skip site navigation (1)Skip section navigation (2)

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
LIBRADIUS(3)	       FreeBSD Library Functions Manual		  LIBRADIUS(3)

NAME
     libradius -- RADIUS client	library

SYNOPSIS
     #include <radlib.h>

     struct rad_handle *
     rad_acct_open(void);

     int
     rad_add_server(struct rad_handle *h, const	char *host, int	port,
	 const char *secret, int timeout, int max_tries);

     struct rad_handle *
     rad_auth_open(void);

     void
     rad_close(struct rad_handle *h);

     int
     rad_config(struct rad_handle *h, const char *file);

     int
     rad_continue_send_request(struct rad_handle *h, int selected, int *fd,
	 struct	timeval	*tv);

     int
     rad_create_request(struct rad_handle *h, int code);

     struct in_addr
     rad_cvt_addr(const	void *data);

     u_int32_t
     rad_cvt_int(const void *data);

     char *
     rad_cvt_string(const void *data, size_t len);

     int
     rad_get_attr(struct rad_handle *h,	const void **data, size_t *len);

     int
     rad_get_vendor_attr(u_int32_t *vendor, const void **data, size_t *len);

     int
     rad_init_send_request(struct rad_handle *h, int *fd, struct timeval *tv);

     int
     rad_put_addr(struct rad_handle *h,	int type, struct in_addr addr);

     int
     rad_put_attr(struct rad_handle *h,	int type, const	void *data,
	 size_t	len);

     int
     rad_put_int(struct	rad_handle *h, int type, u_int32_t value);

     int
     rad_put_string(struct rad_handle *h, int type, const char *str);

     int
     rad_put_vendor_addr(struct	rad_handle *h, int vendor, int type,
	 struct	in_addr	addr);

     int
     rad_put_vendor_attr(struct	rad_handle *h, int vendor, int type,
	 const void *data, size_t len);

     int
     rad_put_vendor_int(struct rad_handle *h, int vendor, int type,
	 u_int32_t value);

     int
     rad_put_vendor_string(struct rad_handle *h, int vendor, int type,
	 const char *str);

     ssize_t
     rad_request_authenticator(struct rad_handle *h, char *buf,	size_t len);

     int
     rad_send_request(struct rad_handle	*h);

     const char	*
     rad_server_secret(struct rad_handle *h);

     const char	*
     rad_strerror(struct rad_handle *h);

DESCRIPTION
     The libradius library implements the client side of the Remote Authenti-
     cation Dial In User Service (RADIUS).  RADIUS, defined in RFCs 2138 and
     2139, allows clients to perform authentication and	accounting by means of
     network requests to remote	servers.

INITIALIZATION
     To	use the	library, an application	must first call	rad_auth_open()	or
     rad_acct_open() to	obtain a struct	rad_handle *, which provides the con-
     text for subsequent operations.  The former function is used for RADIUS
     authentication and	the latter is used for RADIUS accounting.  Calls to
     rad_auth_open() and rad_acct_open() always	succeed	unless insufficient
     virtual memory is available.  If the necessary memory cannot be allo-
     cated, the	functions return NULL.	For compatibility with earlier ver-
     sions of this library, rad_open() is provided as a	synonym	for
     rad_auth_open().

     Before issuing any	RADIUS requests, the library must be made aware	of the
     servers it	can contact.  The easiest way to configure the library is to
     call rad_config().	 rad_config() causes the library to read a configura-
     tion file whose format is described in radius.conf(5).  The pathname of
     the configuration file is passed as the file argument to rad_config().
     This argument may also be given as	NULL, in which case the	standard con-
     figuration	file /etc/radius.conf is used.	rad_config() returns 0 on suc-
     cess, or -1 if an error occurs.

     The library can also be configured	programmatically by calls to
     rad_add_server().	The host parameter specifies the server	host, either
     as	a fully	qualified domain name or as a dotted-quad IP address in	text
     form.  The	port parameter specifies the UDP port to contact on the
     server.  If port is given as 0, the library looks up the `radius/udp' or
     `radacct/udp' service in the network services database, and uses the port
     found there.  If no entry is found, the library uses the standard RADIUS
     ports, 1812 for authentication and	1813 for accounting.  The shared
     secret for	the server host	is passed to the secret	parameter.  It may be
     any NUL-terminated	string of bytes.  The RADIUS protocol ignores all but
     the leading 128 bytes of the shared secret.  The timeout for receiving
     replies from the server is	passed to the timeout parameter, in units of
     seconds.  The maximum number of repeated requests to make before giving
     up	is passed into the max_tries parameter.	 rad_add_server() returns 0 on
     success, or -1 if an error	occurs.

     rad_add_server() may be called multiple times, and	it may be used
     together with rad_config().  At most 10 servers may be specified.	When
     multiple servers are given, they are tried	in round-robin fashion until a
     valid response is received, or until each server's	max_tries limit	has
     been reached.

CREATING A RADIUS REQUEST
     A RADIUS request consists of a code specifying the	kind of	request, and
     zero or more attributes which provide additional information.  To begin
     constructing a new	request, call rad_create_request().  In	addition to
     the usual struct rad_handle *, this function takes	a code parameter which
     specifies the type	of the request.	 Most often this will be
     RAD_ACCESS_REQUEST.  rad_create_request() returns 0 on success, or	-1 on
     if	an error occurs.

     After the request has been	created	with rad_create_request(), attributes
     can be attached to	it.  This is done through calls	to rad_put_addr(),
     rad_put_int(), and	rad_put_string().  Each	accepts	a type parameter iden-
     tifying the attribute, and	a value	which may be an	Internet address, an
     integer, or a NUL-terminated string, respectively.	 Alternatively,
     rad_put_vendor_addr(), rad_put_vendor_int() or rad_put_vendor_string()
     may be used to specify vendor specific attributes.	 Vendor	specific defi-
     nitions may be found in <radlib_vs.h>

     The library also provides a function rad_put_attr() which can be used to
     supply a raw, uninterpreted attribute.  The data argument points to an
     array of bytes, and the len argument specifies its	length.

     The rad_put_X() functions return 0	on success, or -1 if an	error occurs.

SENDING	THE REQUEST AND	RECEIVING THE RESPONSE
     After the RADIUS request has been constructed, it is sent either by means
     of	rad_send_request() or by a combination of calls	to
     rad_init_send_request() and rad_continue_send_request().

     The rad_send_request() function sends the request and waits for a valid
     reply, retrying the defined servers in round-robin	fashion	as necessary.
     If	a valid	response is received, rad_send_request() returns the RADIUS
     code which	specifies the type of the response.  This will typically be
     RAD_ACCESS_ACCEPT,	RAD_ACCESS_REJECT, or RAD_ACCESS_CHALLENGE.  If	no
     valid response is received, rad_send_request() returns -1.

     As	an alternative,	if you do not wish to block waiting for	a response,
     rad_init_send_request() and rad_continue_send_request() may be used
     instead.  If a reply is received from the RADIUS server or	a timeout
     occurs, these functions return a value as described for
     rad_send_request().  Otherwise, a value of	zero is	returned and the val-
     ues pointed to by fd and tv are set to the	descriptor and timeout that
     should be passed to select(2).

     rad_init_send_request() must be called first, followed by repeated	calls
     to	rad_continue_send_request() as long as a return	value of zero is
     given.  Between each call,	the application	should call select(2), passing
     *fd as a read descriptor and timing out after the interval	specified by
     tv.  When select returns, rad_continue_send_request() should be called
     with selected set to a non-zero value if select(2)	indicated that the
     descriptor	is readable.

     Like RADIUS requests, each	response may contain zero or more attributes.
     After a response has been received	successfully by	rad_send_request() or
     rad_continue_send_request(), its attributes can be	extracted one by one
     using rad_get_attr().  Each time rad_get_attr() is	called,	it gets	the
     next attribute from the current response, and stores a pointer to the
     data and the length of the	data via the reference parameters data and
     len, respectively.	 Note that the data resides in the response itself,
     and must not be modified.	A successful call to rad_get_attr() returns
     the RADIUS	attribute type.	 If no more attributes remain in the current
     response, rad_get_attr() returns 0.  If an	error such as a	malformed
     attribute is detected, -1 is returned.

     If	rad_get_attr() returns RAD_VENDOR_SPECIFIC, rad_get_vendor_attr() may
     be	called to determine the	vendor.	 The vendor specific RADIUS attribute
     type is returned.	The reference parameters data and len (as returned
     from rad_get_attr()) are passed to	rad_get_vendor_attr(), and are
     adjusted to point to the vendor specific attribute	data.

     The common	types of attributes can	be decoded using rad_cvt_addr(),
     rad_cvt_int(), and	rad_cvt_string().  These functions accept a pointer to
     the attribute data, which should have been	obtained using rad_get_attr()
     and optionally rad_get_vendor_attr().  In the case	of rad_cvt_string(),
     the length	len must also be given.	 These functions interpret the
     attribute as an Internet address, an integer, or a	string,	respectively,
     and return	its value.  rad_cvt_string() returns its value as a NUL-termi-
     nated string in dynamically allocated memory.  The	application should
     free the string using free(3) when	it is no longer	needed.

     If	insufficient virtual memory is available, rad_cvt_string() returns
     NULL.  rad_cvt_addr() and rad_cvt_int() cannot fail.

     The rad_request_authenticator() function may be used to obtain the
     Request-Authenticator attribute value associated with the current RADIUS
     server according to the supplied rad_handle.  The target buffer buf of
     length len	must be	supplied and should be at least	16 bytes.  The return
     value is the number of bytes written to buf or -1 to indicate that	len
     was not large enough.

     The rad_server_secret() returns the secret	shared with the	current	RADIUS
     server according to the supplied rad_handle.

OBTAINING ERROR	MESSAGES
     Those functions which accept a struct rad_handle *	argument record	an
     error message if they fail.  The error message can	be retrieved by	call-
     ing rad_strerror().  The message text is overwritten on each new error
     for the given struct rad_handle *.	 Thus the message must be copied if it
     is	to be preserved	through	subsequent library calls using the same	han-
     dle.

CLEANUP
     To	free the resources used	by the RADIUS library, call rad_close().

RETURN VALUES
     The following functions return a non-negative value on success.  If they
     detect an error, they return -1 and record	an error message which can be
     retrieved using rad_strerror().

	   rad_add_server()
	   rad_config()
	   rad_create_request()
	   rad_get_attr()
	   rad_put_addr()
	   rad_put_attr()
	   rad_put_int()
	   rad_put_string()
	   rad_init_send_request()
	   rad_continue_send_request()
	   rad_send_request()

     The following functions return a non-NULL pointer on success.  If they
     are unable	to allocate sufficient virtual memory, they return NULL, with-
     out recording an error message.

	   rad_acct_open()
	   rad_auth_open()
	   rad_cvt_string()

FILES
     /etc/radius.conf

SEE ALSO
     radius.conf(5)

     C.	Rigney,	et al, Remote Authentication Dial In User Service (RADIUS),
     RFC 2138.

     C.	Rigney,	RADIUS Accounting, RFC 2139.

AUTHORS
     This software was originally written by John Polstra, and donated to the
     FreeBSD project by	Juniper	Networks, Inc.	Oleg Semyonov subsequently
     added the ability to perform RADIUS accounting.

FreeBSD	9.3		       October 30, 1999			   FreeBSD 9.3

NAME | SYNOPSIS | DESCRIPTION | INITIALIZATION | CREATING A RADIUS REQUEST | SENDING THE REQUEST AND RECEIVING THE RESPONSE | OBTAINING ERROR MESSAGES | CLEANUP | RETURN VALUES | FILES | SEE ALSO | AUTHORS

Want to link to this manual page? Use this URL:
<http://www.freebsd.org/cgi/man.cgi?query=libradius&sektion=3&manpath=FreeBSD+4.11-RELEASE>

home | help