1.\" $OpenBSD: radius_new_request_packet.3,v 1.6 2022/09/11 06:38:11 jmc 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: September 11 2022 $ 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. 288.Pp 289.Fn radius_check_message_authenticator 290checks a Message-Authenticator. 291.Pp 292The request packet must be associated with a response packet by 293.Fn radius_new_response_packet 294or 295.Fn radius_set_request_packet , 296otherwise the packet is treated as a request packet. 297.Sh ENCRYPTED ATTRIBUTE 298There are helper functions for encrypted attributes. 299.Pp 300.Fn radius_encrypt_user_password_attr , 301.Fn radius_decrypt_user_password_attr , 302.Fn radius_encrypt_mppe_key_attr 303and 304.Fn radius_decrypt_mppe_key_attr 305encrypt or decrypt User-Password attribute or MS-MPPE-{Send,Recv}-Key 306attributes respectively. 307.Pp 308.Fn radius_get_user_password_attr , 309.Fn radius_put_user_password_attr , 310.Fn radius_get_mppe_send_key_attr , 311.Fn radius_put_mppe_send_key_attr , 312.Fn radius_get_mppe_recv_key_attr 313and 314.Fn radius_put_mppe_recv_key_attr 315are shortcuts of combination of encrypt/decrypt functions 316and get/put functions. 317.Pp 318.Fn radius_get_eap_msk 319retrieves a Master Session Key (MSK) for Extensible Authentication Protocol 320(EAP). 321Currently retrieving an MSK from MS-MPPE key attributes is supported. 322.Sh SENDING AND RECEIVING PACKETS 323There are helper functions for sending and receiving packets. 324.Pp 325.Fn radius_send , 326.Fn radius_sendto , 327.Fn radius_sendmsg , 328.Fn radius_recv , 329.Fn radius_recvfrom 330and 331.Fn radius_recvmsg 332are helper version of 333.Fn send , 334.Fn sendto , 335.Fn sendmsg , 336.Fn recv , 337.Fn recvfrom 338and 339.Fn recvmsg , 340respectively. 341.Pp 342.Fn radius_send , 343.Fn radius_sendto 344and 345.Fn radius_sendmsg 346return 0 on success and nonzero on failure. 347.Pp 348.Fn radius_recv 349.Fn radius_recvfrom 350and 351.Fn radius_recvmsg 352return the received packet on success and return NULL on failure. 353.Pp 354Note that 355.Li msg_iov 356must be 357.Li NULL 358and 359.Li msg_iovlen 360must be zero in case of 361.Fn radius_sendmsg 362and 363.Fn radius_recvmsg . 364.Sh RETURN VALUES 365Functions that return int return 0 on success and nonzero on failure. 366Functions that return pointer return non-NULL pointer on success and 367NULL on failure. 368.Sh HISTORY 369The 370.Nm radius+ 371library was first written by UMEZAWA Takeshi in 2002 for the ID gateway service 372of Internet Initiative Japan. 373YASUOKA Masahiko added support for Message-Authentication attributes in 2008. 374.Ox 375project rewrote C++ code to pure C code in 2010. 376The 377.Nm radius+ 378library was renamed 379.Nm radius 380and moved to 381.Pa lib/ 382in 2013. 383