Everyware Software Framework Developer's Hub

Everyware Software Framework (ESF) is an enterprise-ready IoT Edge Framework distributed and supported by Eurotech. Based on Eclipse Kura, the open source Java/OSGi middleware for IoT gateways, ESF adds provisioning, advanced security, remote access, diagnostics monitoring. It supports ready-to-use field protocols (including Modbus, OPC-UA, S7), MQTT connectivity, and a web-based visual data flow programming to acquire data from the field, process it at the edge, and publish it to IoT Cloud Platforms. ESF features full remote device management through its integration with Everyware Cloud, Eurotech’s IoT Integration Platform.

Get Started

Move to Production

In order to move a development environment to production and deploy devices to the field, few steps should be done to improve the overall security of the resulting embedded systems:

Linux Hardening

Eurotech suggests few guidelines that can be used to obtain a safer system:

  • Change the default root user password with a more secure one. For example choosing a long, difficult-to-guess credential which should include lowercase and uppercase letters, numbers and special characters.
# 1. Connect to the server:
ssh root@10.10.10.1

# 2. Type the following command:
passwd
  • Create new users without root privileges.
# 1. Connect to the server:
ssh root@10.10.10.1

# 2. Add a new user with the new username:
useradd newUserName

# 3. Specify the password for the newly created user:
passwd newUserName
  • Disable root access from SSH.
# 1. Connect to the server:
ssh root@10.10.10.1

# 2. Edit the ssh server configuration:
sudo nano /etc/ssh/sshd_config

# 3. Edit the configuration:
PermitRootLogin no

# 4. Save and then type: 
/etc/init.d/sshd restart
  • Configure the SSH server to allow public key authentication only.
    • Certificates should have key size bigger or equal than 2048 bit.
# 1. Generate the ssh key pair on the desktop computer:
ssh-keygen

# 2. Copy the public key to the server:
scp ~/.ssh/id_rsa.pub root@10.10.10.1:

# 3. Connect to the server:
ssh root@10.10.10.1

# 4. Append the public key to authorized_keys and remove the uploaded copy:
cat id_rsa.pub >> ~/.ssh/authorized_keys
rm id_rsa.pub

# 5. Edit the ssh server configuration to make sure that public key authentication is enabled (it should be enabled by default):
sudo nano /etc/ssh/sshd_config

# 5.1 These entries must be set to yes:
RSAAuthentication yes
PubkeyAuthentication yes

# 6. Save and then type: 
/etc/init.d/sshd restart
  • Deny SSH password access.
# 1. Connect to the server:
ssh root@10.10.10.1

# 2. Edit the ssh server configuration:
sudo nano /etc/ssh/sshd_config

# 2.1 These entries must be set:
ChallengeResponseAuthentication no
PasswordAuthentication no
UsePAM no

