12. A Wi-Fi Passphrase per Person

Scenario: the office has a WPA2-PSK SSID (the kind you join by typing a passphrase). Printers, TVs and visitors’ devices cannot do 802.1X, so it cannot become the enterprise Wi-Fi of chapter 3; but the whole company shares one passphrase, and every time someone leaves, it has to be reset for everyone.

Instead, give each person their own passphrase, on the same SSID (vendors call this DPSK, iPSK, MPSK or PPSK):

  • Each person joins the same SSID with their own passphrase; rradius recognises who it is from the passphrase and puts them into a VLAN by person.
  • When someone leaves, only their passphrase is stopped; nobody else is affected.
  • Devices need not register their MAC first.

Access points do this in one of two ways, depending on which your AP supports:

ApproachWhat the AP sends to rradiusMust devices register firstWhere in this chapter
Find the passphrase from the 4-way handshakeThe handshake of the connection (the ANonce and the 2nd EAPOL frame)NoThe main approach, [radius.dpsk]
Reply with the passphrase by MACThe device’s MAC addressYesThe second approach

The 4-way handshake is how the device and the AP prove to each other that they know the passphrase; the passphrase itself is never sent. rradius tries each person’s key, and the one that produces the same result belongs to this person.

Example directory: rradius-server/examples/scenarios/psk-wifi/

FileContents
rradius.toml[radius.dpsk], one client for each kind of AP, [accounts] (disabling and enabling people), [accounts.dpsk] (keys)
setup.shCreates dpsk.key and sealed demo data
mac-psk.luaThe script for the second approach
migrations/1_schema.sqlpeople (people and VLANs), dpsk_keys (each person’s keys), device_psk (passphrases by MAC), accounting

Steps

1. Create the key and demo data

cd rradius-server
cargo build --release
examples/scenarios/psk-wifi/setup.sh

It does two things:

  • Creates dpsk.key: the master key used to seal keys, 64 hexadecimal characters, mode 0600.
  • Seals the passphrases of three demo people with rradius-server dpsk-seal, writing migrations/2_demo_keys.sql.

Neither file is in the repository: the master key must not be public, and sealed values go with the master key. Existing files are not overwritten: replace the master key and the old data no longer opens.

With a release archive, setup.sh finds bin/rradius-server by itself; when it lives elsewhere, set RRADIUS_SERVER=/path/to/rradius-server.

2. Start

./target/release/rradius-server --config examples/scenarios/psk-wifi/rradius.toml

3. Test

A 4-way handshake cannot be simulated with radtest; testing it takes a supporting AP and a device. The automated test replays a handshake recorded beforehand (computed by a separate, independent program from bob-passphrase) and checks:

RequestResult
bob’s handshake, SSID officeAccess-Accept, VLAN 30, and Tunnel-Password decrypts to bob’s PMK
The same handshake with one bit changedAccess-Reject: nobody’s passphrase matches
The same handshake with SSID guestAccess-Reject: this SSID has no keys
After user disable bobAccess-Reject, effective at once
After user enable bobAccess-Accept
After dpsk delete --ssid office bobStill Access-Accept (the key the device matched last time is remembered); Access-Reject after SIGHUP
After dpsk add --ssid office bob (passphrase bob-passphrase)Access-Accept

The authentication log says who was recognised:

authentication protocol="radius" client="office-aps" source=10.35.0.7 user="020000000099" account="bob" chain="default" handler="dpsk" decision="accept"

user is the name the AP sent (usually the device’s MAC), and account is the person whose passphrase matched.

The configuration explained

[radius.dpsk]
candidates_query = "SELECT identity, pmk FROM dpsk_keys WHERE ssid = ? LIMIT 10000"
key_file = "dpsk.key"
cache_lifetime_ms = 3600000
max_candidates = 10000
  • candidates_query returns (identity, sealed PMK) for everyone on this SSID. ? is filled with the SSID. rradius tries them one by one in order, at most max_candidates.
  • Add a LIMIT to the query yourself. max_candidates only limits how many are tried; the query results are still read in full.
  • What a PMK is: the key WPA2 actually uses, computed from the passphrase and the SSID. Storing PMKs rather than passphrases means nothing has to be recomputed for each comparison (recomputing takes a few milliseconds each, far too slow across ten thousand people). Whoever has a PMK can join that SSID, so the table holds only sealed values; values that are not sealed do not open and are skipped.
  • key_file is the master key used for sealing. Every node needs the same one, with permissions such as 0600, 0640 or 0400, or startup fails. Back it up separately: it is not in the database, and losing it means everyone has to reset their passphrase.
  • cache_lifetime_ms: the key each device matched last time on this SSID is remembered and tried first next time, without a database query. When it does not match (the device changed passphrase), it is forgotten and the search starts over.

