 Central Regulatory Domain Agent (CRDA)
========================================

This is the Central Regulatory Domain Agent for Linux. It serves two
purposes: keep a database of world-wide regulatory information and
tell the Linux kernel what to enforce.

 HOST REQUIREMENTS
===================

CRDA is provided as a binary file so all the host needs is libc/uclibc.

 BUILD REQUIREMENTS
====================

The package build requirements currently are:

 * python and the m2crypto package (python-m2crypto)
 * libgcrypt or libssl (openssl) header files
 * nl library and header files (libnl1 and libnl-dev)
   available at git://git.kernel.org/pub/scm/libs/netlink/libnl.git

If you want to put up a web site with a database viewer using MoinMoin:

 * MoinMoin (http://moinmo.in) for the web viewer

 CALLING CRDA -- UDEV
======================

Distributions can set up a udev rule to allow the kernel's regulatory
domain change request to be reviewed by CRDA so CRDA can pass an
appropriate regulatory domain. An example regulatory rule is provided
with this package as regulatory.rules

 OVERVIEW
==========

The regulatory information is collected in a text file, `db.txt'. This
text file is then compiled into a binary database `regulatory.bin' and
digitally signed with the key in `key.priv.pem'. The binary database
is then used by the regulatory agent to update the in-kernel enforcement
table.

 TECHNICAL INFORMATION
=======================

The regulatory information in `db.txt' is stored in a human-readable
format which can be read using the `dbparse.py' python module. This
python module is used by the web viewer (web/Regulatory.py) which is
implemented as a MoinMoin macro (and used on http://wireless.kernel.org)
to allow viewing the database for verification.

The dbparse module is also used by db2bin.py, the `compiler', which
compiles and signs the binary database.

The binary database file format is described in `regdb.h' (which has
to be kept in sync with the compiler.

The key file, key.priv.pem, has to be an RSA key, for example created
with openssl using `openssl genrsa -out key.priv.pem 1024'. Building
without such a key file causes the test-key to be used to allow the
build to succeed without generating a key first. This key is not meant
to be used for deployments, however.

Under certain circumstances it may be desirable to have the regulatory
agent accept multiple keys, this can be achieved by compiling it when
more than one key is present in the source directory (named *.pem). In
this case, the agent will accept a signature of any of those keys.

 REGULATORY COMPLIANCE
=======================

It is important to note that the current provided regulatory information
should be used as a guide. With the help of the community we are sure
to keep this database more up to date but even then some vendors tend
to have calibrated power limits embedded in their wireless card's EEPROMs
and these must be read by firmware or host software for proper compliance.

EEPROMs tend to have embedded on them what might usually be called
"compliance limits". Careful consideration must be made to ensure
they are used properly. These compliance limits provide calibrated
power values for *all* frequency ranges, not only for band edges.
These compliance limits should be taken into consideration and used
for proper compliance.

We might be able to provide a framework in the future for drivers to
use generic non-vendor specific data to help with compliance limits
but a general audit must first be made upon how these compliance
limits are handled by each vendor.

 DFS SUPPORT AND ADDITIONAL FLAGS
==================================

DFS support must be provided to be able to use many 5 GHz frequency
channels. We can rely statically on the 5260 MHz - 5700 MHz frequency
range to demand globally DFS support. If complete DFS is not supported
as part of a WLAN stack then effort must be made to ensure that the
following restrictions be made:

  * If a STA does not have DFS, disable active scanning (probe requests)
    for the DFS frequency range.

  * If an Ad-hoc station does not have DFS support, disable Ad-hoc
    and active scanning for the DFS frequency range.

  * If an AP does not have DFS support disable AP support for the
    DFS frequency range.

These rules should be taken as basic guidelines.

 MAGIC PATTERN
===============

Use the following magic(5) pattern to recognise CRDA binary regulatory
database files:

---- %< ----
# CRDA Regulatory database file
# http://git.kernel.org/?p=linux/kernel/git/mcgrof/crda.git;a=summary
# (see regdb.h)
0	belong		0x52474442	CRDA regulatory database file
>4	belong		19		(Version 1)
---- >% ----
