mdoc(7) police: tidy up the formatting.
This commit is contained in:
Ruslan Ermilov
parent
55dd392cb4
commit
81b380a87b
@ -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.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user