1.\" $OpenBSD: radius_new_request_packet.3,v 1.7 2024/07/24 08:19:16 yasuoka Exp $ 2.\" 3.\" Copyright (c) 2009 Internet Initiative Japan Inc. 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 16.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 17.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 18.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 19.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 20.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 21.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 22.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 23.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 24.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 25.\" SUCH DAMAGE. 26.\" 27.Dd $Mdocdate: July 24 2024 $ 28.Dt RADIUS_NEW_REQUEST_PACKET 3 29.Os 30.Sh NAME 31.Nm radius_new_request_packet , 32.Nm radius_new_response_packet , 33.Nm radius_convert_packet , 34.Nm radius_delete_packet , 35.Nm radius_get_id , 36.Nm radius_get_code , 37.Nm radius_get_authenticator , 38.Nm radius_get_authenticator_retval , 39.Nm radius_get_length , 40.Nm radius_update_id , 41.Nm radius_set_id , 42.Nm radius_set_request_packet , 43.Nm radius_get_request_packet , 44.Nm radius_set_response_authenticator , 45.Nm radius_check_response_authenticator , 46.Nm radius_set_accounting_request_authenticator , 47.Nm radius_check_accounting_request_authenticator , 48.Nm radius_get_request_authenticator_retval , 49.Nm radius_get_data , 50.Nm radius_get_raw_attr , 51.Nm radius_put_raw_attr , 52.Nm radius_get_raw_attr_cat , 53.Nm radius_put_raw_attr_cat , 54.Nm radius_get_raw_attr_ptr , 55.Nm radius_set_raw_attr , 56.Nm radius_del_attr_all , 57.Nm radius_has_attr , 58.Nm radius_get_vs_raw_attr , 59.Nm radius_put_vs_raw_attr , 60.Nm radius_get_vs_raw_attr_cat , 61.Nm radius_put_vs_raw_attr_cat , 62.Nm radius_get_vs_raw_attr_ptr , 63.Nm radius_set_vs_raw_attr , 64.Nm radius_del_vs_attr_all , 65.Nm radius_has_vs_attr , 66.Nm radius_get_uint16_attr , 67.Nm radius_get_uint32_attr , 68.Nm radius_get_uint64_attr , 69.Nm radius_get_ipv4_attr , 70.Nm radius_get_ipv6_attr , 71.Nm radius_put_uint16_attr , 72.Nm radius_put_uint32_attr , 73.Nm radius_put_uint64_attr , 74.Nm radius_put_ipv4_attr , 75.Nm radius_put_ipv6_attr , 76.Nm radius_set_uint16_attr , 77.Nm radius_set_uint32_attr , 78.Nm radius_set_uint64_attr , 79.Nm radius_set_ipv4_attr , 80.Nm radius_set_ipv6_attr , 81.Nm radius_get_string_attr , 82.Nm radius_put_string_attr , 83.Nm radius_get_vs_uint16_attr , 84.Nm radius_get_vs_uint32_attr , 85.Nm radius_get_vs_uint64_attr , 86.Nm radius_get_vs_ipv4_attr , 87.Nm radius_get_vs_ipv6_attr , 88.Nm radius_put_vs_uint16_attr , 89.Nm radius_put_vs_uint32_attr , 90.Nm radius_put_vs_uint64_attr , 91.Nm radius_put_vs_ipv4_attr , 92.Nm radius_put_vs_ipv6_attr , 93.Nm radius_set_vs_uint16_attr , 94.Nm radius_set_vs_uint32_attr , 95.Nm radius_set_vs_uint64_attr , 96.Nm radius_set_vs_ipv4_attr , 97.Nm radius_set_vs_ipv6_attr , 98.Nm radius_get_vs_string_attr , 99.Nm radius_put_vs_string_attr , 100.Nm radius_put_message_authenticator , 101.Nm radius_set_message_authenticator , 102.Nm radius_check_message_authenticator , 103.Nm radius_encrypt_user_password_attr , 104.Nm radius_decrypt_user_password_attr , 105.Nm radius_encrypt_mppe_key_attr , 106.Nm radius_decrypt_mppe_key_attr , 107.Nm radius_get_user_password_attr , 108.Nm radius_put_user_password_attr , 109.Nm radius_get_mppe_send_key_attr , 110.Nm radius_put_mppe_send_key_attr , 111.Nm radius_get_mppe_recv_key_attr , 112.Nm radius_put_mppe_recv_key_attr , 113.Nm radius_get_eap_msk , 114.Nm radius_send , 115.Nm radius_sendmsg , 116.Nm radius_sendto , 117.Nm radius_recv , 118.Nm radius_recvfrom , 119.Nm radius_recvmsg , 120.Nm radius 121.Nd manipulate RADIUS packets for RADIUS clients/servers 122.Sh SYNOPSIS 123.In sys/types.h 124.In sys/socket.h 125.In netinet/in.h 126.In stdbool.h 127.In radius.h 128.Sh DESCRIPTION 129.Nm radius 130provides a facility to manipulate RADIUS packets and some helper functions. 131.Sh CREATING AND DESTROYING PACKETS 132RADIUS packet objects are created by 133.Fn radius_new_request_packet , 134.Fn radius_new_response_packet 135or 136.Fn radius_convert_packet . 137The authenticator field of the packet that is returned by 138.Fn radius_new_request_packet 139and 140.Fn radius_new_response_packet 141is filled with random bytes. 142.Pp 143You must call 144.Fn radius_delete_packet 145to free memory associated with the packet object. 146.Sh HEADER ACCESSOR 147.Fn radius_get_id , 148.Fn radius_get_code , 149.Fn radius_get_authenticator , 150.Fn radius_get_authenticator_retval 151and 152.Fn radius_get_length 153retrieves the specified property of the packet. 154.Fn radius_update_id 155updates a packet's ID field with an internal ID counter. 156.Fn radius_set_id 157sets a packet's ID field. 158.Pp 159.Fn radius_set_request_packet 160associates a request packet to a response packet. 161The associated request packet can be retrieved by 162.Fn radius_get_request_packet . 163.Pp 164.Fn radius_set_response_authenticator 165sets a response authenticator to a response packet. 166.Fn radius_check_response_authenticator 167checks the response authenticator of a response packet. 168The request packet must be associated with a response packet by 169.Fn radius_new_response_packet 170or 171.Fn radius_set_request_packet . 172.Pp 173.Fn radius_set_accounting_request_authenticator 174sets a request authenticator to an accounting request packet. 175.Fn radius_check_accounting_request_authenticator 176checks a request authenticator of an accounting request packet. 177.Pp 178.Fn radius_get_request_authenticator_retval 179returns the authenticator field of the packet if the argument is 180a request packet, and returns that of the associated request packet 181if the argument is a response packet. 182.Pp 183.Fn radius_get_data 184returns packet data itself. 185.Sh RAW ATTRIBUTE ACCESSOR 186.Fn radius_get_raw_attr 187retrieves an attribute value. 188.Fa length 189is a value-result parameter, initially containing the size of the buffer 190and modified on return to indicate the size of the value returned. 191If the buffer size is not sufficient, the returned value is truncated. 192.Pp 193.Fn radius_put_raw_attr 194appends attribute data to the end of the packet. 195If buffer size is larger than the maximum size of a single attribute, 196the function returns an error. 197.Pp 198.Fn radius_get_raw_attr_cat 199retrieves an attribute value. 200Unlike 201.Fn radius_get_raw_attr , 202.Fn radius_get_raw_attr_cat 203retrieves ALL attribute values that have the specified attribute type 204concatenated. 205If the buffer size is not sufficient, the function returns an error. 206If 207.Fa buf 208is 209.Dv NULL , 210the initial value of 211.Fa length 212is ignored and the actual size of concatenated values is returned. 213.Pp 214.Fn radius_put_raw_attr_cat 215appends attribute data to the last of the packet. 216Unlike 217.Fn radius_put_raw_attr , 218.Fn radius_put_raw_attr_cat 219divides data into multiple attributes and appends them if the buffer size is 220larger than the maximum size of a single attribute. 221Note that packet objects may be broken (but can be deleted normally by 222.Fn radius_delete_packet ) 223if this function has returned an error. 224.Pp 225.Fn radius_get_raw_attr_ptr 226retrieves a pointer and length of specified attribute. 227The returned buffer must not be modified. 228.Pp 229.Fn radius_set_raw_attr 230overwrites existing an attribute value. 231If the specified attribute does not exist, this function returns an error. 232If 233.Fa length 234is different from the length of the specified attribute, 235the function returns an error. 236.Pp 237.Fn radius_del_attr_all 238deletes all attributes matching its arguments. 239.Pp 240.Fn radius_has_attr 241returns whether packet has a specified attribute. 242.Pp 243.Fn radius_get_vs_raw_attr , 244.Fn radius_put_vs_raw_attr , 245.Fn radius_get_vs_raw_attr_cat , 246.Fn radius_put_vs_raw_attr_cat , 247.Fn radius_get_vs_raw_attr_ptr , 248.Fn radius_set_vs_raw_attr , 249.Fn radius_del_vs_attr_all 250and 251.Fn radius_has_vs_attr 252are vendor-specific versions of raw attribute accessors. 253.Sh TYPED ATTRIBUTE ACCESSOR 254To make code simple, there are many typed attribute accessors. 255.Nm radius 256provides typed accessors for 257.Vt uint16_t , 258.Vt uint32_t , 259.Vt uint64_t , 260.Vt struct in_addr 261and 262.Vt struct in6_addr . 263Byte endian may be appropriately swapped for 264.Vt uint16_t , 265.Vt uint32_t 266and 267.Vt uint64_t . 268.Pp 269These typed accessors do not requires 270.Fa length 271parameters because length is implied by the type. 272For "get" functions, if the actual attribute size is different from the size of 273the type, the functions return an error. 274.Pp 275There are also typed accessors for string 276.Pq Li char * . 277For "get" functions for strings, the returned string is always NUL-terminated 278even if buffer size is smaller than actual attribute size. 279This behavior is similar to 280.Fn strlcpy . 281.Sh MESSAGE AUTHENTICATOR 282There are helper functions for Message-Authenticator attributes. 283.Pp 284.Fn radius_put_message_authenticator 285and 286.Fn radius_set_message_authenticator 287calculate a Message-Authenticator and put or set it to packet, respectively. 288When 289.Fn radius_put_message_authenticator 290is used, 291the Message-Authenticator attribute is placed at the first in the attributes. 292.Pp 293.Fn radius_check_message_authenticator 294checks a Message-Authenticator. 295.Pp 296The request packet must be associated with a response packet by 297.Fn radius_new_response_packet 298or 299.Fn radius_set_request_packet , 300otherwise the packet is treated as a request packet. 301.Sh ENCRYPTED ATTRIBUTE 302There are helper functions for encrypted attributes. 303.Pp 304.Fn radius_encrypt_user_password_attr , 305.Fn radius_decrypt_user_password_attr , 306.Fn radius_encrypt_mppe_key_attr 307and 308.Fn radius_decrypt_mppe_key_attr 309encrypt or decrypt User-Password attribute or MS-MPPE-{Send,Recv}-Key 310attributes respectively. 311.Pp 312.Fn radius_get_user_password_attr , 313.Fn radius_put_user_password_attr , 314.Fn radius_get_mppe_send_key_attr , 315.Fn radius_put_mppe_send_key_attr , 316.Fn radius_get_mppe_recv_key_attr 317and 318.Fn radius_put_mppe_recv_key_attr 319are shortcuts of combination of encrypt/decrypt functions 320and get/put functions. 321.Pp 322.Fn radius_get_eap_msk 323retrieves a Master Session Key (MSK) for Extensible Authentication Protocol 324(EAP). 325Currently retrieving an MSK from MS-MPPE key attributes is supported. 326.Sh SENDING AND RECEIVING PACKETS 327There are helper functions for sending and receiving packets. 328.Pp 329.Fn radius_send , 330.Fn radius_sendto , 331.Fn radius_sendmsg , 332.Fn radius_recv , 333.Fn radius_recvfrom 334and 335.Fn radius_recvmsg 336are helper version of 337.Fn send , 338.Fn sendto , 339.Fn sendmsg , 340.Fn recv , 341.Fn recvfrom 342and 343.Fn recvmsg , 344respectively. 345.Pp 346.Fn radius_send , 347.Fn radius_sendto 348and 349.Fn radius_sendmsg 350return 0 on success and nonzero on failure. 351.Pp 352.Fn radius_recv 353.Fn radius_recvfrom 354and 355.Fn radius_recvmsg 356return the received packet on success and return NULL on failure. 357.Pp 358Note that 359.Li msg_iov 360must be 361.Li NULL 362and 363.Li msg_iovlen 364must be zero in case of 365.Fn radius_sendmsg 366and 367.Fn radius_recvmsg . 368.Sh RETURN VALUES 369Functions that return int return 0 on success and nonzero on failure. 370Functions that return pointer return non-NULL pointer on success and 371NULL on failure. 372.Sh HISTORY 373The 374.Nm radius+ 375library was first written by UMEZAWA Takeshi in 2002 for the ID Gateway service 376of Internet Initiative Japan Inc. 377YASUOKA Masahiko added support for Message-Authenticator attributes in 2008. 378.Ox 379project rewrote C++ code to pure C code in 2010. 380The 381.Nm radius+ 382library was renamed 383.Nm radius 384and moved to 385.Pa lib/ 386in 2013. 387