WPA Personal Credentials: Passphrases, Raw PSKs and Validation Before Association

Validate a credential representation, not a generic password

A WPA-Personal onboarding form needs to know which authentication method and which credential representation the target interface expects. Otherwise a value can pass a superficial length check yet be serialized into the wrong meaning. This guide concentrates on WPA-PSK passphrases and raw pre-shared keys, using the AOSP android16-release supplicant configuration as the reference parser. It does not apply its limits to every WPA3-SAE password, enterprise identity or certificate. TI’s provisioning primer frames personal-network onboarding as collecting a network name and credentials; the engineering step addressed here is preserving the type of those credentials all the way to the association configuration.

Keep passphrases and raw keys as distinct types

The verified AOSP configuration reference accepts a WPA-PSK as either 64 hexadecimal digits representing 32 bytes, or an ASCII passphrase of 8 through 63 characters. The latter is used with the SSID to derive the actual key. A raw key is already the key material; it is not a longer passphrase and must not be run through a passphrase derivation path again. Model these as separate tagged alternatives in your provisioning message and internal data structure. A normal consumer interface may expose only passphrase entry while reserving raw-key input for an explicit advanced workflow. That product choice is preferable to guessing intent from a string after several interfaces have transformed it.

Make authentication selection precede validation

Select the intended security mode from a trusted scan result or an explicit manual-network choice, then choose its validator. The same AOSP reference has a separate sae_password field and explains that SAE does not inherit the psk field’s 8–63-character constraint. This article does not define a universal SAE character policy: inspect the actual SDK and AP configuration. Enterprise authentication likewise needs its own contract. If a mixed-mode product supports more than one authentication path, store the allowed modes and field semantics explicitly. Do not claim “all Wi-Fi passwords must be at least eight characters.” A correct error should name the selected input type, so a user can fix a format problem without repeatedly changing a valid credential for another mode.

Reject ambiguity instead of quietly rewriting secrets

Do not strip spaces, change case, replace punctuation or normalize Unicode on a credential. If the documented WPA-PSK input policy is ASCII, reject unsupported characters visibly rather than transliterating them. For raw PSK input, require exactly 64 hexadecimal characters and convert pairs into 32 bytes; reject separators unless the interface explicitly supports a separate, unambiguous presentation format. A 64-character value containing a non-hexadecimal symbol is not a valid raw PSK under this contract. A 63-character all-hex string remains a possible passphrase when the user chose passphrase mode. Confirm the selected representation before transmission, but do not echo its value into a debug log, analytics event or support ticket.

Map the typed value into each real API

Write a small adapter for every supported backend, with tests that inspect parser output rather than only generated text. In the referenced supplicant configuration, quoted text and an unquoted hexadecimal value carry different meanings. An SDK may instead use a byte buffer, an enumeration, a length field, or one field with documented auto-detection. Verify that behavior on the pinned SDK release; do not import supplicant quoting into an unrelated API. When configuration text must be generated, escape according to that parser, not according to JSON or shell rules. Avoid passing live credentials as shell command arguments or leaving commented plaintext copies beside a derived key. Restrict diagnostic fixtures to deliberately synthetic credentials.

Bind derivation and persistence to the correct network

A derived WPA-PSK passphrase key depends on both the supplied passphrase and the SSID. A cache keyed only by the visible network label can therefore be wrong if byte identity changes. Store the representation type and exact SSID association together, and invalidate any derivation cache when either input changes. Keep the previous working configuration until the new candidate has passed the product’s acceptance state. A crash halfway through saving must not leave a raw key marked as a passphrase or a new type marker paired with old bytes. This is an application persistence requirement, not evidence that authentication has succeeded. Syntactically valid input can still fail because the credential is wrong, the AP rejects the mode, or another association condition is unmet.

Build boundary tests that never require real secrets

Create fixtures for 7, 8, 63 and 64 ASCII characters in passphrase mode; separately test 63, 64 and 65 hexadecimal characters in raw-key mode. Include a 64-character string with one invalid character, leading and trailing spaces, quotes, backslashes and a non-ASCII symbol. Assert whether each case is rejected or accepted before network activity, and verify the exact decoded type and bytes for accepted cases. Test save-and-reload and interrupted updates. Then use an authorized lab AP to test actual association with synthetic credentials, separating parser acceptance from authentication success. No such device test is claimed here. Do not publish a reusable example secret as a recommended deployment password.

Ship an error model that points to the right fix

Require distinct outcomes for unsupported authentication mode, invalid representation, length or character rejection, parser failure and authentication rejection. A format error should return to the relevant field without destroying the last known-good profile. A network failure should retain the non-secret context: selected mode, credential kind, byte length if your privacy policy permits it, firmware version and failure stage. Avoid a credential hash because low-entropy passwords remain guessable. Acceptance is reached when the UI, transport, storage and backend agree on one representation, boundary failures occur locally, and logs remain free of secrets. This guide supplies a reviewable contract and test design, not proof of interoperability with an unnamed radio SDK.