1 .\" Copyright 1998 Juniper Networks, Inc.
2 .\" All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
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.
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
32 .Nd RADIUS client library
35 .Ft "struct rad_handle *"
36 .Fn rad_acct_open "void"
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"
42 .Fn rad_close "struct rad_handle *h"
44 .Fn rad_config "struct rad_handle *h" "const char *file"
46 .Fn rad_continue_send_request "struct rad_handle *h" "int selected" "int *fd" "struct timeval *tv"
48 .Fn rad_create_request "struct rad_handle *h" "int code"
50 .Fn rad_cvt_addr "const void *data"
52 .Fn rad_cvt_int "const void *data"
54 .Fn rad_cvt_string "const void *data" "size_t len"
56 .Fn rad_get_attr "struct rad_handle *h" "const void **data" "size_t *len"
58 .Fn rad_get_vendor_attr "u_int32_t *vendor" "const void **data" "size_t *len"
60 .Fn rad_init_send_request "struct rad_handle *h" "int *fd" "struct timeval *tv"
62 .Fn rad_put_addr "struct rad_handle *h" "int type" "struct in_addr addr"
64 .Fn rad_put_attr "struct rad_handle *h" "int type" "const void *data" "size_t len"
66 .Fn rad_put_int "struct rad_handle *h" "int type" "u_int32_t value"
68 .Fn rad_put_string "struct rad_handle *h" "int type" "const char *str"
70 .Fn rad_put_message_authentic "struct rad_handle *h"
72 .Fn rad_put_vendor_addr "struct rad_handle *h" "int vendor" "int type" "struct in_addr addr"
74 .Fn rad_put_vendor_attr "struct rad_handle *h" "int vendor" "int type" "const void *data" "size_t len"
76 .Fn rad_put_vendor_int "struct rad_handle *h" "int vendor" "int type" "u_int32_t value"
78 .Fn rad_put_vendor_string "struct rad_handle *h" "int vendor" "int type" "const char *str"
80 .Fn rad_request_authenticator "struct rad_handle *h" "char *buf" "size_t len"
82 .Fn rad_send_request "struct rad_handle *h"
84 .Fn rad_server_secret "struct rad_handle *h"
86 .Fn rad_demangle "struct rad_handle *h" "const void *mangled" "size_t mlen"
88 .Fn rad_demangle_mppe_key "struct rad_handle *h" "const void *mangled" "size_t mlen" "size_t *len"
90 .Fn rad_strerror "struct rad_handle *h"
94 library implements the client side of the Remote Authentication Dial
95 In User Service (RADIUS).
96 RADIUS, defined in RFCs 2865 and 2866,
97 allows clients to perform authentication and accounting by means of
98 network requests to remote servers.
100 To use the library, an application must first call
105 .Vt "struct rad_handle *" ,
106 which provides the context for subsequent operations.
107 The former function is used for RADIUS authentication and the
108 latter is used for RADIUS accounting.
113 always succeed unless insufficient virtual memory is available.
115 the necessary memory cannot be allocated, the functions return
117 For compatibility with earlier versions of this library,
119 is provided as a synonym for
122 Before issuing any RADIUS requests, the library must be made aware
123 of the servers it can contact.
124 The easiest way to configure the
128 causes the library to read a configuration file whose format is
131 The pathname of the configuration file is passed as the
135 This argument may also be given as
137 in which case the standard configuration file
141 returns 0 on success, or \-1 if an error occurs.
143 The library can also be configured programmatically by calls to
147 parameter specifies the server host, either as a fully qualified
148 domain name or as a dotted-quad IP address in text form.
151 parameter specifies the UDP port to contact on the server.
154 is given as 0, the library looks up the
158 service in the network
160 database, and uses the port found
162 If no entry is found, the library uses the standard RADIUS
163 ports, 1812 for authentication and 1813 for accounting.
164 The shared secret for the server host is passed to the
168 .Dv NUL Ns -terminated
171 ignores all but the leading 128 bytes of the shared secret.
172 The timeout for receiving replies from the server is passed to the
174 parameter, in units of seconds.
175 The maximum number of repeated
176 requests to make before giving up is passed into the
180 returns 0 on success, or \-1 if an error occurs.
183 may be called multiple times, and it may be used together with
185 At most 10 servers may be specified.
186 When multiple servers are given, they are tried in round-robin
187 fashion until a valid response is received, or until each server's
189 limit has been reached.
190 .Ss Creating a RADIUS Request
191 A RADIUS request consists of a code specifying the kind of request,
192 and zero or more attributes which provide additional information.
194 begin constructing a new request, call
195 .Fn rad_create_request .
196 In addition to the usual
197 .Vt "struct rad_handle *" ,
198 this function takes a
200 parameter which specifies the type of the request.
203 .Dv RAD_ACCESS_REQUEST .
204 .Fn rad_create_request
205 returns 0 on success, or \-1 on if an error occurs.
207 After the request has been created with
208 .Fn rad_create_request ,
209 attributes can be attached to it.
210 This is done through calls to
217 parameter identifying the attribute, and a value which may be
218 an Internet address, an integer, or a
219 .Dv NUL Ns -terminated
223 .Fn rad_put_vendor_addr ,
224 .Fn rad_put_vendor_int
226 .Fn rad_put_vendor_string
227 may be used to specify vendor specific attributes.
229 definitions may be found in
232 The library also provides a function
234 which can be used to supply a raw, uninterpreted attribute.
237 argument points to an array of bytes, and the
239 argument specifies its length.
241 It is possible adding the Message-Authenticator to the request.
242 This is an HMAC-MD5 hash of the entire Access-Request packet (see RFC 3579).
243 This attribute must be present in any packet that includes an EAP-Message
245 It can be added by using the
246 .Fn rad_put_message_authentic
251 calculates the HMAC-MD5 hash implicitly before sending the request.
252 If the Message-Authenticator was found inside the response packet,
253 then the packet is silently dropped, if the validation failed.
254 In order to get this feature, the library should be compiled with
259 functions return 0 on success, or \-1 if an error occurs.
260 .Ss Sending the Request and Receiving the Response
261 After the RADIUS request has been constructed, it is sent either by means of
263 or by a combination of calls to
264 .Fn rad_init_send_request
266 .Fn rad_continue_send_request .
270 function sends the request and waits for a valid reply,
271 retrying the defined servers in round-robin fashion as necessary.
272 If a valid response is received,
274 returns the RADIUS code which specifies the type of the response.
275 This will typically be
276 .Dv RAD_ACCESS_ACCEPT ,
277 .Dv RAD_ACCESS_REJECT ,
279 .Dv RAD_ACCESS_CHALLENGE .
280 If no valid response is received,
284 As an alternative, if you do not wish to block waiting for a response,
285 .Fn rad_init_send_request
287 .Fn rad_continue_send_request
289 If a reply is received from the RADIUS server or a
290 timeout occurs, these functions return a value as described for
291 .Fn rad_send_request .
292 Otherwise, a value of zero is returned and the values pointed to by
296 are set to the descriptor and timeout that should be passed to
299 .Fn rad_init_send_request
300 must be called first, followed by repeated calls to
301 .Fn rad_continue_send_request
302 as long as a return value of zero is given.
303 Between each call, the application should call
307 as a read descriptor and timing out after the interval specified by
312 .Fn rad_continue_send_request
313 should be called with
315 set to a non-zero value if
317 indicated that the descriptor is readable.
319 Like RADIUS requests, each response may contain zero or more
321 After a response has been received successfully by
324 .Fn rad_continue_send_request ,
325 its attributes can be extracted one by one using
329 is called, it gets the next attribute from the current response, and
330 stores a pointer to the data and the length of the data via the
336 Note that the data resides in the response itself,
337 and must not be modified.
340 returns the RADIUS attribute type.
341 If no more attributes remain in the current response,
344 If an error such as a malformed attribute is detected, \-1 is
350 .Dv RAD_VENDOR_SPECIFIC ,
351 .Fn rad_get_vendor_attr
352 may be called to determine the vendor.
353 The vendor specific RADIUS attribute type is returned.
354 The reference parameters
361 .Fn rad_get_vendor_attr ,
362 and are adjusted to point to the vendor specific attribute data.
364 The common types of attributes can be decoded using
369 These functions accept a pointer to the attribute data, which should
370 have been obtained using
373 .Fn rad_get_vendor_attr .
379 These functions interpret the attribute as an
380 Internet address, an integer, or a string, respectively, and return
383 returns its value as a
384 .Dv NUL Ns -terminated
385 string in dynamically
387 The application should free the string using
389 when it is no longer needed.
391 If insufficient virtual memory is available,
401 .Fn rad_request_authenticator
402 function may be used to obtain the Request-Authenticator attribute value
403 associated with the current RADIUS server according to the supplied
409 must be supplied and should be at least 16 bytes.
410 The return value is the number of bytes written to
412 or \-1 to indicate that
414 was not large enough.
417 .Fn rad_server_secret
418 returns the secret shared with the current RADIUS server according to the
423 function demangles attributes containing passwords and MS-CHAPv1 MPPE-Keys.
426 on failure, or the plaintext attribute.
427 This value should be freed using
429 when it is no longer needed.
432 .Fn rad_demangle_mppe_key
433 function demangles the send- and recv-keys when using MPPE (see RFC 2548).
436 on failure, or the plaintext attribute.
437 This value should be freed using
439 when it is no longer needed.
440 .Ss Obtaining Error Messages
441 Those functions which accept a
442 .Vt "struct rad_handle *"
443 argument record an error message if they fail.
445 can be retrieved by calling
447 The message text is overwritten on each new error for the given
448 .Vt "struct rad_handle *" .
449 Thus the message must be copied if it is to be preserved through
450 subsequent library calls using the same handle.
452 To free the resources used by the RADIUS library, call
455 The following functions return a non-negative value on success.
457 they detect an error, they return \-1 and record an error message
458 which can be retrieved using
461 .Bl -item -offset indent -compact
467 .Fn rad_create_request
479 .Fn rad_put_message_authentic
481 .Fn rad_init_send_request
483 .Fn rad_continue_send_request
488 The following functions return a
491 If they are unable to allocate sufficient
492 virtual memory, they return
494 without recording an error message.
496 .Bl -item -offset indent -compact
505 The following functions return a
508 If they fail, they return
510 with recording an error message.
512 .Bl -item -offset indent -compact
516 .Fn rad_demangle_mppe_key
519 .Bl -tag -width indent
520 .It Pa /etc/radius.conf
525 .%A "C. Rigney, et al"
526 .%T "Remote Authentication Dial In User Service (RADIUS)"
531 .%T "RADIUS Accounting"
536 .%T "Microsoft Vendor-specific RADIUS attributes"
541 .%T "RADIUS extensions"
546 This software was originally written by
550 project by Juniper Networks, Inc.
552 subsequently added the ability to perform RADIUS
554 Later additions and changes by
555 .An Michael Bretterklieber .