| blob | 75c5d3939876b7c9b40e14ca78c4a22567f93965 |
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 .