--- name: "libradius" section: "3" platform: "freebsd" package: "base" version: "16.0-CURRENT-20261027-61c70dc16a79" release: "FreeBSD 16.0-CURRENT (2026-10-27)" platforms: ["freebsd"] url: "https://new.carta.tech/libradius" --- # libradius(3) RADIUS client/server library ## NAME **libradius** – RADIUS client/server library ## SYNOPSIS **#include \** *struct rad\_handle \**\ **rad\_acct\_open**(*void*); *int*\ **rad\_add\_server**(*struct rad\_handle \*h*, *const char \*host*, *int port*, *const char \*secret*, *int timeout*, *int max\_tries*); *int*\ **rad\_add\_server\_ex**(*struct rad\_handle \*h*, *const char \*host*, *int port*, *const char \*secret*, *int timeout*, *int max\_tries*, *int dead\_time*, *struct in\_addr \*bindto*); *struct rad\_handle \**\ **rad\_auth\_open**(*void*); *void*\ **rad\_close**(*struct rad\_handle \*h*); *int*\ **rad\_config**(*struct rad\_handle \*h*, *const char \*file*); *int*\ **rad\_continue\_send\_request**(*struct rad\_handle \*h*, *int selected*, *int \*fd*, *struct timeval \*tv*); *int*\ **rad\_create\_request**(*struct rad\_handle \*h*, *int code*); *int*\ **rad\_create\_response**(*struct rad\_handle \*h*, *int code*); *struct in\_addr*\ **rad\_cvt\_addr**(*const void \*data*); *uint32\_t*\ **rad\_cvt\_int**(*const void \*data*); *char* *\**\ **rad\_cvt\_string**(*const void \*data*, *size\_t len*); *int*\ **rad\_get\_attr**(*struct rad\_handle \*h*, *const void \*\*data*, *size\_t \*len*); *int*\ **rad\_get\_vendor\_attr**(*uint32\_t \*vendor*, *const void \*\*data*, *size\_t \*len*); *int*\ **rad\_init\_send\_request**(*struct rad\_handle \*h*, *int \*fd*, *struct timeval \*tv*); *int*\ **rad\_put\_addr**(*struct rad\_handle \*h*, *int type*, *struct in\_addr addr*); *int*\ **rad\_put\_attr**(*struct rad\_handle \*h*, *int type*, *const void \*data*, *size\_t len*); *int*\ **rad\_put\_int**(*struct rad\_handle \*h*, *int type*, *uint32\_t value*); *int*\ **rad\_put\_string**(*struct rad\_handle \*h*, *int type*, *const char \*str*); *int*\ **rad\_put\_message\_authentic**(*struct rad\_handle \*h*); *int*\ **rad\_put\_vendor\_addr**(*struct rad\_handle \*h*, *int vendor*, *int type*, *struct in\_addr addr*); *int*\ **rad\_put\_vendor\_attr**(*struct rad\_handle \*h*, *int vendor*, *int type*, *const void \*data*, *size\_t len*); *int*\ **rad\_put\_vendor\_int**(*struct rad\_handle \*h*, *int vendor*, *int type*, *uint32\_t value*); *int*\ **rad\_put\_vendor\_string**(*struct rad\_handle \*h*, *int vendor*, *int type*, *const char \*str*); *ssize\_t*\ **rad\_request\_authenticator**(*struct rad\_handle \*h*, *char \*buf*, *size\_t len*); *int*\ **rad\_receive\_request**(*struct rad\_handle \*h*); *int*\ **rad\_send\_request**(*struct rad\_handle \*h*); *int*\ **rad\_send\_response**(*struct rad\_handle \*h*); *struct rad\_handle \**\ **rad\_server\_open**(*int fd*); *const char \**\ **rad\_server\_secret**(*struct rad\_handle \*h*); *void*\ **rad\_bind\_to**(*struct rad\_handle \*h*, *in\_addr\_t addr*); *u\_char* *\**\ **rad\_demangle**(*struct rad\_handle \*h*, *const void \*mangled*, *size\_t mlen*); *u\_char* *\**\ **rad\_demangle\_mppe\_key**(*struct rad\_handle \*h*, *const void \*mangled*, *size\_t mlen*, *size\_t \*len*); *const char \**\ **rad\_strerror**(*struct rad\_handle \*h*); ## DESCRIPTION The **libradius** library implements the Remote Authentication Dial In User Service (RADIUS). RADIUS, defined in RFCs 2865 and 2866, allows clients to perform authentication and accounting by means of network requests to remote servers. ### Initialization To use the library, an application must first call **rad\_auth\_open**(), **rad\_acct\_open**() or **rad\_server\_open**() to obtain a *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. Calls to **rad\_auth\_open**(), **rad\_acct\_open**() and **rad\_server\_open**() always succeed unless insufficient virtual memory is available. If the necessary memory cannot be allocated, the functions return NULL. For compatibility with earlier versions of this library, **rad\_open**() is provided as a synonym for **rad\_auth\_open**(). Before issuing any RADIUS requests, the library must be made aware of the servers it can contact. The easiest way to configure the library is to call **rad\_config**(). **rad\_config**() causes the library to read a configuration file whose format is described in [radius.conf(5)](/radius.conf/5.md). The pathname of the configuration file is passed as the *file* argument to **rad\_config**(). This argument may also be given as NULL, in which case the standard configuration file */etc/radius.conf* is used. **rad\_config**() returns 0 on success, or -1 if an error occurs. The library can also be configured programmatically by calls to **rad\_add\_server**() or **rad\_add\_server\_ex**(). **rad\_add\_server**() is a backward compatible function, implemented via **rad\_add\_server\_ex**(). The *host* parameter specifies the server host, either as a fully qualified domain name or as a dotted-quad IP address in text form. The *port* parameter specifies the UDP port to contact on the server. If *port* is given as 0, the library looks up the ‘radius/udp’ or ‘radacct/udp’ service in the network [services(5)](/services/5.md) 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 *secret* parameter. It may be any NUL-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 *timeout* parameter, in units of seconds. The maximum number of repeated requests to make before giving up is passed into the *max\_tries* parameter. Time interval in seconds when the server will not be requested if it is marked as dead (did not answer on the last try) set with *dead\_time* parameter. *bindto* parameter is an IP address on the multihomed host that is used as a source address for all requests. **rad\_add\_server**() returns 0 on success, or -1 if an error occurs. **rad\_add\_server**() or **rad\_add\_server\_ex**() may be called multiple times, and they may be used together with **rad\_config**(). 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 *max\_tries* limit has been reached. ### 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 begin constructing a new request, call **rad\_create\_request**(). In addition to the usual *struct rad\_handle \**, this function takes a *code* parameter which specifies the type of the request. Most often this will be RAD\_ACCESS\_REQUEST. **rad\_create\_request**() returns 0 on success, or -1 on if an error occurs. After the request has been created with **rad\_create\_request**(), attributes can be attached to it. This is done through calls to **rad\_put\_addr**(), **rad\_put\_int**(), and **rad\_put\_string**(). Each accepts a *type* parameter identifying the attribute, and a value which may be an Internet address, an integer, or a NUL-terminated string, respectively. Alternatively, **rad\_put\_vendor\_addr**(), **rad\_put\_vendor\_int**() or **rad\_put\_vendor\_string**() may be used to specify vendor specific attributes. Vendor specific definitions may be found in ⟨radlib\_vs.h⟩ The library also provides a function **rad\_put\_attr**() which can be used to supply a raw, uninterpreted attribute. The *data* argument points to an array of bytes, and the *len* argument specifies its length. It is possible adding the Message-Authenticator to the request. This is an HMAC-MD5 hash of the entire Access-Request packet (see RFC 3579). This attribute must be present in any packet that includes an EAP-Message attribute. It can be added by using the **rad\_put\_message\_authentic**() function. The **libradius** library calculates the HMAC-MD5 hash implicitly before sending the request. If the Message-Authenticator was found inside the response packet, then the packet is silently dropped, if the validation failed. In order to get this feature, the library should be compiled with OpenSSL support. The **rad\_put\_X**() functions return 0 on success, or -1 if an error occurs. ### 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)](/select/2.md). **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)](/select/2.md), passing *\*fd* as a read descriptor and timing out after the interval specified by *tv*. When [select(2)](/select/2.md) returns, **rad\_continue\_send\_request**() should be called with *selected* set to a non-zero value if [select(2)](/select/2.md) 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)](/free/3.md) 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\_bind\_to**() assigns a source address for all requests to the current RADIUS server. 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)](/free/3.md) 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)](/free/3.md) when it is no longer needed. ### Obtaining Error Messages Those functions which accept a *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 *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**(). ### Server operation Server mode operates much alike to client mode, except packet send and receive steps are swapped. To operate as server you should obtain server context with **rad\_server\_open**() function, passing opened and bound UDP socket file descriptor as argument. You should define allowed clients and their secrets using **rad\_add\_server**() function. port, timeout and max\_tries arguments are ignored in server mode. You should call **rad\_receive\_request**() function to receive request from client. If you do not want to block on socket read, you are free to use any poll(), select() or non-blocking sockets for the socket. Received request can be parsed with same parsing functions as for client. To respond to the request you should call **rad\_create\_response**() and fill response content with same packet writing functions as for client. When packet is ready, it should be sent with **rad\_send\_response**(). ## 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**(). - **rad\_add\_server**() - **rad\_config**() - **rad\_create\_request**() - **rad\_create\_response**() - **rad\_get\_attr**() - **rad\_put\_addr**() - **rad\_put\_attr**() - **rad\_put\_int**() - **rad\_put\_string**() - **rad\_put\_message\_authentic**() - **rad\_init\_send\_request**() - **rad\_continue\_send\_request**() - **rad\_send\_request**() - **rad\_send\_response**() The following functions return a non-NULL pointer on success. If they are unable to allocate sufficient virtual memory, they return NULL, without recording an error message. - **rad\_acct\_open**() - **rad\_auth\_open**() - **rad\_server\_open**() - **rad\_cvt\_string**() The following functions return a non-NULL pointer on success. If they fail, they return NULL, with recording an error message. - **rad\_demangle**() - **rad\_demangle\_mppe\_key**() ## FILES - */etc/radius.conf* ## SEE ALSO [radius.conf(5)](/radius.conf/5.md) C. Rigney, et al, *Remote Authentication Dial In User Service (RADIUS)*, RFC 2865. C. Rigney, *RADIUS Accounting*, RFC 2866. G. Zorn, *Microsoft Vendor-specific RADIUS attributes*, RFC 2548. C. Rigney, et al, *RADIUS extensions*, RFC 2869. ## AUTHORS This software was originally written by John Polstra, and donated to the FreeBSD project by Juniper Networks, Inc. Oleg Semyonov subsequently added the ability to perform RADIUS accounting. Later additions and changes by Michael Bretterklieber. Server mode support was added by Alexander Motin.