How fast: measured on a development machine, trying ten thousand candidates takes about 11 milliseconds, fifty thousand about 55 milliseconds; using the remembered key takes under 1 microsecond. At most 4 searches run at once; further requests are dropped and the AP retransmits. How long APs and devices are willing to wait during the handshake varies by vendor and has not been confirmed on real hardware; with many people, measure first. The measurements are in usage section 2.15.

Once matched: may this person connect

[[auth.handlers]]
type = "sql"
user_query = "SELECT NULL FROM people WHERE identity = ?"
certificate_query = "SELECT 1 FROM people WHERE identity = ? AND enabled = 1"
reply_query = """WITH p AS (SELECT vlan FROM people WHERE identity = ?)
  SELECT 'Tunnel-Type:1', 'VLAN' FROM p
  UNION ALL SELECT 'Tunnel-Medium-Type:1', 'IEEE-802' FROM p
  UNION ALL SELECT 'Tunnel-Private-Group-Id:1', vlan FROM p"""

A matching passphrase only proves “this is bob”. The identity then goes to this client’s authentication chain as an already proven name, just as with a certificate login:

  • certificate_query accepts when it finds a row. Put the disabled condition here (enabled = 1), so disabling a person takes effect at once, without waiting for remembered keys to expire.
  • reply_query gives the person’s VLAN. reply_query can have only one ?, so WITH looks it up once and returns three rows.
  • user_query is required, but this SSID has no user name and password logins. The example makes the password column always NULL: any request with just a name and password is rejected.
  • When a script decides, the eap_method it sees is 'dpsk', and get_attr('User-Name') is the matched identity.
  • On accept, rradius adds the PMK to the reply automatically so the AP can complete the handshake: Tunnel-Password for hostapd requests, Ruckus-DPSK for Ruckus. You do not set these attributes yourself.
  • When nobody matches, the answer is an Access-Reject straight away, without the chain or script.

Adding, disabling and changing passphrases

Adding a person

# Add dave to the people table first (decide his VLAN, see below), then add his key for office.
printf '%s\n' 'dave-passphrase' | rradius-server dpsk add --config rradius.toml --ssid office dave
# added key of dave for office
  • The passphrase is read from standard input, not given as an argument (arguments stay in the shell history). On a terminal it asks twice without echoing. A passphrase is 8 to 63 printable ASCII characters, or a PSK of 64 hexadecimal characters.

  • What goes into the table is the sealed PMK, bound to the identity and the SSID, so moved to someone else’s name or another SSID it does not open. To use the same passphrase on two SSIDs, run it once for each. The passphrase itself is never stored.

  • Run it on a host that has key_file, usually a node itself. The write goes through the cluster, so every node sees it at once, with no restart.

  • The SQL it runs is set in [accounts.dpsk]: ?1 is the identity, ?2 the SSID, ?3 the sealed PMK. The example:

    [accounts.dpsk]
    add = "INSERT INTO dpsk_keys (identity, ssid, pmk) VALUES (?1, ?2, ?3)"
    passwd = "UPDATE dpsk_keys SET pmk = ?3 WHERE identity = ?1 AND ssid = ?2"
    delete = "DELETE FROM dpsk_keys WHERE identity = ?1 AND ssid = ?2"
    show = "SELECT identity, ssid FROM dpsk_keys WHERE identity = ?1 AND ssid = ?2"
    

    delete and show may leave out ?2 to handle all of a person’s SSIDs at once; the command still needs --ssid, which is then not filled in, and the result reads deleted keys of bob. The full rules are in section 2.14 of the reference document.

  • The person’s row is in the people table, which decides whether they may connect and their VLAN. The example’s [accounts] sets only enable, disable and show; to add people with user add, add an add to [accounts] that writes people (it expects a password value, which this scenario does not use; write it to an unused column, or add people with SQL directly).

  • Bulk imports can still use dpsk-seal to produce sealed values and write them as a migration file (common for the first go-live; see how setup.sh does it).

Disabling and enabling

rradius-server user disable --config rradius.toml bob
rradius-server user enable --config rradius.toml bob
rradius-server user show --config rradius.toml bob

The example’s [accounts] changes enabled in the people table. It takes effect across the cluster at once, and the next connection is rejected. Devices already connected are not kicked off; that waits until they reconnect (roaming, waking from sleep). To disconnect them at once, see CoA in chapter 7.

Changing and deleting

printf '%s\n' 'new-passphrase' | rradius-server dpsk passwd --config rradius.toml --ssid office bob
rradius-server dpsk delete --config rradius.toml --ssid office bob
rradius-server dpsk show --config rradius.toml --ssid office bob

The results are key changed for bob for office and deleted key of bob for office; when there is no such row, it prints no key of bob for office with status 1.

Afterwards, send SIGHUP to every node: rradius remembers the key each device used last, and without it those devices can still join with the old passphrase for cache_lifetime_ms. The commands only change the table; they do not notify the nodes. Disabling with enabled = 0 alone does not need this, because certificate_query is checked on every connection.

