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

Implementation review

We take regulatory considerations seriously as its one of the major key components to getting proper vendor support on drivers due to fear uncertainty and doubt that Linux drivers cannot follow the requirements for radio spectrum use. For non-technical details on our position on regulatory support on Linux see our Linux wireless regulatory support statement. Despite the fact that drivers and hardware can have their own regulatory solutions we provide this framework as a safety net for regulatory considerations to account for changes and updates on regulatory rules world wide and to provide an API to allow drivers to export their own regulatory restrictions. Our regulatory infrastructure consists of three major components:

We embrace proper regulatory compliance in the Linux kernel by making it part of cfg80211, used by new wireless drivers. We maintain a thorough and flexible regulatory database in userspace and provide a Central Regulatory Domain Agent (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 RSA digital signature. When 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 on 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.

The diagram below illustrates best the current design of CRDA and its interaction kernel and the regulatory database.

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

Status

The new regulatory infrastructure went in as of 2.6.28, so CRDA can be used in kernels kernels >= 2.6.28. It is required for 802.11d operation in 2.6.29.

Code releases

Kernel integration

We have factored common regulatory driver code as part of the wireless stack and provided a way for a userspace agent to update the currently set regulatory domain. All new drivers registered with cfg80211 can reap benefits from this through cfg80211's regulatory support. mac80211 also uses this regulatory infrastructure to support 802.11d. An important component to Linux' own kernel integration is to allow drivers themselves to hint to the wireless core an alpha2 and have a callback to review the data passed by crda based on its own driver or EEPROM data. This allows vendors to use their own regulatory information to help enhance regulatory compliance even further. For more details on the Linux kernel integration see how you can set the regulatory domain.

CRDA

CRDA is our userspace agent which uploads regulatory domains into the kernel, it acts as a udev helper.

The regulatory database

CRDA requires a regulatory database (Web view or gitweb) to be build and maintained. Our hope is that this database can be used by other platforms (open or proprietary), not just Linux. John Linville maintains this database through the wireless-regdb git tree:

git://git.kernel.org/pub/scm/linux/kernel/git/linville/wireless-regdb.git

The regulatory.bin file there is signed with his RSA private key. We keep the RSA public key embedded as part of CRDA which allows us to verify the authorship and integrity of the regulatory database.

Releases of wireless-regdb

You can find official wireless-regdb releases here: http://wireless.kernel.org/download/wireless-regdb/

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. This ensures regulatory.bin file authorship and integrity.

Note that both CRDA and wireless-regdb allows you to build it without RSA key signature checking, if this is something you find useless then do not use them, but we advise against it. The reason RSA digital signature checks are an option and is what is recommend is that regulatory bodies are highly sensitive towards compliance and the current infrastructure we have gives us best effort on our part of doing the best we can to ensure integrity of the files and also gives us a mechanism to use files from trusted parties on-the-fly. Distribution packaging tends to guarantee file integrity upon installation time and from a specific source but it does not give you on-the-fly file integrity checks. Integrity checks are possible through alternate means such as simple CRC checks but you'd then need a list of all allowed CRCs, by using RSA digital signatures you get both file integrity checks for _any_ binary built with the private key by checking for the signature – and while at it you also can get file authorship protection – all of this while the file is being read for usage in memory. Distributions do not protect against file corruption after the files are in place, for example.

John Linville is the default trusted party in CRDA if you enable RSA digital signature checks because he is the maintainer of the Linux wireless subsystem and wireless-regdb. But note that CRDA lets you enable multiple trusted parties by letting you throw in alternative public keys into the pubkeys directory. If your distribution requires you to build your own regulatory.bin then simply add your own pubkey into the pubkeys. CRDA will then run using a regulatory.bin built by John Linville or your distribution's wirelss-regdb package maintainer's key. It would allows users to upgrade using your distribution's built regulatory.bin, or simply upgrade to using John's.

Sending updates to the regulatory database

If you find any errors please send them to the linux-wireless mailing list, either as patches to the db.txt file from the wireless-regdb git tree, or just tell us what is wrong in plain English.

Patches sent to the wireless-regdb git tree should be addressed as follows:

To: linville@tuxdriver.com
Cc: linux-wireless@vger.kernel.org
Subject: wireless-regdb: Update regulatory rules for France (FR) on 5GHz

Changing the database file format

To change the file format you will need to send patches to both crda (start off with regdb.h) and wireless-regdb/dbparse.py. You should send your patch as an RFC on the linux-wireless mailing list and CC both the wireless-regdb and crda maintainers.

Old regulatory implementation

This section exists to explain how we used to do things and to also explain what CONFIG_WIRELESS_OLD_REGULATORY is exactly. Prior to our new regulatory implementation explained throughout this page we had 3 static regulatory domains built-in to the Linux kernel for all cfg802111 drivers (therefore all mac80211 drivers). Apart from the 3 static regulatory domains in the old implementation we also gave users the option to set the regulatory domain via the ieee80211_regdom module parameter. We cover these details below.

Old static regulatory domains

The 3 old static regulatory domains we had implemented in-kernel were for:

  • US
  • EU
  • JP

By static regulatory domains we mean that they were defined in kernel-space and the only way to make changes due to regulatory updates by different countries was to send a patch for submission for inclusion into the Linux kernel. There are several downsides to this approach. We review them briefly below.

  • Country regulatory changes would need to accounted for completely in kernel space, requiring regulatory updates to be backported to older kernel releases.
  • Each country can have their own regulatory rules requiring an entry for each country or some conglomeration of countries into custom groups. This can lead to huge debates on implementation and efficiency – each vendor has their own set of custom regulatory domains to group regulatory information into groups, taking one vendor approach would imply preferring one implementation over another

  • Only accounted for countries in each kernel release would get proper regulatory consideration

Our initial implementation approach for our new regulatory infrastructure was to populate a regulatory domain in-kernel for each country. It was decided that it is a lot easier to deal with this in userspace and so that was one of the design changes for new regulatory implementation.

The ieee80211_regdom module parameter

Another old option for users from the old regulatory implementation was to set the regulatory domain using a module parameter for the cfg80211 module. The module parameter name is ieee80211_regdom. This module parameter only exists in 2.6.27, 2.6.28 when the CONFIG_WIRELESS_OLD_REGULATORY option is enabled.

It should be very well noted that this module parameter is from our old regulatory implementation. We now have a userspace API which allows userspace to inform the kernel what country you are in through nl80211. Currently two userspace applications exists that supports this, iw and wpa_supplicant. This new API is recommended to be used as the module parameter is schedule for removal for March 2010.

Feature removal

The 2.6.30 kernel will have CONFIG_WIRELESS_OLD_REGULATORY set to default to n. Our goal is to completely phase out CONFIG_WIRELESS_OLD_REGULATORY from the Linux kernel. To help with these efforts the ieee80211_regdom module parameter will become available to users without the CONFIG_WIRELESS_OLD_REGULATORY option, but when using the "EU" regulatory domain the user will world roam as "EU" is simply not an ISO / IEC 3166 country code.

If you are are married to the ieee80211_regdom module parameter then consider first abandoning using at least "EU", and plan for it to be removed completely from the Linux kernel.

CONFIG_WIRELESS_OLD_REGULATORY has been removed completely as of the 2.6.34 Linux kernel release. The alternative is to now build the regulatory database into the kernel itself, therefore not requiring a userspace agent. This is achieved with CFG80211_INTERNAL_REGDB.

Automatic country discovery

The Linux desktop is expected to advance to be able to discover what country it is in at any point in time and to pass this off to the kernel to enhance regulatory compliance. To aid with these efforts we had started a Google Summer of Code (GSoC) project for 2009 to help integrate GeoClue to the GNOME desktop. This project did not coplete but for details please see the GeoClue regulatory integration GSoC project.

Custom regulatory information

The Linux regulatory infrastructure was designed to allow compliance but to also address flexibility where a manufacturer customizes hardware or wants to sell hardware that works on a licensed band or a customized regulatory environment not covered by the usual world wide regulatory agencies. The regulatory infrastructure supports both authorship and file integrity, and allows third parties to distribute binary-only regulatory databases even with custom licenses as the software for it is licensed under a permissive license, the ISC license. Below we cover how to achieve all this.

Generating your own private and public key

You typically do not have to build the wireless-regdb, unless you want to attach a customized RSA signature based on your public key. You can generate your own public and private keys by building wireless-regdb. Below is an example of building wireless-regdb:

mcgrof@tux ~/devel/wireless-regdb (git::master)$ make
Generating private key for mcgrof...
openssl genrsa -out ~/.wireless-regdb-mcgrof.key.priv.pem 2048
Generating RSA private key, 2048 bit long modulus
..........................+++
.....................................................................................................+++
e is 65537 (0x10001)
Generating public key for mcgrof...
openssl rsa -in ~/.wireless-regdb-mcgrof.key.priv.pem -out mcgrof.key.pub.pem -pubout -outform PEM
writing RSA key
Generating regulatory.bin digitally signed by mcgrof...
./db2bin.py regulatory.bin db.txt ~/.wireless-regdb-mcgrof.key.priv.pem

On this example the build produced three files:

  • ~mcgrof/.wireless-regdb-mcgrof.key.priv.pem - the RSA private key
  • mcgrof.key.pub.pem - the RSA public key
  • regulatory.bin - digitally signed binary regulatory database

The private key is built into your home directory by default. The public key is built into the wireless-regdb directory. The binary wireless regulatory database is then built and then digitally sign it using your private key. On future builds only a binary regulatory database file will be built.

Importing your public key into CRDA

CRDA has a directory, pubkeys of all trusted public keys it can use to embed onto the binary for RSA signature verification against any particular binary regulatory database. This is used to allow CRDA to trust different authors for regulatory information. By default John Linville's key is always present on the pubkeys directory. You can remove it if for your particular application you cannot trust the upstream community regulatory database information.

To import your public key then all you have to do is copy it into the pubkeys directory prior to building CRDA:

mcgrof@tux ~/devel/crda (git::master)$ cp ../wireless-regdb/mcgrof.key.pub.pem pubkeys/

Building using extra public keys

To build CRDA with extra public keys just run make with the list of public keys you trust in the pubkeys directory. For example to build wireless-regdb with a custom mcgrof.key.pub.pem stuffed into the pubkeys directory you would do:

mcgrof@tux ~/devel/crda (git::master)$ make
  GEN  keys-gcrypt.c
  Trusted pubkeys: pubkeys/linville.key.pub.pem pubkeys/mcgrof.key.pub.pem
  CC   reglib.o
  CC   crda.o
  LD   crda
  CC   intersect.o
  CC   print-regdom.o
  LD   intersect
  CC   regdbdump.o
  LD   regdbdump
  CHK  /usr/lib/crda/regulatory.bin

Redistribution licenses

Since both wireless-regdb and CRDA are licensed under a permissive license, the ISC license, you can choose to modify wireless-regdb, create your own keys and redistribute only the binary regulatory.bin without providing the source code or keys.

You can do the same with crda, provide a custom built binary crda with your public key attached and never provide the source code. Technically an entity creating custom regulatory database should only need to provide its own public key and allow end users to always embed it into their pubkeys directory. That would suffice for allowing the end users to build a CRDA to trust any of your binary-only regulatory databases.


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, v66, v65, v64, v63, v62, v61, v60, v59, v58, v57, v56, v55, v54, 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