1.\" Copyright 1998 Juniper Networks, Inc. 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 16.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 23.\" SUCH DAMAGE. 24.\" 25.\" $FreeBSD$ 26.\" 27.Dd July 29, 1998 28.Dt LIBRADIUS 3 29.Os FreeBSD 30.Sh NAME 31.Nm libradius 32.Nd RADIUS client library 33.Sh SYNOPSIS 34.Fd #include <radlib.h> 35.Ft int 36.Fn rad_add_server "struct rad_handle *h" "const char *host" "int port" "const char *secret" "int timeout" "int max_tries" 37.Ft void 38.Fn rad_close "struct rad_handle *h" 39.Ft int 40.Fn rad_config "struct rad_handle *h" "const char *file" 41.Ft int 42.Fn rad_create_request "struct rad_handle *h" "int code" 43.Ft struct in_addr 44.Fn rad_cvt_addr "const void *data" 45.Ft u_int32_t 46.Fn rad_cvt_int "const void *data" 47.Ft char * 48.Fn rad_cvt_string "const void *data" "size_t len" 49.Ft int 50.Fn rad_get_attr "struct rad_handle *h" "const void **data" "size_t *len" 51.Ft struct rad_handle * 52.Fn rad_open "void" 53.Ft int 54.Fn rad_put_addr "struct rad_handle *h" "int type" "struct in_addr addr" 55.Ft int 56.Fn rad_put_attr "struct rad_handle *h" "int type" "const void *data" "size_t len" 57.Ft int 58.Fn rad_put_int "struct rad_handle *h" "int type" "u_int32_t value" 59.Ft int 60.Fn rad_put_string "struct rad_handle *h" "int type" "const char *str" 61.Ft int 62.Fn rad_send_request "struct rad_handle *h" 63.Ft const char * 64.Fn rad_strerror "struct rad_handle *h" 65.Sh DESCRIPTION 66The 67.Nm 68library implements the client side of the Remote Authentication 69Dial In User Service (RADIUS). RADIUS, defined in RFC 2138, allows 70clients to perform authentication by means of network requests to 71remote authentication servers. 72.Sh INITIALIZATION 73To use the library, an application must first call 74.Fn rad_open 75to obtain a 76.Va struct rad_handle * , 77which provides the context for subsequent operations. 78Calls to 79.Fn rad_open 80always succeed unless insufficient virtual memory is available. If 81the necessary memory cannot be allocated, 82.Fn rad_open 83returns 84.Dv NULL . 85.Pp 86Before issuing any RADIUS requests, the library must be made aware 87of the servers it can contact. The easiest way to configure the 88library is to call 89.Fn rad_config . 90.Fn rad_config 91causes the library to read a configuration file whose format is 92described in 93.Xr radius.conf 5 . 94The pathname of the configuration file is passed as the 95.Va file 96argument to 97.Fn rad_config . 98This argument may also be given as 99.Dv NULL , 100in which case the standard configuration file 101.Pa /etc/radius.conf 102is used. 103.Fn rad_config 104returns 0 on success, or -1 if an error occurs. 105.Pp 106The library can also be configured programmatically by calls to 107.Fn rad_add_server . 108The 109.Va host 110parameter specifies the server host, either as a fully qualified 111domain name or as a dotted-quad IP address in text form. 112The 113.Va port 114parameter specifies the UDP port to contact on the server. If 115.Va port 116is given as 0, the library looks up the 117.Ql radius/udp 118service in the network services database, and uses the port found 119there. If no entry is found, the library uses port 1812, the standard 120RADIUS port. The shared secret for the server host is passed to the 121.Va secret 122parameter. 123It may be any NUL-terminated string of bytes. The RADIUS protocol 124ignores all but the leading 128 bytes of the shared secret. 125The timeout for receiving replies from the server is passed to the 126.Va timeout 127parameter, in units of seconds. The maximum number of repeated 128requests to make before giving up is passed into the 129.Va max_tries 130parameter. 131.Fn rad_add_server 132returns 0 on success, or -1 if an error occurs. 133.Pp 134.Fn rad_add_server 135may be called multiple times, and it may be used together with 136.Fn rad_config . 137At most 10 servers may be specified. 138When multiple servers are given, they are tried in round-robin 139fashion until a valid response is received, or until each server's 140.Va max_tries 141limit has been reached. 142.Sh CREATING A RADIUS REQUEST 143A RADIUS request consists of a code specifying the kind of request, 144and zero or more attributes which provide additional information. To 145begin constructing a new request, call 146.Fn rad_create_request . 147In addition to the usual 148.Va struct rad_handle * , 149this function takes a 150.Va code 151parameter which specifies the type of the request. Most often this 152will be 153.Dv RAD_ACCESS_REQUEST . 154.Fn rad_create_request 155returns 0 on success, or -1 on if an error occurs. 156.Pp 157After the request has been created with 158.Fn rad_create request , 159attributes can be attached to it. This is done through calls to 160.Fn rad_put_addr , 161.Fn rad_put_int , 162and 163.Fn rad_put_string . 164Each accepts a 165.Va type 166parameter identifying the attribute, and a value which may be 167an Internet address, an integer, or a NUL-terminated string, 168respectively. 169.Pp 170The library also provides a function 171.Fn rad_put_attr 172which can be used to supply a raw, uninterpreted attribute. The 173.Va data 174argument points to an array of bytes, and the 175.Va len 176argument specifies its length. 177.Pp 178The 179.Fn rad_put_X 180functions return 0 on success, or -1 if an error occurs. 181.Sh SENDING THE REQUEST AND RECEIVING THE RESPONSE 182After the RADIUS request has been constructed, it is sent by means 183of 184.Fn rad_send_request . 185This function sends the request and waits for a valid reply, 186retrying the defined servers in round-robin fashion as necessary. 187If a valid response is received, 188.Fn rad_send_request 189returns the RADIUS code which specifies the type of the response. 190This will typically be 191.Dv RAD_ACCESS_ACCEPT , 192.Dv RAD_ACCESS_REJECT , 193or 194.Dv RAD_ACCESS_CHALLENGE . 195If no valid response is received, 196.Fn rad_send_request 197returns -1. 198.Pp 199Like RADIUS requests, each response may contain zero or more 200attributes. After a response has been received successfully by 201.Fn rad_send_request , 202its attributes can be extracted one by one using 203.Fn rad_get_attr . 204Each time 205.Fn rad_get_attr 206is called, it gets the next attribute from the current response, and 207stores a pointer to the data and the length of the data via the 208reference parameters 209.Va data 210and 211.Va len , 212respectively. Note that the data resides in the response itself, 213and must not be modified. 214A successful call to 215.Fn rad_get_attr 216returns the RADIUS attribute type. 217If no more attributes remain in the current response, 218.Fn rad_get_attr 219returns 0. 220If an error such as a malformed attribute is detected, -1 is 221returned. 222.Pp 223The common types of attributes can be decoded using 224.Fn rad_cvt_addr , 225.Fn rad_cvt_int , 226and 227.Fn rad_cvt_string . 228These functions accept a pointer to the attribute data, which should 229have been obtained using 230.Fn rad_get_attr . 231In the case of 232.Fn rad_cvt_string , 233the length 234.Va len 235must also be given. These functions interpret the attribute as an 236Internet address, an integer, or a string, respectively, and return 237its value. 238.Fn rad_cvt_string 239returns its value as a NUL-terminated string in dynamically 240allocated memory. The application should free the string using 241.Xr free 3 242when it is no longer needed. 243.Pp 244If insufficient virtual memory is available, 245.Fn rad_cvt_string 246returns 247.Dv NULL . 248.Fn rad_cvt_addr 249and 250.Fn rad_cvt_int 251cannot fail. 252.Sh OBTAINING ERROR MESSAGES 253Those functions which accept a 254.Va struct rad_handle * 255argument record an error message if they fail. The error message 256can be retrieved by calling 257.Fn rad_strerror . 258The message text is overwritten on each new error for the given 259.Va struct rad_handle * . 260Thus the message must be copied if it is to be preserved through 261subsequent library calls using the same handle. 262.Sh CLEANUP 263To free the resources used by the RADIUS library, call 264.Fn rad_close . 265.Sh RETURN VALUES 266The following functions return a non-negative value on success. If 267they detect an error, they return -1 and record an error message 268which can be retrieved using 269.Fn rad_strerror . 270.Pp 271.Bl -item -offset indent -compact 272.It 273.Fn rad_add_server 274.It 275.Fn rad_config 276.It 277.Fn rad_create_request 278.It 279.Fn rad_get_attr 280.It 281.Fn rad_put_addr 282.It 283.Fn rad_put_attr 284.It 285.Fn rad_put_int 286.It 287.Fn rad_put_string 288.It 289.Fn rad_send_request 290.El 291.Pp 292The following functions return a 293.No non- Ns Dv NULL 294pointer on success. If they are unable to allocate sufficient 295virtual memory, they return 296.Dv NULL , 297without recording an error message. 298.Pp 299.Bl -item -offset indent -compact 300.It 301.Fn rad_cvt_string 302.It 303.Fn rad_open 304.El 305.Sh FILES 306.Pa /etc/radius.conf 307.Sh SEE ALSO 308.Xr radius.conf 5 309.Rs 310.%A C. Rigney, et al 311.%T Remote Authentication Dial In User Service (RADIUS) 312.%O RFC 2138 313.Re 314.Sh AUTHORS 315This software was written by 316.An John Polstra , 317and donated to the FreeBSD project by Juniper Networks, Inc. 318