13. Wi-Fi Login with SIM Cards (EAP-AKA')

Scenario: the factory’s handheld terminals and forklift terminals carry USIM cards the company issued itself. When these devices join Wi-Fi, the card itself should be what is verified:

  • No certificate to issue per device, and no expiry dates to manage.
  • No password that can leak or be guessed; the key inside the card cannot be read out.
  • The card and the server verify each other, so devices do not join fake access points.
  • For a lost device, just stop its card.

This is EAP-AKA’: the authentication used by mobile networks, carried over Wi-Fi 802.1X.

Check first whether it fits: rradius only verifies cards you issued yourself, meaning you hold each card’s Ki and OPc (the Milenage algorithm). It does not connect to a mobile operator’s systems (HSS), so SIM cards issued by an operator cannot be used.

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

FileContents
rradius.toml[radius.eap] with only aka-prime, [radius.eap.aka], [accounts.aka] for the aka command
setup.shCreates the master key aka.key and one encrypted demo card
migrations/1_schema.sqlaka_subscribers (cards), accounting

Some terms

TermMeaning
IMSIThe card’s number, at most 15 digits. Here it is the account name
KiThe card’s key, 32 hexadecimal characters. The card and the server each hold a copy; whoever obtains it can clone the card
OPcA value computed from the operator key and Ki, also one per card, and just as secret
SQNThe sequence number. It moves forward with every authentication, and the card does not accept numbers already used, so a recorded authentication cannot be replayed
VectorThe set of values the server computes for one authentication (a random number, a value for the card to verify, the expected answer)

Steps

1. Create the master key and the demo card

cd rradius-server
cargo build --release
examples/scenarios/sim-wifi/setup.sh
  • Creates aka.key: the master key that encrypts Ki and OPc, 64 hexadecimal characters, mode 0600.
  • Encrypts one demo card’s Ki and OPc with rradius-server aka-seal, writing migrations/2_demo_subscribers.sql. The demo card uses the published 3GPP test values, with IMSI 001010000000001.

Neither file is in the repository. Existing files are not overwritten: replace the master key and the ciphertext in the table no longer decrypts.

2. Start

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

3. Test

EAP-AKA’ can only be tested with a card (or a program simulating one); radtest cannot do it.

  • The automated test plays the card itself, going through the whole authentication with the demo card’s Ki and OPc, and checks each row of the table below.
  • With eapol_test: the project’s interoperability tests use a self-built wpa_supplicant 2.11 eapol_test with the simulated USIM enabled; how is in docker/interop/aka-client/.
SituationResult
The demo card logs inAccess-Accept, with the IMSI as User-Name, Filter-Id = "plant-devices", and the keys for wireless encryption
The same card, with the card’s sequence number newer than the server’sThe card asks to resynchronise; once the server catches up, Access-Accept
The same IMSI with a different Ki (a failed clone)Access-Reject
An IMSI never issuedAccess-Reject
After aka disable 001010000000001Access-Reject
After aka add 001010000000002 (given Ki and OPc), logging in with that cardAccess-Accept

The authentication log:

authentication protocol="radius" client="plant-wlc" source=10.45.0.10 user="[email protected]" account="001010000000001" chain="eap" handler="eap-aka-prime" decision="accept"

The configuration explained

[radius.eap]
methods = ["aka-prime"]

[radius.eap.aka]
network_name = "WLAN"
key_file = "aka.key"
subscriber_query = "SELECT ki, opc FROM aka_subscribers WHERE imsi = ?"
current_sqn_query = "SELECT sqn FROM aka_subscribers WHERE imsi = ?"
proven_sqn_query = "UPDATE aka_subscribers SET sqn = max(sqn, ?) WHERE imsi = ? RETURNING sqn"
resync_query = "UPDATE aka_subscribers SET sqn = max(sqn, ?) + 32 WHERE imsi = ? RETURNING sqn"
  • With only aka-prime, no server certificate is needed, and cert_file and key_file cannot be set. When EAP-TLS or PEAP is enabled too, add the certificate and set eap_methods on every client (chapter 3).
  • network_name takes part in key derivation, and devices may check it; both sides must agree.
  • subscriber_query returns the encrypted Ki and OPc.
  • current_sqn_query and proven_sqn_query: the sequence number is written only after the card answers correctly. Sending a Challenge only reads the current number and adds 32, without writing it back; only once the card answers correctly is it written with proven_sqn_query. So someone who knows the IMSI but has no card cannot push the number forward, however often they ask, and cannot lock the card out (see “Preventing abuse” below). proven_sqn_query must be written as max(sqn, ?) so the number only moves forward.
  • resync_query is used when the card says “my sequence number is newer”, and must also be written as max(sqn, ?); SET sqn = ? + 32 also passes the checks, but moves the number backwards.
  • proven_sqn_query and resync_query must end with RETURNING, with the last column named sqn, or startup fails.
  • The older approach is next_sqn_query: every Challenge first writes the number plus 32 to the database, so abuse has to be held off by a per-card limit, and that limit can be used up. New deployments should use the approach above; the two cannot be set together.

Once the card passes: may this card be used

[[auth.handlers]]
type = "sql"
user_query = "SELECT NULL FROM aka_subscribers WHERE imsi = ?"
certificate_query = "SELECT 1 FROM aka_subscribers WHERE imsi = ? AND enabled = 1"
reply_query = "SELECT 'Filter-Id', plan FROM aka_subscribers WHERE imsi = ? AND plan <> ''"

A card passing authentication only proves “this is that card”. The IMSI then goes to the authentication chain as an already proven name, with the same rules as a certificate login: the sql handler checks certificate_query, and accepts when it finds a row. The disabled condition (enabled = 1) goes here. user_query is required but unused; the example makes the password column always NULL, so nobody can log in with an IMSI plus a password.

When a script decides, the eap_method it sees is "aka-prime", and get_attr('User-Name') is the IMSI.

Issuing and stopping cards

Adding a card

printf '%s\n%s\n' <Ki> <OPc> | rradius-server aka add --config rradius.toml 001010000000002
# added subscriber 001010000000002
  • Ki and OPc are read from standard input, one line each, 32 hexadecimal characters each, never as arguments. On a terminal it asks Ki: and OPc: separately, without echoing.

  • The command encrypts with the key_file of [radius.eap.aka] before writing to the table, so the plain values never appear in the table, the log or the command’s output. Run it on a host with the master key, usually a node itself.

  • The ciphertext is bound to the IMSI and the column, so moved to another IMSI, or with Ki and OPc swapped, it does not decrypt.

  • The write goes through the cluster, so every node sees it at once, with no restart.

  • The SQL it runs is set in [accounts.aka]: ?1 is the IMSI, and ?2 and ?3 of add are the encrypted Ki and OPc. The example:

    [accounts.aka]
    add = "INSERT INTO aka_subscribers (imsi, ki, opc) VALUES (?1, ?2, ?3)"
    enable = "UPDATE aka_subscribers SET enabled = 1 WHERE imsi = ?1"
    disable = "UPDATE aka_subscribers SET enabled = 0 WHERE imsi = ?1"
    delete = "DELETE FROM aka_subscribers WHERE imsi = ?1"
    show = "SELECT imsi, label, plan, enabled, sqn FROM aka_subscribers WHERE imsi = ?1"
    

    Do not select ki or opc in show. The full rules are in section 2.14 of the reference document.

  • Other columns (label, plan) are not filled by the command; the example table has defaults. To write them too, have the add SQL write fixed values, or change them later with SQL.

  • The initial sqn is the table’s default (0 in the example), meaning the card’s factory sequence number. Being older than the card is fine: on the first login the card asks to resynchronise, and the server catches up.

  • For issuing many cards, use aka-seal to produce ciphertext for each card and import them at once as a migration file (which is what setup.sh does).

Stopping, restoring, showing and deleting cards

rradius-server aka disable --config rradius.toml 001010000000001
rradius-server aka enable --config rradius.toml 001010000000001
rradius-server aka show --config rradius.toml 001010000000001
rradius-server aka delete --config rradius.toml 001010000000001

The results are messages like disabled subscriber 001010000000001; when there is no such card it prints no subscriber 001010000000001 with status 1. It takes effect across the cluster at once and is seen by the next login, because every login reads the table, with no cache.

The master key

aka.key protects the Ki and OPc of every card in the table.

  • What it protects against: database files, backups, what is replicated between cluster nodes, scripts’ sql_query, and people with database access only. All of these see ciphertext.
  • What it does not protect against: someone who gets onto the host, who can read aka.key and the program’s memory. If the master key leaks, treat every card as leaked; a leaked Ki means the card can be cloned, which changing the master key cannot undo. Only replacing the card can.
  • Every node needs the same key. It is not in the database and is not replicated automatically. Without it, startup fails; when the contents differ, that only shows at decryption, and every login on that node fails.
  • Always back it up separately. Losing it means importing every card again.
  • Permissions must be something like 0600, 0640 or 0400; if others can read it, the server refuses to start.
  • Changing the master key: on every node, put both keys in place (key_file the new one, previous_key_file the old) and send SIGHUP; re-encrypt both ciphertexts of every card with aka-seal --key-file new --old-key-file old --imsi <IMSI> (giving the old ciphertext on standard input) and replace the values in the table; once all are done, remove previous_key_file.

Preventing abuse

The server has to send a Challenge before the other side has proven anything. Someone who knows an IMSI can keep asking.

max_lookups = 64
lookup_wait_ms = 1000
  • The sequence number cannot be pushed: with current_sqn_query and proven_sqn_query, the Challenges someone without the card receives are never written to the database, and neither are wrong answers. So no per-card limit is needed; the attacker has no budget to use up, and the real card can log in at any time. The automated test confirms with 20 wrongly answered conversations that the sequence number does not move, and the real card logs in normally afterwards.
  • The cost: when a card received a Challenge but the server never got the reply (lost signal, a NAS timeout), the next login first takes one extra round of resynchronisation, then succeeds as usual.
  • max_lookups, lookup_wait_ms: each node runs at most this many subscriber lookups at once, which limits the load on the database. When full, it waits lookup_wait_ms first, and refuses only if no slot frees up. When every device comes back online at once after a power cut, they queue instead of failing at once.
  • The older approach (next_sqn_query) advances the number every time, so it has max_vectors_per_minute (a limit per node, per card, per minute) and shared_budget (the limit shared across the whole cluster, at roughly half the login throughput). An attacker can use up this limit and keep that card out for a while. These two settings work only with next_sqn_query.
  • Whether an IMSI exists can be seen: issued IMSIs get a challenge, and unissued ones fail at once.
  • The IMSI is sent in plain text: anyone within radio range can see a device’s IMSI. Pseudonyms and fast re-authentication are not available yet.
  • Not confirmed with real cards: that a card refuses a second Challenge with “the same sequence number, a different RAND” is inferred from the 3GPP specification.

Several nodes

  • One login must complete on one node, as with other EAP methods. Use primary/backup on the NAS, or have a load balancer pin by source (chapter 8).
  • Sequence numbers go through the cluster, so when the cluster loses its majority no vectors can be issued, and AKA’ logins fail.
  • aka.key is one copy per node; see above.

Before going live

  • Not tested with real USIM cards and real devices, only with wpa_supplicant’s simulated USIM and the project’s own tests. How each operating system supports and configures “a card not issued by an operator” is still unknown; always try with real cards and devices before going live.
  • The sequence number step of 32 follows 3GPP practice; how real cards check sequence numbers is up to the card, and only testing on real hardware will tell.
  • Only full EAP-AKA’ authentication. No EAP-AKA (the older version without the prime) and no EAP-SIM.

Common problems

SymptomCause
Startup fails, mentioning aka.keysetup.sh has not been run, or the file’s permissions are too broad
this subscriber's Ki: not a sealed value in the logThe table holds plain values; use the output of aka-seal
sealed under a key this server does not have or it does not openThis node’s aka.key differs from the one used to encrypt, or the ciphertext was moved to another IMSI
an AUTS with a wrong MAC-SThe card asked to resynchronise, but the Ki or OPc in the table differs from the card’s
too many vectors for this subscriberWith next_sqn_query, max_vectors_per_minute was exceeded: the device keeps retrying, or someone keeps trying with this IMSI. With current_sqn_query and proven_sqn_query there is no such limit
the proven sequence number could not be storedThe card answered correctly, but proven_sqn_query failed, found no row, or is not written as max(sqn, ?)
too many subscriber lookups at onceMany devices logging in at once, or the database slowing down; devices just retry. If it happens often, look at the database
resync_query left the sequence number at or below the card'sresync_query is not written as max(sqn, ?) + 32
The card keeps asking to resynchronise and cannot log inThe sequence number in the table has been pushed further than the card accepts. Set sqn back to a value the card accepts: UPDATE aka_subscribers SET sqn = <value> WHERE imsi = '...' (as a migration file)
The card passes but the login is rejected, with EAP conversation ... refusedcertificate_query found nothing: the card is disabled, or the table has no enabled row for this IMSI
Built with Hugo
Theme Stack designed by Jimmy