*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->FreeBSD man pages -> libradius (3)              



NAME    [Toc]    [Back]

     libradius -- RADIUS client library

SYNOPSIS    [Toc]    [Back]

     #include <radlib.h>

     struct rad_handle *

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

     struct rad_handle *

     rad_close(struct rad_handle *h);

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

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

     rad_create_request(struct rad_handle *h, int code);

     struct in_addr
     rad_cvt_addr(const void *data);

     rad_cvt_int(const void *data);

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

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

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

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

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

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

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

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

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

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

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

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

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

     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    [Toc]    [Back]

     The libradius library implements the client side of the Remote Authentication
 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    [Toc]    [Back]
     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 context
 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 allocated,
 the functions return NULL.	For compatibility with earlier versions
 of this library, rad_open() is provided as a synonym for

     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 configuration
 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 configuration
 file /etc/radius.conf is used.	rad_config() returns 0 on success,
 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(5) 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    [Toc]    [Back]
     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 identifying
 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 definitions
 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    [Toc]    [Back]
     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
     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 values
 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(2) 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-terminated 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    [Toc]    [Back]
     Those functions which accept a struct rad_handle * argument record an
     error message if they fail.  The error message can be retrieved by calling
 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 handle.

   Cleanup    [Toc]    [Back]
     To free the resources used by the RADIUS library, call rad_close().

RETURN VALUES    [Toc]    [Back]

     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().


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


FILES    [Toc]    [Back]


SEE ALSO    [Toc]    [Back]


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

     C. Rigney, RADIUS Accounting, RFC 2139.

AUTHORS    [Toc]    [Back]

     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 5.2.1			 June 12, 2002			 FreeBSD 5.2.1
[ Back ]
 Similar pages
Name OS Title
radius.conf FreeBSD RADIUS client configuration file
pam_radius FreeBSD RADIUS authentication PAM module
bbox2 IRIX culls and prunes to bounding box and minimum pixel radius
libtacplus FreeBSD TACACS+ client library
bsnmpclient FreeBSD SNMP client library
clnt_sperror FreeBSD library routines for client side calls
rpc_broadcast NetBSD library routines for client side calls
rpc_call NetBSD library routines for client side calls
clnt_sperror NetBSD library routines for client side calls
clnt_sperrno NetBSD library routines for client side calls
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service