Reference10:Concept Provisioning

Starting with version 10, innovaphone devices connect automatically with http://config.innovaphone.com/init during commissioning or after resetting to the initial state. This process serves to simplify provisioning.

In the future, this mechanism can be used by innovaphone partners to significantly reduce configuration work. You can set up an individual update server that contains pre-prepared configurations for innovaphone devices. These can then be assigned to a specific project in my.innovaphone. A corresponding update URL is all that is stored for this purpose. The allocated update server applies to new devices that are assigned via the MAC address to this project in my.innovaphone.

If an innovaphone device then connects with http://config.innovaphone.com/init, an enquiry is made in my.innovaphone to see whether an update server is available for the MAC address. If this is the case, the device can automatically connect automatically to it via the update URL to retrieve the local configuration - fully automated, without further intervention by the administrator.

A connection is always established automatically to http://config.innovaphone.com/init. If you would like to avoid this procedure, the innovaphone device must be booted in an environment without a public internet connection.

The following information is transmitted to innovaphone upon connection with http://config.innovaphone.com/init: The version and serial number of the device and the public IP address. This information is managed in accordance with innovaphone's data protection policy.

Implementation

From version 10, the default UP1 config file line is config change UP1 /url http://config.innovaphone.com/init /poll 1 for all devices. If this setting becomes effective (that is, if it is not changed before the first poll and no overriding setting is deployed to the device via DHCP), the device will try to read an update script from the URL given. This URL points towards a server that is hosted by innovaphone. If the device in question has a valid and working DNS setting and the devices has access to the internet, the server will be queried and return an update script which is applied to the device. http://config.innovaphone.com/init is said to be the config redirection service.

Under standard circumstances, the script returned will simply remove the update URL from the configuration and have the device reset.

However, if the device

1. is known to my.innovaphone.com
2. is assigned to a my.innovaphone project
3. this project has an URL configured in the project properties

the script returned will change the update URL to the URL defined for the project. This new URL is considered an update server for the device in question.

It is up to the server specified in the URL set (known as config server) how to proceed further. This mechanism can be used by partners to implement 3rd party provisioning schemes. innovaphone may or may not offer such a service (ckl 16:29, 8 July 2013 (CEST) as of today, innovaphone does not).

The redirection process is logged in to a database at innovaphone. This is to be able to maintain and debug this service and also detect possible fraud and misuse.

Security Implications

A device polling the config redirection service will send a request along with certain data to http://config.innovaphone.com/init (for details about the data sent see below). To avoid this process, users must start the device in a network environment that has no internet access. The normal configuration UI can then be used to remove the UP1 configuration settings. Please note that this must be done whenever the device has been set to factory defaults! Another option is to start the device in a network environment where an update URL is deployed via DHCP.

If the device is redirected, certain further information is sent to the device from the config redirection service. This includes at least the new URL of the final config server. Although the config redirection service can be instructed to contact the config server via HTTPS, it should be clear that the information sent from the config redirection service to the device is sent in clear. Also, the device does not need to authenticate against the config redirection service (which would defeat the whole purpose). This implies that everybody can retrieve this information, just by pretending to be the device with said serial number. You can avoid this by not specifying an URL in my.innovaphone.com.

Configuration

To enable the config redirection server scheme for a particular device, you first need to add the device to your account in my.innovaphone.com. You then assign it to a project. For the project, you set the URL and Trust (optional) property. The URL property must be set to a valid URL which targets a config server. If the URL uses HTTPS, the Trust must be set additionally to the public key used by the target config server.

You may obtain the value for the Trust property by trusting your target config server's certificate on any innovaphone device (see Reference10:General/Certificates). You then need to copy the value part of the corresponding vars create X509/TRUSTED/nnnnn variable (available via Reference10:Maintenance/Diagnostics/Config-Show).

Example:

vars create X509/TRUSTED/00000 pb 308203973082027fa0030...

you set URL to

308203973082027fa0030...

Protocol Details

This information is subject to change!

All redirection activities done to the device will be written to the update clients CFG variable, shown here

Current Update Serials

