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