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