summaryrefslogtreecommitdiffstats
path: root/raddb/mods-available/dpsk
blob: 3cd8411403b3ddd5ad6c65186cae9f91b847bd78 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
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"
}