LIBRADIUS(3)

🌸 libradius 🌸

okay so bestie, welcome to the libradius page — the RADIUS client/server library, and yes it's giving "networking but make it a whole era" 💅 this is part 1 so buckle up, we're not even done yet.

---

✨ NAME ✨

libradius — RADIUS client/server library. that's the whole vibe. it's the library, it does RADIUS, clients and servers both. periodt.

---

🎀 SYNOPSIS 🎀

#include <radlib.h>

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);

like, that's a lot of functions, but every single one is iconic in its own way 🫶

---

🦋 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. so basically: you yell at a remote server over the network and it tells you yes/no/how-much, and this library is the megaphone 📣

💖 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. think of the handle as your little backstage pass — everything after this needs it.

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().

ngl the "always succeed unless you're out of virtual memory" thing is such a mood — the bar is literally on the floor and yet 😭

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). 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(). Let's break the params down, bestie:

• host — specifies the server host, either as a fully qualified domain name or as a dotted-quad IP address in text form 🌈
• port — 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) 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 🔥
• secret — 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 👀 (so don't get cute with byte 129, she's not listening)
• timeout — the timeout for receiving replies from the server, in units of seconds ⏰
• max_tries — the maximum number of repeated requests to make before giving up
• dead_time — time interval in seconds when the server will not be requested if it is marked as dead (did not answer on the last try) 💀
• bindto — 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. it's giving "we're going down the friend group until somebody picks up the phone" 📞

💜 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 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. raw bytes, no thoughts, just vibes 🧚

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.

⚠️ ok so read that again: validation fails → packet gets silently dropped. no error, no note, just gone. main character energy but make it ominous 🙈

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. slay when it's an ACCEPT, crying when it's a REJECT, and CHALLENGE is the "girl, we need to talk more" of response codes 😭

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. it's a whole little loop and honestly the non-blocking girlies are obsessed 💅

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. 🫶

⚠️ fr fr: must not be modified. that's not a suggestion, that's the response's house and you're just visiting.

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.

okay so the common types of attributes can be decoded with rad_cvt_addr(), rad_cvt_int(), and rad_cvt_string(). These functions take a pointer to the attribute data — which you should have gotten from rad_get_attr() and optionally rad_get_vendor_attr(), no ✨freestyling✨ the pointer, bestie. For rad_cvt_string() you also have to pass the length len. Then they read that attribute as an Internet address, an integer, or a string respectively, and hand back the value. 💅

rad_cvt_string() gives you its value as a NUL-terminated string in dynamically allocated memory, so the application should free the string using free(3) once you're done with it — don't just leave it there like an unread group chat 💀

If there isn't enough virtual memory, rad_cvt_string() returns NULL. rad_cvt_addr() and rad_cvt_int() cannot fail, icons only 😌.

The rad_request_authenticator() function gets you the Request-Authenticator attribute value that's associated with the current RADIUS server, according to the rad_handle you supply. You gotta give it a target buffer buf with length len, and that should be at least 16 bytes fr fr. Return value is the number of bytes written into buf, or -1 to say len was not large enough 🙈.

The rad_server_secret() returns the secret shared with the current RADIUS server, per the rad_handle you hand over. 🤫

The rad_bind_to() assigns a source address for all requests to the current RADIUS server. one address to rule them all, periodt.

The rad_demangle() function demangles attributes containing passwords and MS-CHAPv1 MPPE-Keys. Return value is NULL on failure, or the plaintext attribute. And yes — this value should be freed using free(3) when it's no longer needed.

The rad_demangle_mppe_key() function demangles the send- and recv-keys when you're using MPPE (see RFC 2548). Return value is NULL on failure, or the plaintext attribute. Same deal: free it using free(3) when you're done.

🌸 Obtaining Error Messages 🌸

So those functions that take a struct rad_handle * argument? They record an error message whenever they fail. You can grab that message by calling rad_strerror(). Lowkey important: the message text gets overwritten on each new error for that given struct rad_handle *. So if you want to keep it around through later library calls on the same handle, you must copy it. no cap, it'll be gone 😭

🧚 Cleanup 🧚

To free the resources the RADIUS library is using, call rad_close(). bye bestie, slay your cleanup 💖

👑 Server operation 👑

Server mode is literally client mode's mirror selfie — it operates much alike, except the packet send and receive steps are swapped. 🪞

To operate as a server you should obtain a server context with the rad_server_open() function, passing an opened and bound UDP socket file descriptor as the argument. You should define allowed clients and their secrets using the rad_add_server() function. In server mode, the port, timeout and max_tries arguments are ignored (yes, ignored, don't come for me).

You should call the rad_receive_request() function to receive a request from a client. If you don't wanna block on socket read, you are free to use any poll(), select() or non-blocking sockets for the socket — your vibe, your choice ✨. A received request can be parsed with the same parsing functions as for the client.

To respond to the request you should call rad_create_response() and fill the response content with the same packet writing functions as for the client. When the packet is ready, it should be sent with rad_send_response(). and that's the whole glow-up 💅

---

⭐ 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 you can retrieve 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 can't allocate sufficient virtual memory, they return NULL — and without recording an error message, sneaky little things:

• rad_acct_open()
• rad_auth_open()
• rad_server_open()
• rad_cvt_string()

And the following functions return a non-NULL pointer on success. If they fail, they return NULL, and this time they do record an error message 🫶:

• rad_demangle()
• rad_demangle_mppe_key()

---

🎀 FILES 🎀

• /etc/radius.conf

🦋 SEE ALSO 🦋

• radius.conf(5)
• 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. legends, every single one 👑

---

and that's the whole page, bestie 🌈 this one came from the Debian edition, dated August 5, 2009, and it's filed as LIBRADIUS(3) — go be the main character of your own RADIUS packets 🍓💖