Name	Value	Date
PROT	100850	08.07.2013-14:17:50
...
CFG	redirected to https://1.2.3.4/DRIVE/CF0/update/staging.txt

Script sent to the device in response to the default URL

This script will instruct the device to poll again with a number of query args

# innovaphone std device redirector
# no device info present - rewriting poll url to https://config.innovaphone.com/init/redirect.php?mac=#m&hwid=#h&firm=#F&boot=#B&type=#t
vars create UPDATE/CFG p no+device+info+present+-+rewriting+poll+url+to+https://config.innovaphone.com/init/redirect.php?mac=#m&hwid=#h&firm=#F&boot=#B&type=#t
config change UP1 /provision 5 /trace /no-dhcp /url https%3A%2F%2Fconfig.innovaphone.com%2Finit%2Fredirect.php%3Fmac%3D%23m%26hwid%3D%23h%26firm%3D%23F%26boot%3D%23B%26type%3D%23t
# activate changes
config write
config activate
iresetn

Script sent to the device if it is unknown to my.innovaphone

# innovaphone std device redirector
# unknown mac 00-90-33-30-00-bf
vars create UPDATE/CFG p unknown+mac+00-90-33-30-00-bf
config rem UP1 /provision
config rem UP1 /poll
config rem UP1 /url
# activate changes
config write
config activate
iresetn

Script sent to the device if a config server is known

# innovaphone std device redirector
# redirect
# redirected to https://1.2.3.4/DRIVE/CF0/update/staging.txt
vars create UPDATE/CFG p redirected+to+https://1.2.3.4/DRIVE/CF0/update/staging.txt
config change UP1 /provision 5 /trace /no-dhcp /url https%3A%2F%2F1.2.3.4%2FDRIVE%2FCF0%2Fupdate%2Fstaging.txt
# activate changes
config write
config activate
iresetn

If there is a Trust value configured for the project, it will be passed to the device in 2 additional lines

# trust
vars create X509/TRUSTED/00099 pb 308205953082037da0030201020201003...

Optional further information sent to the device

The config redirection service can report a number of data to the calling device. This data is stored in the update clients persistent data with commands such as mod cmd UP1 setvar r-type IP232. This is done however only if the project configuration in my.innovaphone is setup accordingly. To do so, you need to prefix the Trust property of the project in my.innovaphone.com with a list of property names, separeted from the trust with a colon (e.g. type,ip:trust-value). To request all of the available properties, use *: as property list.

Here is the current list of properties that can be requested (as of ckl 16:29, 8 July 2013 (CEST)):

property	sample value	description
mac	00-90-33-30-00-af	device serial number
boot	100850	device boot code version
hwid	501	device hardware-id
type	IP232	device type
prj-id	10801	project-id in my.innovaphone
prj-name	Kuenkel00001	project name in my.innovaphone
prj-comment	ckl's+Privat-VM	project comment in my.innovaphone
prj-trust	308205953082037da0030201 ...	config server public key (see above)
cust-name	Hosting Company	customer name in my.innovaphone of the device's project
cust-id	1527	customer id in my.innovaphone of the device's project
ip	172.16.10.45	calling ip
prj-urlroot	https://1.2.3.4/DRIVE/CF0/update	config server's URL with last component stripped
redirected	2013-07-08.14:05:14	date and time stamp of redirection

List of possible Messages sent to Client Device

no device info present - rewriting poll url

update URL query arguments did not include device identification. Query args are appended and update URL is rewritten.

mac not given

incomplete device identification was given in update URL query args. Polling is turned off.

unknown mac

serial number unknown to our database. Polling is turned off.

mac in more than one project with configured update URL

there are ambiguous config server specifications set in my.innovaphone. Polling is turned off.

nothing to redirect for

there is no config server defined for this device. Polling is turned off.

firmware/boot code xxx too old - must be at least yyy

the calling device has an old firmware running which cannot be upgraded safely. Polling is turned off.

firmware/boot code xxx needs upgrade - upgrading to yyy from path

firmware is too old but can be upgraded. An appropriate upgrade command is sent to the device.

redirected to

the device has been redirected to the specified config server