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 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 device 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 after a while.

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.

From July 2018, this mechanism is also used for the discovery of devices after a reset to factory defaults. See #Discovering Devices below.

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 will thus not work.
* - Apache however does support the other mode and will thus work.
* - in lighttpd, we seem to have access to SSL_CLIENT_S_DN_C, SSL_CLIENT_S_DN_CN, SSL_CLIENT_S_DN_O only.  We can not check against $goodCA thus
* and we must synthesize SSL_CLIENT_S_DN.  Also, we must configure so the web server so that it enforces client certificates and ionly trusts the
* innovaphone root CA
*/

$goodCA = array( '/C=DE/O=innovaphone/OU=innovaphone Device Certification Authority', '/C=DE/O=innovaphone/OU=innovaphone Device Certification Authority 2', ); $goodDeviceDNPrefix = '/C=DE/O=innovaphone/CN=';

$useLightTPD = false; // set this to true if you use lighttpd AND have configured it correctly if ($useLightTPD) {

   $_SERVER['SSL_CLIENT_S_DN'] = "/C={$_SERVER['SSL_CLIENT_S_DN_C']}/O={$_SERVER['SSL_CLIENT_S_DN_O']}/CN={$_SERVER['SSL_CLIENT_S_DN_CN']}";
   $_SERVER['SSL_CLIENT_VERIFY'] = 'SUCCESS'; // make sure this is asserted in lighttpd.conf (using ssl.verifyclient.enforce);
   $_SERVER['SSL_CLIENT_I_DN'] = $goodCA[0];

}

// dump TLS info

print "#

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

/*
 *  the dump above will yield something like
# HTTPS: 'on'
# SSL_CLIENT_S_DN: '/C=DE/O=innovaphone/CN=IP1202-35-fe-4d'
# SSL_CLIENT_S_DN_CN: 'IP1202-35-fe-4d'
# SSL_CLIENT_I_DN: '/C=DE/O=innovaphone/OU=innovaphone Device Certification Authority'
# 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'
 *
 * 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 is the requesting device and we must only hand out information that belongs to this device.
 */

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

// get serial
$cn = empty($_SERVER['SSL_CLIENT_S_DN_CN']) ? "??-??" : $_SERVER['SSL_CLIENT_S_DN_CN'];

// some early certificates where broken, fix here:
$brokenCN = array(
    "IP222s" => "IP222",
    "IP232s" => "IP232",
    "IP240a" => "IP240",
    "IP200a" => "IP200",
    );
$cnparts = explode("-", $cn);

foreach ($brokenCN as $broken => $fix) {
    if ($cnparts[0] == $broken) {
        $cnparts[0] = $fix;
        $cn = implode("-", $cnparts);
        break;
    }
}

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

Please note that there was an issue when an innovaphone client attempts to retrieve an update script with MTLS.  This has been fixed with v10sr3.

===== 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
   SSLCertificateFile "C:/Program Files (x86)/Apache Software Foundation/Apache2.2/certs/your-certificate.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>

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

 # the server must be ssl-capable!
 
 ## modules to load
 # we need setenv 
 server.modules              = (
   # ...,
   "mod_setenv",
   # ...
 )
 
 #### SSL engine
 $SERVER["socket"] == ":443" {
   ssl.engine                 = "enable"
   ssl.pemfile                = "C:/Program Files (x86)/Apache Software Foundation/Apache2.2/certs/your-certificate.pem"
   ssl.ca-file                = "C:/Program Files (x86)/Apache Software Foundation/Apache2.2/certs/inno-dev-ca-certificate.crt"
   # allow client side certificates
   ssl.verifyclient.activate = "enable"
   # enforce client side certificates
   ssl.verifyclient.enforce    = "enable" 
   # tell PHP we have HTTPS
   setenv.add-environment = ( "HTTPS" => "on" )
 }

