	RADIUS Authentication Modules
	Version 1.5 2003/11/26
	
	Author: Michal Zygmuntowicz <m.zygmuntowicz@onet.pl>


	Table of Contents:
	1. Introduction
	2. Compilation
	3. RadAuth - H.235 Username/Password Authentication
	3.1. RadAuth Access-Request RADIUS Attributes
	3.2. RadAuth Access-Accept RADIUS Attributes
	4. RadAliasAuth - Alias Based Authentication
	4.1. RadAliasAuth Access-Request RADIUS Attributes
	4.2. RadAliasAuth Access-Accept RADIUS Attributes
	5. RadAcct - RADIUS Accounting Module
	5.1. RadAcct Accounting-Request RADIUS Attributes
	5.2. RadAcct Accounting-Response RADIUS Attributes
	6. TODO
	7. List of files


1. Introduction
---------------

This RADIUS authentication package consists of two
authentication modules - one for H.235 username/password
based scheme and the other for alias based authentication.


2. Compilation
---------------

By default, RADIUS support is compiled as other regular
modules. In order to disable compilation of these RADIUS modules, 
NO_RADIUS has to be defined. Example:

	NO_RADIUS=1 make opt

To disable RADIUS modules compilation under Windows, 
radauth.cxx and radproto.cxx have to be manually excluded
from the build.


3. RadAuth - H.235 Username/Password Authentication
---------------------------------------------------

This modules provides authentication based on H.235
security features. It requires endpoints to include
CATs (Cisco Access Tokens) with username/password 
inside RRQs and ARQs sent (inside m_tokens field).


3.1. RadAuth Access-Request RADIUS Attributes
------------------------------

For RRQs, the following RADIUS attributes are included
inside Access-Request packets (* means optional):

	User-Name - H225_RegistrationRequest.tokens[CAT].m_generalID
	CHAP-Password - H225_RegistrationRequest.tokens[CAT].m_random 
					+ H225_RegistrationRequest.tokens[CAT].m_challenge
	CHAP-Challenge - H225_RegistrationRequest.tokens[CAT].m_timeStamp
	NAS-IP-Address - GNU Gk Home or a particular local network interface set
					by 'LocalInterface' config parameter
	NAS-Identifier - GNU Gk Name
	NAS-Port-Type - Virtual (GNU Gk does not have concept of physical ports)
	*Framed-IP-Address - IP address of registering endpoint signalling channel 
						(only if IncludeEndpointIP config option is set)
	Service-Type - Login-User
	*h323-ivr-out - a list of aliases an endpoint is registering with
						(only if IncludeTerminalAliases config option is set)

NOTE: The list of aliases inside h323-ivr-out is in the following form:
	    h323-ivr-out="h323-ivr-out=terminal-alias:alias1,alias2,...,aliasN;"
      The h323-ivr-out attribute can be (in future) instantiated multiple times
      inside a single Access-Request and may also contain variables other than
	  "terminal-alias", so a RADIUS server should be flexible enough 
	  with processing of this attribute.

