Sending the Request and Receiving the Response
After the RADIUS request has been constructed, it is sent either by means of rad_send_request or by a combination of calls to rad_init_send_request and rad_continue_send_request. The rad_send_request 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, rad_send_request returns the RADIUS code which specifies the type of the response. This will typically be RAD_ACCESS_ACCEPT, RAD_ACCESS_REJECT, or RAD_ACCESS_CHALLENGE. If no valid response is received, rad_send_request returns -1.
As an alternative, if you do not wish to block waiting for a response, rad_init_send_request and rad_continue_send_request 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 rad_send_request. Otherwise, a value of zero is returned and the values pointed to by fd and tv are set to the descriptor and timeout that should be passed to select(2).
rad_init_send_request must be called first, followed by repeated calls to rad_continue_send_request as long as a return value of zero is given. Between each call, the application should call select(2), passing *fd as a read descriptor and timing out after the interval specified by tv. When select(2) returns, rad_continue_send_request should be called with selected set to a non-zero value if select(2) indicated that the descriptor is readable.
Like RADIUS requests, each response may contain zero or more attributes. After a response has been received successfully by rad_send_request or rad_continue_send_request, its attributes can be extracted one by one using rad_get_attr. Each time 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 data and len, respectively. Note that the data resides in the response itself, and must not be modified. A successful call to rad_get_attr returns the RADIUS attribute type. If no more attributes remain in the current response, rad_get_attr returns 0. If an error such as a malformed attribute is detected, -1 is returned.
If rad_get_attr returns RAD_VENDOR_SPECIFIC, rad_get_vendor_attr may be called to determine the vendor. The vendor specific RADIUS attribute type is returned. The reference parameters data and len (as returned from rad_get_attr) are passed to rad_get_vendor_attr, and are adjusted to point to the vendor specific attribute data.
The common types of attributes can be decoded using rad_cvt_addr, rad_cvt_int, and rad_cvt_string. These functions accept a pointer to the attribute data, which should have been obtained using rad_get_attr and optionally rad_get_vendor_attr. In the case of rad_cvt_string, the length len must also be given. These functions interpret the attribute as an Internet address, an integer, or a string, respectively, and return its value. rad_cvt_string returns its value as a NUL -terminated string in dynamically allocated memory. The application should free the string using free(3) when it is no longer needed.
If insufficient virtual memory is available, rad_cvt_string returns NULL. rad_cvt_addr and rad_cvt_int cannot fail.
The rad_request_authenticator 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 buf of length len must be supplied and should be at least 16 bytes. The return value is the number of bytes written to buf or -1 to indicate that len was not large enough.
The rad_server_secret returns the secret shared with the current RADIUS server according to the supplied rad_handle.
The rad_demangle function demangles attributes containing passwords and MS-CHAPv1 MPPE-Keys. The return value is NULL on failure, or the plaintext attribute. This value should be freed using free(3) when it is no longer needed.
The rad_demangle_mppe_key function demangles the send- and recv-keys when using MPPE (see RFC 2548). The return value is NULL on failure, or the plaintext attribute. This value should be freed using free(3) when it is no longer needed.
Obtaining Error Messages
Those functions which accept a
.Vt "struct rad_handle *" argument record an error message if they fail. The error message can be retrieved by calling rad_strerror. The message text is overwritten on each new error for the given
.Vt "struct rad_handle *" . Thus the message must be copied if it is to be preserved through subsequent library calls using the same handle.
Cleanup
To free the resources used by the RADIUS library, call rad_close.
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 rad_strerror.
