d/freebsd-nq
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

mdoc(7) police: tidy up the formatting.

Browse Source
This commit is contained in:
Ruslan Ermilov 2002-08-09 12:07:17 +00:00
parent 55dd392cb4
commit 81b380a87b
1 changed files with 115 additions and 81 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

196
lib/libradius/libradius.3
View File

@ -24,7 +24,7 @@
.\" .\"
.\" $FreeBSD$ .\" $FreeBSD$
.\" .\"
.Dd October 30, 1999 .Dd June 12, 2002
.Dt LIBRADIUS 3 .Dt LIBRADIUS 3
.Os .Os
.Sh NAME .Sh NAME
@ -32,11 +32,11 @@
.Nd RADIUS client library .Nd RADIUS client library
.Sh SYNOPSIS .Sh SYNOPSIS
.In radlib.h .In radlib.h
.Ft struct rad_handle * .Ft "struct rad_handle *"
.Fn rad_acct_open "void" .Fn rad_acct_open "void"
.Ft int .Ft int
.Fn rad_add_server "struct rad_handle *h" "const char *host" "int port" "const char *secret" "int timeout" "int max_tries" .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" .Fn rad_auth_open "void"
.Ft void .Ft void
.Fn rad_close "struct rad_handle *h" .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" .Fn rad_continue_send_request "struct rad_handle *h" "int selected" "int *fd" "struct timeval *tv"
.Ft int .Ft int
.Fn rad_create_request "struct rad_handle *h" "int code" .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" .Fn rad_cvt_addr "const void *data"
.Ft u_int32_t .Ft u_int32_t
.Fn rad_cvt_int "const void *data" .Fn rad_cvt_int "const void *data"
@ -78,24 +78,25 @@
.Fn rad_request_authenticator "struct rad_handle *h" "char *buf" "size_t len" .Fn rad_request_authenticator "struct rad_handle *h" "char *buf" "size_t len"
.Ft int .Ft int
.Fn rad_send_request "struct rad_handle *h" .Fn rad_send_request "struct rad_handle *h"
.Ft const char * .Ft "const char *"
.Fn rad_server_secret "struct rad_handle *h" .Fn rad_server_secret "struct rad_handle *h"
.Ft const char * .Ft "const char *"
.Fn rad_strerror "struct rad_handle *h" .Fn rad_strerror "struct rad_handle *h"
.Sh DESCRIPTION .Sh DESCRIPTION
The The
.Nm .Nm
library implements the client side of the Remote Authentication Dial 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 allows clients to perform authentication and accounting by means of
network requests to remote servers. network requests to remote servers.
.Sh INITIALIZATION .Ss Initialization
To use the library, an application must first call To use the library, an application must first call
.Fn rad_auth_open .Fn rad_auth_open
or or
.Fn rad_acct_open .Fn rad_acct_open
to obtain a to obtain a
.Va struct rad_handle * , .Vt "struct rad_handle *" ,
which provides the context for subsequent operations. which provides the context for subsequent operations.
The former function is used for RADIUS authentication and the The former function is used for RADIUS authentication and the
latter is used for RADIUS accounting. latter is used for RADIUS accounting.
@ -103,7 +104,8 @@ Calls to
.Fn rad_auth_open .Fn rad_auth_open
and and
.Fn rad_acct_open .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 the necessary memory cannot be allocated, the functions return
.Dv NULL . .Dv NULL .
For compatibility with earlier versions of this library, For compatibility with earlier versions of this library,
@ -112,7 +114,8 @@ is provided as a synonym for
.Fn rad_auth_open . .Fn rad_auth_open .
.Pp .Pp
Before issuing any RADIUS requests, the library must be made aware 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 library is to call
.Fn rad_config . .Fn rad_config .
.Fn rad_config .Fn rad_config
@ -120,7 +123,7 @@ causes the library to read a configuration file whose format is
described in described in
.Xr radius.conf 5 . .Xr radius.conf 5 .
The pathname of the configuration file is passed as the The pathname of the configuration file is passed as the
.Va file .Fa file
argument to argument to
.Fn rad_config . .Fn rad_config .
This argument may also be given as This argument may also be given as
@ -129,38 +132,46 @@ in which case the standard configuration file
.Pa /etc/radius.conf .Pa /etc/radius.conf
is used. is used.
.Fn rad_config .Fn rad_config
returns 0 on success, or -1 if an error occurs. returns 0 on success, or \-1 if an error occurs.
.Pp .Pp
The library can also be configured programmatically by calls to The library can also be configured programmatically by calls to
.Fn rad_add_server . .Fn rad_add_server .
The The
.Va host .Fa host
parameter specifies the server host, either as a fully qualified parameter specifies the server host, either as a fully qualified
domain name or as a dotted-quad IP address in text form. domain name or as a dotted-quad IP address in text form.
The The
.Va port .Fa port
parameter specifies the UDP port to contact on the server. If parameter specifies the UDP port to contact on the server.
.Va port If
.Fa port
is given as 0, the library looks up the is given as 0, the library looks up the
.Ql radius/udp .Ql radius/udp
or or
.Ql radacct/udp .Ql radacct/udp
service in the network services database, and uses the port found service in the network
there. If no entry is found, the library uses the standard RADIUS .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. ports, 1812 for authentication and 1813 for accounting.
The shared secret for the server host is passed to the The shared secret for the server host is passed to the
.Va secret .Fa secret
parameter. 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. ignores all but the leading 128 bytes of the shared secret.
The timeout for receiving replies from the server is passed to the The timeout for receiving replies from the server is passed to the
.Va timeout .Fa timeout
parameter, in units of seconds. The maximum number of repeated parameter, in units of seconds.
The maximum number of repeated
requests to make before giving up is passed into the requests to make before giving up is passed into the
.Va max_tries .Fa max_tries
parameter. parameter.
.Fn rad_add_server .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 .Pp
.Fn rad_add_server .Fn rad_add_server
may be called multiple times, and it may be used together with 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. At most 10 servers may be specified.
When multiple servers are given, they are tried in round-robin When multiple servers are given, they are tried in round-robin
fashion until a valid response is received, or until each server's fashion until a valid response is received, or until each server's
.Va max_tries .Fa max_tries
limit has been reached. 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, 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 begin constructing a new request, call
.Fn rad_create_request . .Fn rad_create_request .
In addition to the usual In addition to the usual
.Va struct rad_handle * , .Vt "struct rad_handle *" ,
this function takes a this function takes a
.Va code .Fa code
parameter which specifies the type of the request. Most often this parameter which specifies the type of the request.
Most often this
will be will be
.Dv RAD_ACCESS_REQUEST . .Dv RAD_ACCESS_REQUEST .
.Fn rad_create_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 .Pp
After the request has been created with After the request has been created with
.Fn rad_create_request , .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_addr ,
.Fn rad_put_int , .Fn rad_put_int ,
and and
.Fn rad_put_string . .Fn rad_put_string .
Each accepts a Each accepts a
.Va type .Fa type
parameter identifying the attribute, and a value which may be 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. respectively.
Alternatively, Alternatively,
.Fn rad_put_vendor_addr , .Fn rad_put_vendor_addr ,
.Fn rad_put_vendor_int .Fn rad_put_vendor_int
or or
.Fn rad_put_vendor_string .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 definitions may be found in
.In radlib_vs.h .Aq Pa radlib_vs.h
.Pp .Pp
The library also provides a function The library also provides a function
.Fn rad_put_attr .Fn rad_put_attr
which can be used to supply a raw, uninterpreted attribute. The which can be used to supply a raw, uninterpreted attribute.
.Va data The
.Fa data
argument points to an array of bytes, and the argument points to an array of bytes, and the
.Va len .Fa len
argument specifies its length. argument specifies its length.
.Pp .Pp
The The
.Fn rad_put_X .Fn rad_put_X
functions return 0 on success, or -1 if an error occurs. functions return 0 on success, or \-1 if an error occurs.
.Sh SENDING THE REQUEST AND RECEIVING THE RESPONSE .Ss Sending the Request and Receiving the Response
After the RADIUS request has been constructed, it is sent either by means of After the RADIUS request has been constructed, it is sent either by means of
.Fn rad_send_request .Fn rad_send_request
or by a combination of calls to or by a combination of calls to
@ -239,19 +257,20 @@ or
.Dv RAD_ACCESS_CHALLENGE . .Dv RAD_ACCESS_CHALLENGE .
If no valid response is received, If no valid response is received,
.Fn rad_send_request .Fn rad_send_request
returns -1. returns \-1.
.Pp .Pp
As an alternative, if you do not wish to block waiting for a response, As an alternative, if you do not wish to block waiting for a response,
.Fn rad_init_send_request .Fn rad_init_send_request
and and
.Fn rad_continue_send_request .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 timeout occurs, these functions return a value as described for
.Fn rad_send_request . .Fn rad_send_request .
Otherwise, a value of zero is returned and the values pointed to by Otherwise, a value of zero is returned and the values pointed to by
.Ar fd .Fa fd
and and
.Ar tv .Fa tv
are set to the descriptor and timeout that should be passed to are set to the descriptor and timeout that should be passed to
.Xr select 2 . .Xr select 2 .
.Pp .Pp
@ -262,19 +281,22 @@ as long as a return value of zero is given.
Between each call, the application should call Between each call, the application should call
.Xr select 2 , .Xr select 2 ,
passing passing
.Ar *fd .Fa *fd
as a read descriptor and timing out after the interval specified by as a read descriptor and timing out after the interval specified by
.Ar tv . .Fa tv .
When select returns, When
.Xr select 2
returns,
.Fn rad_continue_send_request .Fn rad_continue_send_request
should be called with should be called with
.Ar selected .Fa selected
set to a non-zero value if set to a non-zero value if
.Xr select 2 .Xr select 2
indicated that the descriptor is readable. indicated that the descriptor is readable.
.Pp .Pp
Like RADIUS requests, each response may contain zero or more 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 .Fn rad_send_request
or or
.Fn rad_continue_send_request , .Fn rad_continue_send_request ,
@ -285,10 +307,11 @@ Each time
is called, it gets the next attribute from the current response, and 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 stores a pointer to the data and the length of the data via the
reference parameters reference parameters
.Va data .Fa data
and and
.Va len , .Fa len ,
respectively. Note that the data resides in the response itself, respectively.
Note that the data resides in the response itself,
and must not be modified. and must not be modified.
A successful call to A successful call to
.Fn rad_get_attr .Fn rad_get_attr
@ -296,7 +319,7 @@ returns the RADIUS attribute type.
If no more attributes remain in the current response, If no more attributes remain in the current response,
.Fn rad_get_attr .Fn rad_get_attr
returns 0. 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. returned.
.Pp .Pp
If If
@ -307,9 +330,9 @@ returns
may be called to determine the vendor. may be called to determine the vendor.
The vendor specific RADIUS attribute type is returned. The vendor specific RADIUS attribute type is returned.
The reference parameters The reference parameters
.Va data .Fa data
and and
.Va len .Fa len
(as returned from (as returned from
.Fn rad_get_attr ) .Fn rad_get_attr )
are passed to are passed to
@ -329,13 +352,17 @@ and optionally
In the case of In the case of
.Fn rad_cvt_string , .Fn rad_cvt_string ,
the length the length
.Va len .Fa len
must also be given. These functions interpret the attribute as an must also be given.
These functions interpret the attribute as an
Internet address, an integer, or a string, respectively, and return Internet address, an integer, or a string, respectively, and return
its value. its value.
.Fn rad_cvt_string .Fn rad_cvt_string
returns its value as a NUL-terminated string in dynamically returns its value as a
allocated memory. The application should free the string using .Dv NUL Ns -terminated
string in dynamically
allocated memory.
The application should free the string using
.Xr free 3 .Xr free 3
when it is no longer needed. when it is no longer needed.
.Pp .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 associated with the current RADIUS server according to the supplied
rad_handle. rad_handle.
The target buffer The target buffer
.Ar buf .Fa buf
of length of length
.Ar len .Fa len
must be supplied and should be at least 16 bytes. must be supplied and should be at least 16 bytes.
The return value is the number of bytes written to The return value is the number of bytes written to
.Ar buf .Fa buf
or -1 to indicate that or \-1 to indicate that
.Ar len .Fa len
was not large enough. was not large enough.
.Pp .Pp
The The
.Fn rad_server_secret .Fn rad_server_secret
returns the secret shared with the current RADIUS server according to the returns the secret shared with the current RADIUS server according to the
supplied rad_handle. supplied rad_handle.
.Sh OBTAINING ERROR MESSAGES .Ss Obtaining Error Messages
Those functions which accept a Those functions which accept a
.Va struct rad_handle * .Vt "struct rad_handle *"
argument record an error message if they fail. The error message argument record an error message if they fail.
The error message
can be retrieved by calling can be retrieved by calling
.Fn rad_strerror . .Fn rad_strerror .
The message text is overwritten on each new error for the given 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 Thus the message must be copied if it is to be preserved through
subsequent library calls using the same handle. subsequent library calls using the same handle.
.Sh CLEANUP .Ss Cleanup
To free the resources used by the RADIUS library, call To free the resources used by the RADIUS library, call
.Fn rad_close . .Fn rad_close .
.Sh RETURN VALUES .Sh RETURN VALUES
The following functions return a non-negative value on success. If The following functions return a non-negative value on success.
they detect an error, they return -1 and record an error message If
they detect an error, they return \-1 and record an error message
which can be retrieved using which can be retrieved using
.Fn rad_strerror . .Fn rad_strerror .
.Pp .Pp
@ -414,7 +443,8 @@ which can be retrieved using
.Pp .Pp
The following functions return a The following functions return a
.No non- Ns Dv NULL .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 virtual memory, they return
.Dv NULL , .Dv NULL ,
without recording an error message. without recording an error message.
@ -428,24 +458,28 @@ without recording an error message.
.Fn rad_cvt_string .Fn rad_cvt_string
.El .El
.Sh FILES .Sh FILES
.Pa /etc/radius.conf .Bl -tag -width indent
.It Pa /etc/radius.conf
.El
.Sh SEE ALSO .Sh SEE ALSO
.Xr radius.conf 5 .Xr radius.conf 5
.Rs .Rs
.%A C. Rigney, et al .%A "C. Rigney, et al"
.%T "Remote Authentication Dial In User Service (RADIUS)" .%T "Remote Authentication Dial In User Service (RADIUS)"
.%O RFC 2138 .%O "RFC 2138"
.Re .Re
.Rs .Rs
.%A C. Rigney .%A "C. Rigney"
.%T RADIUS Accounting .%T "RADIUS Accounting"
.%O RFC 2139 .%O "RFC 2139"
.Re .Re
.Sh AUTHORS .Sh AUTHORS
.An -nosplit
This software was originally written by This software was originally written by
.An John Polstra , .An John Polstra ,
and donated to the and donated to the
.Fx .Fx
project by Juniper Networks, Inc. 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. accounting.