RADIUS_NEW_REQUEST_PACKET(3) | Library Functions Manual | RADIUS_NEW_REQUEST_PACKET(3)

# NAME

`radius_new_request_packet`, `radius_new_response_packet`, `radius_convert_packet`, `radius_delete_packet`, `radius_get_id`, `radius_get_code`, `radius_get_authenticator`, `radius_get_authenticator_retval`, `radius_get_length`, `radius_update_id`, `radius_set_id`, `radius_set_request_packet`, `radius_get_request_packet`, `radius_set_response_authenticator`, `radius_check_response_authenticator`, `radius_set_accounting_request_authenticator`, `radius_check_accounting_request_authenticator`, `radius_get_request_authenticator_retval`, `radius_get_data`, `radius_get_raw_attr`, `radius_put_raw_attr`, `radius_get_raw_attr_cat`, `radius_put_raw_attr_cat`, `radius_get_raw_attr_ptr`, `radius_set_raw_attr`, `radius_del_attr_all`, `radius_has_attr`, `radius_get_vs_raw_attr`, `radius_put_vs_raw_attr`, `radius_get_vs_raw_attr_cat`, `radius_put_vs_raw_attr_cat`, `radius_get_vs_raw_attr_ptr`, `radius_set_vs_raw_attr`, `radius_del_vs_attr_all`, `radius_has_vs_attr`, `radius_get_uint16_attr`, `radius_get_uint32_attr`, `radius_get_uint64_attr`, `radius_get_ipv4_attr`, `radius_get_ipv6_attr`, `radius_put_uint16_attr`, `radius_put_uint32_attr`, `radius_put_uint64_attr`, `radius_put_ipv4_attr`, `radius_put_ipv6_attr`, `radius_set_uint16_attr`, `radius_set_uint32_attr`, `radius_set_uint64_attr`, `radius_set_ipv4_attr`, `radius_set_ipv6_attr`, `radius_get_string_attr`, `radius_put_string_attr`, `radius_get_vs_uint16_attr`, `radius_get_vs_uint32_attr`, `radius_get_vs_uint64_attr`, `radius_get_vs_ipv4_attr`, `radius_get_vs_ipv6_attr`, `radius_put_vs_uint16_attr`, `radius_put_vs_uint32_attr`, `radius_put_vs_uint64_attr`, `radius_put_vs_ipv4_attr`, `radius_put_vs_ipv6_attr`, `radius_set_vs_uint16_attr`, `radius_set_vs_uint32_attr`, `radius_set_vs_uint64_attr`, `radius_set_vs_ipv4_attr`, `radius_set_vs_ipv6_attr`, `radius_get_vs_string_attr`, `radius_put_vs_string_attr`, `radius_put_message_authenticator`, `radius_set_message_authenticator`, `radius_check_message_authenticator`, `radius_encrypt_user_password_attr`, `radius_decrypt_user_password_attr`, `radius_encrypt_mppe_key_attr`, `radius_decrypt_mppe_key_attr`, `radius_get_user_password_attr`, `radius_put_user_password_attr`, `radius_get_mppe_send_key_attr`, `radius_put_mppe_send_key_attr`, `radius_get_mppe_recv_key_attr`, `radius_put_mppe_recv_key_attr`, `radius_get_eap_msk`, `radius_send`, `radius_sendmsg`, `radius_sendto`, `radius_recv`, `radius_recvfrom`, `radius_recvmsg`, `radius` — manipulate RADIUS packets for RADIUS clients/servers

# SYNOPSIS

RADIUS Client Library (libradius, -lradius)
`#include <sys/types.h>`
`#include <sys/socket.h>`
`#include <netinet/in.h>`
`#include <stdbool.h>`
`#include <radius.h>`

# DESCRIPTION

`radius` provides a facility to manipulate RADIUS packets and some helper functions.

# CREATING AND DESTROYING PACKETS

RADIUS packet objects are created by `radius_new_request_packet`(), `radius_new_response_packet`() or `radius_convert_packet`(). The authenticator field of the packet that is returned by `radius_new_request_packet`() and `radius_new_response_packet`() is filled with random bytes.

You must call `radius_delete_packet`() to free memory associated with the packet object.

# HEADER ACCESSOR

`radius_get_id`(), `radius_get_code`(), `radius_get_authenticator`(), `radius_get_authenticator_retval`() and `radius_get_length`() retrieves the specified property of the packet. `radius_update_id`() updates a packet's ID field with an internal ID counter. `radius_set_id`() sets a packet's ID field.

`radius_set_request_packet`() associates a request packet to a response packet. The associated request packet can be retrieved by `radius_get_request_packet`().

`radius_set_response_authenticator`() sets a response authenticator to a response packet. `radius_check_response_authenticator`() checks the response authenticator of a response packet. The request packet must be associated with a response packet by `radius_new_response_packet`() or `radius_set_request_packet`().

`radius_set_accounting_request_authenticator`() sets a request authenticator to an accounting request packet. `radius_check_accounting_request_authenticator`() checks a request authenticator of an accounting request packet.

`radius_get_request_authenticator_retval`() returns the authenticator field of the packet if the argument is a request packet, and returns that of the associated request packet if the argument is a response packet.

`radius_get_data`() returns packet data itself.

# RAW ATTRIBUTE ACCESSOR

