Home › CoovaChilli

CoovaChilli Proxy

(requires CoovaChilli-v1.2.0)

The chilli_proxy server, built in the CoovaChilli distribution, is a light-weight (though it does use libcurl) proxy server that converts RADIUS to/from a HTTP based protocol. The proxy server takes the same configuration as chilli and becomes the RADIUS server that chilli talks to. The proxy then takes the RADIUS and performs HTTP requests for authentication, authorization, and accounting (AAA). The protocol itself is intentionally similar to that of WiFiDog, though with some obvious differences to take advantage of the features of chilli.

Building CoovaChilli

To build CoovaChilli with the chilli_proxy server:

 ./configure --enable-chilliproxy [--with-curl]
 make
 sudo make install
Currently, you should use --with-curl, but a non-curl version will also be available.

HTTP API

The HTTP URL is of the format:

 http://hostname/script?query-string-parameters
The URL is specified to chilli_proxy using the chilli option uamaaaurl.

All HTTP requests by the proxy have a User-Agent HTTP header of "CoovaChilli (version)".

Login (RADIUS Access-Request)

Query string parameters:

  • stage= login
  • service= login | framed | admin
  • user= username
  • pass= password (for when using PAP authentication)
  • chap_id= id - the CHAP ID when using CHAP instead of PAP
  • chap_chal= challenge - the CHAP challenge (for CHAP only)
  • chap_pass= response - the CHAP password response (for CHAP only)
  • ap= Called-Station-Id - the nas MAC address
  • mac= Calling-Station-id - the MAC address of the subscriber
  • ip= IP-Address - the ip address given to the subscriber
  • sessionid= Acct-Session-Id - the chilli assigned session identifier
  • nasid= NAS-Identifier - the nasid name
  • vlan= 802.1Q VLAN Tag ID
  • md= checksum - calculated with MD5([url-without-md-paramater]+[uamsecret])

When not authenticated, sessions are always in the login stage.

Values for the service parameter are:

  • login - a standard form based login from a browser
  • framed - a MAC authentication request that occurs during DHCP negotiation
  • admin - the Administrative-User session, which is the device-wide session chilli maintains

The md parameter is the HEX encoded MD5 Message Digest over the URL and it's query string parameters (minus the md paramater) and the UAM secret. This signature is to help prevent anyone from sending bogus data to the script.

HTTP access-accept response:

 Auth: 1
 (Optional RADIUS Attributes)
HTTP access-reject response:

 Auth: 0
 (Optional RADIUS Attributes)

Accounting (RADIUS Accounting-Request)

Query string parameters:

  • stage= counters
  • status= start | update | stop | up | down
  • ap= Called-Station-Id - the nas MAC address
  • mac= Calling-Station-id - the MAC address of the subscriber
  • ip= IP-Address - the ip address given to the subscriber
  • sessionid= Acct-Session-Id - the chilli assigned session identifier
  • nasid= NAS-Identifier - the nasid name
  • duration= value - the session duration in seconds
  • bytes_up= value - a 64bit value for bytes sent up from subscriber to NAS
  • bytes_down= value - a 64bit value for bytes sent down from NAS to subscriber
  • pkts_up= value - a 32bit value for packets sent up from subscriber to NAS
  • pkts_down= value - a 32bit value for packets sent up from NAS to subscriber
  • md= checksum - calculated with MD5([url-without-md-paramater]+[uamsecret])

The values for status are:

  • start - a session has started
  • update - an interim-update based on Acct-Interim-Interval
  • stop - a session has been stopped
  • up - chilli has just started (Accounting-On)
  • down - chilli is about to shutdown (Accounting-Off)

HTTP accounting response:

 Ack: 1
 (Optional RADIUS Attributes)

Registration and Provisioning

To help better facilitate integration between a captive portal and the AAA back-end, the chilli_proxy program can be used to register resources into the back-end. How it is actually implemented depends on the back-end script. However, this utility provides a way to securely use the HTTP proxy mechanism for provisioning. By using the command:

 chilli_proxy --register name1 value1 name2 value2 ...
