1 .\" Copyright 1998 Juniper Networks, Inc.
2 .\" Copyright 2009 Alexander Motin <mav@FreeBSD.org>.
3 .\" All rights reserved.
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
8 .\" 1. Redistributions of source code must retain the above copyright
9 .\" notice, this list of conditions and the following disclaimer.
10 .\" 2. Redistributions in binary form must reproduce the above copyright
11 .\" notice, this list of conditions and the following disclaimer in the
12 .\" documentation and/or other materials provided with the distribution.
14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
15 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
16 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
17 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
18 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
19 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
20 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
21 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
22 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
23 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
33 .Nd RADIUS client/server library
36 .Ft "struct rad_handle *"
37 .Fn rad_acct_open "void"
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"
43 .Fn rad_close "struct rad_handle *h"
45 .Fn rad_config "struct rad_handle *h" "const char *file"
47 .Fn rad_continue_send_request "struct rad_handle *h" "int selected" "int *fd" "struct timeval *tv"
49 .Fn rad_create_request "struct rad_handle *h" "int code"
51 .Fn rad_create_response "struct rad_handle *h" "int code"
53 .Fn rad_cvt_addr "const void *data"
55 .Fn rad_cvt_int "const void *data"
57 .Fn rad_cvt_string "const void *data" "size_t len"
59 .Fn rad_get_attr "struct rad_handle *h" "const void **data" "size_t *len"
61 .Fn rad_get_vendor_attr "uint32_t *vendor" "const void **data" "size_t *len"
63 .Fn rad_init_send_request "struct rad_handle *h" "int *fd" "struct timeval *tv"
65 .Fn rad_put_addr "struct rad_handle *h" "int type" "struct in_addr addr"
67 .Fn rad_put_attr "struct rad_handle *h" "int type" "const void *data" "size_t len"
69 .Fn rad_put_int "struct rad_handle *h" "int type" "uint32_t value"
71 .Fn rad_put_string "struct rad_handle *h" "int type" "const char *str"
73 .Fn rad_put_message_authentic "struct rad_handle *h"
75 .Fn rad_put_vendor_addr "struct rad_handle *h" "int vendor" "int type" "struct in_addr addr"
77 .Fn rad_put_vendor_attr "struct rad_handle *h" "int vendor" "int type" "const void *data" "size_t len"
79 .Fn rad_put_vendor_int "struct rad_handle *h" "int vendor" "int type" "uint32_t value"
81 .Fn rad_put_vendor_string "struct rad_handle *h" "int vendor" "int type" "const char *str"
83 .Fn rad_request_authenticator "struct rad_handle *h" "char *buf" "size_t len"
85 .Fn rad_receive_request "struct rad_handle *h"
87 .Fn rad_send_request "struct rad_handle *h"
89 .Fn rad_send_response "struct rad_handle *h"
90 .Ft "struct rad_handle *"
91 .Fn rad_server_open "int fd"
93 .Fn rad_server_secret "struct rad_handle *h"
95 .Fn rad_bind_to "struct rad_handle *h" "in_addr_t addr"
97 .Fn rad_demangle "struct rad_handle *h" "const void *mangled" "size_t mlen"
99 .Fn rad_demangle_mppe_key "struct rad_handle *h" "const void *mangled" "size_t mlen" "size_t *len"
101 .Fn rad_strerror "struct rad_handle *h"
105 library implements the Remote Authentication Dial In User Service (RADIUS).
106 RADIUS, defined in RFCs 2865 and 2866,
107 allows clients to perform authentication and accounting by means of
108 network requests to remote servers.
110 To use the library, an application must first call
117 .Vt "struct rad_handle *" ,
118 which provides the context for subsequent operations.
119 The former function is used for RADIUS authentication and the
120 latter is used for RADIUS accounting.
127 always succeed unless insufficient virtual memory is available.
129 the necessary memory cannot be allocated, the functions return
131 For compatibility with earlier versions of this library,
133 is provided as a synonym for
136 Before issuing any RADIUS requests, the library must be made aware
137 of the servers it can contact.
138 The easiest way to configure the
142 causes the library to read a configuration file whose format is
145 The pathname of the configuration file is passed as the
149 This argument may also be given as
151 in which case the standard configuration file
155 returns 0 on success, or \-1 if an error occurs.
157 The library can also be configured programmatically by calls to
161 parameter specifies the server host, either as a fully qualified
162 domain name or as a dotted-quad IP address in text form.
165 parameter specifies the UDP port to contact on the server.
168 is given as 0, the library looks up the
172 service in the network
174 database, and uses the port found
176 If no entry is found, the library uses the standard RADIUS
177 ports, 1812 for authentication and 1813 for accounting.
178 The shared secret for the server host is passed to the
182 .Dv NUL Ns -terminated
185 ignores all but the leading 128 bytes of the shared secret.
186 The timeout for receiving replies from the server is passed to the
188 parameter, in units of seconds.
189 The maximum number of repeated
190 requests to make before giving up is passed into the
194 returns 0 on success, or \-1 if an error occurs.
197 may be called multiple times, and it may be used together with
199 At most 10 servers may be specified.
200 When multiple servers are given, they are tried in round-robin
201 fashion until a valid response is received, or until each server's
203 limit has been reached.
204 .Ss Creating a RADIUS Request
205 A RADIUS request consists of a code specifying the kind of request,
206 and zero or more attributes which provide additional information.
208 begin constructing a new request, call
209 .Fn rad_create_request .
210 In addition to the usual
211 .Vt "struct rad_handle *" ,
212 this function takes a
214 parameter which specifies the type of the request.
217 .Dv RAD_ACCESS_REQUEST .
218 .Fn rad_create_request
219 returns 0 on success, or \-1 on if an error occurs.
221 After the request has been created with
222 .Fn rad_create_request ,
223 attributes can be attached to it.
224 This is done through calls to
231 parameter identifying the attribute, and a value which may be
232 an Internet address, an integer, or a
233 .Dv NUL Ns -terminated
237 .Fn rad_put_vendor_addr ,
238 .Fn rad_put_vendor_int
240 .Fn rad_put_vendor_string
241 may be used to specify vendor specific attributes.
243 definitions may be found in
246 The library also provides a function
248 which can be used to supply a raw, uninterpreted attribute.
251 argument points to an array of bytes, and the
253 argument specifies its length.
255 It is possible adding the Message-Authenticator to the request.
256 This is an HMAC-MD5 hash of the entire Access-Request packet (see RFC 3579).
257 This attribute must be present in any packet that includes an EAP-Message
259 It can be added by using the
260 .Fn rad_put_message_authentic
265 calculates the HMAC-MD5 hash implicitly before sending the request.
266 If the Message-Authenticator was found inside the response packet,
267 then the packet is silently dropped, if the validation failed.
268 In order to get this feature, the library should be compiled with
273 functions return 0 on success, or \-1 if an error occurs.
274 .Ss Sending the Request and Receiving the Response
275 After the RADIUS request has been constructed, it is sent either by means of
277 or by a combination of calls to
278 .Fn rad_init_send_request
280 .Fn rad_continue_send_request .
284 function sends the request and waits for a valid reply,
285 retrying the defined servers in round-robin fashion as necessary.
286 If a valid response is received,
288 returns the RADIUS code which specifies the type of the response.
289 This will typically be
290 .Dv RAD_ACCESS_ACCEPT ,
291 .Dv RAD_ACCESS_REJECT ,
293 .Dv RAD_ACCESS_CHALLENGE .
294 If no valid response is received,
298 As an alternative, if you do not wish to block waiting for a response,
299 .Fn rad_init_send_request
301 .Fn rad_continue_send_request
303 If a reply is received from the RADIUS server or a
304 timeout occurs, these functions return a value as described for
305 .Fn rad_send_request .
306 Otherwise, a value of zero is returned and the values pointed to by
310 are set to the descriptor and timeout that should be passed to
313 .Fn rad_init_send_request
314 must be called first, followed by repeated calls to
315 .Fn rad_continue_send_request
316 as long as a return value of zero is given.
317 Between each call, the application should call
321 as a read descriptor and timing out after the interval specified by
326 .Fn rad_continue_send_request
327 should be called with
329 set to a non-zero value if
331 indicated that the descriptor is readable.
333 Like RADIUS requests, each response may contain zero or more
335 After a response has been received successfully by
338 .Fn rad_continue_send_request ,
339 its attributes can be extracted one by one using
343 is called, it gets the next attribute from the current response, and
344 stores a pointer to the data and the length of the data via the
350 Note that the data resides in the response itself,
351 and must not be modified.
354 returns the RADIUS attribute type.
355 If no more attributes remain in the current response,
358 If an error such as a malformed attribute is detected, \-1 is
364 .Dv RAD_VENDOR_SPECIFIC ,
365 .Fn rad_get_vendor_attr
366 may be called to determine the vendor.
367 The vendor specific RADIUS attribute type is returned.
368 The reference parameters
375 .Fn rad_get_vendor_attr ,
376 and are adjusted to point to the vendor specific attribute data.
378 The common types of attributes can be decoded using
383 These functions accept a pointer to the attribute data, which should
384 have been obtained using
387 .Fn rad_get_vendor_attr .
393 These functions interpret the attribute as an
394 Internet address, an integer, or a string, respectively, and return
397 returns its value as a
398 .Dv NUL Ns -terminated
399 string in dynamically
401 The application should free the string using
403 when it is no longer needed.
405 If insufficient virtual memory is available,
415 .Fn rad_request_authenticator
416 function may be used to obtain the Request-Authenticator attribute value
417 associated with the current RADIUS server according to the supplied
423 must be supplied and should be at least 16 bytes.
424 The return value is the number of bytes written to
426 or \-1 to indicate that
428 was not large enough.
431 .Fn rad_server_secret
432 returns the secret shared with the current RADIUS server according to the
437 assigns a source address for all requests to the current RADIUS server.
441 function demangles attributes containing passwords and MS-CHAPv1 MPPE-Keys.
444 on failure, or the plaintext attribute.
445 This value should be freed using
447 when it is no longer needed.
450 .Fn rad_demangle_mppe_key
451 function demangles the send- and recv-keys when using MPPE (see RFC 2548).
454 on failure, or the plaintext attribute.
455 This value should be freed using
457 when it is no longer needed.
458 .Ss Obtaining Error Messages
459 Those functions which accept a
460 .Vt "struct rad_handle *"
461 argument record an error message if they fail.
463 can be retrieved by calling
465 The message text is overwritten on each new error for the given
466 .Vt "struct rad_handle *" .
467 Thus the message must be copied if it is to be preserved through
468 subsequent library calls using the same handle.
470 To free the resources used by the RADIUS library, call
473 Server mode operates much alike to client mode, except packet send and receive
474 steps are swapped. To operate as server you should obtain server context with
476 function, passing opened and bound UDP socket file descriptor as argument.
477 You should define allowed clients and their secrets using
479 function. port, timeout and max_tries arguments are ignored in server mode.
481 .Fn rad_receive_request
482 function to receive request from client. If you do not want to block on socket
483 read, you are free to use any poll(), select() or non-blocking sockets for
485 Received request can be parsed with same parsing functions as for client.
486 To respond to the request you should call
487 .Fn rad_create_response
488 and fill response content with same packet writing functions as for client.
489 When packet is ready, it should be sent with
490 .Fn rad_send_response
492 The following functions return a non-negative value on success.
494 they detect an error, they return \-1 and record an error message
495 which can be retrieved using
498 .Bl -item -offset indent -compact
504 .Fn rad_create_request
506 .Fn rad_create_response
518 .Fn rad_put_message_authentic
520 .Fn rad_init_send_request
522 .Fn rad_continue_send_request
526 .Fn rad_send_response
529 The following functions return a
532 If they are unable to allocate sufficient
533 virtual memory, they return
535 without recording an error message.
537 .Bl -item -offset indent -compact
548 The following functions return a
551 If they fail, they return
553 with recording an error message.
555 .Bl -item -offset indent -compact
559 .Fn rad_demangle_mppe_key
562 .Bl -tag -width indent
563 .It Pa /etc/radius.conf
568 .%A "C. Rigney, et al"
569 .%T "Remote Authentication Dial In User Service (RADIUS)"
574 .%T "RADIUS Accounting"
579 .%T "Microsoft Vendor-specific RADIUS attributes"
584 .%T "RADIUS extensions"
589 This software was originally written by
593 project by Juniper Networks, Inc.
595 subsequently added the ability to perform RADIUS
597 Later additions and changes by
598 .An Michael Bretterklieber .
599 Server mode support was added by
600 .An Alexander Motin .