On the Linux Application Platform, you can do this as described in [[Reference10:Concept_Linux_Application_Platform#Configure_mutual_TLS | Configure mutual TLS ]].

===== Enforcing mutual TLS on IIS =====
On Microsoft's IIS, we did not succeed to enforce MTLS, unfortunately.

===== How to get <code>inno-dev-ca-certificate.crt</code> =====
The file <code>inno-dev-ca-certificate.crt</code> in the above HTTP server configuration snippets is a PEM encoded version of innovaphone's ''device certifcation authority'' certificate (public key only, of course).  You can get this from any innovaphone device that already trusts another innovaphone device by downloading it from the ''PEM'' link under ''General/Certificates/Trust list''.

[[Image:Concept Provisioning get-inno-ca.png]]

The other certificate file used in the snippets (called <code>your-certificate.pem</code> there) is actually the full blown certificate you want to use for your provisioning server.  Make sure that the calling devices trust this certificate (e.g. by setting it as ''Trust'' in the my.innovaphone project configuration)!

====== New innovaphone device CA from July 2015 ======
From July 2015 on, we are using a new device certification autority, which is called <code>/C=DE/O=innovaphone/OU=innovaphone Device Certification Authority 2</code>.  In your provisioning service, you must accept device certificates from both CAs.  The ''inno-dev-ca-certificate.crt'' file used previously should be replaced by the ''inno-dev-ca-all-certificate.crt'' file which includes the concatenated public keys of both CA.

Here is its content:
<pre>
-----BEGIN CERTIFICATE-----
MIIDlzCCAn+gAwIBAgIBADANBgkqhkiG9w0BAQUFADBYMQswCQYDVQQGDAJERTEU
MBIGA1UECgwLaW5ub3ZhcGhvbmUxMzAxBgNVBAsMKmlubm92YXBob25lIERldmlj
ZSBDZXJ0aWZpY2F0aW9uIEF1dGhvcml0eTAeFw0wODAxMDEwMDAwMDBaFw00ODAx
MDEwMDAwMDBaMFgxCzAJBgNVBAYMAkRFMRQwEgYDVQQKDAtpbm5vdmFwaG9uZTEz
MDEGA1UECwwqaW5ub3ZhcGhvbmUgRGV2aWNlIENlcnRpZmljYXRpb24gQXV0aG9y
aXR5MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAur7epPiIOkN6vIbt
46eH1AzIskP9HvyL63VgG3eJ+oqZRw4xn13FHzDBpnMZw1XW01byAlbYum+w5QTo
QDdZ6NTxe17TCduIXvCAE5MyvTyzF0NuAJ9EZe4UUELoE1whFkYM+xSLvh6uqv4p
TOFMtTBUtIUJ4g2tTgQ7UdxNdgLnXDzb9O0ZedVNydYhqNIPYgI5L6SLzy5Kflbz
mT9eMFEYQSNRlrvAowN5LqjsyA8CFY8rY9G2yZUHoB4TOK4zdhxrQW/mHotWT8hL
eEhAoK9/EBkQckyk/M21K78U4GtoMxYOFAjmH6SaqhnyGOe+03F/VCV6QZbNmzaR
HR2uoQIDAQABo2wwajASBgNVHRMBAf8ECDAGAQH/AgEAMA4GA1UdDwEB/wQEAwIB
BjAiBgNVHSMBAQAEGDAWgBQSom116MPX3gNCCyTsncz1BTBUWjAgBgNVHQ4BAQAE
FgQUEqJtdejD194DQgsk7J3M9QUwVFowDQYJKoZIhvcNAQEFBQADggEBACvQUbBc
AhMsPEuFG/omAHw0O36h7nfSDK+i9/LfsESvjCmQSgMmep7we7/SBIqHTDrvc+e9
MkoIqkBjzO2kpfOMt09i4inff4mKs971tm0lX4I8J+5RO2I/RHdQMbHBgprZYOmQ
Nk6uV2b87LQHh0WU4EE/IctxHQwZ2xq9n3i7io8ODvaJsgEuIe2rpmTi8RJ0MuzV
bNaQqNnmZT2bqgPVUIrIVyEOCHYEY59ZvwuNq9oOpUqqzuIy2N2dJ41ODDE/ivd2
LiUFap5vD+TndeutfMCodLdUR9MsdMCZ/N9QoZ6q4KS4JV/Hc7kwKBw1W6HbQfyh
Ig6j9ACxEGOFRDY=
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
MIIDmzCCAoOgAwIBAgIBADANBgkqhkiG9w0BAQsFADBaMQswCQYDVQQGEwJERTEU
MBIGA1UEChMLaW5ub3ZhcGhvbmUxNTAzBgNVBAsTLGlubm92YXBob25lIERldmlj
ZSBDZXJ0aWZpY2F0aW9uIEF1dGhvcml0eSAyMB4XDTE1MDYyNTAwMDAwMFoXDTQ4
MDEwMTAwMDAwMFowWjELMAkGA1UEBhMCREUxFDASBgNVBAoTC2lubm92YXBob25l
MTUwMwYDVQQLEyxpbm5vdmFwaG9uZSBEZXZpY2UgQ2VydGlmaWNhdGlvbiBBdXRo
b3JpdHkgMjCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAJ9bexBENv6a
uu8k+9Yz1C2Uf1awmPGFlQpyDfCullm8MQKTtcju4yyI6ZvB3O/b6q3Twh44gcN1
CIh3buUyOuc7lOFnil00H8i/qgQLBCt4JRt3y72ZlPJGvuQnDGlTKqfBOuuNh02g
QFVyJk02g1EJHDhcY86m3imZ6YFbxxDw9XDx6BDw0CfqGBptmUUaG/1qejhSW+il
dSPBMGvYnlyyLwYw++wpMa9/h3GFXph+JJ70i5plLPXYLB2ak9HjGJXM+NhC9KXp
qV+YDPdpPZXWg+CpzQRGOzk5hz7NuAgyHkOILsQpftAiq9k1vHy8z6ByKAnW3Jc6
3bSAkrzriAkCAwEAAaNsMGowEgYDVR0TAQH/BAgwBgEB/wIBADAOBgNVHQ8BAf8E
BAMCAQYwIgYDVR0jAQEABBgwFoAUUm9Jo7Xo8yT34tARvFVe0VHks0UwIAYDVR0O
AQEABBYEFFJvSaO16PMk9+LQEbxVXtFR5LNFMA0GCSqGSIb3DQEBCwUAA4IBAQCc
WLWShSLEH4of84A5oxTW2kHMzvsYgG4EmgtE0iSf1xfueHoP7g2bjPwNcp57aWTD
fUzw3sn7wFICK+7b0pDRHZYkC9gmc6mWZ9I16Vm8W/SqvB75DSUfuk/Lrcs7TjrV
q+J2mQXgyrREngq1CXUBCCf6+W/CZbxq0d5TdlEz9TDNjdd1E1G3CDpZiVE4AFlm
uiUi8clkGES/bh5gNcZ+/vfb0pylUjbO84tBYc4fqw7WFPTvEXZ9KHa09uI9dHPN
SSr3jLua7BbhRQALK2M+DFVWFNGFcxTEUfOSMjQbXnRL6mdtDScYCvvunRJlQB81
S0HWEZ+eG+I6lGJk+d8R
-----END CERTIFICATE-----

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 Trust 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
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
config rem UP1 /provision
config rem UP1 /poll
config rem UP1 /url
config rem UP1 /no-dhcp
config rem UP1 /trace
# activate changes
config write
config activate
iresetn

Note that from July 2018, this script is only sent for one hour after the first time the device called to the site after a factory reset. During this hour, the service will return a script that modifies the current query arguments so that it includes a nostdprv=unix-time argument. unix-time is the time the device first called. After the first hour, the script shown above is returned to remove the update URL.

This mechanism is now used for #Discovering Devices.

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 setvar 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, separated 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

Software Phone

Please note that the SoftwarePhone only supports the http://config.innovaphone.com/init scheme from V10 build 101100. Furthermore, as the SoftwarePhone by nature does not have a built-in device certificate, it cannot be trusted automatically by the provisioning server.

Discovering Devices

As outlined above, we do log devices which contact config.innovaphone.com/init in a database. From July 2018, we provide a discovery service for such devices based on this. You can use the web site config.innovaphone.com to see a list of your own devices. This may greatly simplify the process of accessing a device which has been reset to factory defaults recently.

You can also access this information programmatically by calling config.innovaphone.com/mydevice.json:

[{"id":600515,"mac":"00-90-33-41-03-57","text":"grace period 172.16.108.2","time":1530631511,"customerid":0,"projectid":0,"ip":"145.253.157.7","devattrs":{"mac":"00-90-33-41-03-57","hwid":"IP811-41-03-57","firm":"13A127","boot":"113454","type":"IP811","provisioning-code":"","localip":"172.16.108.2","nostdprv":"1530631285","ver":"13r1 dvl IP811[13.A127], Bootcode[113454], Hardware[300] ","_allIPs":["145.253.157.7","145.253.157.20"]},"localip":"172.16.108.2"}]

Related Articles

Reference10:Concept_Update_Server

description of the update server, especially the setvar, replace and eval commands.

Reference:My_Innovaphone#External_interface

description of the programmatic interface to add device serial numbers to a my.innovaphone project