Linux wireless regulatory domains
I had a case where I had an embedded system that should act as a WiFi Access Point on the 5GHz band. The HW was capable and the system managed to act as a client to 5GHz networks, so everything looked good.
However, the system could not create an access point on some frequencies. How is it that? It's all about regulatory domains!
Regulatory domains
Radio regulations is something that applies to all devices that make transmissions in the radio spectrum. The Linux kernel makes itself compliant to these regulations by make the regulatory restrictions as a directly part of the cfg80211 configuration API that all (new) wireless device drivers use.
Radio regulatory hasn't always been so tight integrated into the Linux kernel. This is a result to address the vendor concerns [6] about getting products based on Linux certified against all (geographically dependent) radio regulatory authorities out there.
Before that, all wireless drivers used to be a propritary blob that we load into our kernel, nowadays more and more vendors has a more FOSS driven development for such a drivers which is what we strive for.
To build trust with the chip vendors so that they could consider FOSS drivers as an real alternative, we stick to a number of principles.
Principles
There are a few principles [1] that the Linux kernel follows in order to fulfull the requirements for on use of the radio spectrum:
- It should be reasonably impossible for a user to fail to comply with local regulations either unwittingly or by accident.
- Default configurations should err in favor of more restrictive behavior in order to protect unwitting users.
- Configurations that have no known compliant usage should not be part of the 'official' kernel tree.
- Configurations that are compliant only under special circumstances (e.g. with special licenses) should not be part of the 'official' kernel tree. Any exceptions should have their legal requirements clearly marked and those options should never be configured by default.
- Configurations that disable regulatory enforcement mechanisms should not be part of the 'official' kernel tree.
- The kernel should rely on userland components to determine regulatory policy. Consequently, the kernel's regulatory enforcement mechanisms should be flexible enough to cover known or reasonably anticipated regulatory policies.
- It's the moral duty of responsible distribution vendors, software developers, and community members to make every good faith effort to ensure proper compliance with applicable regulations regarding wireless communications.
The overall approach is "better safe than sorry" with respect to radio regulations. In other words, if no local configuration is setup, the system will fall back to the more restrictive world regulatory domain.
An example on such behaviour could be that the system is not allowed to initiate radio communication on certain radio frequencies that is not globally allowed.
Integration
CRDA
(Used pre Linux v4.15.)
CRDA [3], Central Regulatory Domain Agent, is a userspace agent responsible to read and intepret the regulatory.bin file and update the regulatory domains.
CRDA is intended to be trigged on uevents from the kernel (via udev) upon changes in the regulatory domain and setup the new regulations .
The udev rule to do this my look like this:
KERNEL=="regulatory*", ACTION=="change", SUBSYSTEM=="platform", RUN+="/sbin/crda"
Nowadays, CRDA is no longer needed as of kernel v.4.15 ( commit [2], "cfg80211: support loading regulatory database as firmware file"), the regulatory database is read by the Linux kernel directly as a firmware file during boot.
wireless-regdb
wireless-regdb [4] is the regulatory database used by Linux. The db.txt file in the repository contains regulatory information for each domain.
The output from this project is regulatory.db, which is loaded by the kernel as a firmware. The integrity of regulatory.db is typically ensured by the regulatory daemon by verifying the built-in RSA signature against a list of public keys in a preconfigured directory.
Although it's possible to build regulatory.db without any RSA key signature checking, it is highly recommended not to do so, as if the regulatory database is compromised in some way we could end up with a product that violates product radio compatibility.
wireless-regdb and Yocto
A side note for Yocto users.
The wireless-regdb recipe is part of oe-core [5] and should be included into your image if you intend to use any wireless LAN. wireless-regdb-static should be used with kernel >= v4.15 and wireless-regdb is intended to be used with CRDA.
In other words, add:
IMAGE_INSTALL:append = " wireless-regdb-static "
to your yocto distribution.
Hands on
iw [7] is the nl80211 based tool we use to configure wireless devices in Linux.
Here we will take a look at what the regulations may look like.
World regulatory domain
1# iw reg get
2global
3country 00: DFS-UNSET
4 (755 - 928 @ 2), (N/A, 20), (N/A), PASSIVE-SCAN
5 (2402 - 2472 @ 40), (N/A, 20), (N/A)
6 (2457 - 2482 @ 20), (N/A, 20), (N/A), AUTO-BW, PASSIVE-SCAN
7 (2474 - 2494 @ 20), (N/A, 20), (N/A), NO-OFDM, PASSIVE-SCAN
8 (5170 - 5250 @ 80), (N/A, 20), (N/A), AUTO-BW, PASSIVE-SCAN
9 (5250 - 5330 @ 80), (N/A, 20), (0 ms), DFS, AUTO-BW, PASSIVE-SCAN
10 (5490 - 5730 @ 160), (N/A, 20), (0 ms), DFS, PASSIVE-SCAN
11 (5735 - 5835 @ 80), (N/A, 20), (N/A), PASSIVE-SCAN
12 (57240 - 63720 @ 2160), (N/A, 0), (N/A)Country 00 is the world regulatory domain. This could be a result of a system that failed to load the regulatory database.
Look into the output from dmesg for verify:
1$ dmesg | grep cfg80211
2[ 3.268852] cfg80211: Loading compiled-in X.509 certificates for regulatory database
3[ 3.269107] cfg80211: failed to load regulatory.dbAs a result, this is the restrictions we have on the 5GHz band:
1# iw list
2[...]
3 Frequencies:
4 * 5040 MHz [8] (disabled)
5 * 5060 MHz [12] (disabled)
6 * 5080 MHz [16] (disabled)
7 * 5170 MHz [34] (disabled)
8 * 5190 MHz [38] (20.0 dBm) (no IR)
9 * 5210 MHz [42] (20.0 dBm) (no IR)
10 * 5230 MHz [46] (20.0 dBm) (no IR)
11 * 5180 MHz [36] (20.0 dBm) (no IR)
12 * 5200 MHz [40] (20.0 dBm) (no IR)
13 * 5220 MHz [44] (20.0 dBm) (no IR)
14 * 5240 MHz [48] (20.0 dBm) (no IR)
15 * 5260 MHz [52] (20.0 dBm) (no IR, radar detection)
16 * 5280 MHz [56] (20.0 dBm) (no IR, radar detection)
17 * 5300 MHz [60] (20.0 dBm) (no IR, radar detection)
18 * 5320 MHz [64] (20.0 dBm) (no IR, radar detection)
19 * 5500 MHz [100] (20.0 dBm) (no IR, radar detection)
20 * 5520 MHz [104] (20.0 dBm) (no IR, radar detection)
21 * 5540 MHz [108] (20.0 dBm) (no IR, radar detection)
22 * 5560 MHz [112] (20.0 dBm) (no IR, radar detection)
23 * 5580 MHz [116] (20.0 dBm) (no IR, radar detection)
24 * 5600 MHz [120] (20.0 dBm) (no IR, radar detection)
25 * 5620 MHz [124] (20.0 dBm) (no IR, radar detection)
26 * 5640 MHz [128] (20.0 dBm) (no IR, radar detection)
27 * 5660 MHz [132] (20.0 dBm) (no IR, radar detection)
28 * 5680 MHz [136] (20.0 dBm) (no IR, radar detection)
29 * 5700 MHz [140] (20.0 dBm) (no IR, radar detection)
30 * 5745 MHz [149] (20.0 dBm) (no IR)
31 * 5765 MHz [153] (20.0 dBm) (no IR)
32 * 5785 MHz [157] (20.0 dBm) (no IR)
33 * 5805 MHz [161] (20.0 dBm) (no IR)
34 * 5825 MHz [165] (20.0 dBm) (no IR)
35[...]We can see the no IR flag is set for almost all frequencies on the 5GHz band. Please note that NO-IR is not the same as disabled, it simply means that we cannot initiate radiation on those frequencies.
Initiate radiation simply includes all modes of operations that require us to initiate radiation first. Think of acting as an Access Point, IBSS, Mesh or P2P master.
We can still use the frequency though, there is no problem to connect to an Access Point (we are not the one who initiate the radiation) on these frequencies.
Local regulatory domain
When a proper regulatory database is loaded into the system, we can setup the local regulatory domain instead of the globally one.
Set Swedish (SE) as our local regulatory domain:
1# iw reg set SE
2# iw reg get
3global
4country SE: DFS-ETSI
5 (2400 - 2483 @ 40), (N/A, 20), (N/A)
6 (5150 - 5250 @ 80), (N/A, 23), (N/A), NO-OUTDOOR, AUTO-BW
7 (5250 - 5350 @ 80), (N/A, 20), (0 ms), NO-OUTDOOR, DFS, AUTO-BW
8 (5470 - 5725 @ 160), (N/A, 26), (0 ms), DFS
9 (5725 - 5875 @ 80), (N/A, 13), (N/A)
10 (5945 - 6425 @ 160), (N/A, 23), (N/A), NO-OUTDOOR
11 (57000 - 71000 @ 2160), (N/A, 40), (N/A)And we are now allowed to use the 5GHz band with other restrictions:
1#iw list
2[...]
3 Frequencies:
4 * 5040 MHz [8] (disabled)
5 * 5060 MHz [12] (disabled)
6 * 5080 MHz [16] (disabled)
7 * 5170 MHz [34] (23.0 dBm)
8 * 5190 MHz [38] (23.0 dBm)
9 * 5210 MHz [42] (23.0 dBm)
10 * 5230 MHz [46] (23.0 dBm)
11 * 5180 MHz [36] (23.0 dBm)
12 * 5200 MHz [40] (23.0 dBm)
13 * 5220 MHz [44] (23.0 dBm)
14 * 5240 MHz [48] (23.0 dBm)
15 * 5260 MHz [52] (20.0 dBm) (no IR, radar detection)
16 * 5280 MHz [56] (20.0 dBm) (no IR, radar detection)
17 * 5300 MHz [60] (20.0 dBm) (no IR, radar detection)
18 * 5320 MHz [64] (20.0 dBm) (no IR, radar detection)
19 * 5500 MHz [100] (26.0 dBm) (no IR, radar detection)
20 * 5520 MHz [104] (26.0 dBm) (no IR, radar detection)
21 * 5540 MHz [108] (26.0 dBm) (no IR, radar detection)
22 * 5560 MHz [112] (26.0 dBm) (no IR, radar detection)
23 * 5580 MHz [116] (26.0 dBm) (no IR, radar detection)
24 * 5600 MHz [120] (26.0 dBm) (no IR, radar detection)
25 * 5620 MHz [124] (26.0 dBm) (no IR, radar detection)
26 * 5640 MHz [128] (26.0 dBm) (no IR, radar detection)
27 * 5660 MHz [132] (26.0 dBm) (no IR, radar detection)
28 * 5680 MHz [136] (26.0 dBm) (no IR, radar detection)
29 * 5700 MHz [140] (26.0 dBm) (no IR, radar detection)
30 * 5745 MHz [149] (13.0 dBm)
31 * 5765 MHz [153] (13.0 dBm)
32 * 5785 MHz [157] (13.0 dBm)
33 * 5805 MHz [161] (13.0 dBm)
34 * 5825 MHz [165] (13.0 dBm)
35[...]Regulatory flags
Some of the flags reported by iw may not be obvious at a first glance. Here is an explaination for some of them:
| Flag | Meaning |
|---|---|
| Can be used without restrictions. | |
| disabled | Disabled |
| NO-OUTDOOR | MUST be used indoor only. |
| DFS | MUST be used with DFS regardless indoor or outdoor. |
| SRD | MUST comply with SRD requirements regardless indoor or outdoor. |
| NO-OUTDOOR/DFS | MUST be used with DFS and indoor only. |
| NO-OUTDOOR/TPC | MUST be used with TPC and indoor only. |
| DFS/TPC | MUST be used with DFS and TPC. |
| DFS/TPC + SRD | MUST be used with DFS, TPC and comply with SRD requirements. |
- DFS: stands for Dynamic Frequency Selection and is a channel allocation scheme used to prevent electromagnetic interference with systems that predates Wi-Fi.
- TPC: stands for Transmit Power Control which is a mechanism to automatically reduce the used transmission output power when other networks are within range.
- SRD: stands for Short-Range Device and cover devices that are low-power transmitters typically limited to the range of 24-100mW ERP.
References
| [1] | https://wireless.wiki.kernel.org/en/developers/regulatory/statement |
| [2] | https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=007f6c5e6eb45 |
| [3] | http://www.kernel.org/pub/software/network/crda/ |
| [4] | http://git.kernel.org/?p=linux/kernel/git/sforshee/wireless-regdb.git |
| [5] | https://github.com/openembedded/openembedded-core |
| [6] | https://wireless.wiki.kernel.org/en/vendors/vendorsupport |
| [7] | https://wireless.wiki.kernel.org/en/users/documentation/iw |