Writing a Wi-Fi Tag on Android: The WSC Record Explained

Introduction

An Android Wi-Fi tag is one NDEF record with the MIME type application/vnd.wfa.wsc. Inside it sit your network name, the security type and the password, packed in the Wi-Fi Simple Configuration (WSC) format. Here's what that record contains, how Android builds it and where it stops working.

What the application/vnd.wfa.wsc record is

The WSC record is an NDEF MIME record, and its payload isn't text. It's a run of tag/value entries, and as one hobbyist who built the tag by hand with a PN532 reader put it, "not a simple one (i.e. some implicit lengths)". So most people let an app or library encode it.

The specification describes three ways to use the format: a Password Token, a Configuration Token and Connection Handover. A tag you stick on a wall is a Configuration Token. It carries credentials from a network's registrar to a device that wants to join, so the phone can connect directly.

What is inside the credential

Everything the phone needs lives in one credential block. According to the ndeflib documentation of the WSC format, these fields are required:

A vendor extension block is optional. So are any extra WSC entries.

The type fields are bit flags, so the values are worth knowing if you ever read a hex dump:

WEP and TKIP-only are marked deprecated in the same documentation. A complete Configuration Token in the ndeflib example encodes to 139 octets, so check your tag's NDEF capacity before you write.

How Android builds and reads the record

Android's NFC basics guide says that NDEF data lives in a message that holds one or more records, and that each record must be well-formed for its type. Since Android 4.1 (API level 16), NdefRecord.createMime() exists so you do not assemble MIME records by hand. Google recommends the helper wherever possible to avoid mistakes.

The MIME type is what makes the tag useful. Android's tag dispatch system maps a TNF_MIME_MEDIA record's type to an ACTION_NDEF_DISCOVERED intent, which is the highest-priority intent. For a Wi-Fi tag, that type is application/vnd.wfa.wsc. The docs also say the record you want acted on should be the first record in the message you write, so keep the Wi-Fi record first and do not bury it behind a URL.

The Android docs don't walk through a Wi-Fi example, so treat the byte layout as the job of the encoder you use. If you write your own, test it against a tag written by a known-good app.

Before you write one

The Configuration Token holds unencrypted credentials. Anyone who can tap the tag, or read it with any NFC reader app, can see the password. Put the tag on a guest network, never your main one, and change the password if a tag goes missing. That is also the sensible setup for a Wi-Fi welcome tag in a rental.

Only write tags for networks you own or manage. Simple as that.

What happens when an iPhone taps it

An iPhone behaves differently. Apple's background tag reading documentation says the system inspects the NDEF message for a URI record, a well-known type U. It then lists the URL schemes it supports, such as web links, email, phone and SMS. Wi-Fi credential records are not on the page.

The hobbyist above tested their tag and reported that it "does not work on an iPhone". We cover the details in why an iPhone won't auto-join from the same tag. If your guests carry both kinds of phone, add a Wi-Fi QR code beside the tag, as laid out in NFC vs QR code.

Conclusion

A Wi-Fi tag is a single MIME record with a compact, unencrypted credential block. Android's tag dispatch routes it by MIME type, and iPhones do not act on it. To try it, write a tag with NFCore on iPhone or Android, then scan it back to see the record type and payload.

Frequently Asked Questions

What MIME type does a Wi-Fi NFC tag use?

It uses application/vnd.wfa.wsc, an NDEF MIME record that carries Wi-Fi Simple Configuration data.

Is the Wi-Fi password on the tag encrypted?

No. A Configuration Token carries unencrypted credentials, so anyone who can read the tag can read the password. Use a guest network.

Can I write the WSC record by hand?

You can, but the payload is a set of type-length-value entries with implicit lengths. Use a library or an app that builds it for you.

Will the tag work on an iPhone?

Not as a Wi-Fi join. Background tag reading looks for a URI record, and a tag with a WSC record was reported not to work on an iPhone.