|
Home
| pfodApps/pfodDevices
| WebStringTemplates
| Java/J2EE
| Unix
| Torches
| Superannuation
|
| About
Us
|
|
|
pfodWifiConfigV1™
|
by Matthew Ford 27th March 2015 (original
posted 13th February 2015)
© Forward Computing and
Control Pty. Ltd. NSW Australia
All rights reserved.
This page describes the protocol used by pfodWifiConfigV1, discusses the security issues and what the developer needs to do to implement the protocol on their hardware.
Definition
of the pfodWifiConfigV1 protocol
Implementation
Details for Developers Example libraries are also available for
WildFire and
LinkIt ONE
Security
Issues – Beware of Geeks bearing Gifts
This page describes Version 1 of the pfodWifiConfig protocol – pfodWifiConfigV1. The version number is included as part of the SSID in the QRcode image to identify the format used. Version 1 supports a device connecting to the temporary pfodWifiConfigV1 access point using WPA2 and DHCP.
The device can be configured to connect to the real network via either DHCP or staticIP and running either as server on a configured port or as a client connecting to a configured server. The Features: indicate whether the device will connect using DHCP or staticIP and whether it will run as a server or client. The Features: effect the expected format of the {set....} message. See below for the formats.
Version 1 of pfodWifiConfig communicates between the pfodWifiConfigV1 app (or telnet) and the device in the following way.
Version 1 defines a set of features a device may
support. For pfodWifiConfigV1 the possible features are:-
Mode:
Server|Client|ClientLogin
IPsource: DHCP|staticIP
Security:
OPEN|WEP|WPA|WPA2|WPA-WPA2
where WPA is WPA-PSK and WPA2 is WPA2-PSK and
WPA-WPA2 will connect with either WPA2 or failing that fall back to
WPA security.
Note: None of the options are case sensitive and any
implementation should compare all strings ignoring upper or lower
case.
On connection the device sends a message indicating the pfodWifiConfig version and the features of the device.
An example initial message
is
{!pfodWifiConfigV1
Mode: Server
Security:
WPA2
IPsource: DHCP
}
If the device can handle multiple options then those
are listed as alternatives in the message. The pfodWifiConfing
library generates these alternatives from the settings passed to
configureWifiConfig. For example if the device can use DHCP or
staticIP to set its IP address on the real network and can run
with either WPA2 or OPEN security, then the intial message would
be
{!pfodWifiConfigV1
Mode: Server
IPsource: DHCP |
staticIP
Security: WPA2 | OPEN
}
It is strongly recommended that WPA2 be used as the security as the other options are easily hacked.
The set command is sent from the pfodWifiConfigV1 app (or telent terminal) to configure the device.
All commands sent to the wifi device must be less then 256 bytes in length, including the starting and ending, { }
There are two basic
formats for the set command:- {set and
setSize
If the
SSID and password do not contain any spaces or the '}' character then
you can use the {set format,
that is the command starts with {set .
However if any field contain any spaces or the char '}' then you
need to use the setSize
command format which includes a
field size for each field.
Note: You can use UTF-8 encoding to specify non-ASCII characters in the fields if the device your are configuring supports it. The pfodWifiConfig library treats all data as byte arrays and so handles UTF-8. The pfodWifiConfigV1 app converts the user's input string to UTF-8 bytes before sending them. So the only limitation, if any, is if the wifi hardware on the device can not handle the SSID and password bytes.
If the SSID and password do not contain any spaces or the '}' character then you can use the {set format, that is the command starts with {set .
The format is
{set
<series of space separated
fields> }
Note: there is a space after {set
and a final closing }
An example {set
command is:-
{set FccAP WPA2
myPassword 80}
However if any field contain any spaces or the char '}' then you need to use the setSize command format which includes field sizes for each field. The setSize command format starts with { followed immediately by a digit in the range 1..9.
The setSize
message format
is
{<SSIDfieldsize>:<networkSSID_chars>
<securityfieldsize><security>
<passwordFieldSize>:<password> <portNofieldsize><portNo>
… other space
separated fields with field sizes as necessary }
That is immediately after the opening { there is a number specifying the size in bytes, n, of the SSID field, then a : followed by n bytes of the SSID followed by a space. Then follows the other fields each preceeded by its fieldSize:. The fields are separated by one or more spaces. The command is terminated by }
An example of the
setSize
command is :-
{17:yellow brick
road 4:WPA2 8:pass key 2:80}
If the security type is
OPEN (this is not recommended) then just use a dummy
password, which will be ignored by the device. e.g
{set FccAP
OPEN pwNotSet 80 }
Both the {set and setSize commands have a maximum message size of 255 bytes, including the opening and closing { }
The
number of fields and their content depend on the device's Features
If the Features are
Server DHCP then the
expected fields are
{set <networkSSID> <security>
<password> <portNoToListenOn> }
If
the Features are Server staticIP then
the expected fields are
{set <networkSSID> <security>
<password> <portNoToListenOn> <staticIP>
}
If the Features are Client
staticIP then the expected
fields are
{set <networkSSID> <security> <password>
<portNoToConnectTo> <staticIP> <connectToIP_Hostname>
}
If the Features are Client
DHCP then the expected fields
are
{set <networkSSID> <security> <password>
<portNoToConnectTo> DHCP <connectToIP_Hostname>
}
If the Features are
ClientLogin staticIP then
the expected fields are
{set <networkSSID> <security>
<password> <portNoToConnectTo> <staticIP>
<connectToIP_Hostname> <username>
<userPassword> }
If
the Features are ClientLogin DHCP then
the expected fields are
{set <networkSSID> <security>
<password> <portNoToConnectTo> DHCP
<connectToIP_Hostname> <username>
<userPassword> }
The <username> and <password> fields are generic fields for two pieces of information needed to connect to the server. For example they may represent an APIKEY and a FEEDID. It is up to the device to use them correctly.
Of course the code in the device is free to ignore/override any of these settings but the device must be able to handle the formats appropriate to its advertised Features:
The
device should respond the a set command with a message indicating the
configuration has been accepted, using the following
format
{!<msg>}
If there is an error
in the setting, invalid port or incorrect number of fields for
example, then device should respond with an error message using the
format
{!Error:<msg>}
Any other { } commands sent the device that are not {set or setSize commands, must be responded to with the initial message which contains Features etc.
This section describes what a
developer need to do the implement pfodWifiConfig in their hardware.
Example libraries are available
for WildFire,
LinkIt ONE, WiFly,
AdafruitC3000
and
ESP8266
To implement this configuration system in your Wi-Fi
device you need:-
i) A board and Wi-Fi module, either an add on
shield or built-in, supported by the pfodWifiConfig™
library
ii) EEPROM library support
iii) A push button connected
to one of the board's digital inputs.
Use the free pfodQRpsk™ java application to generate the passkey and the QR code image for the pfodWifiConfig network. The QR code image contains the SSID (pfodWifiConfigV1), Security type (WAP2 PSK) and the password for the temporary pfodWifiConfigV1 configuration Access Point. It also contains the PortNo to connect to in order to configure the device.
Download the pfodWifiConfig library
This library
has configureWifiConfig() method in which you specify
i) Network
security and passkey for the pfodWifiConfig network. These are taken
from the QR code
ii) the eeprom starting address where the network
configuration will be stored when set by pfodWifiConfig.
iii) the
mode the device will run in
iiv the Wi-Fi security types this
board/shield supports and wishes to offer as options for
connections
v) the sources for the devices IP address on the real
network.
Add this configureWifiConfig() method to the setup() code and below that the normal code the will connect to the real network using the values read from EEPROM using the loadNetworkConfigFromEEPROM() method.
There only three methods that need to written for each Wi-Fi device . They are the configureWifiConfig() which takes the temporary network parameters and re-configures the wifi system to connect to that network. The Wi-Fi devices CHAT_SERVER example code will provide most of the code needed. The other two methods are to read and write from EEPROM and are a trivial link to the device's EEPROM support functions.
See the WildFire and LinkIt ONE Arduino libraries for examples of these methods. The common pfodWifiConfig library is used by all devices and does not need to be modified.
The configureWifiConfig() function of the library is called in setup(), if the config setup input is active. It uses the temporary network parameters to connect to the pfodWifiConfig network. It then monitors for in an incoming connection, and responds with Features: message listing the mode the device will run in, the list of supported Wi-Fi security methods and how the device will get its IP address on the real network. When the device receives the {set … } message with the user's configuration details, the library stores the values in EEPROM.
This my non-expert analysis. If you have any concerns you should consult a real security expert.
The critical piece of information to be protected is the password for the local network. Using pfodWifiConfig this password is entered into the Android mobile and then transferred to the device via a WPA2-PSK secured temporary Wi-Fi network (the pfodWifiConfigV1 network).
There are three obvious attack vectors:-
I) The device being connected has been compromised and captures the password (as it should) but then re-transmits it once it can. This issue is on the same level as installing any compromised hardware/software, so it is important to be confident of the manufacture of the device you are configuring.
II) The Android mobile running pfodWifiConfig has been been compromised by spyware which sniffs the keystrokes as you enter the network password, and then re-transmits it once it can. The network password is only held in memory by the pfodWifiConfig app and not saved anywhere. This narrows the attack vector, but it is important to use an Android mobile free from any such spyware. Removing all apps and doing a clean install of the OS will help, as will dedicating just one mobile to configuration. That mobile, not being in general use, is much less likely to be infected.
III) Anyone who can access the QR code can read the
password for the temporary pfodWifiConfigV1 network which
transfers the real network's password. It is assumed that using the
pfodQRpsk™ application to generate the random
passwords, a different one for each device, prevents any one just
guessing it. Having access to the device to scan the temporary
pfodWifiConfig network password would allow a malicious person to
sniff the temporary pfodWifiConfigV1 network and collect the
real network's password.
This attack vector is very narrow
both in time and location. The sniff can only occur while the device
is being configured and only within a short range, due to the low
power of the Android mobile's AccessPoint, and the attacker needs to
have physical access to the device with the QR code attached in order
to read the pfodWifiConfig's temporary network password.
An
obvious means to carry out this type of attack is for a malicious
person to arrive with a new 'toy' from a reputable manufacture that
needs to be connected to the network to run. The malicious person
gives it to you to connect, using pfodWifiConfig, making a point of
not looking while you enter the real network's password. However the
malicious person has already scanned the QR code before arriving, and
their mobile is sniffing the pfodWifiConfig temporary network and so
captures the real networks password. So Beware of Geeks bearing
Gifts.
If an attacker sniffs the pfodWifiConfig traffic and manages to crack the password, they will obtain the real networks password. Using a long passkey for the pfodWifiConfig temporary network makes brute force attacks difficult. However most of the plain text of the messages is known which may assist the attacker using meet-in-the-middle attacks for example.
A typical message sequence is
From app: {.}
From
device: {! pfodWifiConfigV1 mode:
Server security: WPA2 IPsource: DHCP}
From app: {set
knowNetworkSSID WPA2 networkPassKey 4989 }
From device:
{!Configuration Complete}
The last message from the app is the only one that is important. WPA2 uses either TKIP (deprecated) or CCMP which makes it more difficult to use knowledge of one message to decrypt the next. My non-expert opinion is that, using a 128bit key for the pfodWifiConfigV1 temporary network is sufficient. However if the known clear text worries you, you can always modify the pfodWifiConfig app to add lots of random data before and after the { } when sending the last message, containing the real network passkey, from the app to the device. This hides the real data in a sea of junk, all of which is encrypted. This make meet-in-the-middle attacks much more difficult. You can also add junk to the other messages as well if you wish. Note the size (length) of the junk before and after the {…} needs to be random, as well as its content.
Because of the way the parser is implemented, in both the app and the device, this random junk is just dropped and has no impact on storage or RAM requirements. Any such modifications to either the app or the device are completely backward compatible and transparent to non-modified apps and devices. The only effect to so slow down the delivery of the real data.
Originally an OPEN temporary pfodWifiConfig AP was allowable.
When an OPEN network was used to connect to pfodWifiConfig, then the passkey was used to encrypt the real network's password while it is being sent to the Wi-Fi device. A simple but unbreakable XOR encryption is used. Provided a different passkey is used for each device, this one time encryption cannot be broken without knowing the passkey. This is without access to the QR code on the device or the device's source code. Note: the real network's SSID is not encrypted, as it is easily knowable, and so would reveal the passkey being used.
However if the AccessPoint is using an OPEN network, then multiple devices could connect at the same time. This would be a problem as the encrypted network password would be decrypted incorrectly for all but one of them (assuming random encryption passkeys). Because of this issue, OPEN security for the temporary setup AP is not supported.
pfodWifiConfig™
and pfodQRpsk™ are
trademarks of Forward Computing and Control Pty. Ltd.
AndroidTM
is a trademark of Google Inc. For use of
the Arduino name see http://arduino.cc/en/Main/FAQ
The General Purpose Android/Arduino Control App.
pfodDevice™ and pfodApp™ are trade marks of Forward Computing and Control Pty. Ltd.
Contact Forward Computing and Control by
©Copyright 1996-2020 Forward Computing and Control Pty. Ltd.
ACN 003 669 994