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

Central Regulatory Domain Agent

The Central Regulatory Domain Agent (CRDA) is a FOSS project to allow Linux (and possibly other OSes) to obey frequency use regulations around the world when software can play a role in helping enforce regulatory considerations. This also helps vendors support Linux who previously rejected open Linux drivers due to regulatory considerations by dealing with regulatory considerations directly through the wireless subsystem.

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 roames 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.

http://wireless.kernel.org/crda.png

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.

License

CRDA is licensed under the ISC license in hopes other operating systems can benefit from a community project to enhance regulatory considerations.


This is a static dump of the wiki, taken after locking it in January 2015. The new wiki is at https://wireless.wiki.kernel.org/.
versions of this page: last, v53, v52, v51, v50, v49, v48, v47, v46, v45, v44, v43, v42, v41, v40, v39, v38, v37, v36, v35, v34, v33, v32, v31, v30, v29, v28, v27, v26, v25, v24, v23, v22, v21, v20, v19, v18, v17, v16, v15, v14, v13, v12, v11, v10, v9, v8, v7, v6, v5, v4, v3, v2, v1