Copyright [C] The Regents of the University of Michigan and Merit Network, Inc. 1993, 1994, 1995, 1996, 1997 All Rights Reserved. Authentication/Authorization Transfer Vector (AATV) Existing versions of RADIUS servers have used ad hoc methods to obtain authentication credentials for requests originating at a Network Access Server (NAS) client. Early versions performed a simple table lookup in a local "users" database -- essentially a flat file database. Eventually this was extended into fetching passwords on the (default) UNIX host which was running the RADIUS server. Both of these methods did not scale well, although both are extremely popular and adequate in many cases. The Merit extensions added a complex source module to allow for multiple kinds of authentication types (e.g., Kerberos) including the relaying of (proxy) authentication requests to other RADIUS servers reachable over the network. However, adding a new authentication type to the Merit AAA server became a painful and expert level activity. At the requests of several individuals, Merit has added an authentication/authorization Applications Programming Interface (or API). This API is suitable for handling requests of other types than just authentication/authorization. In fact, it is now possible to have a request travel through several "phases" of this API on its journey from the NAS client, into the Merit AAA server and back to the NAS client. It was felt a modular approach would make the code more manageable and more understandable. It also would allow the addition of new authentication types to become an independent and constrained activity no longer requiring the services of "expert" RADIUS programmers. It will also permit different vendors to attach proprietary authentication/authorization/accounting engines in a hopefully portable and standard fashion. The resulting extensions, here called AATV for Authentication/Authorization Transfer Vector, provide the required modularity and eliminate any global name space pollution. Some prefer to think of the modularity made possible by the AATV as an object oriented mechanism (without using C++) while others think of the various client modules as simple black boxes having only one public symbol and one or more local (static) procedures for handling the actual work load. The transfer vector derives from a public structure which is described below. Basically it is an array of several function pointers and a few associated flags used to inform the Merit AAA server about the type of processing needed to perform the given function (e.g., whether sockets or process creation, or neither, are used to maintain a good response time for incoming requests). The "black box" contains an initialization function (think "constructor" for C++) and a workhorse function (method) which implements the actual body of the module's processing algorithm (here called the "action" function). The "cleanup", "recv" and "timer" methods are optional. An integer variable is available to hold the file descriptor for a socket (if needed). The three remaining fields are just overhead to tell the Merit AAA server how to invoke and control the AATV client module should an incoming request match the type of the module. The AATV concept is integral to the use of a Finite State Machine (FSM) in the Merit AAA server. See the related FSM documentation for more information on this subject. The AATV structure (think class in C++) describes the "public interface" or protocol of the client module. These methods (when present) are private to the AATV module (in the strict C++ sense). The Merit AAA server maintains an array of these AATV structure pointers and uses that array to select which module matches the incoming authentication (or authorization or accounting) request. So, now, here is the formal description of the AATV structure: typedef struct aatv { u_char id[32]; char authen_type; u_char aatvfunc_type; void (*init) PROTO((struct aatv *)); int (*timer) PROTO((void)); int (*act_func) PROTO((AUTH_REQ *, int, char *)); AUTH_REQ * (*recv) PROTO((struct sockaddr_in *, UINT4, u_int, EV *)); void (*cleanup) PROTO((void)); int sockfd; u_short process_statistics[5]; time_t timing_statistics[3]; PROC_ENT *proc_q; } AATV; Where: The "id" field is an unsigned character array containing the unique ASCII name for this particular AATV. No more than one AATV having this name may be present in the AATV array in the Merit AAA server. The "authen_type" field is a character containing the numerical type code as defined in the "dictionary" file (REALM, MIT-KRB, TACACS, UNIX-PW, etc.) or "-1" for several built-in types. The "aatvfunc_type" field indicates to the Merit AAA server how a given AATV module deals with flow blocking and how the Merit AAA server should process these types of requests. This field is an unsigned character containing one of the following numbers: 0 (AA_DIRECT) - The AATV "act_func" function has a direct reply. This is the case when it is possible to perform the processing locally using table lookup or some computational means. This is simply a direct function call (and return) within the server running on the local host. 1 (AA_SOCKET) - The deferred reply is returned on a UDP socket for this type of AATV module. Presumably some sort of remote processing is required and the result is eventually returned by the remote host. 2 (AA_FORK) - This type of client spawns a process and informs the engine to expect a deferred reply. The reply is part of the exit status of the child process. 3 (AA_FREPLY) - This type is similar to the AA_FORK since it does fork, but it gets any reply on the standard server reply UDP socket (just like the AA_SOCKET type). The "init" field is a (possibly NULL) function pointer which points to the initialization function for this client module. It takes a pointer to an AATV typically to provide access to the socket file descriptor which would need to be initialized for type AA_SOCKET. The "timer" field is a (possibly NULL) function pointer which points to a timer function which will be called every second when a client request is pending. This allows the AATV module to do some general purpose timing functions, but is not normally necessary. The "act_func" field is a function pointer which points to the main processing function for this AATV module. It is this function which "does all the work" corresponding to the given request. The "action" function has arguments for an AUTH_REQ pointer, integer and a string. The integer and string are just general purpose arguments which the action function may or may not need. All action functions need and use the AUTH_REQ pointer which grants them access to the engine's global queue of request data structures. This structure contains everything there is to know about the current (outstanding) request. Each action function returns the results of its execution in a small integer valued return code. A list of these "events" is given below. The "recv" field is a (possibly NULL) function pointer which points to a receiving function (if needed) to receive packets from a socket. The engine will hand off received packets to this function when it receives them and will determine which function to call based on the socket upon which it arrived. The first argument carries information about the originating socket, the second argument contains the IP address of the sender, the third argument is the number of octets received by the engine and the last argument is an EVENT_ENT pointer. The receive function builds an AUTH_REQ structure and populates it. It also returns an "event" for the FSM using the EVENT_ENT pointer. The "cleanup" field is a (possibly NULL) pointer to a function which is used to perform any post-processing or clean up type activities (if necessary) for this AATV module (think "destructor" for C++). The "sockfd" field is an integer containing the file descriptor for this AATV module (if it is an AA_SOCKET type). The process_statistics fields are used to keep track of forking type AATV modules (AA_FORK and AA_FREPLY) and may be used to track and control the number of outstanding forked processes (children). The timing_statistics fields are used to identify when the various process_statistics fields described above transitioned or reached their current value(s). The flow of data through the Merit AAA server normally begins on a well-known socket and is then handed off to one of (perhaps) several AATV modules for processing. From these modules, the request may be satisfied locally or relayed off the local host for further processing. Eventually, the request is satisfied in either a positive, or negative sense, and the Merit AAA server returns an acknowledgement, or a negative acknowledgement, to the NAS (RADIUS client), respectively. A list of exemplary AATV names is given below. Several different "utility" AATV concepts have been identified and made part of the Merit AAA server, for developers' convenience. The TIMER AATV sets a timer interval to an initial value. The END AATV terminates the FSM for this request. The LOG AATV is used to log an error condition. The REPLY AATV is used to do whatever is needed to issue the reply or response to the original request. The TIMEOUT AATV logs the fact that a request on the global queue has timed out. Exemplary List of Event Names and Their Meaning ACK acknowledgment of the previous action NAK negative acknowledgment of the previous action WAIT the previous action generated a pending event ERROR the previous action generated an error FATAL the previous action generated a fatal error DUP the incoming request is a duplicate TIMER the timer value has expired TIMEOUT the request has timed out due to inactivity AUTHEN the incoming request is an Access-Request ACCT the incoming request is an Accounting-Request PASSWD the incoming request is a Passwd-Request REACCESS the incoming request is is an Access-Request with State ACC_CHAL the incoming request is and Access-Challenge MGT_POLL the incoming request is is a Status-Server AUTH_ONLY the incoming request is for Authentication-Only ACCT_START the incoming request is an Accounting Start ACCT_STOP the incoming request is an Accounting Stop RC1 general purpose return code of one RC2 general purpose return code of two RC3 general purpose return code of three RC4 general purpose return code of four RC5 general purpose return code of five RC6 general purpose return code of six RC7 general purpose return code of seven RC8 general purpose return code of eight RC9 general purpose return code of nine RC10 general purpose return code of ten Exemplary List of AATV Names and Their Purpose ACCT the AATV for Accounting requests ACK utility AATV used to always signify success AKERB the AATV for AFS Kerberos Authentication AUTHENTICATE the AATV for Authentication requests CLEANUP utility AATV used to exit the FSM FILE the AATV for FILE Authentication KCHAP the AATV for KCHAP Authentication KILL utility AATV used to unconditionally remove pending events LOG utility AATV used to log some error MKERB the AATV for MIT Kerberos Authentication NULL utility NULL AATV PASSWD the AATV for Passwd requests PENDING utility AATV used to test for pending events RAD2RAD the AATV used to send (relay) RADIUS proxy requests RADDNS the AATV for resolving DNS names RADIUS the main AATV in the Merit AAA server REALM the AATV for handling realm based Authentication REDO utility AATV used to re-invoke an action REPLY utility AATV used to send a RADIUS reply SRV_STATUS the AATV for Status-Server (Management-Poll) requests TACACS the AATV for TACACS Authentication TIMEOUT utility AATV used to do timeout logging TIMER utility AATV used to initialize the timeout value UNIX-PW the AATV for for UNIX password file Authentication