	RADIUS Authentication Modules
	Version 1.7 2005/02/05
	
	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 it, use configure script:

	./configure --disable-radius

To disable RADIUS modules compilation under Windows, 
radauth.cxx, radacct.cxx and radproto.cxx have to be 
manually excluded from the build or HAS_RADIUS=0 preprocessor
variable has to be set.


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 RRQ, ARQ and/or Setup being 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
	
		An IP address of registering endpoint signalling channel 

	Service-Type
	
		Login-User

	*VSA: VendorId=Cisco, Cisco-AVPair, 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 ARQ and Setup messages, 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
	
		An IP address of registering endpoint signalling channel 

	Service-Type
	
		Login-User (for ARQs from originating endpoint)
		or Call-Check (for ARQs from answering endpoint)
	
	Calling-Station-Id
	
		Calling party's number (if available)
		
	Called-Station-Id
	
		Called party's number

	*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:

	VSA: VendorId=Cisco, 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,

	VSA: VendorId=Cisco, h323-billing-model
	
		Billing mode for this account. Can be 0 (credit), 1 or 2 (debit). 
		If an endpoint can understand H.225.0 CallCreditServiceControl messages,
		this information is used to build the message,
		
	VSA: VendorId=Cisco, h323-credit-amout
		
		A string representing current user's account balance. If an endpoint 
		can understand H.225.0 CallCreditServiceControl messages, 
		this information is used to build the message,
		
	VSA: VendorId=Cisco, Cisco-AVPair, h323-ivr-in
	
		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:

	VSA: VendorId=Cisco, 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,

	VSA: VendorId=Cisco, h323-billing-model
	
		Billing mode for this account. Can be 0 (credit), 1 or 2 (debit). 
		If an endpoint can understand H.225.0 CallCreditServiceControl messages,
		this information is used to build the message,
		
	VSA: VendorId=Cisco, h323-credit-amout
	
		A string representing current user account balance. If an endpoint can 
		understand H.225.0 CallCreditServiceControl messages, this information 
		is used to build the message,
		
	VSA: VendorId=Cisco, h323-credit-time
	
		If present, it enforces maximum call duration (in seconds).
		The attribute can be in form of 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,

	VSA: VendorId=Cisco, h323-redirect-number
	
		If present, a call destination is overwritten with the number present 
		in this attribute,

	VSA: VendorId=Cisco, h323-redirect-ip-address
	
		If present, a call is sent to the IP address present in this attribute.

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 same attributes as with RadAuth are sent, with an exception
of username/password attributes (CHAP-Password, CHAP-Challenge, User-Name):

	User-Name
	
		Either an endpoint alias from RRQ or a value of FixedUsername 
		config parameter. If no alias is present, an IP address is used

	User-Password
	
		Either the same as User-Name or a value of FixedPassword
		config parameter
	
For ARQ and Setup messages, the same attributes as with RadAuth are sent,
with an exception of username/password attributes (CHAP-Password, 
CHAP-Challenge, User-Name)::

	User-Name
	
		Either an endpoint alias or a value of FixedUsername config parameter

	User-Password
	
		Either the same as User-Name or a value of FixedPassword config parameter

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

Exactly the same attributes are recognized as with RadAuth module.

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)
	
		Calling party's account name.

	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)
	
		Calling party's number.
		
	Called-Station-Id (start,update,stop)
	
		Called party's number.

	*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).

	*VSA: VendorId=Cisco, Cisco-AVPair, h323-ivr-out (start, update, stop)
	
		h323-call-id variable that contains an H.323 Call Identifier.
		The syntax is as follows: "h323-ivr-out=h323-call-id:123FDE 12348765 9abc1234 12".
		
	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
-------
	
	* proper call forwarding information in accounting packets

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
