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 plays a role in enforcing regulations. 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 AR (Argentina).

country AR:
        (2402 - 2482 @ 40), (N/A, 20), NO-HT40
        (5270 - 5330 @ 40), (6, 17), NO-HT40
        (5735 - 5815 @ 40), (6, 30), NO-HT40

Note that the frequency range (e.g. 2402-2482) covers the complete used bandwidth, so this definition allows using channels 1 through 13 as 20 MHz channels and channels 3 through 11 as 40 MHz channels.

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

The userspace agent components of parsing a db.txt, implementing RSA digital signature support and defining a file format are all complete. A guide db.txt is also available. What is left:

  • Integration with the kernel
  • Write the userspace agent the kernel will communicate with

A first patch for RFC has been posted, follows are expected soon.

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.

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.


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