Changing the master key

On every node, set the new key as key_file and the old one as previous_key_file, and send SIGHUP; meanwhile both keys open values. Once everyone’s passphrase has been sealed again with the new key and the values in the table replaced, remove previous_key_file. dpsk passwd and dpsk-seal take only passphrases (or a 64-hexadecimal-character PSK) and cannot turn an old sealed value straight into a new one, so the original passphrases are needed.

The second approach: reply with the passphrase by MAC

When the AP does not send the 4-way handshake (Cisco iPSK, Aruba MPSK, Meraki, Mist, or hostapd’s wpa_psk_radius=1 or 2), it asks rradius with the MAC address, when the device connects, “what is this device’s passphrase”. Every device must be registered first. This approach does not need [radius.dpsk].

[auth.chains.mac-psk]
policy = "first_match"

[[auth.chains.mac-psk.handlers]]
type = "lua"
script = "mac-psk.lua"

[[radius.clients]]
name = "lab-aps"
address = "10.36.0.0/24"
secret_file = "lab-aps.secret"
auth = "mac-psk"

What mac-psk.lua does:

  1. User-Name and Calling-Station-Id must be the same MAC (both are first normalised to 12 lowercase hexadecimal characters, however they are written).
  2. Looks up the device_psk table, and rejects when nothing is found.
  3. Replies with the passphrase through set_attr('Tunnel-Password', ...), which rradius encrypts with the shared secret; then the VLAN.

Local test (change the address of lab-aps to 127.0.0.1):

echo 'User-Name=00-11-22-33-44-AA,User-Password=00-11-22-33-44-AA,Calling-Station-Id=00:11:22:33:44:aa' \
  | radclient -x 127.0.0.1:1812 auth lab-aps-secret-change-me

You get an Access-Accept with Tunnel-Password and VLAN 40.

  • Each vendor wants a different attribute: the Tunnel-Password used in the example works for hostapd, Meraki and Mist. Cisco uses Cisco-AVPair, Aruba Aruba-MPSK-Passphrase, Ruckus Ruckus-DPSK (with the PMK computed by the wpa_pmk function); see usage section 2.15 for how.
  • The table holds passphrases in plain text, because the AP needs the passphrase itself. Anyone who can read the database can see them.
  • Cisco-AVPair values are not encrypted; use it only on a trusted network or over RadSec.
  • A MAC is not a secret. Someone can ask with a registered MAC, but the passphrase comes back encrypted for the AP, and the device still has to know the passphrase itself to join.

Before going live

  • Only WPA2-PSK (the HMAC-SHA1 kind) is supported. WPA3-SAE, WPA2-PSK-SHA256 and the version used when PMF (protected management frames) is required are not supported; such requests get an Access-Reject, with key descriptor version 3 is not supported in the log. Set the SSID to plain WPA2-PSK, with PMF not set to “required”.
  • Supported APs: hostapd 2.11 and later with wpa_psk_radius=3, and Ruckus APs that send Ruckus-DPSK-Params. The AP’s MAC and the SSID are read from Called-Station-Id (in the form AA-BB-CC-DD-EE-FF:SSID), and the device’s MAC from Calling-Station-Id.
  • Passphrases should be long and different for everyone. When two people have the same passphrase, the one earlier in the query results is recognised.
  • Do not let users choose passphrases that are too short: anyone within radio range can record the handshake and guess the passphrase offline. That is a limit of WPA2-PSK itself.
  • Not tested: any real AP. Handshake matching has been cross-checked with the dpsk module of FreeRADIUS 3.2.10 (the same handshake, both find the same passphrase). The Ruckus reply format comes from its dictionary notes and community discussion; there is no official documentation. The vendor attributes of the second approach have not been verified on real devices.

Common problems

SymptomCause
Startup fails, mentioning dpsk.keysetup.sh has not been run, or the file’s permissions are too broad (it needs something like 0600)
Nobody can join, with do not open with key_file in the logThe values in the table were not sealed with this dpsk.key, or the identity or SSID at sealing time differs from the row
key descriptor version 3 is not supported in the logThe SSID has PMF required or SHA256 on; change it to plain WPA2-PSK
Called-Station-Id ... is not <access point MAC>:<SSID> in the logThe AP’s Called-Station-Id does not carry the SSID; adjust the AP’s settings
Right passphrase but rejected, with a name in the log’s accountThe passphrase matched, but certificate_query found nothing: the person is disabled, or not in the people table
The request is treated as an ordinary login, and handler is not dpskThe AP sent no handshake attributes: it does not support this approach, or it is not turned on (wpa_psk_radius=3 for hostapd)
Still able to join after the key was deletedNo SIGHUP was sent, so the key the device used last is still remembered
rradius_dpsk_total{result="busy"} increasesMore than 4 searches at once: too many people, or too many connecting at once; reduce the candidates per SSID
Built with Hugo
Theme Stack designed by Jimmy