Contents
Central Regulatory Domain Agent
The Central Regulatory Domain Agent (CRDA) is a free software project to allow Linux (and possibly other operating systems) comply with radio spectrum regulations around the world by enforcing the regulatory requirements in software. CRDA is also aimed to encourage Linux support from the vendors who were previously afraid to support Linux drivers that would not follow the requirements for radio spectrum use.
We will maintain a thorough and flexible regulatory database in userspace and provide CRDA, a userspace agent, which can be triggered to update the kernel wireless core's definition of the regulatory permissions for a specific country. Keeping the database in userspace allows distributions to provide updates without kernel upgrades. The database is shipped in binary form using a binary file format designed for size efficiency that also includes an integrity check; more details below. When the a regulatory domain change is detected (for example by observing an AP with country information), the kernel will request, from CRDA, the regulatory permissions for the new domain to enforce those at drivers.
For some hardware, regulatory permissions are programmed into the EEPROM, these can be observed as well, depending on the driver. Some drivers rely on EEPROM values for enforcement or calibration and drivers can continue to rely on these values by filtering the CRDA data according to the EEPROM settings. For these type of drivers, CRDA provides an extra layer of regulatory compliance, for instance when the card is in a laptop that roams between countries.
Country information in 802.11
Country Information Element
The Country Information Element (cf. 802.11-2007 7.3.2.9) contains the information required to allow a station to identify the regulatory domain in which the AP is located and to configure its PHY for operation in that regulatory domain. The Country IE contains, amongst other things, the list of permissions (channels and transmit power on those channels) and an ISO/IEC 3166-1 country code.
Design
The diagram below illustrates the current design of CRDA and its kernel interaction.
ASCII file format
Below is an example of a country entry for the db.txt regulatory file for EC (Ecuador)
country EC: (2402 - 2482 @ 40), (N/A, 20) (5170 - 5250 @ 20), (6, 17) (5250 - 5330 @ 20), (6, 23), DFS (5735 - 5835 @ 20), (6, 30)
Note that the frequency range (e.g. 2402-2482) covers the complete used bandwidth, so this definition allows using the 2 GHz channels 1 through 13 as 40 MHz channels. 5 GHz channels of a bandwidth of 20 MHz can be used if the frequencies used by the channel fit into the specified frequency ranges.
Binary file format
We define a new custom binary file format for use with CRDA, to have the data available quickly and as compact as possible as well as allowing to distribute the data along with the digital signature (see below) as easily as possible. The file format is defined in the regdb.h header file.
RSA Digital Signature
Integrity of the binary regulatory file is ensured by digitally signing the regulatory data using a private key and embedding the signature into the binary file. When the file is loaded by the regulatory daemon the signature is checked against a list of public keys built into the regulatory daemon binary.
Status
All code is ready for inclusion into Linux. Kernel integration patches were submitted.
Code
You can get the latest CRDA code from:
git://git.kernel.org/pub/scm/linux/kernel/git/mcgrof/crda.git
Usage design in Linux
In this section we cover how CRDA is used in Linux and how different types of drivers will cooperate with it.
Wireless core initialization
Upon the initialization of the wireless core (cfg80211) a world regulatory domain (highly restrictive) will be set as the central regulatory domain. If CRDA is present the latest dynamic world regulatory domain is queried from CRDA; if it is not then a statically defined list is used.
When a wiphy is registered to cfg80211 (possibly via mac80211) the effective set of permitted channels/maximum power is calculated for that device based on the current regulatory domain. As initially that will be the world regulatory domain, devices start out being restricted to that.
Setting the current regulatory domain
The Linux kernel wireless subsystem, at least in mac80211 [code still missing] effectively always enables the dot11MultiDomainCapabilityEnabled flag. Therefore, it tries to follow country information received in AP beacons.
Driver settings
Each driver can hint to the wireless core (cfg80211) which regulatory domain to set by providing an ISO-3166 alpha2 country code; this is intended to be used as a first start-up hint based on the device's EEPROM.
Conflicts can arise when you have multiple wireless devices present on a system which claim different regulatory domains. Arbitrarily complex algorithms could be invented to resolve such conflicts; for now the regulatory domain selected by the first wireless card is chosen. It would also be reasonable to let users resolve the conflict manually.
Once an alpha2 is suggested to the wireless core it will query CRDA for a regulatory domain for that alpha2. The wireless core will then iterate overall all registered wireless devices and update the device's list of enabled channels, max power, max bandwidth and max antenna gain for each of them.
After a regulatory domain has been set the notification chain is called and each registered callback informed of the event. Drivers have the option to register their callback for this notification chain to review the current regulatory settings and update them based on further requirements.
Drivers may also choose to build their own regulatory domain and pass this along to the wireless subsystem. This allows drivers which have no mapping of a regulatory domain to an ISO-3166 alpha2 country code to still be able to hint to the wireless core what regulatory restrictions it believes it should be abiding by.
802.11 country information
APs can provide an ISO/IEC 3166-1 country code and a channel list (with associated max tx power setting.) In practice though one can not always trust APs country information element regulatory information due to considerations for outdated data or rogue APs. Therefore, the wireless code determines the regulatory permissions based on the common denominator data from the APs country information element and what CRDA provides for the given country code.
Manual setting of the regulatory domain
Manual setting for a regulatory domain only makes sense if you have no AP capable of broadcasting regulatory information or if your card has no EEPROM regulatory information. To help these type of devices we can allow setting of the regulatory domain to help the user comply to regulatory rules. This can happen, for example, when you travel with a wireless card. For devices with their own EEPROM regulatory information the callback routine registered to the regulatory callback chain for the driver can ensure the EEPROM data is respected even if a user changes the regulatory information manually.
Driver initialization
As mentioned above, after the driver has registered to the wireless core (cfg80211) the world regulatory domain settings will have been set by default as no beacons with country information could have been received yet. Drivers should register all supported hardware channels to the wireless core.
Drivers with EEPROM regulatory information
Drivers that have country information in their EEPROM should provide an ISO/IEC 3166-1 alpha2 code to cfg80211 as a hint about the current regulatory domain. This can be done at any time, but should be done at hardware discovery or after wiphy registration.
For the special case where the EEPROM regulatory information must be observed at all times, the driver will not register any other channels.
In the special case where the EEPROM regulatory information must be observed unless 802.11 country information is received, the driver may register a regulatory notifier and restrict any information that CRDA supplied to the EEPROM information depending on the cause of the regulatory change.
Drivers without EEPROM regulatory information
Drivers with no EEPROM regulatory information can simply rely on the world regulatory domain, wait for an 802.11 country information or the user setting the regulatory domain manually.
Letting the kernel call CRDA
We use userspace events (uevents) to let he kernel speak to userspace. Below is an example udev rule you can place into your distribution's udev rules directory (usually /etc/udev/rules.d/). Note that most distributions have udev configured with inotify on the udev rules directory, so there is no need to restart udev after adding the new rule.
# Example file, should be put in /etc/udev/rules.d/regulatory.rules KERNEL=="regulatory*", ACTION=="change", SUBSYSTEM=="platform", RUN+="/sbin/crda"
Debugging kernel to CRDA communication
To debug communication between the kernel and udev you can monitor udev events:
udevadm monitor --environment kernel
License
CRDA is licensed under the ISC license in hopes other operating systems can benefit from a community project to enhance regulatory considerations.