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: /repoman/r/ncvs/src/lib/libradius/libradius.3,v 1.17 2004/04/27 15:00:29 ru Exp $
  26 .\" $NetBSD: libradius.3,v 1.1.1.1 2005/02/19 23:56:31 manu Exp $
  27 .\"
  28 .Dd April 27, 2004
  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 uint32_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 "uint32_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" "uint32_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_message_authentic "struct rad_handle *h"
  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" "uint32_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 u_char *
  87 .Fn rad_demangle "struct rad_handle *h" "const void *mangled" "size_t mlen"
  88 .Ft u_char *
  89 .Fn rad_demangle_mppe_key "struct rad_handle *h" "const void *mangled" "size_t mlen" "size_t *len"
  90 .Ft "const char *"
  91 .Fn rad_strerror "struct rad_handle *h"
  92 .Sh DESCRIPTION
  93 The
  94 .Nm
  95 library implements the client side of the Remote Authentication Dial
  96 In User Service (RADIUS).
  97 RADIUS, defined in RFCs 2865 and 2866,
  98 allows clients to perform authentication and accounting by means of
  99 network requests to remote servers.
 100 .Ss Initialization
 101 To use the library, an application must first call
 102 .Fn rad_auth_open
 103 or
 104 .Fn rad_acct_open
 105 to obtain a
 106 .Vt "struct rad_handle *" ,
 107 which provides the context for subsequent operations.
 108 The former function is used for RADIUS authentication and the
 109 latter is used for RADIUS accounting.
 110 Calls to
 111 .Fn rad_auth_open
 112 and
 113 .Fn rad_acct_open
 114 always succeed unless insufficient virtual memory is available.
 115 If
 116 the necessary memory cannot be allocated, the functions return
 117 .Dv NULL .
 118 For compatibility with earlier versions of this library,
 119 .Fn rad_open
 120 is provided as a synonym for
 121 .Fn rad_auth_open .
 122 .Pp
 123 Before issuing any RADIUS requests, the library must be made aware
 124 of the servers it can contact.
 125 The easiest way to configure the
 126 library is to call
 127 .Fn rad_config .
 128 .Fn rad_config
 129 causes the library to read a configuration file whose format is
 130 described in
 131 .Xr radius.conf 5 .
 132 The pathname of the configuration file is passed as the
 133 .Fa file
 134 argument to
 135 .Fn rad_config .
 136 This argument may also be given as
 137 .Dv NULL ,
 138 in which case the standard configuration file
 139 .Pa /etc/radius.conf
 140 is used.
 141 .Fn rad_config
 142 returns 0 on success, or \-1 if an error occurs.
 143 .Pp
 144 The library can also be configured programmatically by calls to
 145 .Fn rad_add_server .
 146 The
 147 .Fa host
 148 parameter specifies the server host, either as a fully qualified
 149 domain name or as a dotted-quad IP address in text form.
 150 The
 151 .Fa port
 152 parameter specifies the UDP port to contact on the server.
 153 If
 154 .Fa port
 155 is given as 0, the library looks up the
 156 .Ql radius/udp
 157 or
 158 .Ql radacct/udp
 159 service in the network
 160 .Xr services 5
 161 database, and uses the port found
 162 there.
 163 If no entry is found, the library uses the standard RADIUS
 164 ports, 1812 for authentication and 1813 for accounting.
 165 The shared secret for the server host is passed to the
 166 .Fa secret
 167 parameter.
 168 It may be any
 169 .Dv NUL Ns -terminated
 170 string of bytes.
 171 The RADIUS protocol
 172 ignores all but the leading 128 bytes of the shared secret.
 173 The timeout for receiving replies from the server is passed to the
 174 .Fa timeout
 175 parameter, in units of seconds.
 176 The maximum number of repeated
 177 requests to make before giving up is passed into the
 178 .Fa max_tries
 179 parameter.
 180 .Fn rad_add_server
 181 returns 0 on success, or \-1 if an error occurs.
 182 .Pp
 183 .Fn rad_add_server
 184 may be called multiple times, and it may be used together with
 185 .Fn rad_config .
 186 At most 10 servers may be specified.
 187 When multiple servers are given, they are tried in round-robin
 188 fashion until a valid response is received, or until each server's
 189 .Fa max_tries
 190 limit has been reached.
 191 .Ss Creating a RADIUS Request
 192 A RADIUS request consists of a code specifying the kind of request,
 193 and zero or more attributes which provide additional information.
 194 To
 195 begin constructing a new request, call
 196 .Fn rad_create_request .
 197 In addition to the usual
 198 .Vt "struct rad_handle *" ,
 199 this function takes a
 200 .Fa code
 201 parameter which specifies the type of the request.
 202 Most often this
 203 will be
 204 .Dv RAD_ACCESS_REQUEST .
 205 .Fn rad_create_request
 206 returns 0 on success, or \-1 on if an error occurs.
 207 .Pp
 208 After the request has been created with
 209 .Fn rad_create_request ,
 210 attributes can be attached to it.
 211 This is done through calls to
 212 .Fn rad_put_addr ,
 213 .Fn rad_put_int ,
 214 and
 215 .Fn rad_put_string .
 216 Each accepts a
 217 .Fa type
 218 parameter identifying the attribute, and a value which may be
 219 an Internet address, an integer, or a
 220 .Dv NUL Ns -terminated
 221 string,
 222 respectively.
 223 Alternatively,
 224 .Fn rad_put_vendor_addr ,
 225 .Fn rad_put_vendor_int
 226 or
 227 .Fn rad_put_vendor_string
 228 may be used to specify vendor specific attributes.
 229 Vendor specific
 230 definitions may be found in
 231 .In radlib_vs.h
 232 .Pp
 233 The library also provides a function
 234 .Fn rad_put_attr
 235 which can be used to supply a raw, uninterpreted attribute.
 236 The
 237 .Fa data
 238 argument points to an array of bytes, and the
 239 .Fa len
 240 argument specifies its length.
 241 .Pp
 242 It is possible adding the Message-Authenticator to the request.
 243 This is an HMAC-MD5 hash of the entire Access-Request packet (see RFC 3579).
 244 This attribute must be present in any packet that includes an EAP-Message
 245 attribute.
 246 It can be added by using the
 247 .Fn rad_put_message_authentic
 248 function.
 249 The
 250 .Nm
 251 library
 252 calculates the HMAC-MD5 hash implicitly before sending the request.
 253 If the Message-Authenticator was found inside the response packet,
 254 then the packet is silently dropped, if the validation failed.
 255 In order to get this feature, the library should be compiled with
 256 OpenSSL support.
 257 .Pp
 258 The
 259 .Fn rad_put_X
 260 functions return 0 on success, or \-1 if an error occurs.
 261 .Ss Sending the Request and Receiving the Response
 262 After the RADIUS request has been constructed, it is sent either by means of
 263 .Fn rad_send_request
 264 or by a combination of calls to
 265 .Fn rad_init_send_request
 266 and
 267 .Fn rad_continue_send_request .
 268 .Pp
 269 The
 270 .Fn rad_send_request
 271 function sends the request and waits for a valid reply,
 272 retrying the defined servers in round-robin fashion as necessary.
 273 If a valid response is received,
 274 .Fn rad_send_request
 275 returns the RADIUS code which specifies the type of the response.
 276 This will typically be
 277 .Dv RAD_ACCESS_ACCEPT ,
 278 .Dv RAD_ACCESS_REJECT ,
 279 or
 280 .Dv RAD_ACCESS_CHALLENGE .
 281 If no valid response is received,
 282 .Fn rad_send_request
 283 returns \-1.
 284 .Pp
 285 As an alternative, if you do not wish to block waiting for a response,
 286 .Fn rad_init_send_request
 287 and
 288 .Fn rad_continue_send_request
 289 may be used instead.
 290 If a reply is received from the RADIUS server or a
 291 timeout occurs, these functions return a value as described for
 292 .Fn rad_send_request .
 293 Otherwise, a value of zero is returned and the values pointed to by
 294 .Fa fd
 295 and
 296 .Fa tv
 297 are set to the descriptor and timeout that should be passed to
 298 .Xr select 2 .
 299 .Pp
 300 .Fn rad_init_send_request
 301 must be called first, followed by repeated calls to
 302 .Fn rad_continue_send_request
 303 as long as a return value of zero is given.
 304 Between each call, the application should call
 305 .Xr select 2 ,
 306 passing
 307 .Fa *fd
 308 as a read descriptor and timing out after the interval specified by
 309 .Fa tv .
 310 When
 311 .Xr select 2
 312 returns,
 313 .Fn rad_continue_send_request
 314 should be called with
 315 .Fa selected
 316 set to a non-zero value if
 317 .Xr select 2
 318 indicated that the descriptor is readable.
 319 .Pp
 320 Like RADIUS requests, each response may contain zero or more
 321 attributes.
 322 After a response has been received successfully by
 323 .Fn rad_send_request
 324 or
 325 .Fn rad_continue_send_request ,
 326 its attributes can be extracted one by one using
 327 .Fn rad_get_attr .
 328 Each time
 329 .Fn rad_get_attr
 330 is called, it gets the next attribute from the current response, and
 331 stores a pointer to the data and the length of the data via the
 332 reference parameters
 333 .Fa data
 334 and
 335 .Fa len ,
 336 respectively.
 337 Note that the data resides in the response itself,
 338 and must not be modified.
 339 A successful call to
 340 .Fn rad_get_attr
 341 returns the RADIUS attribute type.
 342 If no more attributes remain in the current response,
 343 .Fn rad_get_attr
 344 returns 0.
 345 If an error such as a malformed attribute is detected, \-1 is
 346 returned.
 347 .Pp
 348 If
 349 .Fn rad_get_attr
 350 returns
 351 .Dv RAD_VENDOR_SPECIFIC ,
 352 .Fn rad_get_vendor_attr
 353 may be called to determine the vendor.
 354 The vendor specific RADIUS attribute type is returned.
 355 The reference parameters
 356 .Fa data
 357 and
 358 .Fa len
 359 (as returned from
 360 .Fn rad_get_attr )
 361 are passed to
 362 .Fn rad_get_vendor_attr ,
 363 and are adjusted to point to the vendor specific attribute data.
 364 .Pp
 365 The common types of attributes can be decoded using
 366 .Fn rad_cvt_addr ,
 367 .Fn rad_cvt_int ,
 368 and
 369 .Fn rad_cvt_string .
 370 These functions accept a pointer to the attribute data, which should
 371 have been obtained using
 372 .Fn rad_get_attr
 373 and optionally
 374 .Fn rad_get_vendor_attr .
 375 In the case of
 376 .Fn rad_cvt_string ,
 377 the length
 378 .Fa len
 379 must also be given.
 380 These functions interpret the attribute as an
 381 Internet address, an integer, or a string, respectively, and return
 382 its value.
 383 .Fn rad_cvt_string
 384 returns its value as a
 385 .Dv NUL Ns -terminated
 386 string in dynamically
 387 allocated memory.
 388 The application should free the string using
 389 .Xr free 3
 390 when it is no longer needed.
 391 .Pp
 392 If insufficient virtual memory is available,
 393 .Fn rad_cvt_string
 394 returns
 395 .Dv NULL .
 396 .Fn rad_cvt_addr
 397 and
 398 .Fn rad_cvt_int
 399 cannot fail.
 400 .Pp
 401 The
 402 .Fn rad_request_authenticator
 403 function may be used to obtain the Request-Authenticator attribute value
 404 associated with the current RADIUS server according to the supplied
 405 rad_handle.
 406 The target buffer
 407 .Fa buf
 408 of length
 409 .Fa len
 410 must be supplied and should be at least 16 bytes.
 411 The return value is the number of bytes written to
 412 .Fa buf
 413 or \-1 to indicate that
 414 .Fa len
 415 was not large enough.
 416 .Pp
 417 The
 418 .Fn rad_server_secret
 419 returns the secret shared with the current RADIUS server according to the
 420 supplied rad_handle.
 421 .Pp
 422 The
 423 .Fn rad_demangle
 424 function demangles attributes containing passwords and MS-CHAPv1 MPPE-Keys.
 425 The return value is
 426 .Dv NULL
 427 on failure, or the plaintext attribute.
 428 This value should be freed using
 429 .Xr free 3
 430 when it is no longer needed.
 431 .Pp
 432 The
 433 .Fn rad_demangle_mppe_key
 434 function demangles the send- and recv-keys when using MPPE (see RFC 2548).
 435 The return value is
 436 .Dv NULL
 437 on failure, or the plaintext attribute.
 438 This value should be freed using
 439 .Xr free 3
 440 when it is no longer needed.
 441 .Ss Obtaining Error Messages
 442 Those functions which accept a
 443 .Vt "struct rad_handle *"
 444 argument record an error message if they fail.
 445 The error message
 446 can be retrieved by calling
 447 .Fn rad_strerror .
 448 The message text is overwritten on each new error for the given
 449 .Vt "struct rad_handle *" .
 450 Thus the message must be copied if it is to be preserved through
 451 subsequent library calls using the same handle.
 452 .Ss Cleanup
 453 To free the resources used by the RADIUS library, call
 454 .Fn rad_close .
 455 .Sh RETURN VALUES
 456 The following functions return a non-negative value on success.
 457 If
 458 they detect an error, they return \-1 and record an error message
 459 which can be retrieved using
 460 .Fn rad_strerror .
 461 .Pp
 462 .Bl -item -offset indent -compact
 463 .It
 464 .Fn rad_add_server
 465 .It
 466 .Fn rad_config
 467 .It
 468 .Fn rad_create_request
 469 .It
 470 .Fn rad_get_attr
 471 .It
 472 .Fn rad_put_addr
 473 .It
 474 .Fn rad_put_attr
 475 .It
 476 .Fn rad_put_int
 477 .It
 478 .Fn rad_put_string
 479 .It
 480 .Fn rad_put_message_authentic
 481 .It
 482 .Fn rad_init_send_request
 483 .It
 484 .Fn rad_continue_send_request
 485 .It
 486 .Fn rad_send_request
 487 .El
 488 .Pp
 489 The following functions return a
 490 .No non- Ns Dv NULL
 491 pointer on success.
 492 If they are unable to allocate sufficient
 493 virtual memory, they return
 494 .Dv NULL ,
 495 without recording an error message.
 496 .Pp
 497 .Bl -item -offset indent -compact
 498 .It
 499 .Fn rad_acct_open
 500 .It
 501 .Fn rad_auth_open
 502 .It
 503 .Fn rad_cvt_string
 504 .El
 505 .Pp
 506 The following functions return a
 507 .No non- Ns Dv NULL
 508 pointer on success.
 509 If they fail, they return
 510 .Dv NULL ,
 511 with recording an error message.
 512 .Pp
 513 .Bl -item -offset indent -compact
 514 .It
 515 .Fn rad_demangle
 516 .It
 517 .Fn rad_demangle_mppe_key
 518 .El
 519 .Sh FILES
 520 .Bl -tag -width indent
 521 .It Pa /etc/radius.conf
 522 .El
 523 .Sh SEE ALSO
 524 .Xr radius.conf 5
 525 .Rs
 526 .%A "C. Rigney, et al"
 527 .%T "Remote Authentication Dial In User Service (RADIUS)"
 528 .%O "RFC 2865"
 529 .Re
 530 .Rs
 531 .%A "C. Rigney"
 532 .%T "RADIUS Accounting"
 533 .%O "RFC 2866"
 534 .Re
 535 .Rs
 536 .%A G. Zorn
 537 .%T "Microsoft Vendor-specific RADIUS attributes"
 538 .%O RFC 2548
 539 .Re
 540 .Rs
 541 .%A C. Rigney, et al
 542 .%T "RADIUS extensions"
 543 .%O RFC 2869
 544 .Re
 545 .Sh AUTHORS
 546 .An -nosplit
 547 This software was originally written by
 548 .An John Polstra ,
 549 and donated to the
 550 .Fx
 551 project by Juniper Networks, Inc.
 552 .An Oleg Semyonov
 553 subsequently added the ability to perform RADIUS
 554 accounting.
 555 Later additions and changes by
 556 .An Michael Bretterklieber .