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"
41 .Fn rad_add_server_ex "struct rad_handle *h" "const char *host" "int port" "const char *secret" "int timeout" "int max_tries" "int dead_time" "struct in_addr *bindto"
42 .Ft "struct rad_handle *"
43 .Fn rad_auth_open "void"
45 .Fn rad_close "struct rad_handle *h"
47 .Fn rad_config "struct rad_handle *h" "const char *file"
49 .Fn rad_continue_send_request "struct rad_handle *h" "int selected" "int *fd" "struct timeval *tv"
51 .Fn rad_create_request "struct rad_handle *h" "int code"
53 .Fn rad_create_response "struct rad_handle *h" "int code"
55 .Fn rad_cvt_addr "const void *data"
57 .Fn rad_cvt_int "const void *data"
59 .Fn rad_cvt_string "const void *data" "size_t len"
61 .Fn rad_get_attr "struct rad_handle *h" "const void **data" "size_t *len"
63 .Fn rad_get_vendor_attr "uint32_t *vendor" "const void **data" "size_t *len"
65 .Fn rad_init_send_request "struct rad_handle *h" "int *fd" "struct timeval *tv"
67 .Fn rad_put_addr "struct rad_handle *h" "int type" "struct in_addr addr"
69 .Fn rad_put_attr "struct rad_handle *h" "int type" "const void *data" "size_t len"
71 .Fn rad_put_int "struct rad_handle *h" "int type" "uint32_t value"
73 .Fn rad_put_string "struct rad_handle *h" "int type" "const char *str"
75 .Fn rad_put_message_authentic "struct rad_handle *h"
77 .Fn rad_put_vendor_addr "struct rad_handle *h" "int vendor" "int type" "struct in_addr addr"
79 .Fn rad_put_vendor_attr "struct rad_handle *h" "int vendor" "int type" "const void *data" "size_t len"
81 .Fn rad_put_vendor_int "struct rad_handle *h" "int vendor" "int type" "uint32_t value"
83 .Fn rad_put_vendor_string "struct rad_handle *h" "int vendor" "int type" "const char *str"
85 .Fn rad_request_authenticator "struct rad_handle *h" "char *buf" "size_t len"
87 .Fn rad_receive_request "struct rad_handle *h"
89 .Fn rad_send_request "struct rad_handle *h"
91 .Fn rad_send_response "struct rad_handle *h"
92 .Ft "struct rad_handle *"
93 .Fn rad_server_open "int fd"
95 .Fn rad_server_secret "struct rad_handle *h"
97 .Fn rad_bind_to "struct rad_handle *h" "in_addr_t addr"
99 .Fn rad_demangle "struct rad_handle *h" "const void *mangled" "size_t mlen"
101 .Fn rad_demangle_mppe_key "struct rad_handle *h" "const void *mangled" "size_t mlen" "size_t *len"
103 .Fn rad_strerror "struct rad_handle *h"
107 library implements the Remote Authentication Dial In User Service (RADIUS).
108 RADIUS, defined in RFCs 2865 and 2866,
109 allows clients to perform authentication and accounting by means of
110 network requests to remote servers.
112 To use the library, an application must first call
118 .Vt "struct rad_handle *" ,
119 which provides the context for subsequent operations.
120 The former function is used for RADIUS authentication and the
121 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
160 .Fn rad_add_server_ex .
162 is a backward compatible function, implemented via
163 .Fn rad_add_server_ex .
166 parameter specifies the server host, either as a fully qualified
167 domain name or as a dotted-quad IP address in text form.
170 parameter specifies the UDP port to contact on the server.
173 is given as 0, the library looks up the
177 service in the network
179 database, and uses the port found
181 If no entry is found, the library uses the standard RADIUS
182 ports, 1812 for authentication and 1813 for accounting.
183 The shared secret for the server host is passed to the
187 .Dv NUL Ns -terminated
190 ignores all but the leading 128 bytes of the shared secret.
191 The timeout for receiving replies from the server is passed to the
193 parameter, in units of seconds.
194 The maximum number of repeated
195 requests to make before giving up is passed into the
198 Time interval in seconds when the server will not be requested
199 if it is marked as dead (did not answer on the last try) set with
203 parameter is an IP address on the multihomed host that is used as
204 a source address for all requests.
206 returns 0 on success, or \-1 if an error occurs.
210 .Fn rad_add_server_ex
211 may be called multiple times, and they may be used together with
213 At most 10 servers may be specified.
214 When multiple servers are given, they are tried in round-robin
215 fashion until a valid response is received, or until each server's
217 limit has been reached.
218 .Ss Creating a RADIUS Request
219 A RADIUS request consists of a code specifying the kind of request,
220 and zero or more attributes which provide additional information.
222 begin constructing a new request, call
223 .Fn rad_create_request .
224 In addition to the usual
225 .Vt "struct rad_handle *" ,
226 this function takes a
228 parameter which specifies the type of the request.
231 .Dv RAD_ACCESS_REQUEST .
232 .Fn rad_create_request
233 returns 0 on success, or \-1 on if an error occurs.
235 After the request has been created with
236 .Fn rad_create_request ,
237 attributes can be attached to it.
238 This is done through calls to
245 parameter identifying the attribute, and a value which may be
246 an Internet address, an integer, or a
247 .Dv NUL Ns -terminated
251 .Fn rad_put_vendor_addr ,
252 .Fn rad_put_vendor_int
254 .Fn rad_put_vendor_string
255 may be used to specify vendor specific attributes.
257 definitions may be found in
260 The library also provides a function
262 which can be used to supply a raw, uninterpreted attribute.
265 argument points to an array of bytes, and the
267 argument specifies its length.
269 It is possible adding the Message-Authenticator to the request.
270 This is an HMAC-MD5 hash of the entire Access-Request packet (see RFC 3579).
271 This attribute must be present in any packet that includes an EAP-Message
273 It can be added by using the
274 .Fn rad_put_message_authentic
279 calculates the HMAC-MD5 hash implicitly before sending the request.
280 If the Message-Authenticator was found inside the response packet,
281 then the packet is silently dropped, if the validation failed.
282 In order to get this feature, the library should be compiled with
287 functions return 0 on success, or \-1 if an error occurs.
288 .Ss Sending the Request and Receiving the Response
289 After the RADIUS request has been constructed, it is sent either by means of
291 or by a combination of calls to
292 .Fn rad_init_send_request
294 .Fn rad_continue_send_request .
298 function sends the request and waits for a valid reply,
299 retrying the defined servers in round-robin fashion as necessary.
300 If a valid response is received,
302 returns the RADIUS code which specifies the type of the response.
303 This will typically be
304 .Dv RAD_ACCESS_ACCEPT ,
305 .Dv RAD_ACCESS_REJECT ,
307 .Dv RAD_ACCESS_CHALLENGE .
308 If no valid response is received,
312 As an alternative, if you do not wish to block waiting for a response,
313 .Fn rad_init_send_request
315 .Fn rad_continue_send_request
317 If a reply is received from the RADIUS server or a
318 timeout occurs, these functions return a value as described for
319 .Fn rad_send_request .
320 Otherwise, a value of zero is returned and the values pointed to by
324 are set to the descriptor and timeout that should be passed to
327 .Fn rad_init_send_request
328 must be called first, followed by repeated calls to
329 .Fn rad_continue_send_request
330 as long as a return value of zero is given.
331 Between each call, the application should call
335 as a read descriptor and timing out after the interval specified by
340 .Fn rad_continue_send_request
341 should be called with
343 set to a non-zero value if
345 indicated that the descriptor is readable.
347 Like RADIUS requests, each response may contain zero or more
349 After a response has been received successfully by
352 .Fn rad_continue_send_request ,
353 its attributes can be extracted one by one using
357 is called, it gets the next attribute from the current response, and
358 stores a pointer to the data and the length of the data via the
364 Note that the data resides in the response itself,
365 and must not be modified.
368 returns the RADIUS attribute type.
369 If no more attributes remain in the current response,
372 If an error such as a malformed attribute is detected, \-1 is
378 .Dv RAD_VENDOR_SPECIFIC ,
379 .Fn rad_get_vendor_attr
380 may be called to determine the vendor.
381 The vendor specific RADIUS attribute type is returned.
382 The reference parameters
389 .Fn rad_get_vendor_attr ,
390 and are adjusted to point to the vendor specific attribute data.
392 The common types of attributes can be decoded using
397 These functions accept a pointer to the attribute data, which should
398 have been obtained using
401 .Fn rad_get_vendor_attr .
407 These functions interpret the attribute as an
408 Internet address, an integer, or a string, respectively, and return
411 returns its value as a
412 .Dv NUL Ns -terminated
413 string in dynamically
415 The application should free the string using
417 when it is no longer needed.
419 If insufficient virtual memory is available,
429 .Fn rad_request_authenticator
430 function may be used to obtain the Request-Authenticator attribute value
431 associated with the current RADIUS server according to the supplied
437 must be supplied and should be at least 16 bytes.
438 The return value is the number of bytes written to
440 or \-1 to indicate that
442 was not large enough.
445 .Fn rad_server_secret
446 returns the secret shared with the current RADIUS server according to the
451 assigns a source address for all requests to the current RADIUS server.
455 function demangles attributes containing passwords and MS-CHAPv1 MPPE-Keys.
458 on failure, or the plaintext attribute.
459 This value should be freed using
461 when it is no longer needed.
464 .Fn rad_demangle_mppe_key
465 function demangles the send- and recv-keys when using MPPE (see RFC 2548).
468 on failure, or the plaintext attribute.
469 This value should be freed using
471 when it is no longer needed.
472 .Ss Obtaining Error Messages
473 Those functions which accept a
474 .Vt "struct rad_handle *"
475 argument record an error message if they fail.
477 can be retrieved by calling
479 The message text is overwritten on each new error for the given
480 .Vt "struct rad_handle *" .
481 Thus the message must be copied if it is to be preserved through
482 subsequent library calls using the same handle.
484 To free the resources used by the RADIUS library, call
487 Server mode operates much alike to client mode, except packet send and receive
489 To operate as server you should obtain server context with
491 function, passing opened and bound UDP socket file descriptor as argument.
492 You should define allowed clients and their secrets using
494 function. port, timeout and max_tries arguments are ignored in server mode.
496 .Fn rad_receive_request
497 function to receive request from client.
498 If you do not want to block on socket read, you are free to use any
499 poll(), select() or non-blocking sockets for the socket.
500 Received request can be parsed with same parsing functions as for client.
501 To respond to the request you should call
502 .Fn rad_create_response
503 and fill response content with same packet writing functions as for client.
504 When packet is ready, it should be sent with
505 .Fn rad_send_response .
507 The following functions return a non-negative value on success.
509 they detect an error, they return \-1 and record an error message
510 which can be retrieved using
513 .Bl -item -offset indent -compact
519 .Fn rad_create_request
521 .Fn rad_create_response
533 .Fn rad_put_message_authentic
535 .Fn rad_init_send_request
537 .Fn rad_continue_send_request
541 .Fn rad_send_response
544 The following functions return a
547 If they are unable to allocate sufficient
548 virtual memory, they return
550 without recording an error message.
552 .Bl -item -offset indent -compact
563 The following functions return a
566 If they fail, they return
568 with recording an error message.
570 .Bl -item -offset indent -compact
574 .Fn rad_demangle_mppe_key
577 .Bl -tag -width indent
578 .It Pa /etc/radius.conf
583 .%A "C. Rigney, et al"
584 .%T "Remote Authentication Dial In User Service (RADIUS)"
589 .%T "RADIUS Accounting"
594 .%T "Microsoft Vendor-specific RADIUS attributes"
599 .%T "RADIUS extensions"
604 This software was originally written by
608 project by Juniper Networks, Inc.
610 subsequently added the ability to perform RADIUS
612 Later additions and changes by
613 .An Michael Bretterklieber .
614 Server mode support was added by
615 .An Alexander Motin .