NOTE: this page is for archival only, see the note at the end of the page.

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.

Country definition

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:

country CR:

Regulatory rules

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.

Frequency range

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.

Power rule

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:

        (N/A, 20)

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.

Example analysis

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:

                        * 2412 MHz [1]
                        * 2417 MHz [2]
                        * 2422 MHz [3]
                        * 2427 MHz [4]
                        * 2432 MHz [5]
                        * 2437 MHz [6]
                        * 2442 MHz [7]
                        * 2447 MHz [8]
                        * 2452 MHz [9]
                        * 2457 MHz [10]
                        * 2462 MHz [11]
                        * 2467 MHz [12]
                        * 2472 MHz [13]
                        * 2484 MHz [14]

                        * 5180 MHz [36]
                        * 5200 MHz [40]
                        * 5220 MHz [44]
                        * 5240 MHz [48]
                        * 5260 MHz [52]
                        * 5280 MHz [56]
                        * 5300 MHz [60]
                        * 5320 MHz [64]
                        * 5500 MHz [100]
                        * 5520 MHz [104]
                        * 5540 MHz [108]
                        * 5560 MHz [112]
                        * 5580 MHz [116]
                        * 5600 MHz [120]
                        * 5620 MHz [124]
                        * 5640 MHz [128]
                        * 5660 MHz [132]
                        * 5680 MHz [136]
                        * 5700 MHz [140]
                        * 5745 MHz [149]
                        * 5765 MHz [153]
                        * 5785 MHz [157]
                        * 5805 MHz [161]
                        * 5825 MHz [165]

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.

Beacon hints

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.

Country IE processing

APs can provide an ISO/IEC 3166-1 country code and a channel list (with associated max tx power setting) as part of the IEEE 802.11 Country Information Element. In practice though one can not always trust APs country information element regulatory information due to considerations for outdated data, rogue/busted APs. Therefore, the wireless code determines the regulatory permissions based on the intersection of data from the APs country information element and what CRDA provides for the given country code.

The Linux kernel wireless subsystem always enables the dot11MultiDomainCapabilityEnabled flag. Therefore, STA devices in the Linux kernel try to follow country information received in AP beacons.

If an AP supports sending the Country IE it will send the country IE appended on every beacon. Since we have an initial regulatory setting (set by the driver, user, or core) we don't pay attention to the country IE until we try to associate to the AP. Upon association we will parse the country IE, convert it to a cfg80211 regulatory domain structure and pass it up as a country IE regulatory hint to the wireless core. Processing of country IEs is done automatically for both cfg80211 and mac80211 drivers by the core (cfg80211) issuing regulatory_hint_11d() when processing an AP's IEs. regulatory_hint_11d() is optimized to ignore hints from the same AP or that match the same country IE checksum, but it should be noted that we only issue regulatory_hint_11d() once upon a successful association to an AP.

APs may support 3 bands (2.4 GHz, 5 GHz, 60 GHz) or 2 bands (2.4 GHz and 5 GHz) or one band (2.4 GHz, 5 GHz, or 60 GHz). When an AP supports 1 band, as per IEEE-802.11 2007 country IE clarification request the AP may send a subset of the allowed regulatory rules and not the complete set. Because of this the cfg80211 regulatory infrastructure trusts its original regulatory requests if the AP does not send any information on a band it does not support. Since band information is purely artificial in cfg80211 we conclude an AP does not support a band if it has no channel information in its country IE that fits within 2 GHz of the tested band. We can can tune this as we see fit, in freq_in_rule_band().

If an AP has no information on a supported device band we trust the last trusted regulatory request. The last trusted regulatory request will vary depending on the device.

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

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. We also do not process beacon hints for DFS channels. To determine if you are seeing beacon hints you can query dmesg as follows:

jose@chupacabras ~ $ dmesg| grep beacon
cfg80211: Found new beacon on frequency: 5180 MHz (Ch 36) on phy0
cfg80211: Found new beacon on frequency: 5200 MHz (Ch 40) on phy0
cfg80211: Found new beacon on frequency: 5220 MHz (Ch 44) on phy0
cfg80211: Found new beacon on frequency: 5240 MHz (Ch 48) on phy0
cfg80211: Found new beacon on frequency: 5745 MHz (Ch 149) on phy0
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 [153]:
        o active scanning enabled
        o beaconing enabled
1343339189.613367: phy #0: beacon hint:
phy0 5785 MHz [157]:
        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.

This is a static dump of the wiki, taken after locking it in January 2015. The new wiki is at
versions of this page: last, v22, v21, v20, v19, v18, v17, v16, v15, v14, v13, v12, v11, v10, v9, v8, v7, v6, v5, v4, v3, v2, v1