README

   1  Central Regulatory Domain Agent (CRDA)
   2 ========================================
   3
   4 This is the Central Regulatory Domain Agent for Linux. It serves two
   5 purposes: keep a database of world-wide regulatory information and
   6 tell the Linux kernel what to enforce.
   7
   8  HOST REQUIREMENTS
   9 ===================
  10
  11 CRDA is provided as a binary file so all the host needs is libc/uclibc.
  12
  13  BUILD REQUIREMENTS
  14 ====================
  15
  16 The package build requirements currently are:
  17
  18  * python and the m2crypto package (python-m2crypto)
  19  * libgcrypt or libssl (openssl) header files
  20  * nl library and header files (libnl1 and libnl-dev)
  21    available at git://git.kernel.org/pub/scm/libs/netlink/libnl.git
  22
  23 If you want to put up a web site with a database viewer using MoinMoin:
  24
  25  * MoinMoin (http://moinmo.in) for the web viewer
  26
  27  CALLING CRDA -- UDEV
  28 ======================
  29
  30 Distributions can set up a udev rule to allow the kernel's regulatory
  31 domain change request to be reviewed by CRDA so CRDA can pass an
  32 appropriate regulatory domain. An example regulatory rule is provided
  33 with this package as regulatory.rules
  34
  35  OVERVIEW
  36 ==========
  37
  38 The regulatory information is collected in a text file, `db.txt'. This
  39 text file is then compiled into a binary database `regulatory.bin' and
  40 digitally signed with the key in `key.priv.pem'. The binary database
  41 is then used by the regulatory agent to update the in-kernel enforcement
  42 table.
  43
  44  TECHNICAL INFORMATION
  45 =======================
  46
  47 The regulatory information in `db.txt' is stored in a human-readable
  48 format which can be read using the `dbparse.py' python module. This
  49 python module is used by the web viewer (web/Regulatory.py) which is
  50 implemented as a MoinMoin macro (and used on http://wireless.kernel.org)
  51 to allow viewing the database for verification.
  52
  53 The dbparse module is also used by db2bin.py, the `compiler', which
  54 compiles and signs the binary database.
  55
  56 The binary database file format is described in `regdb.h' (which has
  57 to be kept in sync with the compiler.
  58
  59 The key file, key.priv.pem, has to be an RSA key, for example created
  60 with openssl using `openssl genrsa -out key.priv.pem 1024'. Building
  61 without such a key file causes the test-key to be used to allow the
  62 build to succeed without generating a key first. This key is not meant
  63 to be used for deployments, however.
  64
  65 Under certain circumstances it may be desirable to have the regulatory
  66 agent accept multiple keys, this can be achieved by compiling it when
  67 more than one key is present in the source directory (named *.pem). In
  68 this case, the agent will accept a signature of any of those keys.
  69
  70  REGULATORY COMPLIANCE
  71 =======================
  72
  73 It is important to note that the current provided regulatory information
  74 should be used as a guide. With the help of the community we are sure
  75 to keep this database more up to date but even then some vendors tend
  76 to have calibrated power limits embedded in their wireless card's EEPROMs
  77 and these must be read by firmware or host software for proper compliance.
  78
  79 EEPROMs tend to have embedded on them what might usually be called
  80 "compliance limits". Careful consideration must be made to ensure
  81 they are used properly. These compliance limits provide calibrated
  82 power values for *all* frequency ranges, not only for band edges.
  83 These compliance limits should be taken into consideration and used
  84 for proper compliance.
  85
  86 We might be able to provide a framework in the future for drivers to
  87 use generic non-vendor specific data to help with compliance limits
  88 but a general audit must first be made upon how these compliance
  89 limits are handled by each vendor.
  90
  91  DFS SUPPORT AND ADDITIONAL FLAGS
  92 ==================================
  93
  94 DFS support must be provided to be able to use many 5 GHz frequency
  95 channels. We can rely statically on the 5260 MHz - 5700 MHz frequency
  96 range to demand globally DFS support. If complete DFS is not supported
  97 as part of a WLAN stack then effort must be made to ensure that the
  98 following restrictions be made:
  99
 100   * If a STA does not have DFS, disable active scanning (probe requests)
 101     for the DFS frequency range.
 102
 103   * If an Ad-hoc station does not have DFS support, disable Ad-hoc
 104     and active scanning for the DFS frequency range.
 105
 106   * If an AP does not have DFS support disable AP support for the
 107     DFS frequency range.
 108
 109 These rules should be taken as basic guidelines.
 110
 111  MAGIC PATTERN
 112 ===============
 113
 114 Use the following magic(5) pattern to recognise CRDA binary regulatory
 115 database files:
 116
 117 ---- %< ----
 118 # CRDA Regulatory database file
 119 # http://git.kernel.org/?p=linux/kernel/git/mcgrof/crda.git;a=summary
 120 # (see regdb.h)
 121 0       belong          0x52474442      CRDA regulatory database file
 122 >4      belong          19              (Version 1)
 123 ---- >% ----