Home | pfodApps/pfodDevices | WebStringTemplates | Java/J2EE | Unix | Torches | Superannuation | | About Us

Forward Logo (image)      

Protcol Definition

by Matthew Ford 27th March 2015 (original posted 13th February 2015)
© Forward Computing and Control Pty. Ltd. NSW Australia
All rights reserved.

Version 1 Protocol Definition


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

Note about pfodWifiConfig versions

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.

Definition of the pfodWifiConfigV1 protocol

Version 1 of pfodWifiConfig communicates between the pfodWifiConfigV1 app (or telnet) and the device in the following way.

Device Features for Version 1

Version 1 defines a set of features a device may support. For pfodWifiConfigV1 the possible features are:-
Mode: Server|Client|ClientLogin
IPsource: DHCP|staticIP

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.

Initial Message

On connection the device sends a message indicating the pfodWifiConfig version and the features of the device.

An example initial message is
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
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 commands.

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.

{set Command

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}

setSize Command

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}

Use a dummy password if Security type is 'OPEN'

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 }

Maximum length of set commands

Both the {set and setSize commands have a maximum message size of 255 bytes, including the opening and closing { }

Fields in the set Commands depend on the device's features

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
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

Invalid Commands

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.

Implementation Details for Developers

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.

What the developer needs to do

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.

What the pfodWifiConfig library does

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.

Security Issues – Beware of Geeks bearing Gifts

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.

Note on Off-Line Brute Force Attacks.

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.

Update 14th February 2015

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 pfodQRpskare 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.

Forward home page link (image)

Contact Forward Computing and Control by
©Copyright 1996-2020 Forward Computing and Control Pty. Ltd. ACN 003 669 994