Overview

When migrating a bundle from ESF 2 to ESF 3.x, you need to refactor the code so it matches the Kura namespace upon which ESF 3.x is developed. The general migration workflow is as follows:

  • Refactor the MANIFEST.MF file
  • Refactor the imports for each file
  • Refactor exceptions and Kura-specific classes (i.e., EsfPayload to KuraPayload)
  • Refactor the pom.xml file, if needed
  • Modify ESF-specific paths and system variables to the Kura related ones
  • ESF 3.1.x security policy

This section uses the com.eurotech.example.publisher bundle as a porting example.

Refactor the MANIFEST.MF and build.properties Files

In the MANIFEST.MF file, and replace com.eurotech.framework with org.eclipse.kura as shown in the import statements below:

ESF 2 Import Statements:

Import-Package:
    com.eurotech.framework,
    com.eurotech.framework.cloud,
    com.eurotech.framework.configuration,
    com.eurotech.framework.message,
    org.osgi.service.component;version="1.2.0",
    org.slf4j;version="1.6.4"

ESF 3.x Refactored Import Statements:

Import-Package:
    org.eclipse.kura,
    org.eclipse.kura.cloud,
    org.eclipse.kura.configuration,
    org.eclipse.kura.message,
    org.osgi.service.component;version="1.2.0",
    org.slf4j;version="1.6.4"

Similarly, in the build.properties file, replace com.eurotech.framework with org.eclipse.kura.

Refactor the Imports

Next, refactor the imports for each file in the source folders by changing com.eurotech.framework to org.eclipse.kura. In this example, the ExamplePublisher.java file needs to be refactored with this change.

NOTE: Some of the new imports will refer to classes that have changed from ESF 2 and consequently they will not be resolved. These imports may be removed and added later.

ESF 2 Import Statements:

import com.eurotech.framework.EsfException;
import com.eurotech.framework.cloud.CloudClient;
import com.eurotech.framework.cloud.CloudClientListener;
import com.eurotech.framework.cloud.CloudService;
import com.eurotech.framework.configuration.ConfigurableComponent;
import com.eurotech.framework.message.EsfPayload;

ESF 3.x Refactored Import Statements:

import org.eclipse.kura.EsfException;
import org.eclipse.kura.cloud.CloudClient;
import org.eclipse.kura.cloud.CloudClientListener;
import org.eclipse.kura.cloud.CloudServic;
import org.eclipse.kura.configuration.ConfigurableComponent;
import org.eclipse.kura.message.EsfPayload;

NOTE: EsfException and EsfPayload will report an error. The resolution to this error is addressed in the next section Refactor Kura Specific Classes.

Refactor Kura Specific Classes

Now that the imports are correct, replace ESF-specific classes in the code with the Kura counterpart.

  • Replace any occurrence of EsfException with KuraException
  • Replace any occurrence of EsfPayload with KuraPayload

The import section of the code should appear as follows:

import org.eclipse.kura.KuraException;
import org.eclipse.kura.cloud.CloudClient;
import org.eclipse.kura.cloud.CloudClientListener;
import org.eclipse.kura.cloud.CloudService;
import org.eclipse.kura.configuration.ConfigurableComponent;
import org.eclipse.kura.message.KuraPayload;

The refactoring of ExamplePublisher.java file is now finished and there should be no errors in the source code.

Edit the pom.xml File

If the bundle that is being ported is included in a Maven build, the pom.xml file may need to be edited so that the bundle is correctly included in the build process. While this should not be the case for custom, third-party bundles, for ESF bundles, the parent_pom tag must have com.eurotech.framework changed to org.eclipse.kura as shown in the example below:

ESF 2 Parent Tag:

<parent>
    <groupId>com.eurotech.framework</groupId>
    <artifactId>esf</artifactId>
    <version>1.0.0-SNAPSHOT</version>
    <relativePath>../pom.xml</relativePath>
</parent>

ESF 3.x Parent Tag:

<parent>
    <groupId>org.eclipse.kura</groupId>
    <artifactId>kura</artifactId>
    <version>1.1.0-SNAPSHOT</version>
    <relativePath>../pom.xml</relativePath>
</parent>

Refactor Hardcoded Paths

If the bundle uses any hardcoded file paths or system variables identifiers, they must be changed appropriately to reflect the new Kura-based file system.

NOTE: Character-case should be maintained in the Esf to Kura porting. For example, esf.database.path would become kura.database.path and CustomEsfClass would become to CustomKuraClass.

ESF 3.1.x security policy

ESF 3.1.0 and newer versions added a new security layer to protect the secrets handled by the framework.
ESF uses a set of rules to determine the privileges that have to be assigned to the different bundles and what specifically a bundle can do.
Secrets are protected using AES-128 to encrypt the passwords and to protect the snapshots that contain those passwords in the filesystem.

The set of rules specified in ESF 3.1.x give full resources access to the bundles that are signed by Eurotech and to the bundles signed by Eurotech’s partners that have a proper signature chain.
Other bundles that are unsigned or signed with a certificate chain that is not recognized by ESF have a reduced set of permissions. These bundles can use a subset of all the installed packages. A bundle that breaks one of the following rules can be blocked or can behave unexpectedly.

An unauthorized bundle cannot:

  • Register or get a reference to the org.eclipse.kura.crypto.CryptoService;

  • Register or get a reference to the org.eclipse.kura.certificate.CertificatesService;

  • Register or get a reference to the org.eclipse.kura.configuration.ConfigurationService;

  • Get a reference to the org.eclipse.kura.data.DataTransportService;

  • Register a service named org.eclipse.kura.ssl.SslManagerService;

  • Change its “startlevel” or the start level of other bundles;

  • Set a new Java Security Manager;

  • Export an interface named “org.eclipse.paho.client.mqttv3.*”.

NOTE: Snapshots are encrypted with a per-device key. For this reason, an encrypted snapshot cannot be directly used in a different device: since ESF 3.1.x, the user that wants to use a snapshot encrypted by a device should download it first from the local web UI or from the Eurotech Cloud interface.

How to generate a Certificate Signing Request (CSR)

  • The first step is to use Open SSL (https://www.openssl.org) to create a private key and the corresponding Certificate Signing Request (csr) that you have to send to Eurotech representatives.
    The key generation can be done as follows:
openssl req -new -newkey rsa:2048 -nodes -keyout yourdomain.key -out yourdomain.csr

  • After having received the certificate chain countersigned by Eurotech, you have to include it with the correspondent private key into a keystore (for example you can use openssl and/or keytool for this purpose).

    • openssl can be used to create a pkcs12 keystore containing the public and the private key.
    openssl pkcs12 -export -name alias -in publicCertChain.pem -inkey privateKey.key -out resultingKeystore.p12
    • keytool can be used to import the pkcs12 keystore into the final file.
    keytool -importkeystore -destkeystore destinationKeyStore.ks -srckeystore resultingKeystore.p12 -srcstoretype pkcs12 -alias alias

  • The bundle signing can be done with “jarsigner”.

jarsigner -keystore file:destinationKeyStore.ks -storepass foobar -keypass barbaz bundle.jar alias