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);
uint32_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(
uint32_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,
uint32_t
value);
int
rad_put_string(
struct
rad_handle *h,
int
type,
const char
*str);
int
rad_put_message_authentic(
struct
rad_handle *h);
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,
uint32_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);
u_char *
rad_demangle(
struct
rad_handle *h,
const void
*mangled,
size_t
mlen);
u_char *
rad_demangle_mppe_key(
struct
rad_handle *h,
const void
*mangled,
size_t
mlen,
size_t *len);
const char *
rad_strerror(
struct
rad_handle *h);
DESCRIPTION
The
libradius library implements the client side of the Remote
Authentication Dial In User Service (RADIUS). RADIUS, defined in RFCs 2865 and
2866, 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 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
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 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
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.
It is possible adding the Message-Authenticator to the request. This is an
HMAC-MD5 hash of the entire Access-Request packet (see RFC 3579). This
attribute must be present in any packet that includes an EAP-Message
attribute. It can be added by using the
rad_put_message_authentic() function. The
libradius library calculates the HMAC-MD5 hash implicitly
before sending the request. If the Message-Authenticator was found inside the
response packet, then the packet is silently dropped, if the validation
failed. In order to get this feature, the library should be compiled with
OpenSSL support.
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 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.
The
rad_demangle() function demangles attributes containing
passwords and MS-CHAPv1 MPPE-Keys. The return value is
NULL
on failure, or the plaintext attribute. This
value should be freed using
free(3) when it is no longer
needed.
The
rad_demangle_mppe_key() function demangles the send- and
recv-keys when using MPPE (see RFC 2548). The return value is
NULL
on failure, or the plaintext attribute. This
value should be freed using
free(3) when it is no longer
needed.
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 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
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_put_message_authentic()
- 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
, without recording an error message.
- rad_acct_open()
- rad_auth_open()
- rad_cvt_string()
The following functions return a
non-NULL
pointer on success.
If they fail, they return
NULL
, with recording an
error message.
- rad_demangle()
- rad_demangle_mppe_key()
FILES
-
-
- /etc/radius.conf
-
SEE ALSO
radius.conf(5)
C. Rigney, et al,
Remote Authentication Dial In User Service (RADIUS),
RFC 2865.
C. Rigney, RADIUS
Accounting, RFC 2866.
G. Zorn, Microsoft
Vendor-specific RADIUS attributes, RFC
2548.
C. Rigney, et al,
RADIUS extensions, RFC
2869.
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. Later additions and changes by
Michael Bretterklieber.