README

   1  Central Regulatory Domain Agent (CRDA)
   2 ========================================
   3
   4 This is the Central Regulatory Domain Agent for Linux. It serves one
   5 purpose: tell Linux kernel what to enforce. In essence it is a udev
   6 helper for communication between the kernel and userspace. You only
   7 need to run this manually for debugging purposes. For manual changing
   8 of regulatory domains use iw (iw reg set) or wpa_supplicant (feature
   9 yet to be added).
  10
  11  HOST REQUIREMENTS
  12 ===================
  13
  14 CRDA is provided as a binary file so all the host needs is libc/uclibc.
  15 You will also need udev and at least libnl1.
  16
  17  BUILD REQUIREMENTS
  18 ====================
  19
  20 The package build requirements currently are:
  21
  22  * python and the m2crypto package (python-m2crypto)
  23  * libgcrypt or libssl (openssl) header files
  24  * nl library and header files (libnl1 and libnl-dev)
  25    available at git://git.kernel.org/pub/scm/libs/netlink/libnl.git
  26  * RSA public key of John Linville, we include this as part of this package
  27    so you do not need to install it. This RSA public key comes
  28    from the wireless-regdb.git tree and we keep it up to date here.
  29  * regulatory database, clone this tree:
  30
  31    git://git.kernel.org/pub/scm/linux/kernel/git/linville/wireless-regdb.git
  32
  33    and then stuff regulatory.bin (no need to build) provided there in
  34    REG_BIN location specified in this Makefile. This regulatory.bin file
  35    is only required to verify the CRDA built here can read its database file
  36    which has been signed with the RSA private key.
  37
  38  CALLING CRDA -- UDEV
  39 ======================
  40
  41 Distributions can set up a udev rule to allow the kernel's regulatory
  42 domain change request to be reviewed by CRDA so CRDA can pass an
  43 appropriate regulatory domain. An example regulatory rule is provided
  44 with this package as regulatory.rules
  45
  46  OVERVIEW
  47 ==========
  48
  49 The database is maintained on the wireless-regdb.git tree. This git
  50 tree maintains a binary regulatory database file which is produced
  51 using its own ASCII db.txt into binary form for size efficiency. The
  52 contents of the binary database are then signed using the private key.
  53
  54 CRDA will use regulatory.bin if its signature checks out with the public
  55 key provided. This will prevent us from using corrupted data (in case
  56 of hard drive failure) in the running kernel. This separation between
  57 CRDA and the regulatory database also allows us to provide regulatory
  58 updates on distributions without having to require an update on CRDA.
  59
  60 Note that upon updating the regulatory database it is advised the
  61 user reboots or all the wireless modules get unloaded and reloaded.
  62
  63 Under certain circumstances it may be desirable to have the regulatory
  64 agent accept multiple keys, this can be achieved by stuffing all the keys
  65 desired into pubkeys. Right now we only use John Linville's public key.
  66
  67  REGDB AUTHORS
  68 ===============
  69
  70 Authors of regulatory.bin (John Linville) first need a private key, which can
  71 be generated with something like this:
  72
  73         openssl genrsa -out your.key.priv.pem 2048
  74
  75 You'll then need to generate the public key and publish it. You
  76 can generate it as follows:
  77
  78         openssl rsa -in your.key.priv.pem -out your.key.pub.pem -pubout -outform PEM
  79
  80 Then with this key you can generate regulatory.bin files like this:
  81
  82         ./utils/db2bin.py regulatory.bin db.txt your.key.priv.pem
  83
  84  MAGIC PATTERN
  85 ===============
  86
  87 Use the following magic(5) pattern to recognise CRDA binary regulatory
  88 database files:
  89
  90 ---- %< ----
  91 # CRDA Regulatory database file
  92 # http://git.kernel.org/?p=linux/kernel/git/mcgrof/crda.git;a=summary
  93 # (see regdb.h)
  94 0       belong          0x52474442      CRDA regulatory database file
  95 >4      belong          19              (Version 1)
  96 ---- >% ----