Request for Comments:
A. Watt
iStumbler Labs
March 2017
The Wi-Fi URL scheme
Abstract
This document defines the format of Uniform Resource Locators (URL) for sharing
Wi-Fi network and user credentials. The syntax of 'wifi' URLs is designed to
facilitate distribution of network provisioning and connection information, and
to encourage the use of secure Wi-Fi networks in public places, by simplifying
the connection process for end users.
Key Words
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be
interpreted as described in RFC 2119 [RFC2119].
1. Introduction
The Wi-Fi URL scheme is used to provide 802.11 Wireless Network connection
details to a client system which can use the information to join the specified
networks. Wi-Fi URLs MUST minimally specify the SSID or Name of the network and
MAY include the WPA/WPA2 password as well as an 802.1X username for WPA/WPA2
Enterprise networks.
2. Syntax of a Wi-Fi URL
Following the syntax conventions of RFC 1738 [RFC1738] and RFC 1808 [RFC1808]
to allow clients to use existing parsing libraries, Wi-Fi URLs MUST include a
<host> component and MAY contain a <user> and/or <password> component and
MUST NOT include the <port>, <path>, <params> or <query> components.
wifiURL = "wifi:" // [username] : [password] @ ssid # [clip]
user = user name for WPA/WPA2 Enterprise 802.1X authentication
passsword = password for WPA/WPA2 Personal or Enterprise authentication
ssid = 802.11 SSID for the the Wi-Fi network to connect to
clip = URL for network information
3. Semantics and operations
A Wi-Fi URL designates an "internet resource", which is the SSID of a 802.11
network and it's associated WPA Personal or Enterprise access credentials.
In current practice, resolving most URLs such as those in the "http" scheme
causes an immediate interaction between the client software and another host
running the designated server, a Wi-Fi network URL provides instructions for
the configuration of the host system for internet access.
Operating Systems SHOULD provide a user confirmation mechanism before allowing
any application to update system settings such as network or Wi-Fi configuration.
Applications MAY choose to prompt the user with details of the configuration and
request confirmation in the case that the OS does not, but don't count on it.
4. Security Considerations
A Wi-Fi URL can be used to direct a client system to connect to a specific
network, which potentially exposes the client to a large number of attacks or
interception of unencrypted data exchanged between the client and servers.
Clients SHOULD adopt a low attack profile when connecting to public networks,
particularly when using a network configured through a URL from an untrusted
source.
The client SHOULD also make it clear that the user is about to configure their
network connection, since the user may not be aware that this is the result of
a Wi-Fi URL.
5. Encoding
RFC 1738 requires that the many characters in URLs be encoded. This affect the
Wi-Fi scheme as an 802.11 SSID is defined in [IEEE 802.11-2012] as an arbitrary
32 byte sequence which MAY be interpreted as UTF-8. Later standards [TODO REF]
provide an Information Element explicitly indicating that the client should
interpret the SSID as a UTF-8 string.
SSIDs used for wi-fi URLs MUST be encoded with UTF-8.
Note that all URL reserved characters in <user>, <password>,
<ssid> must be encoded.
6. Examples
The following examples all use 'ssid' for the network name, 'user' and 'password'
URL for an Open Wi-Fi network
wifi://ssid
URL for a WPA Personal network with password
wifi://:password@ssid
URL for a WPA Enterprise network with a username
wifi://user@ssid
URL for a WPA Enterprise network with a username and password
wifi://user:password@ssid
URL for an Open Wi-Fi network with a Web Clip
wifi://ssid#https://wi-fi.org
7. Trademarks
Wi-Fi is a registered Trademark of the Wi-Fi Alliance: https://wi-fi.org
8. References
[RFC1738] Berners-Lee, T., Masinter, L., and M. McCahill, Editors,
"Uniform Resource Locators (URL)", RFC 1738, December 1994.
[RFC1808] Fielding, R., "Relative Uniform Resource Locators",
RFC 1808, June 1995.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement
Levels" RFC 2119, March 1997.
[RFC2368] Hoffman, P., Masinter, L., Zawinski, J., Editors,
"The mailto URL scheme"", RFC 2368, July 1998
9. External References
[WHATWG URL-SPEC] https://url.spec.whatwg.org
[IEEE 802.11-2012] http://standards.ieee.org/getieee802/download/802.11-2012.pdf
[IEEE 802.11i-2004] http://standards.ieee.org/getieee802/download/802.11i-2004.pdf
10. Revisions
20161016 - Initial Draft Published at https://smartjoin.us/wifi-url.html
20170518 - Updated Security and Encodings sections
wifi://:password@ssid#https://smartjoin.us