Skip to content

Home

Jump to bottom
sink edited this page Nov 20, 2024 · 5 revisions

WiFiDog Protocol V1

Main contributors: Benoit Grégoire, datamile, Sink

Gateway heartbeating (Ping Protocol)

Wifidog uses the ping protocol as a heartbeat mechanism to send current status information to the auth server. This enables central logging of the status for each node at the auth server.

The wifidog client uses a setting in the conf file to periodically start a thread ( ping_thread.c ) to send a status message via http to the auth server. The message format is

http://auth_sever/ping/?
gw_id=%s
sys_uptime=%lu
sys_memfree=%u
sys_load=%.2f
wifidog_uptime=%lu

With the data gathered via system calls on the wifidog client.

Headers
HTTP/1.0\r\n" 
"User-Agent: WiFiDog %s\r\n" 
"Host: %s\r\n" 
"\r\n",

A typical HTTP request would be:

GET /ping/?gw_id=001217DA42D2&sys_uptime=742725&sys_memfree=2604&sys_load=0.03&wifidog_uptime=3861 HTTP/1.0
User-Agent: WiFiDog 1.3.0
Host: wifidog-auth.lan

To this the auth server is expected to respond with an http message containing the word "Pong".

redirect to login when connect wifi

After a device connects the captive wifi(gateway), modern OS(Android 5+/iOS 4+/macOS 10.6+/Windows 8+) will request a HTTP url, such as:

Or when the user try to access internet(must HTTP) in browser, such as: http://example.com

the client will be redirected to the auth server by the gateway:

http://auth_server/login/?
gw_address=
gw_port=
gw_id=
url=

Example:

http://wifidog-auth.lan/login/?gw_id=0016B6DA9AE0&gw_address=192.168.31.1&gw_port=2060&url=http://example.com
image

redirect to gateway with token

Upon successful login, the client will be redirected to the gateway:

http://gw_address:gw_port/wifidog/auth?
token=

Example:

http://192.168.31.1:2060/wifidog/auth?token=4f473ae3ddc5c1c2165f7a0973c57a98

Auth server authentication protocol

The gateway requests the auth server to verify the token obtained in the previous step:

GET http://auth_server/auth/?
stage=
&ip=
&mac=
&token=
&incoming=
&outgoing=

Note: stage= login, logout or counters, depending if this is a new client or not.

Even though the incoming and outgoing variables are present in all messages they are only valid for messages with a stage of counters. In all other cases incoming and outgoing are always set to 0.

In response the auth server will respond with a valid status, and a new user message, or an auth server error.

The format of the response should be text/plain:

Auth: <user status number>

The user status can be:

  • 0 - AUTH_DENIED - User firewall users are deleted and the user removed. The gateway will either do nothing or display an error similar to http://auth_server/messages/?message=denied.
  • 6 - AUTH_VALIDATION_FAILED - User email validation timeout has occured and user/firewall is deleted. The gateway will either do nothing or display an error similar to http://auth_server/messages/?message=failed_validation.
  • 1 - AUTH_ALLOWED - User was valid, gateway should add firewall rules if not present, and redirect user to portal http://auth_server/portal/?gw_id=%s
  • 5 - AUTH_VALIDATION - Permit user access to email to get validation email under default rules. The gateway will either do nothing or display an error similar to http://auth_server/messages/?message=activate.
  • -1 - AUTH_ERROR - An error occurred during the validation process.

logout

When user logout from the auth server, the auth server should request the gateway to logout, the gateway will remove user device from firewall:

POST http://auth_server/logout
HTTP/1.1 302 FOUND
location: http://gw_address:gw_port/wifidog/auth?logout=1&token=%s

GET http://gw_address:gw_port/wifidog/auth?
logout=1
&token=%s

Example:

POST http://wifidog-auth.lan/logout
HTTP/1.1 302 FOUND
location: http://192.168.31.1:2060/wifidog/auth?logout=1&token=4f473ae3ddc5c1c2165f7a0973c57a98
Clone this wiki locally