- Regulatory rules processing
- Country definition
- Processing channels in cfg80211
- Hidden SSIDs
Regulatory rules processing
This section is intended to help document cfg80211's algorithm for processing regulatory rules and applying them. You can read this if you are not so well versed with code or don't want to bother reading it.
Lets start out first by understanding how a country is defined. We start by declaring it with the key word "country" followed by the respective ISO 3166 alpha2 country code followed by a colon. So for example:
Each country can have a set of regulatory rules. Each regulatory rule has an attached frequency range and a respective power rule. An example of one regulatory rule follows:
(2402 - 2482 @ 40), (N/A, 20)
A country can have multiple regulatory rules.
Each frequency range provides a starting frequency and ending frequency in MHz followed by the maximum allowed bandwidth that a channel of communication can have in that frequency range. So for example, in the following regulatory rule:
(2402 - 2482 @ 40), (N/A, 20)
The frequency range is just:
(2402 - 2482 @ 40)
This is telling us that you can use a channel of communication of max bandwidth of up to 40 MHz in the frequency range 2402 MHz - 2482 MHz.
The power rule is the last section in a regulatory rule. For example in the regulatory rule:
(2402 - 2482 @ 40), (N/A, 20)
the power rule is:
This tells us the maximum allowed EIRP that can be used on a frequency range, and the maximum antenna gain if it is known. If the maximum antenna gain is not known N/A can be used to annotate this. The maximum EIRP is assumed to be in dBm, the maximum antenna gain is assumed to be in dBi.
Reading a regulatory rule
Now lets read a regulatory rule all together. The following regulatory rule:
(2402 - 2482 @ 40), (N/A, 20)
then tell us that we can use a channel of communication of up to 40 MHz in the frequency range 2402 MHz - 2482 MHz with a maximum EIRP output power of 20 dBm. No maximum antenna gain is known.
20 MHz channels
cfg80211 assumes all 802.11 cards want to use 20 MHz channels so channels get disabled if no 20 MHz channels are allowed in a given frequency range defined by the country the card is in.
40 MHz channels
40 MHz channels will only be allowed if 20 MHz channels are allowed as well. 40 MHz channels work by using a regular 20 MHz channel and then using an extra 20 MHz channel either on the left hand side of the first channel or the right hand side. We refer to this as either HT40- or HT40+, respectively.
cfg80211 checks if an HT40- or HT40+ channel fits on each center frequency for each power rule and will enable HT40- or HT40+ on each channel. This HT40 allow map is available currently only through debugfs. For example, here is an output:
root@tux:~# cat /sys/kernel/debug/ieee80211/phy0/ht40allow_map 2412 HT40 + 2417 HT40 + 2422 HT40 + 2427 HT40 + 2432 HT40 -+ 2437 HT40 -+ 2442 HT40 -+ 2447 HT40 - 2452 HT40 - 2457 HT40 - 2462 HT40 - 2467 Disabled 2472 Disabled 2484 Disabled 5180 HT40 + 5200 HT40 -+ 5220 HT40 -+ 5240 HT40 -+ 5260 HT40 -+ 5280 HT40 -+ 5300 HT40 -+ 5320 HT40 - 5500 HT40 + 5520 HT40 -+ 5540 HT40 -+ 5560 HT40 -+ 5580 HT40 - 5600 Disabled 5620 Disabled 5640 Disabled 5660 HT40 + 5680 HT40 -+ 5700 HT40 - 5745 HT40 + 5765 HT40 -+ 5785 HT40 -+ 5805 HT40 -+ 5825 HT40 -
This list is not exposed via nl80211 as cfg80211 will get a revisit as to how this is handled after the regulatory rules are restructured in the future.
Processing channels in cfg80211
When cfg80211 initializes it will have a list of wiphy devices. Each 802.11 card has a respective single wiphy device. Multiple interfaces can be attached to a wiphy device. The wiphy device has a list of channels which are shared. When a wiphy is registered to cfg80211 it has a list of supported 802.11 channels with a respective center frequency. The currently regulatory domain is read and each wiphy is processed to apply the regulatory domain to it. A wiphy device can have its own regulatory domain though. This allows us to enable two different cards which have two different regulatory domains to be present on a single system and for cfg80211 to respect it. When this happens there will be three regulatory domains, one for each wiphy and a core central regulatory domain which will consist of the intersection between the two wiphy's regulatory domains.
If a wiphy has no regulatory domain of its own cfg80211 will use its own core central regulatory domain to iterate over the card's 802.11 channels and apply rules, otherwise cfg80211 will use the card's own regulatory domain.
Suppose a wiphy is registered to cfg80211 and the driver that registers it claims that the wiphy has a regulatory domain of its own which indicates it is a card which is programmed to operate in Costa Rica. In this case cfg80211 would have queried CRDA for CR's regulatory domain and CRDA would reply with:
country CR: (2402 - 2482 @ 40), (N/A, 20) (5170 - 5250 @ 20), (3, 17) (5250 - 5330 @ 20), (3, 23), DFS (5735 - 5835 @ 20), (3, 30)
Now the wiphy that was registered to cfg80211 has these channels:
Frequencies: * 2412 MHz  * 2417 MHz  * 2422 MHz  * 2427 MHz  * 2432 MHz  * 2437 MHz  * 2442 MHz  * 2447 MHz  * 2452 MHz  * 2457 MHz  * 2462 MHz  * 2467 MHz  * 2472 MHz  * 2484 MHz  Frequencies: * 5180 MHz  * 5200 MHz  * 5220 MHz  * 5240 MHz  * 5260 MHz  * 5280 MHz  * 5300 MHz  * 5320 MHz  * 5500 MHz  * 5520 MHz  * 5540 MHz  * 5560 MHz  * 5580 MHz  * 5600 MHz  * 5620 MHz  * 5640 MHz  * 5660 MHz  * 5680 MHz  * 5700 MHz  * 5745 MHz  * 5765 MHz  * 5785 MHz  * 5805 MHz  * 5825 MHz 
What cfg80211 will do next is iterate over each channel's center frequency and see from the current regulatory domain on what regulatory rule a channel of 20 MHz bandwidth using the channel's center frequency fits in. If no match is found the channel is disabled. If a match is found cfg80211 will enable 20 MHz communication on the channel.
Post processing mechanisms
Once cfg80211 processes a regulatory domain on a wiphy device it goes through a series of post processing on the wiphy. Below we document the different types of post processing performed by cfg80211.
cfg80211 has a feature called beacon hinting to assist cfg80211 in allowing a card to life passive-scan and no-beaconing flags. Passive-scan flags are used on channels to ensure that an interface will not issue a probe request out. The no-beaconing flag (today its just called no-adhoc) exists to allow regulatory domain definitions to disallow a device from initiating communication using beacons, so for example AP/IBSS/Mesh interfaces would not be able to initiate communication on these channels unless the channel does not have this flag. If either of these flags are present on a channel a device is prohibited from initiating communication on cfg80211. The reason two flags exist instead of one is some regulatory definitions need to state that modes of operation like adhoc are strictly prohibited even though active scan is allowed.
Regulatory rule flags like passive-scan and no-beaconing were originally invented to help with World Roaming. If you do not know what country you are in you can still behave as an 802.11 STA interface but can wait to enable active scans until you see a beacon from an AP, if the channel being used is not a DFS channel and not channels 12-14 on the 2.4 GHz band. The same can be said for initiating communication, so both the passive-scan and no-beaconing flags can be lifted if an AP is found beaconing on a non-DFS channel and if the channel is also not channels 12-14 on the 2.4 GHz band. cfg80211 takes advantage of this bit of logic to life both of these flags if and only if the wiphy device is world roaming.
Driver override on rules
To allow more driver flexibility cfg80211 allows drivers to review the regulatory settings on the wiphy and override them. This enables more flexibility on regulatory design but also enables drivers to take advantage of offloading most of the regulatory work to cfg80211/CRDA. The way that drivers can override regulatory settings is by defining a wiphy regulatory reg_notifier(). The wiphy's reg_notifier() callback will be called after cfg80211 has completed processing its regulatory settings on the wiphy device.
Driver regulatory hints
Drivers can issue their own regulatory domain hints to cfg80211. If they do this the wiphy gets its own regulatory domain. This enables two different 802.11 devices even with the same 802.11 driver to have different regulatory domains. This also enables there to be a central 802.11 regulatory domain which will consists of an intersection between the two present regulatory domains if two cards are present with different regulatory domains.
Enabling users to enhance regulatory
Users can enhance regulatory settings by further restricting devices by picking a regulatory domain. This will enable users to help compliance further. Currently regulatory rules for certain countries ("US" and "JP") do not allow users to select their regulatory domain though so blindly trusting a user is not something that can be allowed if you are in certain regulatory domain. If a user picks a regulatory domain channels will be restricted further on a device if the device has its own regulatory domain already listed.
Cellular base station regulatory hints
Cell base station towers can inform mobile / laptop devices of their location with great accuracy. As of the 3.6 release Linux supports the ability for cell base station towers to supply a regulatory hint to the Linux kernel. This is done by providing an attribute to the Linux kernel that classifies the hint as coming from a cellular base station. Device drivers require testing / compliance prior to enabling this feature mostly due to possible synchronization issues with a device's firmware when the device implements some regulatory functionality in firmware. Device drivers which have completed validation for this feature can enable a Kconfig feature for system integrators for this feature on their driver by depending on the CONFIG_CFG80211_CERTIFICATION_ONUS option. When capable, a device driver would enable the wiphy->features NL80211_FEATURE_CELL_BASE_REG_HINTS feature, and upon registration to cfg80211 would inform it that there is at least one driver present that support cellular base station hints. cfg80211 will ignore cellular base station hints unless one device driver is present with one device (wiphy) that supports this feature. If all devices have been removed from the system that support this feature the cell base station hints would be ignored afterwards.
Userspace software solutions are expected to implement support for this feature through a dbus event and enabling such event to send a cell base station regulatory hint from wpa_supplicant to the kernel by using the NL80211_ATTR_USER_REG_HINT_TYPE attribute and classifying the hint as NL80211_USER_REG_HINT_CELL_BASE. System integrators which enable this feature must ensure cell base station hints is not a feature enabled for users to use manually, instead its designed for userspace software to implement a hint only when a cell modem has detected we are in a new country.
Hidden SSIDs should be avoided in any AP scenario and and in fact its not supported if you are to support WPS. If you insist on using hidden SSIDs be sure you are not enabling support for WPS as an option then. Communication with hidden SSIDs can become problematic if your card is world roaming under specific scenarios documented here.
You can determine if you are world roaming as follows:
maria@pupusas ~ $ iw reg get country 00: (2402 - 2472 @ 40), (3, 20) (2457 - 2482 @ 20), (3, 20), PASSIVE-SCAN, NO-IBSS (2474 - 2494 @ 20), (3, 20), NO-OFDM, PASSIVE-SCAN, NO-IBSS (5170 - 5250 @ 40), (3, 20), PASSIVE-SCAN, NO-IBSS (5735 - 5835 @ 40), (3, 20), PASSIVE-SCAN, NO-IBSS
If you get a 00 country code it means you are world roaming.
World roaming means we cannot initiate radiation on certain channels given that certain countries may prohibit initiating radiation on some channels or may require DFS master support prior to initiating any radiation. DFS master support for client devices requires quite a lot of work and is not yet implemented on mac80211 / cfg80211. This means that if your AP is in a channel that requires DFS then you will not be able to send probe requests to them. Since SSIDs are hidden the only way to communicate with them is to send probe requests / association requests to them directly, but if you cannot initiate radiation on that channel then you obviously not be able to communicate with them.
If the channel your AP is on is not a DFS channel but a 5 GHz channel that requires passive scan, the passive scan flags are lifted through beacon hints, but we only process beacon hints if obviously the AP is beaconing. To determine if you are seeing beacon hints you can query dmesg as follows:
jose@chupacabras ~ $ dmesg| grep beacon [67280.268696] cfg80211: Found new beacon on frequency: 5180 MHz (Ch 36) on phy0 [67280.369049] cfg80211: Found new beacon on frequency: 5200 MHz (Ch 40) on phy0 [67280.410822] cfg80211: Found new beacon on frequency: 5220 MHz (Ch 44) on phy0 [67280.460508] cfg80211: Found new beacon on frequency: 5240 MHz (Ch 48) on phy0 [67282.207645] cfg80211: Found new beacon on frequency: 5745 MHz (Ch 149) on phy0 [67282.321197] cfg80211: Found new beacon on frequency: 5805 MHz (Ch 161) on phy0
You can also monitor for the events with iw event, for example, leave a window open with iw event running and then issue the iw dev wlan0 scan command, you should see something as follows:
pedro@pulperia:~$ iw event -t 1343339185.840035: wlan0 (phy #0): scan started 1343339189.395215: phy #0: beacon hint: phy0 5765 MHz : o active scanning enabled o beaconing enabled 1343339189.613367: phy #0: beacon hint: phy0 5785 MHz : o active scanning enabled o beaconing enabled 1343339189.886251: wlan0 (phy #0): scan finished: 2412 2417 2422 2427 2432 2437 2442 2447 2452 2457 2462 2467 2472 5180 5200 5220 5240 5260 5280 5300 5320 5500 5520 5540 5560 5580 5600 5620 5640 5660 5680 5700 5745 5765 5785 5805 5825, ""
If you do not see these then you are not getting the beacon hints.
Best is to simply avoid hidden SSIDs. They buy you no security at all and are clearly incompatible with WPS.