# 3. Save and then type: 
/etc/init.d/sshd restart
  • Move the SSH server to a non-default port (i.e. move the server from port 22 to a port in the range [49152-65535].
# 1. Connect to the server:
ssh root@10.10.10.1

# 2. Edit the ssh server configuration:
sudo nano /etc/ssh/sshd_config

# 2.1 Modify the Port field:
Port 49153

# 3. Save and then type: 
/etc/init.d/sshd restart
  • Disable unnecessary network services like Avahi or SysRq.
  • Protect U-Boot by setting the boot delay to 0. The following commands can be used for this purpose.
# 1. Reboot the device:
reboot

# 2. Use the serial console to access U-Boot.

# 3. Type the following command to set the boot delay to 0:
setenv bootdelay 0

# 4. Save the environment:
saveenv

Eurotech suggests to keeps the devices updated with the latest Linux released image, in order to take advantage of all the latest security patches applied.

ESF Hardening

ESF should be fine tuned before field deployment. Eurotech suggests to:

  • Move ESF into production mode .
    • Adopt a strong security policy.
  • Review the installed firewall rules to avoid exposing unwanted services (i.e. remove entries for port 8000 and 1450).
  • Restrict the access to the local ESF Gateway Administration Console, for example, allowing access only to​ the VPN subnet by setting the IP network range to 10.234.0.0/16 and the allowed interface to tun0.
  • Adopt strong ESF Gateway Administration Console username and password (it should be long, difficult-to-guess, including lowercase and uppercase letters, numbers, and special characters).
  • Every new device should connect to the target account through provisioning .
  • Disable the remote command execution or protect the service with a strong password.
  • Disable all the network interfaces that are not used or protect them with suitable firewall rules.
    • If the device is setup to enable the Wi-Fi interface in Access Point (AP) mode, it is recommended to ensure that the wireless network is protected using a strong WPA/WPA2 password.
    • If the Wi-Fi connectivity is not required, it should be disabled.

Eurotech suggests to keep ESF up-to-date, in order to take advantage of all the latest security improvements.

Creating a Custom ESF Installer

Often there is the need to install ESF with a custom configuration and software.
First of all, a golden sample with the desired configuration has to be created, following the previous guidelines. The security features of ESF do not allow cloning the disk of the golden sample to another device. For this reason, the following steps should be performed in order to replicate the golden sample configuration.

Prepare Configuration Snapshot

The last configuration snapshot of the golden sample contains the whole configuration of the ESF gateway. This includes the configuration of the ESF core services and the configuration of the bundles and packages installed by the customer.

The snapshot will likely contain the MQTT credentials used by the golden sample to connect to the customer account. It's important that every ESF gateway connects to the customer account using unique credentials. Unique MQTT credentials can be obtained if the gateway connects to the customer account through Everyware Cloud Provisioning. For these reasons the snapshot of the golden sample cannot be used as-is ​but needs to be edited.

  1. Download the latest configuration snapshot from the golden sample using the local ESF Gateway Administration Console.

The downloaded snapshot is unencrypted, so keep it in a safe place!

  1. Open the snapshot with an editor and change the configuration of the component org.eclipse.kura.core.data.transport.mqtt.MqttDataTransport replacing the values of the properties username, topic.context.account-name, broker-url and password so that they look like this:
<esf:configuration pid="org.eclipse.kura.core.data.transport.mqtt.MqttDataTransport">
  <esf:properties>
    <esf:property name="username" array="false" encrypted="false" type="String">
      <esf:value>username</esf:value>
    </esf:property>
    <esf:property name="topic.context.account-name" array="false" encrypted="false" type="String">
      <esf:value>account-name</esf:value>
    </esf:property>
    <esf:property name="broker-url" array="false" encrypted="false" type="String">
      <esf:value>mqtts://broker-url:8883/</esf:value>
    </esf:property>
    <esf:property name="password" array="false" encrypted="false" type="Password">
      <esf:value>password</esf:value>
    </esf:property>
  </esf:properties>
</esf:configuration>
  1. Set to false the value of the connect.auto-on-startup property of the component org.eclipse.kura.data.DataService

  2. Set to true the value of the enabled property of the component org.eclipse.kura.provisioning.ProvisioningService. If the golden sample has been connected to the customer account through Device Provisioning the credentials and the URL of the provisioning broker should be already set. Otherwise please see Everyware Cloud Provisioning.

The modified snapshot will replace the factory snapshot_0.xml under /opt/eurotech/esf/user/snapshots/ on the other gateways.

Backup Installed Packages

Copy from the golden sample to the PC the software installed through Deployment Packages:

  1. dpa.properties (available at /opt/eurotech/esf/data/dpa.properties)
  2. packages directory (available at /opt/eurotech/esf/data/packages/)

Backup the Security Policy

Copy from the golden sample to the PC the security.policy file (available at /opt/eurotech/esf/user/security/security.policy).

Make sure the security policy file is suitable for production. See Execution Modalities and Security Policy File.

Backup Network Configurations

The ESF configuration snapshot (snapshot_0.xml) alone is not enough to restore the whole network configuration. The following configuration files and directories must be backed-up:

  1. DNS server configuration under the /etc/bind/named.conf
  2. The network interfaces configuration file /etc/network/interfaces
  3. The ESF firewall configuration file /etc/sysconfig/iptables
  4. The custom firewall script /etc/init.d/firewall_cust
  5. The cellular connection configuration directory /etc/ppp/
  6. The DHCP server configuration files /etc/dhcpd-*.conf
  7. The Wi-Fi WPA configuration files /etc/wpa_supplicant-*.conf
  8. The Wi-Fi access point configuration files /etc/hostapd-*.conf
  9. The ESF network configuration file /opt/eurotech/esf/user/kuranet.conf

The above list refers to an Debian-based Linux distribution (like Yocto).
Depending on the network configuration some of the above files might not exist.

ESF Bundle and Message Signing Keystore Preparation

Prepare ESF keystore used to verify the signature of the bundles as described in the Bundle Signing page.

Do not copy the keystore from the golden sample to another gateway. The keystore is "personal" to a gateway and cannot be transferred​.

The ESF keystore used to verify the signature of the bundles is also used to verify the signatures of the incoming MQTT control messages. The certificate to verify the messages is obtained by the gateway during Device Provisioning.

ESF SSL Keystore Preparation

cacerts.ks is the keystore containing the certificates and private keys for the SSL server and client handshake. Normally, the cacerts.ks file is available at /opt/eurotech/esf/user/security/cacerts.ks.

By default, the factory SSL keystore provided with a vanilla ESF installation contains the certificate of the public Everyware Cloud platform that is used by ESF to authenticate the MQTT broker. To connect the ESF gateway to an on-premises Everyware Cloud platform or another cloud platform, or to enable SSL mutual authentication, the proper certificates and private keys must be added to the SSL keystore.

The default cacerts.ks password, for security purposes, is not released by Eurotech.
Furthermore, by default, at the first ESF booth, the default keystore password is changed with one known only to the specific ESF instance.

To ease the creation of a golden master ESF installation, Eurotech provides a basic ESF cacerts.ks file, available at the following link and that can be accessed/changed with the changeit password.

The customer can import his own certificates in this keystore and replace the ESF factory keystore.

the value of the initial keystore password is written in plain text in the value of the kura.ssl.keyStorePassword property in /opt/eurotech/esf/framework/kura.properties. For improved security it is advisable to change the initial keystore password and modify the kura.ssl.keyStorePassword accordingly.

Having the keystore password stored in plain text in the kura.properties file represents a momentary vulnerability where the keystore could be tampered by an attacker before the very first ESF boot. For improved security it is advisable to boot ESF once before shipping the gateway.

In all cases, ESF will change the initial keystore password to a randomly generated password at the very first boot. The new password will be securely stored.

Copy Everything to Another Gateway

To replicate the golden sample configuration to another "vanilla" gateway follow these steps:

  1. Stop ESF if it is running:
/etc/init.d/monit stop
/etc/init.d/kura stop
  1. Reinstall ESF using the same release as the golden sample

Do not reboot the system or start ESF.

  1. Copy the above files to their respective locations on the gateway filesystem. If the cellular interface is configured, the following soft-link must be created:
ln -s /etc/ppp/peers/LE910_2-1 /etc/ppp/peers/ppp0
  1. Reboot and verify that ESF runs in production mode
  2. Verify that all services and applications are active and that their configurations are correct