Merging upstream version 3.2.5+dfsg.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 145 insertions, 0 deletions

diff --git a/raddb/mods-available/dpsk b/raddb/mods-available/dpsk
new file mode 100644
index 0000000..3cd8411
--- /dev/null
+++ b/raddb/mods-available/dpsk
@@ -0,0 +1,145 @@
+# -*- text -*-
+#
+#  $Id$
+
+#
+#  Calculate dynamic PSKs
+#
+#  This module needs the following attributes as input:
+#
+#	* control:Pre-Shared-Key -  the PSK for the user
+#	* User-Name - the supplicant MAC in hex format, e.g. "abcdef012345"
+#	* Called-Station-MAC - the AP MAC in binary
+#	  this attribute is set by the "rewrite_called_station_id" policy.
+#	* FreeRADIUS-802.1X-Anonce - from the AP
+#	* FreeRADIUS-802.1X-EAPoL-Key-Msg - from the AP
+#
+#  Note that you MUST run the "rewrite_called_station_id" policy before calling this module.
+#
+#  That policy MUST also create the Called-Station-MAC attribute.
+#
+#  Then place the following configuration into the "authorize" section:
+#
+#	authorize {
+#		...
+#		rewrite_called_station_id
+#
+#		update control {
+#			&PSK-Identity := "bob"
+#			&Pre-Shared-Key := "this-is-super-secret"
+#		}
+#		dpsk
+#
+#	}
+#
+#  And update the "authenticate" section to list the "dpsk" module:
+#
+#	authenticate {
+#		...
+#		dpsk
+#		...
+#	}
+#
+#  The module will return "fail" if the PSK is not correct.  It will return "ok"
+#  if the PSK is correct.
+#
+#  It also updates &reply:Pre-Shared-Key with the found key, along with
+#  &reply:PSK-Identity with the found identity.
+#
+#  We STRONGLY RECOMMEND THAT NO ONE USE THIS MODULE.
+#
+#  While it works, it needs to use a brute-force method to match MAC
+#  to PSK.  That process is extremely slow, and scales very poorly.
+#
+#  i.e. if you have 10 PSKs, it's not too bad.  If you have 10,000
+#  PSKs, then the module can comsume 100% of CPU trying to
+#  brute-force every PSK.
+#
+#  This is a limitation of how DPSK works.  There is no way to make it
+#  better.  The only thing we've done is to add a cache which can help
+#  to minimize the amount of brute-force attempts.
+#
+
+#
+#  The modules configuration.
+#
+dpsk {
+	#
+	#  The maximum number of entries to cache.
+	#
+	#  The cache is keyed by (supplicant MAC + SSID)
+	#
+	#  The cache entry is the PSK-Identity and Pre-Sharedd-Key,
+	#  and/or the PMK which are used to verify the information in
+	#  the Access-Request.
+	#
+	cache_size = 1024
+
+	#
+	#  The lifetime of an entry in the cache.
+	#
+	cache_lifetime = 86400
+
+	#
+	#  PSKs can also be stored in a CSV file.  The format of the file is:
+	#
+	#	identity,psk,mac
+	#
+	#  If there are commas in a field, then the field can be
+	#  double quoted: "psk".
+	#
+	#  The mac field is optional.  If it exists, then that PSK
+	#  will be used.  It is highly recommended that the MAC *not* be placed
+	#  into the CSV file.  Instead, the MAC and PSK should be placed into a
+	#  database.  The server can then be configured to look up the MAC in the
+	#  database, which returns the PSK.  That way this module will only ever
+	#  check one PSK, which is fast.
+	#
+	#  i.e. the CSV file should only contain the small number of PSKs where
+	#  you do not yet know the MAC.  As soon as you know the MAC, you should
+	#  put the MAC and PSK into a database, and then remove the MAC and PSK
+	#  from the CSV file.
+	#
+	#  NOTE: the file is opened and read from top to bottom for every
+	#  new request which comes in.  This process can be very slow!
+	#
+	#  However, opening the file for every new request means that the
+	#  server does not have to be reloaded when the file changes.  Instead,
+	#  the file can be generated, and then moved into place atomically:
+	#
+	# 	create csv file > psk.csv.new
+	#	mv psk.csv.new psk.csv
+	#
+	#  Any process which writes a new "psk.csv" file MUST NOT
+	#  write to the file directly, as that will cause the dpsk
+	#  module to read partial entries and fail.  Instead, use "mv"
+	#  to atomically overwrite the old file with a new one.
+	#
+	#  Both "cache_size" and "filename" can be configured at the
+	#  same time, which is recommended.  When an entry in the file
+	#  is found, the identity, PSK, and MAC are saved in the cache.
+	#
+	#  If a cache entry is found, then the filename is NOT read.
+	#
+	#  The resulting combination of features means that the module
+	#  should be as fast as possible, given the limitations of DPSK.
+	#
+	#  NOTE: Tests show that the module can do ~100K PSK / DPSK
+	#  checks per second.  This means that if you have 10,000
+	#  users and 10 packets a second, the system will be 100% busy
+	#  checking PSKs.
+	#
+	#  As a result, the DPSK functionality is scales poorly.  It
+	#  should be used only with a small number of PSKs (100s
+	#  perhaps), and only at low packet rates.  If the server is
+	#  getting 1000 packets per second, then it can only handle
+	#  100 PSKs before running out of CPU.
+	#
+	#  Using the cache will help substantially.  But the cache is
+	#  only in memory, which means that all cache entries are lost
+	#  when the server restarts.  As a result, the combination of
+	#  number of PSKs and packet rates should be kept as low as
+	#  possible.
+	#
+#	filename = "${modconfdir}/${..:name}/psk.csv"
+}