lib/libradius/libradius.3

   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: src/lib/libradius/libradius.3,v 1.6.2.6 2002/11/27 17:36:00 archie Exp $
  26 .\" $DragonFly: src/lib/libradius/libradius.3,v 1.3 2007/09/14 19:47:03 swildner Exp $
  27 .\"
  28 .Dd October 30, 1999
  29 .Dt LIBRADIUS 3
  30 .Os
  31 .Sh NAME
  32 .Nm libradius
  33 .Nd RADIUS client library
  34 .Sh LIBRARY
  35 .Lb libradius
  36 .Sh SYNOPSIS
  37 .In radlib.h
  38 .Ft struct rad_handle *
  39 .Fn rad_acct_open "void"
  40 .Ft int
  41 .Fn rad_add_server "struct rad_handle *h" "const char *host" "int port" "const char *secret" "int timeout" "int max_tries"
  42 .Ft struct rad_handle *
  43 .Fn rad_auth_open "void"
  44 .Ft void
  45 .Fn rad_close "struct rad_handle *h"
  46 .Ft int
  47 .Fn rad_config "struct rad_handle *h" "const char *file"
  48 .Ft int
  49 .Fn rad_continue_send_request "struct rad_handle *h" "int selected" "int *fd" "struct timeval *tv"
  50 .Ft int
  51 .Fn rad_create_request "struct rad_handle *h" "int code"
  52 .Ft struct in_addr
  53 .Fn rad_cvt_addr "const void *data"
  54 .Ft u_int32_t
  55 .Fn rad_cvt_int "const void *data"
  56 .Ft char *
  57 .Fn rad_cvt_string "const void *data" "size_t len"
  58 .Ft int
  59 .Fn rad_get_attr "struct rad_handle *h" "const void **data" "size_t *len"
  60 .Ft int
  61 .Fn rad_get_vendor_attr "u_int32_t *vendor" "const void **data" "size_t *len"
  62 .Ft int
  63 .Fn rad_init_send_request "struct rad_handle *h" "int *fd" "struct timeval *tv"
  64 .Ft int
  65 .Fn rad_put_addr "struct rad_handle *h" "int type" "struct in_addr addr"
  66 .Ft int
  67 .Fn rad_put_attr "struct rad_handle *h" "int type" "const void *data" "size_t len"
  68 .Ft int
  69 .Fn rad_put_int "struct rad_handle *h" "int type" "u_int32_t value"
  70 .Ft int
  71 .Fn rad_put_string "struct rad_handle *h" "int type" "const char *str"
  72 .Ft int
  73 .Fn rad_put_vendor_addr "struct rad_handle *h" "int vendor" "int type" "struct in_addr addr"
  74 .Ft int
  75 .Fn rad_put_vendor_attr "struct rad_handle *h" "int vendor" "int type" "const void *data" "size_t len"
  76 .Ft int
  77 .Fn rad_put_vendor_int "struct rad_handle *h" "int vendor" "int type" "u_int32_t value"
  78 .Ft int
  79 .Fn rad_put_vendor_string "struct rad_handle *h" "int vendor" "int type" "const char *str"
  80 .Ft ssize_t
  81 .Fn rad_request_authenticator "struct rad_handle *h" "char *buf" "size_t len"
  82 .Ft int
  83 .Fn rad_send_request "struct rad_handle *h"
  84 .Ft const char *
  85 .Fn rad_server_secret "struct rad_handle *h"
  86 .Ft const char *
  87 .Fn rad_strerror "struct rad_handle *h"
  88 .Sh DESCRIPTION
  89 The
  90 .Nm
  91 library implements the client side of the Remote Authentication Dial
  92 In User Service (RADIUS).  RADIUS, defined in RFCs 2138 and 2139,
  93 allows clients to perform authentication and accounting by means of
  94 network requests to remote servers.
  95 .Sh INITIALIZATION
  96 To use the library, an application must first call
  97 .Fn rad_auth_open
  98 or
  99 .Fn rad_acct_open
 100 to obtain a
 101 .Va struct rad_handle * ,
 102 which provides the context for subsequent operations.
 103 The former function is used for RADIUS authentication and the
 104 latter is used for RADIUS accounting.
 105 Calls to
 106 .Fn rad_auth_open
 107 and
 108 .Fn rad_acct_open
 109 always succeed unless insufficient virtual memory is available.  If
 110 the necessary memory cannot be allocated, the functions return
 111 .Dv NULL .
 112 For compatibility with earlier versions of this library,
 113 .Fn rad_open
 114 is provided as a synonym for
 115 .Fn rad_auth_open .
 116 .Pp
 117 Before issuing any RADIUS requests, the library must be made aware
 118 of the servers it can contact.  The easiest way to configure the
 119 library is to call
 120 .Fn rad_config .
 121 .Fn rad_config
 122 causes the library to read a configuration file whose format is
 123 described in
 124 .Xr radius.conf 5 .
 125 The pathname of the configuration file is passed as the
 126 .Va file
 127 argument to
 128 .Fn rad_config .
 129 This argument may also be given as
 130 .Dv NULL ,
 131 in which case the standard configuration file
 132 .Pa /etc/radius.conf
 133 is used.
 134 .Fn rad_config
 135 returns 0 on success, or -1 if an error occurs.
 136 .Pp
 137 The library can also be configured programmatically by calls to
 138 .Fn rad_add_server .
 139 The
 140 .Va host
 141 parameter specifies the server host, either as a fully qualified
 142 domain name or as a dotted-quad IP address in text form.
 143 The
 144 .Va port
 145 parameter specifies the UDP port to contact on the server.  If
 146 .Va port
 147 is given as 0, the library looks up the
 148 .Ql radius/udp
 149 or
 150 .Ql radacct/udp
 151 service in the network services database, and uses the port found
 152 there.  If no entry is found, the library uses the standard RADIUS
 153 ports, 1812 for authentication and 1813 for accounting.
 154 The shared secret for the server host is passed to the
 155 .Va secret
 156 parameter.
 157 It may be any NUL-terminated string of bytes.  The RADIUS protocol
 158 ignores all but the leading 128 bytes of the shared secret.
 159 The timeout for receiving replies from the server is passed to the
 160 .Va timeout
 161 parameter, in units of seconds.  The maximum number of repeated
 162 requests to make before giving up is passed into the
 163 .Va max_tries
 164 parameter.
 165 .Fn rad_add_server
 166 returns 0 on success, or -1 if an error occurs.
 167 .Pp
 168 .Fn rad_add_server
 169 may be called multiple times, and it may be used together with
 170 .Fn rad_config .
 171 At most 10 servers may be specified.
 172 When multiple servers are given, they are tried in round-robin
 173 fashion until a valid response is received, or until each server's
 174 .Va max_tries
 175 limit has been reached.
 176 .Sh CREATING A RADIUS REQUEST
 177 A RADIUS request consists of a code specifying the kind of request,
 178 and zero or more attributes which provide additional information.  To
 179 begin constructing a new request, call
 180 .Fn rad_create_request .
 181 In addition to the usual
 182 .Va struct rad_handle * ,
 183 this function takes a
 184 .Va code
 185 parameter which specifies the type of the request.  Most often this
 186 will be
 187 .Dv RAD_ACCESS_REQUEST .
 188 .Fn rad_create_request
 189 returns 0 on success, or -1 on if an error occurs.
 190 .Pp
 191 After the request has been created with
 192 .Fn rad_create_request ,
 193 attributes can be attached to it.  This is done through calls to
 194 .Fn rad_put_addr ,
 195 .Fn rad_put_int ,
 196 and
 197 .Fn rad_put_string .
 198 Each accepts a
 199 .Va type
 200 parameter identifying the attribute, and a value which may be
 201 an Internet address, an integer, or a NUL-terminated string,
 202 respectively.
 203 Alternatively,
 204 .Fn rad_put_vendor_addr ,
 205 .Fn rad_put_vendor_int
 206 or
 207 .Fn rad_put_vendor_string
 208 may be used to specify vendor specific attributes.  Vendor specific
 209 definitions may be found in
 210 .In radlib_vs.h
 211 .Pp
 212 The library also provides a function
 213 .Fn rad_put_attr
 214 which can be used to supply a raw, uninterpreted attribute.  The
 215 .Va data
 216 argument points to an array of bytes, and the
 217 .Va len
 218 argument specifies its length.
 219 .Pp
 220 The
 221 .Fn rad_put_X
 222 functions return 0 on success, or -1 if an error occurs.
 223 .Sh SENDING THE REQUEST AND RECEIVING THE RESPONSE
 224 After the RADIUS request has been constructed, it is sent either by means of
 225 .Fn rad_send_request
 226 or by a combination of calls to
 227 .Fn rad_init_send_request
 228 and
 229 .Fn rad_continue_send_request .
 230 .Pp
 231 The
 232 .Fn rad_send_request
 233 function sends the request and waits for a valid reply,
 234 retrying the defined servers in round-robin fashion as necessary.
 235 If a valid response is received,
 236 .Fn rad_send_request
 237 returns the RADIUS code which specifies the type of the response.
 238 This will typically be
 239 .Dv RAD_ACCESS_ACCEPT ,
 240 .Dv RAD_ACCESS_REJECT ,
 241 or
 242 .Dv RAD_ACCESS_CHALLENGE .
 243 If no valid response is received,
 244 .Fn rad_send_request
 245 returns -1.
 246 .Pp
 247 As an alternative, if you do not wish to block waiting for a response,
 248 .Fn rad_init_send_request
 249 and
 250 .Fn rad_continue_send_request
 251 may be used instead.  If a reply is received from the RADIUS server or a
 252 timeout occurs, these functions return a value as described for
 253 .Fn rad_send_request .
 254 Otherwise, a value of zero is returned and the values pointed to by
 255 .Ar fd
 256 and
 257 .Ar tv
 258 are set to the descriptor and timeout that should be passed to
 259 .Xr select 2 .
 260 .Pp
 261 .Fn rad_init_send_request
 262 must be called first, followed by repeated calls to
 263 .Fn rad_continue_send_request
 264 as long as a return value of zero is given.
 265 Between each call, the application should call
 266 .Xr select 2 ,
 267 passing
 268 .Ar *fd
 269 as a read descriptor and timing out after the interval specified by
 270 .Ar tv .
 271 When select returns,
 272 .Fn rad_continue_send_request
 273 should be called with
 274 .Ar selected
 275 set to a non-zero value if
 276 .Xr select 2
 277 indicated that the descriptor is readable.
 278 .Pp
 279 Like RADIUS requests, each response may contain zero or more
 280 attributes.  After a response has been received successfully by
 281 .Fn rad_send_request
 282 or
 283 .Fn rad_continue_send_request ,
 284 its attributes can be extracted one by one using
 285 .Fn rad_get_attr .
 286 Each time
 287 .Fn rad_get_attr
 288 is called, it gets the next attribute from the current response, and
 289 stores a pointer to the data and the length of the data via the
 290 reference parameters
 291 .Va data
 292 and
 293 .Va len ,
 294 respectively.  Note that the data resides in the response itself,
 295 and must not be modified.
 296 A successful call to
 297 .Fn rad_get_attr
 298 returns the RADIUS attribute type.
 299 If no more attributes remain in the current response,
 300 .Fn rad_get_attr
 301 returns 0.
 302 If an error such as a malformed attribute is detected, -1 is
 303 returned.
 304 .Pp
 305 If
 306 .Fn rad_get_attr
 307 returns
 308 .Dv RAD_VENDOR_SPECIFIC ,
 309 .Fn rad_get_vendor_attr
 310 may be called to determine the vendor.
 311 The vendor specific RADIUS attribute type is returned.
 312 The reference parameters
 313 .Va data
 314 and
 315 .Va len
 316 .Pq as returned from Fn rad_get_attr
 317 are passed to
 318 .Fn rad_get_vendor_attr ,
 319 and are adjusted to point to the vendor specific attribute data.
 320 .Pp
 321 The common types of attributes can be decoded using
 322 .Fn rad_cvt_addr ,
 323 .Fn rad_cvt_int ,
 324 and
 325 .Fn rad_cvt_string .
 326 These functions accept a pointer to the attribute data, which should
 327 have been obtained using
 328 .Fn rad_get_attr
 329 and optionally
 330 .Fn rad_get_vendor_attr .
 331 In the case of
 332 .Fn rad_cvt_string ,
 333 the length
 334 .Va len
 335 must also be given.  These functions interpret the attribute as an
 336 Internet address, an integer, or a string, respectively, and return
 337 its value.
 338 .Fn rad_cvt_string
 339 returns its value as a NUL-terminated string in dynamically
 340 allocated memory.  The application should free the string using
 341 .Xr free 3
 342 when it is no longer needed.
 343 .Pp
 344 If insufficient virtual memory is available,
 345 .Fn rad_cvt_string
 346 returns
 347 .Dv NULL .
 348 .Fn rad_cvt_addr
 349 and
 350 .Fn rad_cvt_int
 351 cannot fail.
 352 .Pp
 353 The
 354 .Fn rad_request_authenticator
 355 function may be used to obtain the Request-Authenticator attribute value
 356 associated with the current RADIUS server according to the supplied
 357 rad_handle.
 358 The target buffer
 359 .Ar buf
 360 of length
 361 .Ar len
 362 must be supplied and should be at least 16 bytes.
 363 The return value is the number of bytes written to
 364 .Ar buf
 365 or -1 to indicate that
 366 .Ar len
 367 was not large enough.
 368 .Pp
 369 The
 370 .Fn rad_server_secret
 371 returns the secret shared with the current RADIUS server according to the
 372 supplied rad_handle.
 373 .Sh OBTAINING ERROR MESSAGES
 374 Those functions which accept a
 375 .Va struct rad_handle *
 376 argument record an error message if they fail.  The error message
 377 can be retrieved by calling
 378 .Fn rad_strerror .
 379 The message text is overwritten on each new error for the given
 380 .Va struct rad_handle * .
 381 Thus the message must be copied if it is to be preserved through
 382 subsequent library calls using the same handle.
 383 .Sh CLEANUP
 384 To free the resources used by the RADIUS library, call
 385 .Fn rad_close .
 386 .Sh RETURN VALUES
 387 The following functions return a non-negative value on success.  If
 388 they detect an error, they return -1 and record an error message
 389 which can be retrieved using
 390 .Fn rad_strerror .
 391 .Pp
 392 .Bl -item -offset indent -compact
 393 .It
 394 .Fn rad_add_server
 395 .It
 396 .Fn rad_config
 397 .It
 398 .Fn rad_create_request
 399 .It
 400 .Fn rad_get_attr
 401 .It
 402 .Fn rad_put_addr
 403 .It
 404 .Fn rad_put_attr
 405 .It
 406 .Fn rad_put_int
 407 .It
 408 .Fn rad_put_string
 409 .It
 410 .Fn rad_init_send_request
 411 .It
 412 .Fn rad_continue_send_request
 413 .It
 414 .Fn rad_send_request
 415 .El
 416 .Pp
 417 The following functions return a
 418 .No non- Ns Dv NULL
 419 pointer on success.  If they are unable to allocate sufficient
 420 virtual memory, they return
 421 .Dv NULL ,
 422 without recording an error message.
 423 .Pp
 424 .Bl -item -offset indent -compact
 425 .It
 426 .Fn rad_acct_open
 427 .It
 428 .Fn rad_auth_open
 429 .It
 430 .Fn rad_cvt_string
 431 .El
 432 .Sh FILES
 433 .Pa /etc/radius.conf
 434 .Sh SEE ALSO
 435 .Xr radius.conf 5
 436 .Rs
 437 .%A C. Rigney, et al
 438 .%T "Remote Authentication Dial In User Service (RADIUS)"
 439 .%O RFC 2138
 440 .Re
 441 .Rs
 442 .%A C. Rigney
 443 .%T RADIUS Accounting
 444 .%O RFC 2139
 445 .Re
 446 .Sh AUTHORS
 447 This software was originally written by
 448 .An John Polstra ,
 449 and donated to the
 450 .Fx
 451 project by Juniper Networks, Inc.
 452 Oleg Semyonov subsequently added the ability to perform RADIUS
 453 accounting.