For ARQs, the following RADIUS attributes are included
inside Access-Request packets (* means optional):

	User-Name - ARQ.tokens[CAT].m_generalID
	CHAP-Password - ARQ.tokens[CAT].m_random + ARQ.tokens[CAT].m_challenge
	CHAP-Challenge - ARQ.tokens[CAT].m_timeStamp
	NAS-IP-Address - GNU Gk Home or a particular local network interface set
					by 'LocalInterface' config parameter
	NAS-Identifier - GNU Gk Name
	NAS-Port-Type - Virtual (GNU Gk does not have concept of physical ports)
	*Framed-IP-Address - IP address of registering endpoint signalling channel 
						(only if IncludeEndpointIP config option is set)
	Service-Type - Login-User (for ARQs from originating endpoint)
					or Call-Check (for ARQs from answering endpoint)
	
	Calling-Station-Id - one of:
							ARQ.m_srcInfo (dialedDigits or partyNumber
								or h323id, in order the preceeding order)
							first dialedDigits, partyNumber or h323_ID alias
								from the list of registered aliases for originating ep
							the same as User-Name (only if requesting
								endpoint is the one that is originating 
								the call - ARQ.m_answerCall is FALSE).
	Called-Station-Id - one of:
							ARQ.m_destinationInfo (dialedDigits or partyNumber
								or h323id, in order the preceeding order)
							first dialedDigits, partyNumber or h323_ID alias
								from the list of registered aliases for answering ep
							ARQ.m_destCallSignalAddress::e_ipAddress.
							the same as User-Name (only if requesting
								endpoint is the one that is answering 
								the call - ARQ.m_answerCall is FALSE).

	*VSA: VendorId=Cisco, h323-conf-id - H.323 conference ID from ARQ;
	*VSA: VendorId=Cisco, h323-call-type - call type (fixed value: "h323-call-type=VoIP");
	*VSA: VendorId=Cisco, h323-call-origin - call origin ("answer","originate");
	*VSA: VendorId=Cisco, h323-gw-id - the same as NAS-Identifier;

3.2. RadAuth Access-Accept RADIUS Attributes
------------------------------

For RRQs, the following RADIUS attributes are recognized 
inside Access-Accept packets:

	h323-ivr-in (Cisco-AVPair) - if present, it is scanned for
		'terminal-alias' variable that can contain a list of aliases
		that should be assigned to the endpoint being registered.
		All RRQ aliases that do not match this list are removed.
		The format of this attribute is as follows:
		
			Cisco-AVPair = "h323-ivr-in=variable:value;[variable:value;]"
			
		where the "variable" can be "terminal-alias":
		
			Cisco-AVPair = "h323-ivr-in=terminal-alias:alias1[,alias2,...];"
			
		Example 1:
			RRQ {
				m_terminalAlias = { "myalias", "1234" }
			}
		if RADIUS server returns the following h323-ivr-in:
			Access-Accept {
				Cisco-AVPair = "h323-ivr-in=terminal-alias:anotheralias,6789;"
			}
		the endpoint will get registered with aliases "anotheralias" and "6789".
		Also RCF will contain:
			RCF {
				m_terminalAlias = { "anotheralias", "6789" }
			}
		
		Example 2 (add E164 to an existing alias):
			RRQ {
				m_terminalAlias = { "it_s_me" }
			}
		if RADIUS server returns the following h323-ivr-in:
			Access-Accept {
				Cisco-AVPair = "h323-ivr-in=terminal-alias:it_s_me,48586259732;"
			}
		RCF will contain:
			RCF {
				m_terminalAlias = { "it_s_me", "48586259732" }
			}
		
	
For ARQs, the following RADIUS attributes are recognized
inside Access-Accept packets:

	h323-return-code - if present and not 0, the request is rejected.
	                   This check is provided to allow interoperability
					   with some poor billing systems, that send Access-Accept
					   with non-zero h323-return-code to reject the call
					   instead of Access-Reject.
					   The attribute can be in form h323-return-code="1"
					   or h323-return-code="h323-return-code=1". Note that 
					   the return code is a string, not an integer,

	h323-credit-time - if present, it enforces maximum call duration (in seconds).
					   The attribute can be in form h323-credit-time="120"
					   or h323-credit-time="h323-credit-time=120". Note that 
					   the return code is a string, not an integer,
					   
	Session-Timeout - if present, it enforces maximum call duration (in seconds).
					  This is a standard RADIUS attribute of integer type.

If both Session-Timeout and h323-credit-time are present, a lesser value
is taken.

4. RadAliasAuth - Alias Based Authentication
--------------------------------------------

This modules provides authentication based on endpoint
aliases and/or endpoint signalling address. RadAliasAuth 
can be configured to include fixed username and/or fixed
user password.


4.1. RadAliasAuth RADIUS Attributes
-----------------------------------

