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