RADIUS ACCOUNTING FOR SIP Abstract: The project included: 1. Configuring and running the yard-radius daemon (radiusd). 2. Configuring and runing the GNUradius server. 3. Configuring and running the Freeradius server. 4. Writing a test client that sends SIP specific accounting attributes to radiusd. 5. Integrating this client and thus adding functionality to the sipd server ,specifically the log.c file to send logging/accounting information to radiusd keeping with the specifications of RFCs 2865 and 2866. 6. Defining new RADIUS accounting attributes relevant to SIP. The programming language used was C. Introduction and Background: Radius is a system serving for authentication and accounting. The name RADIUS stands for Remote Authentication in Dial-In User Service. Radius servers were used as a means to authenticate the user coming from a dial-in connection, but in this case we are using it as an accounting server for Sipd. Radius uses the Client/Server model. The main server keeps a centralized user database. The Radius server is configured to accept accounting information. SIPD operates as a client of RADIUS. SIPD sends logging/accounting information about specific events in a SIP session to the RADIUS server. Most of the parameters to be logged can be mapped into the attributes defined in RFC 2865 and 2866. However, a few SIP specific attributes were needed. Currently they are being mapped into vendor-specific attribute values. The vendor ID for Columbia University is 11862. The RADIUS servers used for testing were yard-radius daemon 1.0.19(radiusd), GNUradius and Freeradius. The RADIUS server can act as a proxy client to other RADIUS servers. Transactions between SIPD and the RADIUS server are authenticated through the use of a shared secret, which is never sent over the network. This shared secret must be preconfigured in the RADIUS server configuration files. The RADIUS accounting server silently discards packets in error. If the packet is accepted an ACCOUNTING RESPONSE is sent back. In the absence of a response the following steps are recommended by RFC 2865. 1. It is recommended that the client continue attempting to send the Accounting-Request packet until it receives an acknowledgement, using some form of "backoff". If no response is returned within a length of time, the request is re-sent a number of times. A binary backoff with 5 retries is used. 2. The client can also forward requests to an alternate server or servers in the event that the primary server is down or unreachable. This hasn't been implemented in sipd. YARD-RADIUSD-1.0.19 Configuration: radiusd is run using the command: ./radiusd -a sets accounting directory -b uses GDBM for users file -c clears user stats database -d set radiusd database directory -f sets alternate password file -i sets alternate ipaddress -l sets radiusd log file -p -x sets debug mode on -s do fork The command used was ./radiusd -a ../acct -d ../acct -l ../acct/radiusd.log -x -p 1812 Although the udp_port is set to 1812, the radius accounting server listens on port 1813. 1812 refers to the port used by the radius authentication/ authorisation server. radiusd requires a group of configuration files in the /usr/local/yardradius/conf directory by default in order to properly work. In our case ../acct was specified as the directory. ../acct/users This file contains the human readable information for users' accounting and authorization. It contains the security and configuration information for each user. The first field is the user name and can be upto 8 charaters in length. This is followed with the list of authetication requirements which are not very relevant for accounting since the user authentication is done by SIPD itself. Indented lines following the first line indicate configuration values to be passed back to the radiusd client (SIPD). An example is shown below: DEFAULT Auth-Type = System, Yard-Simulataneous-Use = 1, Reply-Message = "login ok" ../acct/dictionary This read-only file contains the codes and formats for standard and vendor RADIUS protocol attributes and values along with their human readable representation. The following statements needed to be added to the dictionary: VALUE Service-Type Sip-session 12 ############################################################################## # Columbia University VSAs ############################################################################## VENDOR Columbia-University 11862 # #ATTRIBUTE User-Name see User-Name #ATTRIBUTE SIPD-IP-Address see NAS-IP-Address #ATTRIBUTE SIPD-Port see NAS-Port #ATTRIBUTE Service-Type see Service-Type #ATTRIBUTE Acct-Status-Type see Acct-Status-Type #ATTRIBUTE Acct-Delay-Time see Acct-Delay-Time #ATTRIBUTE Call-Id see Acct-Session-Id #ATTRIBUTE Acct-Authentic see Acct-Authentic #ATTRIBUTE Acct-Session-Time see Acct-Session-Time #ATTRIBUTE Acct-Terminate-Cause see Acct-Terminate-Cause #ATTRIBUTE Event-Timestamp see Event-Timestamp ATTRIBUTE Sip-Method 0 integer Columbia-University ATTRIBUTE Sip-From 1 string Columbia-University ATTRIBUTE Sip-To 2 string Columbia-University ATTRIBUTE Sip-Translated-Request-URI 4 string Columbia-University VALUE Sip-Method INVITE 0 VALUE Sip-Method BYE 1 VALUE Sip-Method REGISTER 2 ..acct/clients This file contains a list of clients which are allowed to make authentication requests and their encryption key. The first field is a valid hostname. The second field (seperated by blanks or tabs) is the encryption key. One should use 600 level protection for this file. An example is shown below: metro.cs.columbia.edu sip laverne.clic.cs.columbia.edu sip ../acct/allowuser It lists (one per line) usernames/groupnames who are granted for having access (if their passwords are correct). Each entry must respect one of the following syntaxes: USER: GROUP: GECOS: SHELL: An empty or missing file grants access to anyone which is not listed in the next file. For testing purposes the values were set to ANY. ..acct/denyuser The same syntax of allowuser can be used to deny access to specific classes of users, with the same previous matching criteria. An empty or missing file grants access to anyone which is listed in the previous file or not. All logging and accounting files of YARD RADIUS are stored under ..acct/ It also creates some specific binary files to store the on-line status of users, and collect users statistics. A seperate logging directory is used for each user. The logging file structure is as follows: //detail-XX eg: metro.cs.columbia.edu/2001/detail-12 An example log entry is shown below: Tue Dec 25 20:58:48 2001 Acct-Status-Type = Start Acct-Status-Type = Accounting-On Acct-Session-Id = "trial" Acct-Authentic = Remote User-Name = "Henning Schulzrinne" NAS-IP-Address = 128.59.19.190 NAS-Port = 5060 Acct-Delay-Time = 0 Event-Timestamp = 1009331928 Service-Type = Sip-session Sip-Method = INVITE Sip-From = "sip:anshul@columbia.edu" Sip-To = "sip:sankaran@cs.columbia.edu" Sip-Translated-Request-URI = "sip:erlang.cs.columbia.edu" Timestamp = 1009331928 GNURADIUS-0.95 Configuration: radiusd is run using the command: ./radiusd -a ../radacct -d ../radacct -l ../radacct/radius.log -x -p 1812 When started `radiusd' uses the configuration values from the following sources (in order of increasing precedence): 1. Compiled-In defaults 2. config file. 3. Command line arguments The following command line options are accepted: -A Enable detailed authentication logging. When this option is specified each authentication request is logged to the file 'radacct/NASNAME/detail.auth', where NASNAME is replaced by the short name of the NAS from `raddb/naslist. -a DIR Specify accounting directory. -b Enable DBM support. -d DIR Specify alternate configuration directory. Default is `/usr/local/etc/raddb'. -f Stay in foreground. Used for debugging purposes only. -i IP Specifies a source IP address. `Radiusd' will listen to packets coming to this address. If this option is not specified, the program picks up the first IP address it sees on the machine. -l DIR Specify alternate logging directory. -mb "Builddbm" mode. Builds a DBM version of a plaintext users database. -mc Check configuration files and exit. -mt Test mode. In this mode `radiusd' starts an interactive interpreter which allows to test various aspects of its configuration. -n Process only authentication requests. -p PORTNO Listen to the udp port PORTNO. The accounting port is computed as PORTNO + 1. -P DIR Specifies the alternate path for the pidfile. -S Log usernames stripped off any prefixes/suffixes. -s Run in single process mode. Used for debugging purposes only. -v Display program version and exit -x Set debugging level. -y Log authentications. With this option enabled, Radius will log any authentication attempt into its logfile. -z Log passwords along with authentication information. Only for debugging purposes. radiusd requires the following configuration files to function properly. All these files are present in the ../radacct/ directory. The relevant files are: ../radacct/config Runtime configuration options. The minimum configuration file used is: option { usr2delay 30; max-requests 1024; log-dir "/home/abk2001/project/radius/gnu-radius-0.95/gnurad/radacct/"; acct-dir "/home/abk2001/project/radius/gnu-radius-0.95/gnurad/radacct/"; }; logging { channel info { file "radius.info"; option pid; }; channel debug { file "radius.debug"; }; category auth { level auth,failed_pass; }; category info { channel info; }; category debug { channel debug; }; }; auth { port 1812; max-requests 127; request-cleanup-delay 2; detail yes; strip-names yes; checkrad-assume-logged yes; }; acct { port 1813; max-requests 127; request-cleanup-delay 2; }; proxy { max-requests 127; request-cleanup-delay 2; }; notify off; ../radacct/dictionary The dictionary file defines the symbolic names for radius attributes and their values. The file consists of a series of statements. Each statement occupies one line. The following statements were added to the dictionary. $INCLUDE dictionary.sip VALUE Service-Type Sip-session 12 We also create a new file called 'dictionary.sip' which specifies the SIP specific attributes and values. This file is included in the main dictionary file using the $INCLUDE statement as shown above. The 'dictionary.sip' file is as follows: ############################################################################## # Columbia University VSAs ############################################################################## VENDOR Columbia-University 11862 # #ATTRIBUTE User-Name see User-Name #ATTRIBUTE SIPD-IP-Address see NAS-IP-Address #ATTRIBUTE SIPD-Port see NAS-Port #ATTRIBUTE Service-Type see Service-Type #ATTRIBUTE Acct-Status-Type see Acct-Status-Type #ATTRIBUTE Acct-Delay-Time see Acct-Delay-Time #ATTRIBUTE Call-Id see Acct-Session-Id #ATTRIBUTE Acct-Authentic see Acct-Authentic #ATTRIBUTE Acct-Session-Time see Acct-Session-Time #ATTRIBUTE Acct-Terminate-Cause see Acct-Terminate-Cause #ATTRIBUTE Event-Timestamp see Event-Timestamp ATTRIBUTE Sip-Method 0 integer Columbia-University ATTRIBUTE Sip-From 1 string Columbia-University ATTRIBUTE Sip-To 2 string Columbia-University ATTRIBUTE Sip-Translated-Request-URI 4 string Columbia-University VALUE Sip-Method INVITE 0 VALUE Sip-Method BYE 1 VALUE Sip-Method REGISTER 2 ../radacct/clients This file contains a list of clients which are allowed to make authentication requests and their encryption key. The first field is a valid hostname. The second field (seperated by blanks or tabs) is the encryption key. One should use 600 level protection for this file. An example is shown below: metro.cs.columbia.edu sip laverne.clic.cs.columbia.edu sip ../radacct/naslist The 'naslist' file contains a list of clients known to the Radius server. Each record in the file consist of three fields. NAS name: Specifies a hostname or IP address of the client. Short Name: This field defines a short name under which this client will be listed in logfiles. Type: Specifies the type of client. Using this value `radiusd' determines the way to query NAS about the presence of a given user on it. Two reserved types `true' and `false' disable NAS querying. When `true' is specified `radiusd' assumes the user is logged in to the NAS, when `false' is specified it assumes the user is not logged in. The sample contents of the file are as follows: metro.cs.columbia.edu metro true laverne.clic.cs.columbia.edu laverne true localhost local true ../radacct/users File `raddb/users' contains the database of Radius users. Each record in the file describes a user's profile. When trying to find a match for an input request, `radiusd' uses the following algorithm: 1. Match the username 2. Determine the authentication type and verify the user 3. Delete from the check-pair list Attribute/Value pairs internal to the server The internal A/V pairs are those with the attribute number greater than 255 This list is called the "Effective checklist". 4. Compare the "Effective checklist" with the supplied pairlist. 5. Process special reply attributes DEFAULT Auth-Type = System, Simultaneous-Use = 1 Reply-Message = "login ok" SANK Password = "sank", Simultaneous-Use = 1 Reply-Message = "login ok" All logging and accounting files of YARD RADIUS are stored under ..radacct/ A seperate logging directory is used for each client. The logging file structure is as follows: /detail eg: metro.cs.columbia.edu/detail If an entry corresponding to the client exists in the 'naslist' list then the short name of the client is used for the directory. eg: metro/detail An example log entry is shown below: Tue Dec 25 21:28:52 2001 Acct-Status-Type = Start Acct-Status-Type = Accounting-On Acct-Session-Id = "trial" Acct-Authentic = 3 User-Name = "Henning Schulzrinne" NAS-IP-Address = 128.59.19.190 NAS-Port-Id = 5060 Acct-Delay-Time = 0 Service-Type = Sip-session Sip-Method = INVITE Sip-From = "sip:anshul@columbia.edu" Sip-To = "sip:sankaran@cs.columbia.edu" Sip-Translated-Request-URI = "sip:erlang.cs.columbia.edu" Timestamp = 1009333732 Request-Authenticator = Verified RADIUS Attributes Specific to SIP: A summary of the RADIUS data format is shown below. The fields are transmitted from left to right. 0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Code | Identifier | Length | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | | | Authenticator | | | | | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Attributes ... +-+-+-+-+-+-+-+-+-+-+-+-+- 1. Code: The Code field is "one octet", and identifies the type of RADIUS packet. RADIUS Accounting Codes (decimal) are assigned as follows: 4 Accounting-Request 5 Accounting-Response 2. Identifier: The Identifier field is "one octet", and aids in matching requests and replies. The RADIUS server can detect a duplicate request if it has the same client source IP address and source UDP port and Identifier within a short span of time. 3. Length: The Length field is "two octets". It is the length of Code+Identifier+Length+Authenticator+Attribute fields. The minimum length is 20 and maximum length is 4095. 4. Authenticator: The Authenticator field is "sixteen (16) octet. It contains a one-way MD5 hash calculated over a stream of octets consisting of the Code + Identifier + Length + 16 zero octets + request attributes + shared secret (where + indicates concatenation). 5. Attribute: A summary of the Attribute format for predefined attributes is shown below. 0 1 2 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+- | Type | Length | Value ... +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+- The Type field takes the following values. Type Attribute_name 1 User-Name 4 NAS-IP-Address 5 NAS-Port 6 Service-Type 26 Vendor-Specific 40 Acct-Status-Type 41 Acct-Delay-Time 44 Acct-Session-Id 45 Acct-Authentic 46 Acct-Session-Time 49 Acct-Terminate-Cause 55 Event-Timestamp User-Name takes the its value from the SIP message header. NAS-IP-Address is set to the value of sipd's ip address. NAS-Port is set to 5060 which is the sipd's port. Service-Type is assigned a value of 12 indicating SIP-Session, for the time being. Acct-Status-Type is set to 1 and 2 respectively when receiving 200 OK and BYE (if Record-Route is used) from the callee. Acct-Delay-Time is the time in seconds between the arrival of an INVITE and the receipt of an ACK corresponding to the same transaction. Acct-Session-Id is set to the SIP-CallId. Acct-Authentic is set to 3 indicating remote authentication. Acct-Session-Time is the time in seconds between accounting start and stop. Acct-Terminate-Cause is set to 1 when the SIP message method is BYE. Event-Timestamp is the gettimeofday value in seconds. A summary of the Vendor-Specific Attribute format used for some SIP specific attributes is shown below. 0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Type | Length | Vendor-Id +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Vendor-Id (cont) | Vendor type | Vendor length | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Attribute-Specific... +-+-+-+-+-+-+-+-+-+-+-+-+-+-+- For the vendor specific attributes namely the SIP specific attributes the Vendor-Id is set to 1 for the time being. The SIP specific vendor types include Vendor-Type Vendor-Length Vendor_type_name 0 6 SIP-Method 1 >= 7 SIP-From 2 >= 7 SIP-To 4 >= 7 SIP-Translated-Request-URI The values the SIP-Method type takes are integers i.e. 4 octets in length. They are further enumerated as follows: Value Method 0 INVITE 1 BYE 2 REGISTER SIP-From, SIP-To and SIP-Translated-Request-URI take strings as values. References: [1] Rigney, C., Willens, S., Rubens, A. and W. Simpson, "Remote Authentication Dial In User Service (RADIUS)", RFC 2865, June 2000 http://www.ietf.org/rfc/rfc2865.txt [2] Rigney, C., "RADIUS Accounting", RFC 2866, June 2000 http://www.ietf.org/rfc/rfc2866.txt [3] YARDRADIUS 1.0.19 Documentation http://www.yardradius.sourceforge.net/ [4] GNURADIUS 0.95 Documentation http://www.gnu.org/software/radius/radius.html