`radius_get_raw_attr`() retrieves an attribute value. length is a value-result parameter, initially containing the size of the buffer and modified on return to indicate the size of the value returned. If the buffer size is not sufficient, the returned value is truncated.

`radius_put_raw_attr`() appends attribute data to the end of the packet. If buffer size is larger than the maximum size of a single attribute, the function returns an error.

`radius_get_raw_attr_cat`() retrieves an attribute value. Unlike `radius_get_raw_attr`(), `radius_get_raw_attr_cat`() retrieves ALL attribute values that have the specified attribute type concatenated. If the buffer size is not sufficient, the function returns an error. If buf is `NULL`, the initial value of length is ignored and the actual size of concatenated values is returned.

`radius_put_raw_attr_cat`() appends attribute data to the last of the packet. Unlike `radius_put_raw_attr`(), `radius_put_raw_attr_cat`() divides data into multiple attributes and appends them if the buffer size is larger than the maximum size of a single attribute. Note that packet objects may be broken (but can be deleted normally by `radius_delete_packet`()) if this function has returned an error.

`radius_get_raw_attr_ptr`() retrieves a pointer and length of specified attribute. The returned buffer must not be modified.

`radius_set_raw_attr`() overwrites existing an attribute value. If the specified attribute does not exist, this function returns an error. If length is different from the length of the specified attribute, the function returns an error.

`radius_del_attr_all`() deletes all attributes matching its arguments.

`radius_has_attr`() returns whether packet has a specified attribute.

`radius_get_vs_raw_attr`(), `radius_put_vs_raw_attr`(), `radius_get_vs_raw_attr_cat`(), `radius_put_vs_raw_attr_cat`(), `radius_get_vs_raw_attr_ptr`(), `radius_set_vs_raw_attr`(), `radius_del_vs_attr_all`() and `radius_has_vs_attr`() are vendor-specific versions of raw attribute accessors.

# TYPED ATTRIBUTE ACCESSOR

To make code simple, there are many typed attribute accessors. `radius` provides typed accessors for uint16_t, uint32_t, uint64_t, struct in_addr and struct in6_addr. Byte endian may be appropriately swapped for uint16_t, uint32_t and uint64_t.

These typed accessors do not requires length parameters because length is implied by the type. For "get" functions, if the actual attribute size is different from the size of the type, the functions return an error.

There are also typed accessors for string (`char *`). For "get" functions for strings, the returned string is always NUL-terminated even if buffer size is smaller than actual attribute size. This behavior is similar to `strlcpy`().

# MESSAGE AUTHENTICATOR

There are helper functions for Message-Authenticator attributes.

`radius_put_message_authenticator`() and `radius_set_message_authenticator`() calculate a Message-Authenticator and put or set it to packet, respectively. When `radius_put_message_authenticator`() is used, the Message-Authenticator attribute is placed at the first in the attributes.

`radius_check_message_authenticator`() checks a Message-Authenticator.

The request packet must be associated with a response packet by `radius_new_response_packet`() or `radius_set_request_packet`(), otherwise the packet is treated as a request packet.

# ENCRYPTED ATTRIBUTE

There are helper functions for encrypted attributes.

`radius_encrypt_user_password_attr`(), `radius_decrypt_user_password_attr`(), `radius_encrypt_mppe_key_attr`() and `radius_decrypt_mppe_key_attr`() encrypt or decrypt User-Password attribute or MS-MPPE-{Send,Recv}-Key attributes respectively.

`radius_get_user_password_attr`(), `radius_put_user_password_attr`(), `radius_get_mppe_send_key_attr`(), `radius_put_mppe_send_key_attr`(), `radius_get_mppe_recv_key_attr`() and `radius_put_mppe_recv_key_attr`() are shortcuts of combination of encrypt/decrypt functions and get/put functions.

`radius_get_eap_msk`() retrieves a Master Session Key (MSK) for Extensible Authentication Protocol (EAP). Currently retrieving an MSK from MS-MPPE key attributes is supported.

# SENDING AND RECEIVING PACKETS

There are helper functions for sending and receiving packets.

`radius_send`(), `radius_sendto`(), `radius_sendmsg`(), `radius_recv`(), `radius_recvfrom`() and `radius_recvmsg`() are helper version of `send`(), `sendto`(), `sendmsg`(), `recv`(), `recvfrom`() and `recvmsg`(), respectively.

`radius_send`(), `radius_sendto`() and `radius_sendmsg`() return 0 on success and nonzero on failure.

`radius_recv`() `radius_recvfrom`() and `radius_recvmsg`() return the received packet on success and return NULL on failure.

Note that `msg_iov` must be `NULL` and `msg_iovlen` must be zero in case of `radius_sendmsg`() and `radius_recvmsg`().

# RETURN VALUES

Functions that return int return 0 on success and nonzero on failure. Functions that return pointer return non-NULL pointer on success and NULL on failure.

# HISTORY

The `radius+` library was first written by UMEZAWA Takeshi in 2002 for the ID Gateway service of Internet Initiative Japan Inc. YASUOKA Masahiko added support for Message-Authenticator attributes in 2008. OpenBSD project rewrote C++ code to pure C code in 2010. The `radius+` library was renamed `radius` and moved to lib/ in 2013.

June 9, 2025 | Debian