aboutsummaryrefslogtreecommitdiff
path: root/lib/libradius
diff options
context:
space:
mode:
authorRuslan Ermilov <ru@FreeBSD.org>2002-08-09 12:07:17 +0000
committerRuslan Ermilov <ru@FreeBSD.org>2002-08-09 12:07:17 +0000
commit81b380a87bdfbc1bc0be0140454c63675d3b2d35 (patch)
tree5ce1c47cee67b267bb81631e9ce78f76e88867c0 /lib/libradius
parent55dd392cb47072ad3c38ce885343bcce19e509fd (diff)
downloadsrc-81b380a87bdfbc1bc0be0140454c63675d3b2d35.tar.gz
src-81b380a87bdfbc1bc0be0140454c63675d3b2d35.zip
mdoc(7) police: tidy up the formatting.
Notes
Notes: svn path=/head/; revision=101581
Diffstat (limited to 'lib/libradius')
-rw-r--r--lib/libradius/libradius.3196
1 files changed, 115 insertions, 81 deletions
diff --git a/lib/libradius/libradius.3 b/lib/libradius/libradius.3
index 9291c387af52..2e675bc79aca 100644
--- a/lib/libradius/libradius.3
+++ b/lib/libradius/libradius.3
@@ -24,7 +24,7 @@
.\"
.\" $FreeBSD$
.\"
-.Dd October 30, 1999
+.Dd June 12, 2002
.Dt LIBRADIUS 3
.Os
.Sh NAME
@@ -32,11 +32,11 @@
.Nd RADIUS client library
.Sh SYNOPSIS
.In radlib.h
-.Ft struct rad_handle *
+.Ft "struct rad_handle *"
.Fn rad_acct_open "void"
.Ft int
.Fn rad_add_server "struct rad_handle *h" "const char *host" "int port" "const char *secret" "int timeout" "int max_tries"
-.Ft struct rad_handle *
+.Ft "struct rad_handle *"
.Fn rad_auth_open "void"
.Ft void
.Fn rad_close "struct rad_handle *h"
@@ -46,7 +46,7 @@
.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
+.Ft "struct in_addr"
.Fn rad_cvt_addr "const void *data"
.Ft u_int32_t
.Fn rad_cvt_int "const void *data"
@@ -78,24 +78,25 @@
.Fn rad_request_authenticator "struct rad_handle *h" "char *buf" "size_t len"
.Ft int
.Fn rad_send_request "struct rad_handle *h"
-.Ft const char *
+.Ft "const char *"
.Fn rad_server_secret "struct rad_handle *h"
-.Ft const char *
+.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 RFCs 2138 and 2139,
+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.
-.Sh INITIALIZATION
+.Ss Initialization
To use the library, an application must first call
.Fn rad_auth_open
or
.Fn rad_acct_open
to obtain a
-.Va struct rad_handle * ,
+.Vt "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.
@@ -103,7 +104,8 @@ Calls to
.Fn rad_auth_open
and
.Fn rad_acct_open
-always succeed unless insufficient virtual memory is available. If
+always succeed unless insufficient virtual memory is available.
+If
the necessary memory cannot be allocated, the functions return
.Dv NULL .
For compatibility with earlier versions of this library,
@@ -112,7 +114,8 @@ is provided as a synonym for
.Fn rad_auth_open .
.Pp
Before issuing any RADIUS requests, the library must be made aware
-of the servers it can contact. The easiest way to configure the
+of the servers it can contact.
+The easiest way to configure the
library is to call
.Fn rad_config .
.Fn rad_config
@@ -120,7 +123,7 @@ 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
+.Fa file
argument to
.Fn rad_config .
This argument may also be given as
@@ -129,38 +132,46 @@ 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.
+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
+.Fa 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
+.Fa port
+parameter specifies the UDP port to contact on the server.
+If
+.Fa port
is given as 0, the library looks up the
.Ql radius/udp
or
.Ql 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
+service in the network
+.Xr 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
-.Va secret
+.Fa secret
parameter.
-It may be any NUL-terminated string of bytes. The RADIUS protocol
+It may be any
+.Dv NUL Ns -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
+.Fa timeout
+parameter, in units of seconds.
+The maximum number of repeated
requests to make before giving up is passed into the
-.Va max_tries
+.Fa max_tries
parameter.
.Fn rad_add_server
-returns 0 on success, or -1 if an error occurs.
+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
@@ -168,56 +179,63 @@ may be called multiple times, and it may be used together with
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
+.Fa max_tries
limit has been reached.
-.Sh CREATING A RADIUS REQUEST
+.Ss 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
+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 * ,
+.Vt "struct rad_handle *" ,
this function takes a
-.Va code
-parameter which specifies the type of the request. Most often this
+.Fa 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.
+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
+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
+.Fa type
parameter identifying the attribute, and a value which may be
-an Internet address, an integer, or a NUL-terminated string,
+an Internet address, an integer, or a
+.Dv NUL Ns -terminated
+string,
respectively.
Alternatively,
.Fn rad_put_vendor_addr ,
.Fn rad_put_vendor_int
or
.Fn rad_put_vendor_string
-may be used to specify vendor specific attributes. Vendor specific
+may be used to specify vendor specific attributes.
+Vendor specific
definitions may be found in
-.In radlib_vs.h
+.Aq Pa radlib_vs.h
.Pp
The library also provides a function
.Fn rad_put_attr
-which can be used to supply a raw, uninterpreted attribute. The
-.Va data
+which can be used to supply a raw, uninterpreted attribute.
+The
+.Fa data
argument points to an array of bytes, and the
-.Va len
+.Fa 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
+functions return 0 on success, or \-1 if an error occurs.
+.Ss 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
@@ -239,19 +257,20 @@ or
.Dv RAD_ACCESS_CHALLENGE .
If no valid response is received,
.Fn rad_send_request
-returns -1.
+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
+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
+.Fa fd
and
-.Ar tv
+.Fa tv
are set to the descriptor and timeout that should be passed to
.Xr select 2 .
.Pp
@@ -262,19 +281,22 @@ as long as a return value of zero is given.
Between each call, the application should call
.Xr select 2 ,
passing
-.Ar *fd
+.Fa *fd
as a read descriptor and timing out after the interval specified by
-.Ar tv .
-When select returns,
+.Fa tv .
+When
+.Xr select 2
+returns,
.Fn rad_continue_send_request
should be called with
-.Ar selected
+.Fa 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
+attributes.
+After a response has been received successfully by
.Fn rad_send_request
or
.Fn rad_continue_send_request ,
@@ -285,10 +307,11 @@ Each time
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
+.Fa data
and
-.Va len ,
-respectively. Note that the data resides in the response itself,
+.Fa len ,
+respectively.
+Note that the data resides in the response itself,
and must not be modified.
A successful call to
.Fn rad_get_attr
@@ -296,7 +319,7 @@ 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
+If an error such as a malformed attribute is detected, \-1 is
returned.
.Pp
If
@@ -307,9 +330,9 @@ returns
may be called to determine the vendor.
The vendor specific RADIUS attribute type is returned.
The reference parameters
-.Va data
+.Fa data
and
-.Va len
+.Fa len
(as returned from
.Fn rad_get_attr )
are passed to
@@ -329,13 +352,17 @@ and optionally
In the case of
.Fn rad_cvt_string ,
the length
-.Va len
-must also be given. These functions interpret the attribute as an
+.Fa 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
+returns its value as a
+.Dv NUL Ns -terminated
+string in dynamically
+allocated memory.
+The application should free the string using
.Xr free 3
when it is no longer needed.
.Pp
@@ -354,36 +381,38 @@ 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
-.Ar buf
+.Fa buf
of length
-.Ar len
+.Fa len
must be supplied and should be at least 16 bytes.
The return value is the number of bytes written to
-.Ar buf
-or -1 to indicate that
-.Ar len
+.Fa buf
+or \-1 to indicate that
+.Fa len
was not large enough.
.Pp
The
.Fn rad_server_secret
returns the secret shared with the current RADIUS server according to the
supplied rad_handle.
-.Sh OBTAINING ERROR MESSAGES
+.Ss Obtaining Error Messages
Those functions which accept a
-.Va struct rad_handle *
-argument record an error message if they fail. The error message
+.Vt "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 * .
+.Vt "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
+.Ss 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
+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
@@ -414,7 +443,8 @@ which can be retrieved using
.Pp
The following functions return a
.No non- Ns Dv NULL
-pointer on success. If they are unable to allocate sufficient
+pointer on success.
+If they are unable to allocate sufficient
virtual memory, they return
.Dv NULL ,
without recording an error message.
@@ -428,24 +458,28 @@ without recording an error message.
.Fn rad_cvt_string
.El
.Sh FILES
-.Pa /etc/radius.conf
+.Bl -tag -width indent
+.It Pa /etc/radius.conf
+.El
.Sh SEE ALSO
.Xr radius.conf 5
.Rs
-.%A C. Rigney, et al
+.%A "C. Rigney, et al"
.%T "Remote Authentication Dial In User Service (RADIUS)"
-.%O RFC 2138
+.%O "RFC 2138"
.Re
.Rs
-.%A C. Rigney
-.%T RADIUS Accounting
-.%O RFC 2139
+.%A "C. Rigney"
+.%T "RADIUS Accounting"
+.%O "RFC 2139"
.Re
.Sh AUTHORS
+.An -nosplit
This software was originally written by
.An John Polstra ,
and donated to the
.Fx
project by Juniper Networks, Inc.
-Oleg Semyonov subsequently added the ability to perform RADIUS
+.An Oleg Semyonov
+subsequently added the ability to perform RADIUS
accounting.