For RRQs, the following RADIUS attributes are included
inside Access-Request packets (* means optional):

	User-Name - either endpoint alias from RRQ or a value of FixedUsername 
				config parameter. User-Name is taken as follows:
					FixedUsername or
					RRQ.m_terminalAlias (preference order: h323_ID, dialedDigits) or
					RRQ.m_callSignalAddress or
					RRQ.m_rasAddress or
					RRQ.m_endpointIdentifier;
	User-Password - either the same as User-Name or a value of FixedPassword
					config parameter
	NAS-IP-Address - GNU Gk Home or a particular local network interface set
					by 'LocalInterface' config parameter
	NAS-Port-Type - Virtual (GNU Gk does not have concept of physical ports)
	NAS-Identifier - GNU Gk Name
	*Framed-IP-Address - IP address of registering endpoint signalling channel 
						(only if IncludeEndpointIP config option is set)
	Service-Type - Login-User
	*h323-ivr-out - a list of aliases an endpoint is registering with
						(only if IncludeTerminalAliases config option is set)
	
For ARQs, the following RADIUS attributes are included
inside Access-Request packets (* means optional):

	User-Name - either endpoint alias from ARQ or a value of FixedUsername 
				config parameter. User-Name is taken as follows:
					FixedUsername or
					first endpoint alias from registration table 
						(preference order: h323_ID, dialedDigits) or
					ARQ.m_srcInfo (preference order: h323_ID, dialedDigits) or
					ARQ.m_srcCallSignalAddress or
					call signalling address from registration table or
					ARQ.m_endpointIdentifier;
	User-Password - either the same as User-Name or a value of FixedPassword
					config parameter
	NAS-IP-Address - GNU Gk Home or a particular local network interface set
					by 'LocalInterface' config parameter
	NAS-Port-Type - Virtual (GNU Gk does not have concept of physical ports)
	NAS-Identifier - GNU Gk Name
	*Framed-IP-Address - IP address of registering endpoint signalling channel 
						(only if IncludeEndpointIP config option is set)
	Service-Type - Login-User (for ARQs from originating endpoint)
					or Call-Check (for ARQs from answering endpoint)
	
	Calling-Station-Id - one of:
							ARQ.m_srcInfo (dialedDigits or partyNumber
								or h323id, in order the preceeding order)
							first dialedDigits, partyNumber or h323_ID alias
								from the list of registered aliases for originating ep
							the same as User-Name (only if requesting
								endpoint is the one that is originating 
								the call - ARQ.m_answerCall is FALSE).
	Called-Station-Id - one of:
							ARQ.m_destinationInfo (dialedDigits or partyNumber
								or h323id, in order the preceeding order)
							first dialedDigits, partyNumber or h323_ID alias
								from the list of registered aliases for answering ep
							ARQ.m_destCallSignalAddress::e_ipAddress.
							the same as User-Name (only if requesting
								endpoint is the one that is answering 
								the call - ARQ.m_answerCall is FALSE).

	*VSA: VendorId=Cisco, h323-conf-id - H.323 conference ID from ARQ;
	*VSA: VendorId=Cisco, h323-call-type - call type (fixed value: "h323-call-type=VoIP");
	*VSA: VendorId=Cisco, h323-call-origin - call origin ("answer","originate");
	*VSA: VendorId=Cisco, h323-gw-id - the same as NAS-Identifier;

