CRDA 802.11 Regulatory Management

CRDA 802.11 Regulatory Management

What is CRDA?

Central Regulatory Domain Agent

CRDA acts as the udev helper for communication between the kernel and userspace for regulatory compliance. It relies on nl80211 for communication. CRDA is intended to be run only through udev communication from the kernel. The user should never have to run it manually except if debugging udev issues.

https://wireless.wiki.kernel.org/en/developers/regulatory/crda

Configs in Kernel

• CONFIG_CFG80211_CRDA_SUPPORT

To support CRDA or ‘iw reg set/get’ commands, user should enable this config, otherwise enable the config below.

• CONFIG_CFG80211_INTERNAL_REGDB

  If you do not want to install CRDA on a host, you can simply enable the CONFIG_CFG80211_INTERNAL_REGDB on your kernel.

• CONFIG_CFG80211_REG_DEBUG [ It seems has been deprecated in kernel 4.9], but in previous version the following message can be output if enable this config.

[    7.145061] cfg80211: Calling CRDA to update world regulatory domain
[    7.215262] cfg80211: World regulatory domain updated:
[    7.220425] cfg80211:  DFS Master region: unset
[    7.224779] cfg80211:   (start_freq - end_freq @ bandwidth), (max_antenna_gain, max_eirp), (dfs_cac_time)
[    7.234573] cfg80211:   (2402000 KHz - 2472000 KHz @ 40000 KHz), (N/A, 2000 mBm), (N/A)
[    7.242615] cfg80211:   (2457000 KHz - 2482000 KHz @ 40000 KHz), (N/A, 2000 mBm), (N/A)
[    7.250672] cfg80211:   (2474000 KHz - 2494000 KHz @ 20000 KHz), (N/A, 2000 mBm), (N/A)
[    7.258745] cfg80211:   (5170000 KHz - 5250000 KHz @ 80000 KHz, 160000 KHz AUTO), (N/A, 2000 mBm), (N/A)
[    7.268289] cfg80211:   (5250000 KHz - 5330000 KHz @ 80000 KHz, 160000 KHz AUTO), (N/A, 2000 mBm), (0 s)
[    7.277838] cfg80211:   (5490000 KHz - 5730000 KHz @ 160000 KHz), (N/A, 2000 mBm), (0 s)
[    7.285977] cfg80211:   (5735000 KHz - 5835000 KHz @ 80000 KHz), (N/A, 2000 mBm), (N/A)
[    7.293983] cfg80211:   (57240000 KHz - 63720000 KHz @ 2160000 KHz), (N/A, 0 mBm), (N/A)

• CONFIG_CFG80211_DEBUGFS

The following debug files are showed if the config is switched on.

root@am57xx-evm:/sys/kernel/debug/ieee80211/phy0# ls
fragmentation_threshold  ht40allow_map            long_retry_limit         rts_threshold            short_retry_limit

• CONFIG_CFG80211_DEVELOPER_WARNINGS

• CONFIG_CFG80211_REG_CELLULAR_HINTS

• CONFIG_CFG80211_REG_RELAX_NO_IR

bool cfg80211_reg_can_beacon_relax(struct wiphy *wiphy,
                                   struct cfg80211_chan_def *chandef,
                                   enum nl80211_iftype iftype)
{
        bool check_no_ir;

        ASSERT_RTNL();

        /*
         * Under certain conditions suggested by some regulatory bodies a
         * GO/STA can IR on channels marked with IEEE80211_NO_IR. Set this flag
         * only if such relaxations are not enabled and the conditions are not
         * met.
         */
        check_no_ir = !cfg80211_ir_permissive_chan(wiphy, iftype,
                                                   chandef->chan);

        return _cfg80211_reg_can_beacon(wiphy, chandef, iftype, check_no_ir);
}

/*
 * Check if the channel can be used under permissive conditions mandated by
 * some regulatory bodies, i.e., the channel is marked with
 * IEEE80211_CHAN_IR_CONCURRENT and there is an additional station interface
 * associated to an AP on the same channel or on the same UNII band
 * (assuming that the AP is an authorized master).
 * In addition allow operation on a channel on which indoor operation is
 * allowed, iff we are currently operating in an indoor environment.
 */
static bool cfg80211_ir_permissive_chan(struct wiphy *wiphy,
                    enum nl80211_iftype iftype,
                    struct ieee80211_channel *chan)
{
    struct wireless_dev *wdev;
    struct cfg80211_registered_device *rdev = wiphy_to_rdev(wiphy);

    ASSERT_RTNL();

    if (!IS_ENABLED(CONFIG_CFG80211_REG_RELAX_NO_IR) ||
        !(wiphy->regulatory_flags & REGULATORY_ENABLE_RELAX_NO_IR))
        return false;

    /* only valid for GO and TDLS off-channel (station/p2p-CL) */
    if (iftype != NL80211_IFTYPE_P2P_GO &&
        iftype != NL80211_IFTYPE_STATION &&
        iftype != NL80211_IFTYPE_P2P_CLIENT)
        return false;

    if (regulatory_indoor_allowed() &&
        (chan->flags & IEEE80211_CHAN_INDOOR_ONLY))
        return true;

    if (!(chan->flags & IEEE80211_CHAN_IR_CONCURRENT))
        return false;