a HTTP POST request is sent to the configured uamaaaurl with the query string parameters of stage= register and with ap= and nasid= also set (see above for descriptions). In addition, the arguments after the --register are encoded into the URL as well (note: any command line options before --register are considered as chilli options) and any data from standard input is delivered to the URL in the POST. At the end of the URL, the standard md= signature is added for authenticity.

As an example, the following might be used to create an access code into the back-end system:

 echo "Session-Timeout: 3600" | 
    chilli_proxy --register status new_code user xxxxx pass yyyyy
which would result into the Session-Timeout attribute being POSTed in the HTTP request to:

 http://remote-site/script.php?stage=register&ap=00-XX-XX-XX-XX-XX&nasid=nas01&
    status=new_code&user=xxxxx&pass=yyyyyy&md=B4E11CB550BDCFD4965DFDC1CFA6F7AF
the script is then able to verify the request came from chilli by verifying the md parameter using the UAM secret before creating the access code.

Optional Session (RADIUS) Attributes

In the HTTP responses, after the initial protocol response, session parameters can be set by using one or more of the following attributes, one per line.

  • Idle-Timeout - idle time limit
  • Session-Timeout - session time limit
  • Acct-Interim-Interval - interval (in seconds) of accounting updates
  • Reply-Message - reply message in the event of access-reject
  • ChilliSpot-Config - set some session or general chilli options
  • ChilliSpot-Bandwidth-Max-Up - bandwidth limitation in kilobits per second
  • ChilliSpot-Bandwidth-Max-Down - bandwidth limitation in kilobits per second
  • ChilliSpot-Max-Input-Octets - 32 bit value of number of allowed input octets
  • ChilliSpot-Max-Output-Octets - 32 bit value of number of allowed output octets
  • ChilliSpot-Max-Total-Octets - 32 bit value of number of allowed total octets
  • ChilliSpot-Max-Input-Gigawords - upper 32 bit value of the 64 bit value of allowed input octets
  • ChilliSpot-Max-Output-Gigawords - upper 32 bit value of the 64 bit value of allowed output octets
  • ChilliSpot-Max-Total-Gigawords - upper 32 bit value of the 64 bit value of allowed total octets
  • WISPr-Bandwidth-Max-Up - bandwidth limitation in bits per second (WISPr compatibility)
  • WISPr-Bandwidth-Max-Down - bandwidth limitation in bits per second (WISPr compatibility)
  • WISPr-Redirection-URL - redirection url

Examples

Standard Login Authentication

Request:

 http://localhost/script.php?stage=login&service=login&user=test&pass=test
   &ap=00-XX-XX-XX-XX-XX&mac=00-XX-XX-XX-XX-XX&ip=10.1.0.2&sessionid=4adb5f4000000001
   &nasid=nas01&md=A9EA5F98B104F41FC330CFE44B2681AD
Reply (success):

 Auth: 1
 Idle-Timeout: 300
 Session-Timeout: 3600
 Acct-Interim-Interval: 300
Reply (reject):

 Auth: 0
MAC Address Authentication (DHCP)

Request:

 http://localhost/script.php?stage=login&service=framed&user=00-XX-XX-XX-XX-XX&pass=00-XX-XX-XX-XX-XX
   &ap=00-XX-XX-XX-XX-XX&mac=00-XX-XX-XX-XX-XX&sessionid=4adb5f4000000001&nasid=nas01
   &md=A9EA5F98B104F41FC330CFE44B2681AD
Reply (success), with optional bandwidth limitations (80 kilobits per second = 10 kilobyte per second):

 Auth: 1
 Idle-Timeout: 300
 Session-Timeout: 3600
 Acct-Interim-Interval: 300
 ChilliSpot-Bandwidth-Max-Up: 80
 ChilliSpot-Bandwidth-Max-Down: 80
Reply (reject), with optional Redirection URL:

 Auth: 0
 WISPr-Redirection-URL: http://remote-site/YouAreBanned
.