1 files changed, 317 insertions, 0 deletions
diff --git a/lib/libradius/libradius.3 b/lib/libradius/libradius.3
new file mode 100644
index 000000000000..25ccdc09d816
--- /dev/null
+++ b/lib/libradius/libradius.3
@@ -0,0 +1,317 @@
+.\" 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_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 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 by means
+of
+.Fn rad_send_request .
+This 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
+Like RADIUS requests, each response may contain zero or more
+attributes.  After a response has been received successfully by
+.Fn rad_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_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.