# $Id: $
# 

Generic AAA Protocol Interface
-------------------------------

Overview

 This is a generic interface for modules that want to use features provided
 by AAA protocols.
 The interface is independent of the underlying AAA protocol that implements
 it and it should be used by all modules that use AAA.
 
 The API architecture is based on the assumption that every AAA protocol uses 
 messages based on AVPs, since both Radius and Diameter, two of the current 
 AAA implementations, do that.
 
 
 
 
1 Data types

There are several new data types used by the API. All of them are defined in 
the header file aaa.h, a client must include the header file to be able to 
use them.


1.1 Type aaa_map

1.1.1 Description

This type represents a generic structure for an AVP.

1.1.2 Definition

typedef struct _aaa_map {
	char *name;
	int value;
} aaa_map;

1.1.3 Macros

There are no macros for this type.


1.2 Type aaa_message

1.2.1 Description

This type is a generic structure for a message sent or received by the AAA 
protocol. 
The fields of the structure have the following meaning:
avpair     : the list of AVPs contained by the message
last_found : a pointer in the list of AVPs used to store the last 
		element found by a search, this is needed by the 
		find function in case a AAA_GET_FROM_CURRENT type of 
		search is wanted
type 	   : the type of message (AAA_AUTH or AAA_ACCT)
	
1.2.2 Definition

typedef struct _aaa_message {
	void* avpair;
	void* last_found;
	int type;
} aaa_message;

1.2.3 Macros

For this type there are three macro's defined representing the allowed
types of messages:
AAA_AUTH : the message will be for authentication
AAA_ACCT : the message will be for accounting
AAA_RECV : the message will contain received information


1.3 Type aaa_conn

1.3.1 Description
	
This is a type definition for a generic AAA connection.
The implementation for a connection variable is protocol dependent.

1.3.2 Definition

typedef void aaa_conn;

1.3.3 Macros

There are no macros for this type.


1.4 Type aaa_prot

1.4.1 Description

This structure is a collection of callbacks provided by the modules
that implement this generic AAA interface.
A variable of this type will be filled when a bind call is made, and 
therefore it cannot be used before aaa_prot_bind.
	
1.4.2 Definition

typedef struct _aaa_prot {
	init_prot_f* 	   init_prot;		/*initializes a protocol implementation*/
	create_request_f*  create_aaa_request;	/*creates a request*/
	destroy_message_f* destroy_aaa_message;	/*destroys a message*/
	send_request_f*    send_aaa_request;	/*sends a request*/
	find_f* 	   dictionary_find;	/*searches a name in a dictionary*/
	avp_add_f* 	   avp_add;		/*adds a AVP to a message*/
	avp_get_f* 	   avp_get		/*gets the value of a AVP in a message*/
} aaa_prot;

1.4.3 Macros

There are no macros for this type.


1.5 Type aaa_prot_config

1.5.1 Description

Thsi type represents the configuration structure for an AAA protocol. 

The structure fields have the following meaning:
prot_name : the protocol name extracted from the URL
rest      : a pointer to the location of what is left of the URL string

The "rest" field can be used by the module that implements the
AAA interface as it pleases.

1.5.2 Definition

typedef struct _aaa_prot_config {
	str *prot_name;
	void *rest;
} aaa_prot_config;


1.6 Type aaa_bind_api_f

1.6.1 Description

1.6.2 Definition

typedef int (*aaa_bind_api_f)(aaa_prot*);


2 Functions


2.1 Callback prot.create_aaa_request

2.1.1 Description

This function creates a structure for a message.
The message can be a request, or a reply.

2.1.2 Prototype
typedef aaa_message* (create_request_f)(aaa_conn* ac, int f);

2.1.3 Parameters
The function takes two parameters:
ac: pointer to an AAA connection variable
f:  a flag representing the type of message (for authentication or accounting)

2.1.4 Return Value

The return value is a pointer to the AAA message structure, or NULL if error
occurred.


2.2 Callback prot.destroy_aaa_message

2.2.1 Description

This function destroys the AVP list contained by the message, and then
releases the memory allocated for the message.
The message can be a request or reply.

2.2.2 Prototype

typedef int (destroy_message_f)(aaa_conn* ac, aaa_message* mess);

2.2.3 Parameters

The function takes two parameters:
ac   : pointer to an AAA connection variable
mess : pointer to an AAA message variable

2.2.4 Return Value

The return value is an error code: 0 for succes, -1 for error.


2.3 Callback prot.send_aaa_request

2.3.1 Description

This function sends a message on a specified connection.

2.3.2 Prototype

typedef int (send_request_f)(aaa_conn* ac, aaa_message* send, aaa_message* recv);

2.3.3 Parameters

The function takes three parameters:
ac   : a pointer to an AAA connection variable
send : the address of a message to be sent
recv : the address of a message to be received (may be NULL)
	
