Next Previous

Authentication State Machine

One main function of the Hotspot Helper is to participate in the authentication state machine summarized in Figure 1-1. This state machine incorporates feedback from the helpers at various times after associating to a Wi-Fi network.

HotspotHelper1.pdf — **Figure 1-1** Authentication state machine

The state machine maintains a cache of results for each network that is visited, which lets it remember which helper was last chosen for a given network.

To help understand how the state machine works, consider the typical sequences of events for the following scenarios.

Sequence When Network Is Captive

State machine is in Inactive state.
Associate to Wi-Fi network.
IP connectivity is established.
State machine moves to Evaluating state.
Sends Evaluate command to each Hotspot Helper.
Each Hotspot Helper processes the Evaluate command and determines whether the network is captive (it requires authentication).
Results from Evaluate indicate that network is captive; the “best” Hotspot Helper is chosen (best_helper).
State machine moves to Authenticating state; cache entry is created specifying best_helper.
Sends Authenticate command to best_helper.
best_helper performs necessary operation to authenticate to the network and returns kNEHotspotHelperResultSuccess.
State machine moves to Authenticated state and sets a Maintaining timer.
Timer fires; State machine moves to Maintaining state.
Sends Maintain command to best_helper.
best_helper processes command and returns kNEHotspotHelperResultSuccess.
Repeat steps 11 though 14.

Sequence When Network Is Not Captive

State machine is in Inactive state.
Associate to Wi-Fi network.
IP connectivity is established.
State machine moves to Evaluating state.
Sends Evaluate command to each Hotspot Helper.
Each helper processes the Evaluate command to determine whether the network is captive.
Results from Evaluate indicate the network is not captive.
State machine moves to Authenticated state; cache entry is created indicating network not captive.

Sequence When Network Is Captive and UI Is Required

State machine is in Inactive state.
Associate to Wi-Fi network.
IP connectivity is established.
State machine moves to Evaluating state.
Sends Evaluate command to each Hotspot Helper.
Each helper processes the Evaluate command to determine whether the network is captive.
Results from Evaluate indicate the network is captive; the “best” Hotspot Helper (best_helper) is chosen.
State machine moves to Authenticating state.
Sends Authenticate command to best_helper.
best_helper determines that it needs user input to continue; creates UILocalNotification and returns kNEHotspotHelperResultUIRequired.
State machine moves to PresentingUI state.
Sends PresentUI command to best_helper.
best_helper gets brought to the foreground as the result of the UILocalNotification, performs necessary authentication, and returns kNEHotspotHelperResultSuccess.
State machine moves to Authenticated state; cache entry is created specifying best_helper.

Sequence When Network Is Captive (Cached)

State machine is in Inactive state.
Associate to Wi-Fi network.
IP connectivity is established.
Cache entry is found specifying best_helper.
State machine moves to Maintaining state.
Sends Maintain command to best_helper.
best_helper performs necessary operation to authenticate to the network and returns kNEHotspotHelperResultSuccess.
State machine moves to Authenticated state; sets a Maintaining timer.
Timer fires; State machine moves to Maintaining state.
Sends Maintain command to best_helper.
best_helper processes command and returns kNEHotspotHelperResultSuccess.
Repeat steps 8 though 11.

Authentication State Machine Details

This section describes each state in the authentication state machine in detail.

Inactive State

The Inactive state is entered when interface has no IP connectivity. It is also the initial state when the state machine first starts up. This state clears the best_helper and exclude_list (see below).

The interface’s IP connectivity is suppressed until the Authenticated state is reached. This is done to avoid sending application traffic over an interface that is not yet able to carry general network traffic.

Evaluating State

The Evaluating state is entered when the interface gains IP connectivity and no cache entry specifies a Hotspot Helper. This state is also entered from other states (see Figure 1-1). Each helper that is not in the exclude_list (see below) is given the kNEHotspotHelperCommandTypeEvaluate command. The helper indicates its level of confidence in its ability to handle the network (none, low, high).

If no helper claims the network with any confidence, the state machine transitions to the Authenticated state.

Of the helpers that claim the network, the state machine selects the one with the highest confidence, the best_helper, and transitions to the Authenticating state. As an optimization, the first helper to claim the network with high confidence becomes the best_helper.

Authenticating State

The Authenticating state is entered when the interface requires authentication. The best_helper is given the kNEHotspotHelperCommandTypeAuthenticate command. If the helper returns kNEHotspotHelperResultSuccess, the state machine transitions to the Authenticated state. If the helper returns kNEHotspotHelperResultUIRequired, the state machine transitions to the PresentingUI state. If the helper returns kNEHotspotHelperResultUnsupportedNetwork, the helper is added to an exclude_list and the state machine transitions to the Evaluating state. For all other results, the state machine enters the Failure state.

Authenticated State

The Authenticated state is entered when the interface either requires no authentication or the network is successfully authenticated. In this state, the interface’s IP connectivity is no longer suppressed and is eligible to carry general network traffic.

A maintaining timer is scheduled to fire in 300 seconds. When the timer fires, the state machine transitions to the Maintaining state.

Maintaining State

The Maintaining state is entered in two instances:

When the maintaining timer fires from the Authenticated state.
When the interface gains IP connectivity and a cache entry is found  that specifies the helper best_helper.

The best_helper is given the kNEHotspotHelperCommandTypeMaintain command. If the result returned is kNEHotspotHelperResultSuccess, the state machine transitions back to the Authenticated state. If the result returned is kNEHotspotHelperResultAuthenticationRequired, it enters the Authenticating state. If any other result is returned, the interface’s IP connectivity is once again suppressed and the state machine enters the Evaluating state.

PresentingUI State

The PresentingUI state is entered when the best_helper indicates that it needs to present some UI. The kNEHotspotHelperCommandTypePresentUI command is given to the best_helper to process in the foreground. If the helper returns kNEHotspotHelperResultSuccess, the state machine transitions to the Authenticated state. If the helper returns kNEHotspotHelperResultUnsupportedNetwork, the helper is added to an exclude_list and the state machine transitions to the Evaluating state. For all other results, the state machine enters the Failure state.

Failure State

The Failure state is entered when an unrecoverable error occurs. The Wi-Fi network is disassociated, and the state machine transitions to its Inactive state.

Next Previous