Splash Page Redirect
A WiFi client may be redirected to the splash page several times during the login and logout process (an overview of these two processes can be found in this article). During these redirects, the captive portal service and the Access Point exchange several HTTP GET parameters such as “res”, which indicates the state the WiFi client is in.
The first time a WiFi client attempts to access the network it gets redirected from the Access Point to the splash page. Since the WiFi client is not yet authenticated at this point, the “res” parameter is set to “notyet”. After the WiFi client has completed the required authentication steps, it is redirected back from the splash page to the Access Point. Alongside this redirect, the captive portal service shares the WiFi client’s information with the Access Point: username, password and, optionally, a link to be redirected to upon successful login (i.e., “redir”).
The Access Point then determines whether authentication was successful or not (how this step is implemented depends on the protocol being used: either HTTP or RADIUS). In case authentication failed, the WiFi client is redirected to the failed login page (“res” set to “failed”). On the other hand, if authentication succeeded, the Access Point first checks whether “redir” was provided and either sends the WiFi client to the supplied link or to the success splash page (“res” set to “success”).
Finally, when a WiFi client initiates logout process, it gets redirected to the logout splash page and “res” is set to “logout”.
The graphic below illustrates the aforementioned interactions between the Access Point (AP, blue) and the captive portal service (CPS, brown). Redirects are indicated by horizontal arrows.
Please find the various HTTP GET parameters exchanged between the Access Point and the captive portal service below.
Redirect from Access Point to Captive Portal service
The following parameters can be exchanged when a WiFi client is redirected from the Access Point to the captive portal service:
| parameter | value |
|---|---|
res | Used by the Access Point to indicate the state of the WiFi client to the captive portal service. It is assigned one of the following values:
|
uamip | The IP address of the Access Point. It is used by the captive portal service to create the URL to redirect the WiFi client to after successful authentication. |
uamport | The port number of the Access Point. It is used together with “uamip” to create the URL to redirect the WiFi client to after successful authentication. |
mac | The MAC address of the WiFi client. Format: six groups of two hexadecimal digits, separated by hyphens (“-”). |
called | The primary MAC address of the Access Point. Format: six groups of two hexadecimal digits, separated by hyphens (“-”). |
ssid | The name of the SSID broadcasted by the Access Point to which the WiFi client is connected. |
nasid | The unique string classifying SSIDs in different groups. |
userurl | The URL requested by the WiFi client. Format: URL encoded web page (e.g., “http%3A%2F%2Fwww.google.com%2F”). |
challenge | The sequence of random characters provided by the Access Point and passed as an hexadecimal string. It is used by the captive portal service along with a shared secret to encrypt the WiFi client password (see Password Encryption paragraph below). |
Please find below an example of a redirect URL from the Access Point to the captive portal service:
https://splashpageserver.com/?
res=notyet
&uamip=172.31.0.1
&uamport=8081
&mac=11-22-33-44-55-66
&called=66-55-44-33-22-11
&ssid=SSIDNAME
&nasid=
&userurl=http%3A%2F%2Fclients3.google.com%2Fgenerate_204
&challenge=20AE6DFEE96B5C6066AA1C36D76934B6EDF00F3402EF1D0304F3998147AB3B32
Redirect from Captive Portal Service to Access Point
The following parameters can be exchanged when a WiFi client is redirected from the captive portal service to the Access Point:
| parameter | value |
|---|---|
username | The username provided by the captive portal service. It is used by the Access Point together with the password to verify the client authentication via HTTP or RADIUS. |
password | The encrypted password (see Password Encryption paragraph below). It is used by the Access Point together with the username to verify the client authentication via HTTP or RADIUS. |
redir | The URL to be redirected to upon successful login. The assigned value may be the same as in “userurl”, or different, or left empty. Format: URL encoded web page (e.g., “http%3A%2F%2Fwww.google.com%2F”). |
Please find below an example of a redirect URL:
http://uamip:uamport/logon?
username=splashpage-username
&password=76cb39aee60c56a8b14a1e181ebb8ef429d50fa981296a9aa9585967199bc28c0d8d0cffe01543a494422e712f
&redir=http%3A%2F%2Fmydomain.com
Password Encryption
The plaintext password is encrypted by the captive portal service before redirecting the WiFi client back to the Access Point. This is done using the challenge generated by the Access Point, along with the UAM secret configured on the Kaiwoo Console or the Provisioning API.
Password encryption needs to be implemented by the service provider as follows:
- Convert challenge from hexadecimal to binary form;
- Concatenate binary challenge and UAM secret into a single array of bytes and compute its 16 bytes long MD5 checksum (called ‘key’);
- Make sure that the plaintext password is null-terminated (C style);
- XOR the plaintext password with the corresponding bytes of the key. This results in the encrypted password if the plaintext password is shorter or the same size of the key;
- If the plaintext password is longer than the key, XOR the next bytes of the plaintext password with the key (starting from the first byte again). Repeat this point until the entire plaintext password has been XOR’ed. This results in the encrypted password;
- Convert encrypted password from binary to hexadecimal.
Please find below the pseudo code depicting the steps to be implemented.
hexCHAL = hexadecimal challenge, string received from AP
binCHAL = binary challenge converted from hexadecimal string, hexadecimal_to_binary(hexCHAL)
plainPWD = plaintext password, string generated by Captive Portal service
key = MD5(binCHAL + UAM_secret)
plainPWD = plainPWD + '\0'
for each byte I in plainPWD do
// When XORing the password and the key, if the latter
// is not long enough, restart from its first byte
encPWD[I] = plainPWD[I] XOR key[I % length(key)]
done
hexEncPWD = binary_to_hexadecimal(encPWD)For your convenience, please also find the PHP code containing the password encryption function below.
function encode_password($plain, $challenge, $UAM_secret) {
if ((strlen($challenge) % 2) != 0 ||
strlen($challenge) == 0)
return FALSE;
$hexchall = hex2bin($challenge);
if ($hexchall === FALSE)
return FALSE;
$key = md5($hexchall . $UAM_secret, TRUE);
$key_len = 16;
/* simulate C style \0 terminated string */
$plain .= "\x00";
$crypted = '';
for ($i = 0; $i < strlen($plain); $i++)
$crypted .= $plain[$i] ^ $key[$i % $key_len];
return bin2hex($crypted);
}