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.

Securing the Configuration Data sent

The config server needs to be careful whom to send configuration data. Generally, to secure the data, it must be sent securely to the device it is intended for only.

So 2 things must be done:

• the data must be delivered via HTTPS, so nobody can sniff it on the wire
• mutual TLS must be enforced and the calling devices certificate must be verified, so that config files are delivered to the intended target device only

Let us assume the config server is implemented as a PHP web server. The following code can be used as a starter then: <?php /*

* this interface is for secure provisioning.  It demo's sample code that provides a config file in a secure manner.  This in particular means:
* - delivered via HTTPS
* - config files are delivered to the intended target device only
*
* This makes sure no configuration data can be accessed by an attacker unless the attacker has access to the calling devices certificate (which
* is practically the same as having access to the device itself)
*
* For this to work, mutual TLS is used between the device and the web server.  The PHP code then has access to the (trustable) certificate
* information presented by the client and can then tailor the information provided accordingly.
*
* there are two versions of negotiating mutual TLS.  One of them upgrades the one-way TLS only after establishing the HTTP command.  This mode
* is not supported by the innovaphone http client (as of v10sr2).  Tests have shown that IIS is using this mode and wil thuis not work.
* Apache however does support the other mode and will thus work.  No other servers tried so far.
*/

// dump TLS info

print "#

";
foreach (
    array(
    "HTTPS", "SSL_PROTOCOL", "SSL_CLIENT_S_DN", "SSL_CLIENT_S_DN_CN", "SSL_CLIENT_I_DN", "SSL_CLIENT_V_REMAIN", "SSL_CLIENT_VERIFY", "SSL_SERVER_S_DN", "SSL_SERVER_S_DN_CN"
    )
    as $var) {
    print "# $var: '" . (empty($_SERVER[$var]) ? "<not-set>" : $_SERVER[$var]) . "'\n";
}

$goodCA = '/C=DE/O=innovaphone/OU=innovaphone Device Certification Authority';
$goodDeviceDNPrefix = '/C=DE/O=innovaphone/CN=';

/*
 *  the dump above will yield something like
    HTTPS: 'on'
    SSL_PROTOCOL: 'TLSv1'
    SSL_CLIENT_S_DN: '/C=DE/O=innovaphone/CN=IP232s-30-00-af'
    SSL_CLIENT_S_DN_CN: 'IP232s-30-00-af'
    SSL_CLIENT_I_DN: '/C=DE/O=innovaphone/OU=innovaphone Device Certification Authority'
    SSL_CLIENT_V_REMAIN: '12529'
    SSL_CLIENT_VERIFY: 'SUCCESS'
    SSL_SERVER_S_DN: '/C=cert-country/ST=cert-state/L=cert-locality/O=cert-o/OU=cert-ou/CN=cert-cn'
    SSL_SERVER_S_DN_CN: 'cert-cn'
 *
 * the provisioning server needs to verify
 * - HTTPS is on
 * - SSL_CLIENT_VERIFY is 'SUCCESS' so certificate validation was OK
 * - SSL_CLIENT_I_DN is '/C=DE/O=innovaphone/OU=innovaphone Device Certification Authority', so it is a trusted innovaphone certificate
 * - SSL_CLIENT_S_DN starts with '/C=DE/O=innovaphone/CN=' so it is an innovaphone device certificate
 * 
 * if all this is true, then it has to look at SSL_CLIENT_S_DN_CN.  This the requesting device and we must only hand out information that belongs to this device.
 * 
 */

if ($_SERVER['HTTPS'] != 'on') die("# https required\n");
if ($_SERVER['SSL_CLIENT_VERIFY'] != 'SUCCESS') die("# certificates not verified\n");
if ($_SERVER['SSL_CLIENT_I_DN'] != $goodCA) die("# wrong CA\n");
if (substr($_SERVER['SSL_CLIENT_S_DN'], 0, strlen($goodDeviceDNPrefix)) != $goodDeviceDNPrefix) die("# not an innovaphone device\n");

// now get and return relevant configuration data
print "# update script for {$_SERVER['SSL_CLIENT_S_DN_CN']}\n";
?>
</code>

===== Enforcing mutual TLS on Apache =====
Here are the relevant snippets you have to add to your httpd.conf to setup Apache for mutual TLS:

 # make sure you listen for HTTPS
 Listen 443 https
 
 # ssl must be loaded
 LoadModule ssl_module modules/mod_ssl.so
 
 # configure SSL 
 <IfModule ssl_module>
   SSLRandomSeed startup builtin
   SSLRandomSeed connect builtin
  
   # require client verification
   SSLVerifyClient require
 
   # the web servers own certificate 
   # must be something that is trusted by the calling device, that is, derived from innovaphone device certification authority!
   SSLCertificateFile "C:/Program Files (x86)/Apache Software Foundation/Apache2.2/certs/ip800-full-cert-01.pem"
 
   # the CA we trust - innovaphone device certification authority only!
   SSLCACertificateFile "C:/Program Files (x86)/Apache Software Foundation/Apache2.2/certs/inno-dev-ca-certificate.crt"
 
   # make certificate data available to PHP programs
   SSLOptions +StdEnvVars +ExportCertData
 
   # switch on SSL engine for all virtual hosts on port 443
   <VirtualHost _default_:443>
     SSLEngine on
     #...
   </VirtualHost>
 
 </IfModule>

=== 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 <code>vars create X509/TRUSTED/nnnnn</code> 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
<pre>
# 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