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
116 .Vt "struct rad_handle *" ,
117 which provides the context for subsequent operations.
118 The former function is used for RADIUS authentication and the
119 latter is used for RADIUS accounting.
125 always succeed unless insufficient virtual memory is available.
127 the necessary memory cannot be allocated, the functions return
129 For compatibility with earlier versions of this library,
131 is provided as a synonym for
134 Before issuing any RADIUS requests, the library must be made aware
135 of the servers it can contact.
136 The easiest way to configure the
140 causes the library to read a configuration file whose format is
143 The pathname of the configuration file is passed as the
147 This argument may also be given as
149 in which case the standard configuration file
153 returns 0 on success, or \-1 if an error occurs.
155 The library can also be configured programmatically by calls to
159 parameter specifies the server host, either as a fully qualified
160 domain name or as a dotted-quad IP address in text form.
163 parameter specifies the UDP port to contact on the server.
166 is given as 0, the library looks up the
170 service in the network
172 database, and uses the port found
174 If no entry is found, the library uses the standard RADIUS
175 ports, 1812 for authentication and 1813 for accounting.
176 The shared secret for the server host is passed to the
180 .Dv NUL Ns -terminated
183 ignores all but the leading 128 bytes of the shared secret.
184 The timeout for receiving replies from the server is passed to the
186 parameter, in units of seconds.
187 The maximum number of repeated
188 requests to make before giving up is passed into the
192 returns 0 on success, or \-1 if an error occurs.
195 may be called multiple times, and it may be used together with
197 At most 10 servers may be specified.
198 When multiple servers are given, they are tried in round-robin
199 fashion until a valid response is received, or until each server's
201 limit has been reached.
202 .Ss Creating a RADIUS Request
203 A RADIUS request consists of a code specifying the kind of request,
204 and zero or more attributes which provide additional information.
206 begin constructing a new request, call
207 .Fn rad_create_request .
208 In addition to the usual
209 .Vt "struct rad_handle *" ,
210 this function takes a
212 parameter which specifies the type of the request.
215 .Dv RAD_ACCESS_REQUEST .
216 .Fn rad_create_request
217 returns 0 on success, or \-1 on if an error occurs.
219 After the request has been created with
220 .Fn rad_create_request ,
221 attributes can be attached to it.
222 This is done through calls to
229 parameter identifying the attribute, and a value which may be
230 an Internet address, an integer, or a
231 .Dv NUL Ns -terminated
235 .Fn rad_put_vendor_addr ,
236 .Fn rad_put_vendor_int
238 .Fn rad_put_vendor_string
239 may be used to specify vendor specific attributes.
241 definitions may be found in
244 The library also provides a function
246 which can be used to supply a raw, uninterpreted attribute.
249 argument points to an array of bytes, and the
251 argument specifies its length.
253 It is possible adding the Message-Authenticator to the request.
254 This is an HMAC-MD5 hash of the entire Access-Request packet (see RFC 3579).
255 This attribute must be present in any packet that includes an EAP-Message
257 It can be added by using the
258 .Fn rad_put_message_authentic
263 calculates the HMAC-MD5 hash implicitly before sending the request.
264 If the Message-Authenticator was found inside the response packet,
265 then the packet is silently dropped, if the validation failed.
266 In order to get this feature, the library should be compiled with
271 functions return 0 on success, or \-1 if an error occurs.
272 .Ss Sending the Request and Receiving the Response
273 After the RADIUS request has been constructed, it is sent either by means of
275 or by a combination of calls to
276 .Fn rad_init_send_request
278 .Fn rad_continue_send_request .
282 function sends the request and waits for a valid reply,
283 retrying the defined servers in round-robin fashion as necessary.
284 If a valid response is received,
286 returns the RADIUS code which specifies the type of the response.
287 This will typically be
288 .Dv RAD_ACCESS_ACCEPT ,
289 .Dv RAD_ACCESS_REJECT ,
291 .Dv RAD_ACCESS_CHALLENGE .
292 If no valid response is received,
296 As an alternative, if you do not wish to block waiting for a response,
297 .Fn rad_init_send_request
299 .Fn rad_continue_send_request
301 If a reply is received from the RADIUS server or a
302 timeout occurs, these functions return a value as described for
303 .Fn rad_send_request .
304 Otherwise, a value of zero is returned and the values pointed to by
308 are set to the descriptor and timeout that should be passed to
311 .Fn rad_init_send_request
312 must be called first, followed by repeated calls to
313 .Fn rad_continue_send_request
314 as long as a return value of zero is given.
315 Between each call, the application should call
319 as a read descriptor and timing out after the interval specified by
324 .Fn rad_continue_send_request
325 should be called with
327 set to a non-zero value if
329 indicated that the descriptor is readable.
331 Like RADIUS requests, each response may contain zero or more
333 After a response has been received successfully by
336 .Fn rad_continue_send_request ,
337 its attributes can be extracted one by one using
341 is called, it gets the next attribute from the current response, and
342 stores a pointer to the data and the length of the data via the
348 Note that the data resides in the response itself,
349 and must not be modified.
352 returns the RADIUS attribute type.
353 If no more attributes remain in the current response,
356 If an error such as a malformed attribute is detected, \-1 is
362 .Dv RAD_VENDOR_SPECIFIC ,
363 .Fn rad_get_vendor_attr
364 may be called to determine the vendor.
365 The vendor specific RADIUS attribute type is returned.
366 The reference parameters
373 .Fn rad_get_vendor_attr ,
374 and are adjusted to point to the vendor specific attribute data.
376 The common types of attributes can be decoded using
381 These functions accept a pointer to the attribute data, which should
382 have been obtained using
385 .Fn rad_get_vendor_attr .
391 These functions interpret the attribute as an
392 Internet address, an integer, or a string, respectively, and return
395 returns its value as a
396 .Dv NUL Ns -terminated
397 string in dynamically
399 The application should free the string using
401 when it is no longer needed.
403 If insufficient virtual memory is available,
413 .Fn rad_request_authenticator
414 function may be used to obtain the Request-Authenticator attribute value
415 associated with the current RADIUS server according to the supplied
421 must be supplied and should be at least 16 bytes.
422 The return value is the number of bytes written to
424 or \-1 to indicate that
426 was not large enough.
429 .Fn rad_server_secret
430 returns the secret shared with the current RADIUS server according to the
435 assigns a source address for all requests to the current RADIUS server.
439 function demangles attributes containing passwords and MS-CHAPv1 MPPE-Keys.
442 on failure, or the plaintext attribute.
443 This value should be freed using
445 when it is no longer needed.
448 .Fn rad_demangle_mppe_key
449 function demangles the send- and recv-keys when using MPPE (see RFC 2548).
452 on failure, or the plaintext attribute.
453 This value should be freed using
455 when it is no longer needed.
456 .Ss Obtaining Error Messages
457 Those functions which accept a
458 .Vt "struct rad_handle *"
459 argument record an error message if they fail.
461 can be retrieved by calling
463 The message text is overwritten on each new error for the given
464 .Vt "struct rad_handle *" .
465 Thus the message must be copied if it is to be preserved through
466 subsequent library calls using the same handle.
468 To free the resources used by the RADIUS library, call
471 Server mode operates much alike to client mode, except packet send and receive
472 steps are swapped. To operate as server you should obtain server context with
474 function, passing opened and bound UDP socket file descriptor as argument.
475 You should define allowed clients and their secrets using
477 function. port, timeout and max_tries arguments are ignored in server mode.
479 .Fn rad_receive_request
480 function to receive request from client. If you do not want to block on socket
481 read, you are free to use any poll(), select() or non-blocking sockets for
483 Received request can be parsed with same parsing functions as for client.
484 To respond to the request you should call
485 .Fn rad_create_response
486 and fill response content with same packet writing functions as for client.
487 When packet is ready, it should be sent with
488 .Fn rad_send_response .
490 The following functions return a non-negative value on success.
492 they detect an error, they return \-1 and record an error message
493 which can be retrieved using
496 .Bl -item -offset indent -compact
502 .Fn rad_create_request
504 .Fn rad_create_response
516 .Fn rad_put_message_authentic
518 .Fn rad_init_send_request
520 .Fn rad_continue_send_request
524 .Fn rad_send_response
527 The following functions return a
530 If they are unable to allocate sufficient
531 virtual memory, they return
533 without recording an error message.
535 .Bl -item -offset indent -compact
546 The following functions return a
549 If they fail, they return
551 with recording an error message.
553 .Bl -item -offset indent -compact
557 .Fn rad_demangle_mppe_key
560 .Bl -tag -width indent
561 .It Pa /etc/radius.conf
566 .%A "C. Rigney, et al"
567 .%T "Remote Authentication Dial In User Service (RADIUS)"
572 .%T "RADIUS Accounting"
577 .%T "Microsoft Vendor-specific RADIUS attributes"
582 .%T "RADIUS extensions"
587 This software was originally written by
591 project by Juniper Networks, Inc.
593 subsequently added the ability to perform RADIUS
595 Later additions and changes by
596 .An Michael Bretterklieber .
597 Server mode support was added by
598 .An Alexander Motin .