366 lines
11 KiB
Groff
366 lines
11 KiB
Groff
.\" Copyright 1998 Juniper Networks, Inc.
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
|
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
|
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
.\" SUCH DAMAGE.
|
|
.\"
|
|
.\" $FreeBSD$
|
|
.\"
|
|
.Dd July 29, 1998
|
|
.Dt LIBRADIUS 3
|
|
.Os FreeBSD
|
|
.Sh NAME
|
|
.Nm libradius
|
|
.Nd RADIUS client library
|
|
.Sh SYNOPSIS
|
|
.Fd #include <radlib.h>
|
|
.Ft int
|
|
.Fn rad_add_server "struct rad_handle *h" "const char *host" "int port" "const char *secret" "int timeout" "int max_tries"
|
|
.Ft void
|
|
.Fn rad_close "struct rad_handle *h"
|
|
.Ft int
|
|
.Fn rad_config "struct rad_handle *h" "const char *file"
|
|
.Ft int
|
|
.Fn rad_continue_send_request "struct rad_handle *h" "int selected" "int *fd" "struct timeval *tv"
|
|
.Ft int
|
|
.Fn rad_create_request "struct rad_handle *h" "int code"
|
|
.Ft struct in_addr
|
|
.Fn rad_cvt_addr "const void *data"
|
|
.Ft u_int32_t
|
|
.Fn rad_cvt_int "const void *data"
|
|
.Ft char *
|
|
.Fn rad_cvt_string "const void *data" "size_t len"
|
|
.Ft int
|
|
.Fn rad_get_attr "struct rad_handle *h" "const void **data" "size_t *len"
|
|
.Ft int
|
|
.Fn rad_init_send_request "struct rad_handle *h" "int *fd" "struct timeval *tv"
|
|
.Ft struct rad_handle *
|
|
.Fn rad_open "void"
|
|
.Ft int
|
|
.Fn rad_put_addr "struct rad_handle *h" "int type" "struct in_addr addr"
|
|
.Ft int
|
|
.Fn rad_put_attr "struct rad_handle *h" "int type" "const void *data" "size_t len"
|
|
.Ft int
|
|
.Fn rad_put_int "struct rad_handle *h" "int type" "u_int32_t value"
|
|
.Ft int
|
|
.Fn rad_put_string "struct rad_handle *h" "int type" "const char *str"
|
|
.Ft int
|
|
.Fn rad_send_request "struct rad_handle *h"
|
|
.Ft const char *
|
|
.Fn rad_strerror "struct rad_handle *h"
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm
|
|
library implements the client side of the Remote Authentication
|
|
Dial In User Service (RADIUS). RADIUS, defined in RFC 2138, allows
|
|
clients to perform authentication by means of network requests to
|
|
remote authentication servers.
|
|
.Sh INITIALIZATION
|
|
To use the library, an application must first call
|
|
.Fn rad_open
|
|
to obtain a
|
|
.Va struct rad_handle * ,
|
|
which provides the context for subsequent operations.
|
|
Calls to
|
|
.Fn rad_open
|
|
always succeed unless insufficient virtual memory is available. If
|
|
the necessary memory cannot be allocated,
|
|
.Fn rad_open
|
|
returns
|
|
.Dv NULL .
|
|
.Pp
|
|
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
|
|
.Fn rad_config .
|
|
.Fn rad_config
|
|
causes the library to read a configuration file whose format is
|
|
described in
|
|
.Xr radius.conf 5 .
|
|
The pathname of the configuration file is passed as the
|
|
.Va file
|
|
argument to
|
|
.Fn rad_config .
|
|
This argument may also be given as
|
|
.Dv NULL ,
|
|
in which case the standard configuration file
|
|
.Pa /etc/radius.conf
|
|
is used.
|
|
.Fn rad_config
|
|
returns 0 on success, or -1 if an error occurs.
|
|
.Pp
|
|
The library can also be configured programmatically by calls to
|
|
.Fn rad_add_server .
|
|
The
|
|
.Va host
|
|
parameter specifies the server host, either as a fully qualified
|
|
domain name or as a dotted-quad IP address in text form.
|
|
The
|
|
.Va port
|
|
parameter specifies the UDP port to contact on the server. If
|
|
.Va port
|
|
is given as 0, the library looks up the
|
|
.Ql radius/udp
|
|
service in the network services database, and uses the port found
|
|
there. If no entry is found, the library uses port 1812, the standard
|
|
RADIUS port. The shared secret for the server host is passed to the
|
|
.Va 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
|
|
.Va timeout
|
|
parameter, in units of seconds. The maximum number of repeated
|
|
requests to make before giving up is passed into the
|
|
.Va max_tries
|
|
parameter.
|
|
.Fn rad_add_server
|
|
returns 0 on success, or -1 if an error occurs.
|
|
.Pp
|
|
.Fn rad_add_server
|
|
may be called multiple times, and it may be used together with
|
|
.Fn 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
|
|
.Va max_tries
|
|
limit has been reached.
|
|
.Sh 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
|
|
.Fn rad_create_request .
|
|
In addition to the usual
|
|
.Va struct rad_handle * ,
|
|
this function takes a
|
|
.Va code
|
|
parameter which specifies the type of the request. Most often this
|
|
will be
|
|
.Dv RAD_ACCESS_REQUEST .
|
|
.Fn rad_create_request
|
|
returns 0 on success, or -1 on if an error occurs.
|
|
.Pp
|
|
After the request has been created with
|
|
.Fn rad_create_request ,
|
|
attributes can be attached to it. This is done through calls to
|
|
.Fn rad_put_addr ,
|
|
.Fn rad_put_int ,
|
|
and
|
|
.Fn rad_put_string .
|
|
Each accepts a
|
|
.Va type
|
|
parameter identifying the attribute, and a value which may be
|
|
an Internet address, an integer, or a NUL-terminated string,
|
|
respectively.
|
|
.Pp
|
|
The library also provides a function
|
|
.Fn rad_put_attr
|
|
which can be used to supply a raw, uninterpreted attribute. The
|
|
.Va data
|
|
argument points to an array of bytes, and the
|
|
.Va len
|
|
argument specifies its length.
|
|
.Pp
|
|
The
|
|
.Fn rad_put_X
|
|
functions return 0 on success, or -1 if an error occurs.
|
|
.Sh SENDING THE REQUEST AND RECEIVING THE RESPONSE
|
|
After the RADIUS request has been constructed, it is sent either by means of
|
|
.Fn rad_send_request
|
|
or by a combination of calls to
|
|
.Fn rad_init_send_request
|
|
and
|
|
.Fn rad_continue_send_request .
|
|
.Pp
|
|
The
|
|
.Fn 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,
|
|
.Fn rad_send_request
|
|
returns the RADIUS code which specifies the type of the response.
|
|
This will typically be
|
|
.Dv RAD_ACCESS_ACCEPT ,
|
|
.Dv RAD_ACCESS_REJECT ,
|
|
or
|
|
.Dv RAD_ACCESS_CHALLENGE .
|
|
If no valid response is received,
|
|
.Fn rad_send_request
|
|
returns -1.
|
|
.Pp
|
|
As an alternative, if you do not wish to block waiting for a response,
|
|
.Fn rad_init_send_request
|
|
and
|
|
.Fn 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
|
|
.Fn rad_send_request .
|
|
Otherwise, a value of zero is returned and the values pointed to by
|
|
.Ar fd
|
|
and
|
|
.Ar tv
|
|
are set to the descriptor and timeout that should be passed to
|
|
.Xr select 2 .
|
|
.Pp
|
|
.Fn rad_init_send_request
|
|
must be called first, followed by repeated calls to
|
|
.Fn rad_continue_send_request
|
|
as long as a return value of zero is given.
|
|
Between each call, the application should call
|
|
.Xr select 2 ,
|
|
passing
|
|
.Ar *fd
|
|
as a read descriptor and timing out after the interval specified by
|
|
.Ar tv .
|
|
When select returns,
|
|
.Fn rad_continue_send_request
|
|
should be called with
|
|
.Ar selected
|
|
set to a non-zero value if
|
|
.Xr select 2
|
|
indicated that the descriptor is readable.
|
|
.Pp
|
|
Like RADIUS requests, each response may contain zero or more
|
|
attributes. After a response has been received successfully by
|
|
.Fn rad_send_request
|
|
or
|
|
.Fn rad_continue_send_request ,
|
|
its attributes can be extracted one by one using
|
|
.Fn rad_get_attr .
|
|
Each time
|
|
.Fn 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
|
|
.Va data
|
|
and
|
|
.Va len ,
|
|
respectively. Note that the data resides in the response itself,
|
|
and must not be modified.
|
|
A successful call to
|
|
.Fn rad_get_attr
|
|
returns the RADIUS attribute type.
|
|
If no more attributes remain in the current response,
|
|
.Fn rad_get_attr
|
|
returns 0.
|
|
If an error such as a malformed attribute is detected, -1 is
|
|
returned.
|
|
.Pp
|
|
The common types of attributes can be decoded using
|
|
.Fn rad_cvt_addr ,
|
|
.Fn rad_cvt_int ,
|
|
and
|
|
.Fn rad_cvt_string .
|
|
These functions accept a pointer to the attribute data, which should
|
|
have been obtained using
|
|
.Fn rad_get_attr .
|
|
In the case of
|
|
.Fn rad_cvt_string ,
|
|
the length
|
|
.Va len
|
|
must also be given. These functions interpret the attribute as an
|
|
Internet address, an integer, or a string, respectively, and return
|
|
its value.
|
|
.Fn rad_cvt_string
|
|
returns its value as a NUL-terminated string in dynamically
|
|
allocated memory. The application should free the string using
|
|
.Xr free 3
|
|
when it is no longer needed.
|
|
.Pp
|
|
If insufficient virtual memory is available,
|
|
.Fn rad_cvt_string
|
|
returns
|
|
.Dv NULL .
|
|
.Fn rad_cvt_addr
|
|
and
|
|
.Fn rad_cvt_int
|
|
cannot fail.
|
|
.Sh OBTAINING ERROR MESSAGES
|
|
Those functions which accept a
|
|
.Va struct rad_handle *
|
|
argument record an error message if they fail. The error message
|
|
can be retrieved by calling
|
|
.Fn rad_strerror .
|
|
The message text is overwritten on each new error for the given
|
|
.Va struct rad_handle * .
|
|
Thus the message must be copied if it is to be preserved through
|
|
subsequent library calls using the same handle.
|
|
.Sh CLEANUP
|
|
To free the resources used by the RADIUS library, call
|
|
.Fn rad_close .
|
|
.Sh 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
|
|
.Fn rad_strerror .
|
|
.Pp
|
|
.Bl -item -offset indent -compact
|
|
.It
|
|
.Fn rad_add_server
|
|
.It
|
|
.Fn rad_config
|
|
.It
|
|
.Fn rad_create_request
|
|
.It
|
|
.Fn rad_get_attr
|
|
.It
|
|
.Fn rad_put_addr
|
|
.It
|
|
.Fn rad_put_attr
|
|
.It
|
|
.Fn rad_put_int
|
|
.It
|
|
.Fn rad_put_string
|
|
.It
|
|
.Fn rad_init_send_request
|
|
.It
|
|
.Fn rad_continue_send_request
|
|
.It
|
|
.Fn rad_send_request
|
|
.El
|
|
.Pp
|
|
The following functions return a
|
|
.No non- Ns Dv NULL
|
|
pointer on success. If they are unable to allocate sufficient
|
|
virtual memory, they return
|
|
.Dv NULL ,
|
|
without recording an error message.
|
|
.Pp
|
|
.Bl -item -offset indent -compact
|
|
.It
|
|
.Fn rad_cvt_string
|
|
.It
|
|
.Fn rad_open
|
|
.El
|
|
.Sh FILES
|
|
.Pa /etc/radius.conf
|
|
.Sh SEE ALSO
|
|
.Xr radius.conf 5
|
|
.Rs
|
|
.%A C. Rigney, et al
|
|
.%T Remote Authentication Dial In User Service (RADIUS)
|
|
.%O RFC 2138
|
|
.Re
|
|
.Sh AUTHORS
|
|
This software was written by
|
|
.An John Polstra ,
|
|
and donated to the FreeBSD project by Juniper Networks, Inc.
|