For H.225/Q.931 Setup message, the following RADIUS attributes are included
inside Access-Request packets (* means optional):

	User-Name - either endpoint alias from Setup or a value of FixedUsername 
				config parameter. User-Name is taken as follows:
					FixedUsername or
					first endpoint alias from registration table 
						(preference order: h323_ID, dialedDigits) or
					Setup.m_sourceAddress (preference order: h323_ID, dialedDigits) or
					Setup.m_sourceCallSignalAddress or
					call signalling address from registration table or
					Setup.m_endpointIdentifier;
	User-Password - either the same as User-Name or a value of FixedPassword
					config parameter
	NAS-IP-Address - GNU Gk Home or a particular local network interface set
					by 'LocalInterface' config parameter
	NAS-Port-Type - Virtual (GNU Gk does not have concept of physical ports)
	NAS-Identifier - GNU Gk Name
	*Framed-IP-Address - IP address of endpoint signalling channel 
						(only if IncludeEndpointIP config option is set)
	Service-Type - Login-User
	
	Calling-Station-Id - one of:
							CallingPartyNumber from Setup
							first dialedDigits, partyNumber or h323_ID alias
								from the list of registered aliases for originating ep
							first dialedDigits, partyNumber or h323_ID aliase
								from Setup.m_sourceAddress
							the same as User-Name
	Called-Station-Id - one of:
							CalledPartyNumber from Setup
							first dialedDigits, partyNumber, h323_ID alias
								from Setup.m_destinationAddress
							Setup.m_destCallSignalAddress::e_ipAddress.

	*VSA: VendorId=Cisco, h323-conf-id - H.323 conference ID from Setup;
	*VSA: VendorId=Cisco, h323-call-type - call type (fixed value: "h323-call-type=VoIP");
	*VSA: VendorId=Cisco, h323-call-origin - call origin ("originate");
	*VSA: VendorId=Cisco, h323-gw-id - the same as NAS-Identifier;

4.2. RadAliasAuth Access-Accept RADIUS Attributes
-------------------------------------------------

For RRQs, the following RADIUS attributes are recognized 
inside Access-Accept packets:

	h323-ivr-in (Cisco-AVPair) - if present, it is scanned for
		'terminal-alias' variable that can contain a list of aliases
		that should be assigned to the endpoint being registered.
		All RRQ aliases that do not match this list are removed.
		The format of this attribute is as follows:
		
			Cisco-AVPair = "h323-ivr-in=variable:value;[variable:value;]"
			
		where the "variable" can be "terminal-alias":
		
			Cisco-AVPair = "h323-ivr-in=terminal-alias:alias1[,alias2,...];"
		
	
For ARQs, the following RADIUS attributes are recognized
inside Access-Accept packets:

	h323-return-code - if present and not 0, the request is rejected.
	                   This check is provided to allow interoperability
					   with some poor billing systems, that send Access-Accept
					   with non-zero h323-return-code to reject the call
					   instead of Access-Reject.
					   The attribute can be in form h323-return-code="1"
					   or h323-return-code="h323-return-code=1". Note that 
					   the return code is a string, not an integer,

	h323-credit-time - if present, it enforces maximum call duration (in seconds).
					   The attribute can be in form h323-credit-time="120"
					   or h323-credit-time="h323-credit-time=120". Note that 
					   the return code is a string, not an integer,
					   
	Session-Timeout - if present, it enforces maximum call duration (in seconds).
					  This is a standard RADIUS attribute of integer type.

If both Session-Timeout and h323-credit-time are present, a lesser value
is taken.

For Q.931/H.225 Setup messages, the same attributes as for ARQs are recognized
(h323-return-code,h323-credit-time,Session-Timeout).

5. RadAcct - RADIUS Accounting Module
-------------------------------------

This modules enables the gatekeeper to send call accounting information
to RADIUS servers. It can log gatekeeper start (NAS On), gatekeeper shutdown
(NAS Off), call start, call interim-update, call stop events. 
RadAcct can be configured to include fixed username and/or fixed
user password.


5.1. RadAcct Accounting-Request RADIUS Attributes
-------------------------------------------------

