path: root/lib/libradius/radius_new_request_packet.3

.\" $OpenBSD: radius_new_request_packet.3,v 1.6 2022/09/11 06:38:11 jmc Exp $
.\"
.\" Copyright (c) 2009 Internet Initiative Japan Inc.
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.Dd $Mdocdate: September 11 2022 $
.Dt RADIUS_NEW_REQUEST_PACKET 3
.Os
.Sh NAME
.Nm radius_new_request_packet ,
.Nm radius_new_response_packet ,
.Nm radius_convert_packet ,
.Nm radius_delete_packet ,
.Nm radius_get_id ,
.Nm radius_get_code ,
.Nm radius_get_authenticator ,
.Nm radius_get_authenticator_retval ,
.Nm radius_get_length ,
.Nm radius_update_id ,
.Nm radius_set_id ,
.Nm radius_set_request_packet ,
.Nm radius_get_request_packet ,
.Nm radius_set_response_authenticator ,
.Nm radius_check_response_authenticator ,
.Nm radius_set_accounting_request_authenticator ,
.Nm radius_check_accounting_request_authenticator ,
.Nm radius_get_request_authenticator_retval ,
.Nm radius_get_data ,
.Nm radius_get_raw_attr ,
.Nm radius_put_raw_attr ,
.Nm radius_get_raw_attr_cat ,
.Nm radius_put_raw_attr_cat ,
.Nm radius_get_raw_attr_ptr ,
.Nm radius_set_raw_attr ,
.Nm radius_del_attr_all ,
.Nm radius_has_attr ,
.Nm radius_get_vs_raw_attr ,
.Nm radius_put_vs_raw_attr ,
.Nm radius_get_vs_raw_attr_cat ,
.Nm radius_put_vs_raw_attr_cat ,
.Nm radius_get_vs_raw_attr_ptr ,
.Nm radius_set_vs_raw_attr ,
.Nm radius_del_vs_attr_all ,
.Nm radius_has_vs_attr ,
.Nm radius_get_uint16_attr ,
.Nm radius_get_uint32_attr ,
.Nm radius_get_uint64_attr ,
.Nm radius_get_ipv4_attr ,
.Nm radius_get_ipv6_attr ,
.Nm radius_put_uint16_attr ,
.Nm radius_put_uint32_attr ,
.Nm radius_put_uint64_attr ,
.Nm radius_put_ipv4_attr ,
.Nm radius_put_ipv6_attr ,
.Nm radius_set_uint16_attr ,
.Nm radius_set_uint32_attr ,
.Nm radius_set_uint64_attr ,
.Nm radius_set_ipv4_attr ,
.Nm radius_set_ipv6_attr ,
.Nm radius_get_string_attr ,
.Nm radius_put_string_attr ,
.Nm radius_get_vs_uint16_attr ,
.Nm radius_get_vs_uint32_attr ,
.Nm radius_get_vs_uint64_attr ,
.Nm radius_get_vs_ipv4_attr ,
.Nm radius_get_vs_ipv6_attr ,
.Nm radius_put_vs_uint16_attr ,
.Nm radius_put_vs_uint32_attr ,
.Nm radius_put_vs_uint64_attr ,
.Nm radius_put_vs_ipv4_attr ,
.Nm radius_put_vs_ipv6_attr ,
.Nm radius_set_vs_uint16_attr ,
.Nm radius_set_vs_uint32_attr ,
.Nm radius_set_vs_uint64_attr ,
.Nm radius_set_vs_ipv4_attr ,
.Nm radius_set_vs_ipv6_attr ,
.Nm radius_get_vs_string_attr ,
.Nm radius_put_vs_string_attr ,
.Nm radius_put_message_authenticator ,
.Nm radius_set_message_authenticator ,
.Nm radius_check_message_authenticator ,
.Nm radius_encrypt_user_password_attr ,
.Nm radius_decrypt_user_password_attr ,
.Nm radius_encrypt_mppe_key_attr ,
.Nm radius_decrypt_mppe_key_attr ,
.Nm radius_get_user_password_attr ,
.Nm radius_put_user_password_attr ,
.Nm radius_get_mppe_send_key_attr ,
.Nm radius_put_mppe_send_key_attr ,
.Nm radius_get_mppe_recv_key_attr ,
.Nm radius_put_mppe_recv_key_attr ,
.Nm radius_get_eap_msk ,
.Nm radius_send ,
.Nm radius_sendmsg ,
.Nm radius_sendto ,
.Nm radius_recv ,
.Nm radius_recvfrom ,
.Nm radius_recvmsg ,
.Nm radius
.Nd manipulate RADIUS packets for RADIUS clients/servers
.Sh SYNOPSIS
.In sys/types.h
.In sys/socket.h
.In netinet/in.h
.In stdbool.h
.In radius.h
.Sh DESCRIPTION
.Nm radius
provides a facility to manipulate RADIUS packets and some helper functions.
.Sh CREATING AND DESTROYING PACKETS
RADIUS packet objects are created by
.Fn radius_new_request_packet ,
.Fn radius_new_response_packet
or
.Fn radius_convert_packet .
The authenticator field of the packet that is returned by
.Fn radius_new_request_packet
and
.Fn radius_new_response_packet
is filled with random bytes.
.Pp
You must call
.Fn radius_delete_packet
to free memory associated with the packet object.
.Sh HEADER ACCESSOR
.Fn radius_get_id ,
.Fn radius_get_code ,
.Fn radius_get_authenticator ,
.Fn radius_get_authenticator_retval
and
.Fn radius_get_length
retrieves the specified property of the packet.
.Fn radius_update_id
updates a packet's ID field with an internal ID counter.
.Fn radius_set_id
sets a packet's ID field.
.Pp
.Fn radius_set_request_packet
associates a request packet to a response packet.
The associated request packet can be retrieved by
.Fn radius_get_request_packet .
.Pp
.Fn radius_set_response_authenticator
sets a response authenticator to a response packet.
.Fn radius_check_response_authenticator
checks the response authenticator of a response packet.
The request packet must be associated with a response packet by
.Fn radius_new_response_packet
or
.Fn radius_set_request_packet .
.Pp
.Fn radius_set_accounting_request_authenticator
sets a request authenticator to an accounting request packet.
.Fn radius_check_accounting_request_authenticator
checks a request authenticator of an accounting request packet.
.Pp
.Fn 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.
.Pp
.Fn radius_get_data
returns packet data itself.
.Sh RAW ATTRIBUTE ACCESSOR
.Fn radius_get_raw_attr
retrieves an attribute value.
.Fa 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.
.Pp
.Fn 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.
.Pp
.Fn radius_get_raw_attr_cat
retrieves an attribute value.
Unlike
.Fn radius_get_raw_attr ,
.Fn 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
.Fa buf
is
.Dv NULL ,
the initial value of
.Fa length
is ignored and the actual size of concatenated values is returned.
.Pp
.Fn radius_put_raw_attr_cat
appends attribute data to the last of the packet.
Unlike
.Fn radius_put_raw_attr ,
.Fn 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
.Fn radius_delete_packet )
if this function has returned an error.
.Pp
.Fn radius_get_raw_attr_ptr
retrieves a pointer and length of specified attribute.
The returned buffer must not be modified.
.Pp
.Fn radius_set_raw_attr
overwrites existing an attribute value.
If the specified attribute does not exist, this function returns an error.
If
.Fa length
is different from the length of the specified attribute,
the function returns an error.
.Pp
.Fn radius_del_attr_all
deletes all attributes matching its arguments.
.Pp
.Fn radius_has_attr
returns whether packet has a specified attribute.
.Pp
.Fn radius_get_vs_raw_attr ,
.Fn radius_put_vs_raw_attr ,
.Fn radius_get_vs_raw_attr_cat ,
.Fn radius_put_vs_raw_attr_cat ,
.Fn radius_get_vs_raw_attr_ptr ,
.Fn radius_set_vs_raw_attr ,
.Fn radius_del_vs_attr_all
and
.Fn radius_has_vs_attr
are vendor-specific versions of raw attribute accessors.
.Sh TYPED ATTRIBUTE ACCESSOR
To make code simple, there are many typed attribute accessors.
.Nm radius
provides typed accessors for
.Vt uint16_t ,
.Vt uint32_t ,
.Vt uint64_t ,
.Vt struct in_addr
and
.Vt struct in6_addr .
Byte endian may be appropriately swapped for
.Vt uint16_t ,
.Vt uint32_t
and
.Vt uint64_t .
.Pp
These typed accessors do not requires
.Fa 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.
.Pp
There are also typed accessors for string
.Pq Li 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
.Fn strlcpy .
.Sh MESSAGE AUTHENTICATOR
There are helper functions for Message-Authenticator attributes.
.Pp
.Fn radius_put_message_authenticator
and
.Fn radius_set_message_authenticator
calculate a Message-Authenticator and put or set it to packet, respectively.
.Pp
.Fn radius_check_message_authenticator
checks a Message-Authenticator.
.Pp
The request packet must be associated with a response packet by
.Fn radius_new_response_packet
or
.Fn radius_set_request_packet ,
otherwise the packet is treated as a request packet.
.Sh ENCRYPTED ATTRIBUTE
There are helper functions for encrypted attributes.
.Pp
.Fn radius_encrypt_user_password_attr ,
.Fn radius_decrypt_user_password_attr ,
.Fn radius_encrypt_mppe_key_attr
and
.Fn radius_decrypt_mppe_key_attr
encrypt or decrypt User-Password attribute or MS-MPPE-{Send,Recv}-Key
attributes respectively.
.Pp
.Fn radius_get_user_password_attr ,
.Fn radius_put_user_password_attr ,
.Fn radius_get_mppe_send_key_attr ,
.Fn radius_put_mppe_send_key_attr ,
.Fn radius_get_mppe_recv_key_attr
and
.Fn radius_put_mppe_recv_key_attr
are shortcuts of combination of encrypt/decrypt functions
and get/put functions.
.Pp
.Fn 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.
.Sh SENDING AND RECEIVING PACKETS
There are helper functions for sending and receiving packets.
.Pp
.Fn radius_send ,
.Fn radius_sendto ,
.Fn radius_sendmsg ,
.Fn radius_recv ,
.Fn radius_recvfrom
and
.Fn radius_recvmsg
are helper version of
.Fn send ,
.Fn sendto ,
.Fn sendmsg ,
.Fn recv ,
.Fn recvfrom
and
.Fn recvmsg ,
respectively.
.Pp
.Fn radius_send ,
.Fn radius_sendto
and
.Fn radius_sendmsg
return 0 on success and nonzero on failure.
.Pp
.Fn radius_recv
.Fn radius_recvfrom
and
.Fn radius_recvmsg
return the received packet on success and return NULL on failure.
.Pp
Note that
.Li msg_iov
must be
.Li NULL
and
.Li msg_iovlen
must be zero in case of
.Fn radius_sendmsg
and
.Fn radius_recvmsg .
.Sh 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.
.Sh HISTORY
The
.Nm radius+
library was first written by UMEZAWA Takeshi in 2002 for the ID gateway service
of Internet Initiative Japan.
YASUOKA Masahiko added support for Message-Authentication attributes in 2008.
.Ox
project rewrote C++ code to pure C code in 2010.
The
.Nm radius+
library was renamed
.Nm radius
and moved to
.Pa lib/
in 2013.