diff options
Diffstat (limited to 'lib/libradius/libradius.3')
| -rw-r--r-- | lib/libradius/libradius.3 | 196 |
1 files changed, 115 insertions, 81 deletions
diff --git a/lib/libradius/libradius.3 b/lib/libradius/libradius.3 index 9291c38..2e675bc 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. |