2.3.4 Return Value

The return value is an error code: 0 for succes, -1 for error.


2.4 Callback prot.dictionary_find

2.4.1 Description

This function searches a certain value for a name in the dictionary of
AVPs loaded at protcol intialization.
The result is returned in the value field of the aaa_map structure.

2.4.2 Prototype
typedef int (find_f)(aaa_conn* ac, aaa_map* map, int flag);

2.4.3 Parameters

The function takes 3 parameters:
ac   : a pointer to an AAA connection variable
map  : a pointer to the aaa_map structure wich contains the name searched
flag : a flag representing the type of search wanted: for a value, 
	for an attribute or for a vendor dictionary entry.

The values allowed for the flag are the given by the following definitions:
AAA_DICT_FIND_VAL  : a value is searched
AAA_DICT_FIND_ATTR : an attribute is searched
AAA_DICT_FIND_VEND : a vendor entry is searched


2.4.4 Return Value

The return value is an error code: 0 if the name was found, 1 if the name was
not found, -1 for error.

2.5 Callback prot.avp_add

2.5.1 Description

This function adds a AVP to a specified AAA message.

2.5.2 Prototype
typedef int (avp_add_f)(aaa_conn* ac, aaa_message* mess, aaa_map* map, 
			 void* value, int length, int vendor);

2.5.3 Parameters
ac     : a pointer to an AAA connection variable
mess   : a pointer to the message where the AVP will be added
map    : a pointer to a map structure wich contains the name of the AVP to be added
value  : a pointer to the value to be added
length : the length of the value added
vendor : the vendorpec

Depending on the implementation, some of these values may be empty.

2.5.4 Return Value

The return value is an error code: 0 for succes, -1 for error.


2.6 Callback prot.avp_get

2.6.1 Description

This function gets a AVP from a specified AAA message.

2.6.2 Prototype

typedef int (avp_get_f)(aaa_conn* ac, aaa_message* mess, aaa_map* map, 
			 void** value, int* length, int flag);

2.6.3 Parameters

ac     : a pointer to an AAA connection variable
mess   : a pointer to the message where the AVP will be added
map    : a pointer to a map structure wich contains the name searched
value  : a pointer to the location where the value should be placed
length : a pointer to the location where the value length should be placed
flag   : a flag specifying the type of search in the AVPs list (from the start 
	 or from the current position)

There are two possible values for the flag:
AAA_GET_FROM_START : the search should start from the beginning of the AVPs list
AAA_GET_FROM_CURRENT : the search should start from the current search position

2.6.4 Return Value

The return value is an error code: 0 for succes, -1 for error.


2.7 Callback prot.init_prot

2.7.1 Description

This function initializes the protocol and returns a pointer to the
connection variable that represents it.

2.7.2 Prototype

typedef aaa_conn* (init_prot_f)(str* url);

2.7.3 Parameters

The function receives only one parameter:
url : a string that contains protocol dependent information needed to identify
	the module that implements the interface and other useful information

2.7.4 Return Value

The return value is a pointer to a connection variable, or NULL if error
occurred.


2.8 Function aaa_prot_bind

2.8.1 Description

This is the function called by a module that wishes to use animplementation 
for an AAA protocol.

2.8.2 Prototype

int aaa_prot_bind(str* url, aaa_prot* ap);

2.8.3 Parameters

url : the protocol URL.
ap  : where the structure for the protocol callback functions should be stored.

2.8.4 Return Value

The return value is an error code: 0 for succes, -1 for error.

2.9 Function aaa_parse_url

2.9.1 Description
This function parses a string representing the URL given through the
configuration file and returns a configuration structure for the
protocol implementation.

An example for a URL for an AAA Radius Module is:
"radius:/etc/radiusclient-ng/radiusclient.conf"

2.9.2 Prototype
int aaa_parse_url(str* url, aaa_prot_config* protcfg);

2.9.3 Parameters
url 	: the string for the url
protcfg : pointer to the configuration structure resulted

2.9.4 Return Value
The return value is an error code: 0 for succes, -1 for error.


3 Other useful information

3.1 Useful Macros


3.1.1 INIT_AV Macro

3.1.1.1 Description

This macro initializes two arrays of AVPs with the corresponding
information from the protocol dictionary.
The first array needs to be filled with the corresponding information
for some given attributes, and the second array, for some given values.

3.1.1.2 Prototype

#define INIT_AV(ap, rh, at, nr_at, vl, nr_vl, fn, e1, e2)

3.1.1.2 Parameters
ap    : the aaa protocol
rh    : the aaa connection handle
at    : array of attributes
nr_at : number of attributes
vl    : array of values
nr_vl : number of values
fn    : the name of the function that calls this macro
e1    : error code 1
e2    : error code 2