For an Accounting-Request, the following RADIUS attributes are included
inside Accounting-Request packets (* means optional). Each attribute 
is followed by a list of accounting event types, it is sent for:

	Acct-Status-Type (start,update,stop,on,off)
	
		The accounting event type (Start, Iterim-Update, Stop, 
		Accounting-On, Accounting-Off).
		
	NAS-IP-Address (start,update,stop,on,off)
	
		An IP address of the gatekeeper.
		
	NAS-Identifier (start,update,stop,on,off)
	
		The gatekeeper identifier (Name= gk parameter).
		
	NAS-Port-Type (start,update,stop,on,off)
	
		Fixed value Virtual.
		
	Service-Type (start,update,stop)
	
		Fixed value Login-User.
		
	Acct-Session-Id (start,update,stop)
	
		An unique accounting session identifier string.
		
	User-Name (start,update,stop)
	
		Identity of the calling party.
		Priority:
			FixedUserName RadAcct parameter,
			an alias for the calling party from the registration table
			    (with preference for h323_ID),
			an alias for the calling party specified inside ARQ or Setup message,
			an endpoint call signalling address or an IP address of the calling socket.

	Framed-IP-Address (start,update,stop)
	
		An IP address for the calling party. Either an endpoint call signalling
		address or a remote socket address for the signalling channel.

	Acct-Session-Time (update,stop)
	
		Call duration (seconds) - for interim-update events this is the actual
		duration.
		
	Calling-Station-Id (start,update,stop)
	
		Priority:
			Calling-Station-Id set by authenticator modules,
			an alias for the calling endpoint from the registration table
				(with preference for dialedDigits, partyNumber, h323_ID),
			an alias for the calling party specified inside ARQ or Setup message,
			an endpoint call signalling address or an IP address of the calling socket.

	Called-Station-Id (start,update,stop)
	
		Priority:
			Called-Station-Id set by authenticator modules,
			an alias for the called party specified inside ARQ or Setup message,
			an alias for the called endpoint from the registration table
				(with preference for dialedDigits, partyNumber, h323_ID),
			a call signalling address for the called endpoint.

	*VSA: VendorId=Cisco, h323-gw-id (start,update,stop)
	
		The same as NAS-Identifier.
		
	*VSA: VendorId=Cisco, h323-conf-id (start,update,stop)
	
		H.323 Conference ID for the call.
		
	*VSA: VendorId=Cisco, h323-call-origin (start,update,stop)
	
		Fixed string "proxy".
		
	*VSA: VendorId=Cisco, h323-call-type (start,update,stop)
	
		Fixed string "VoIP".
		
	*VSA: VendorId=Cisco, h323-setup-time (start,update,stop)
	
		Timestamp when the Q.931 Setup message has been received by the gk.
		
	*VSA: VendorId=Cisco, h323-connect-time (update,stop)
		
		Timestamp when the call has been connected (Q.931 Setup message 
		has been received or ACF has been sent in direct signalling mode).
	
	*VSA: VendorId=Cisco, h323-disconnect-time (stop)

		Timestamp when the call has been disconnected (ReleaseComplete or DRQ
		has been received).
		
	*VSA: VendorId=Cisco, h323-disconnect-cause (stop)
	
		Q.931 two digit hexadecimal disconnect cause.
		
	*VSA: VendorId=Cisco, h323-remote-address (start,update,stop)
	
		An IP address of the called party (if known).
		
	Acct-Delay-Time (start,update,stop)
	
		Amount of time (seconds) the gk is trying to send the request.
		Currently always 0.
		
5.2. RadAcct Accounting-Response RADIUS Attributes
--------------------------------------------------

The gatekeeper does not interpter any attributes present in Accounting-Response
RADIUS packets.

6. TODO
-------

	* Better ARQ handling (more attributes, etc.)
	* Other authentication methods to CAT - CryptoEPPwdHash, etc.
		- is it possible without modifying RADIUS server logic?
	* DRQ, BRQ handling;
	
7. List of files
----------------

	openh323gk/radproto.cxx - RADIUS protocol generic client
	openh323gk/radproto.h 
	openh323gk/radauth.cxx - Authenticator for GNU Gk
	openh323gk/radauth.h
	openh323gk/radacct.cxx - Accounting Module for GNU Gk
	openh323gk/radacct.h
	openh323gk/etc/radauth.ini - example RadAuth configuration
	openh323gk/etc/radaliasauth.ini - example RadAliasAuth configuration
	openh323gk/etc/radacct.ini - example RadAcct configuration
	openh323gk/docs/radauth.txt - documentation