    /*
     * Generally, it is possible to rely on another device/driver to allow
     * the IR concurrent relaxation, however, since the device can further
     * enforce the relaxation (by doing a similar verifications as this),
     * and thus fail the GO instantiation, consider only the interfaces of
     * the current registered device.
     */
    list_for_each_entry(wdev, &rdev->wiphy.wdev_list, list) {
        struct ieee80211_channel *other_chan = NULL;
        int r1, r2;

        wdev_lock(wdev);
        if (wdev->iftype == NL80211_IFTYPE_STATION &&
            wdev->current_bss)
            other_chan = wdev->current_bss->pub.channel;

        /*
         * If a GO already operates on the same GO_CONCURRENT channel,
         * this one (maybe the same one) can beacon as well. We allow
         * the operation even if the station we relied on with
         * GO_CONCURRENT is disconnected now. But then we must make sure
         * we're not outdoor on an indoor-only channel.
         */
        if (iftype == NL80211_IFTYPE_P2P_GO &&
            wdev->iftype == NL80211_IFTYPE_P2P_GO &&
            wdev->beacon_interval &&
            !(chan->flags & IEEE80211_CHAN_INDOOR_ONLY))
            other_chan = wdev->chandef.chan;
        wdev_unlock(wdev);

        if (!other_chan)
            continue;

        if (chan == other_chan)
            return true;

        if (chan->band != NL80211_BAND_5GHZ)
            continue;

        r1 = cfg80211_get_unii(chan->center_freq);
        r2 = cfg80211_get_unii(other_chan->center_freq);

        if (r1 != -EINVAL && r1 == r2) {
            /*
             * At some locations channels 149-165 are considered a
             * bundle, but at other locations, e.g., Indonesia,
             * channels 149-161 are considered a bundle while
             * channel 165 is left out and considered to be in a
             * different bundle. Thus, in case that there is a
             * station interface connected to an AP on channel 165,
             * it is assumed that channels 149-161 are allowed for
             * GO operations. However, having a station interface
             * connected to an AP on channels 149-161, does not
             * allow GO operation on channel 165.
             */
            if (chan->center_freq == 5825 &&
                other_chan->center_freq != 5825)
                continue;
            return true;
        }
    }

    return false;
}

• CONFIG_CFG80211_CERTIFICATION_ONUS

  The CONFIG_CFG80211_CERTIFICATION_ONUS is available for features which require additional regulatory compliance testing and validation by the system integrator. This allows us to define 802.11 specific kernel features under a flag that is intended by design to be disabled by standard Linux distributions, and only enabled by system integrators or distributions that have done work to ensure regulatory certification on the system with the enabled features. Regulatory verification may at times only be possible until you have the final system in place. Examples of features which depend on this option are DFS, cellular base station regulatory hints, custom 802.11 research features, and OEM / ODM chip verification features useful for testing / validation.

• CONFIG_ATH10K_DFS_CERTIFIED

Debugging kernel to CRDA communication

To debug communication between the kernel and udev you can monitor udev events:

udevadm monitor –environment kernel

You should not use this command instead:

iw event -t

The following information is prompted when run ‘iw reg set “00”’:

root@am57xx-evm:~# udevadm monitor --environment kernel
monitor will print the received events for:
UDEV - the event which udev sends out after rule processing
KERNEL - the kernel uevent

KERNEL[2042.698250] change   /devices/platform/regulatory.0 (platform)
ACTION=change
COUNTRY=00
DEVPATH=/devices/platform/regulatory.0
MODALIAS=platform:regulatory
SEQNUM=3461
SUBSYSTEM=platform

UDEV  [2042.728933] change   /devices/platform/regulatory.0 (platform)
ACTION=change
COUNTRY=00
DEVPATH=/devices/platform/regulatory.0
MODALIAS=platform:regulatory
SEQNUM=3461
SUBSYSTEM=platform
USEC_INITIALIZED=2042704085

How to change regulatory domain

• Using iw to change regulatory domains

  You can use iw from the command line as follows:

  iw reg set US

• Using wpa_supplicant to change regulatory domains

  Get the wpa_supplicant (as of 0.6.7) and then add as part of your configuration file a line that has something like this:

  COUNTRY=US

• Set with module parameter

  Although modern kernels do support the ieee80211_regdom module parameter. distributions are encouraged to use userspace utilties to supply country hints instead since in the future the Linux desktop may be providing userspace regulatory hints by default.

• Kernel initiated regulatory change, like Beacon hints
  The kernel side initiate the domain change when receiving a beacon hint from AP. It is also important to note that the Linux kernel beacon hint mechanism only trusts beacons from 802.11 APs, not Mesh or IBSS. Specifically, the Linux kernel beacon hint mechanism ensures that the beacon ESS capability is set:

  if (res->pub.capability & WLAN_CAPABILITY_ESS)                          
          regulatory_hint_found_beacon(wiphy, channel, gfp);
  

Regulatory Applying Procedure

When user space change the regulatory domain using above commands, the kernel report a udev event back to user space and then ‘/usr/sbin/crda’ is called if the following udev rule has been added to /etc/udev/rules.d/ or /lib/udev/rule.d/.

KERNEL=="regulatory*", ACTION=="change", SUBSYSTEM=="platform", RUN+="/usr/sbin/crda"

The /usr/sbin/crda will read /usr/lib/crda/regulatory.bin, check its signature with public keys stored in /etc/wireless-regdb/pubkeys/ folder, and then apply the regulatory limitations.

Note: the new version of wireless-regdb install the public keys into /lib/crda/pubkeys/ instead.

Look at the picture https://wireless.wiki.kernel.org/en/developers/regulatory, which structures the CRDA related components.

Look the regulator processing rule: https://wireless.wiki.kernel.org/en/developers/regulatory/processing_rules.

Summary the regulatory applying rule:
1. Initially,the most strict domain is applied by cfg80211, i.e world domian - 00.
2. Drivers should register all supported hardware channels to the wireless core.
3. 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 should be done after wiphy registration.
4. for now the regulatory domain selected by the first wireless card is chosen and if cards have their own regulatory domain that regulatory domain is always respected for that card.
5. 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.
6. 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. The core (cfg80211) issuing regulatory_hint_11d() when processing an AP’s IEs.