TrustFence tamper API | ConnectCore 8X

The tamper interface provides a mechanism to detect unauthorized attempts to access the system such as the opening of the enclosure.

The ConnectCore 8X has up to two pins associated: input pin and an optional output pin. See Tamper pins to find information about these pins.

Digi adds to Android an API to detect and interact with tamper events. In the Digi APIx javadoc you can find a complete list of the available methods in this API.

To work with tamper interfaces, you must:

Enable the mca_tamper interface in the device tree. See Device tree bindings.
Configure the tamper interfaces with tamper_config application and save into NVRAM. See Configure the tamper interfaces.

Unless noted, all TrustFence tamper API methods require the com.digi.android.permission.TRUSTFENCE permission.

If your application does not have the com.digi.android.permission.TRUSTFENCE permission it will not have access to any TrustFence service feature.

First, a new TrustfenceManager object must be instantiated by passing the Android Application Context.

Instantiate the TrustfenceManager

import android.app.Activity;
import android.os.Bundle;

import com.digi.android.trustfence.TrustfenceManager;

public class TfTamperSampleActivity extends Activity {

    TrustfenceManager trustfenceManager;

    [...]

    @Override
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);

        // Instantiate the TrustFence manager object.
        trustfenceManager= new TrustfenceManager(this);

        [...]
    }

    [...]
}

Instantiate a tamper interface

The TrustfenceManager allows you to create a tamper object for a given index.

Create an tamper object

import com.digi.android.trustfence.TamperInterface;
import com.digi.android.trustfence.TrustfenceManager;

[...]

TrustfenceManager trustfenceManager = ...;

// Get number of available tamper interfaces
int numInterfaces = trustfenceManager.getNumTamperInterfaces();

for (int i = 0; i < numInterfaces; i++) {
    TamperInterface tamperInterface = trustfenceManager.getTamperInterface(interfaceIndex);
    System.out.format("Tamper index %d - active: %s", i, tamperInterface.isActive())
}

[...]

You can get information about events in a tamper interface, acknowledge, or clear the event:

Method Description

Method	Description
`isEventTriggered()`	Returns whether the tamper event has been triggered.
`isEventAck()`	Returns whether the tamper event has been acknowledged.
`ackEvent()`	Acknowledges the tamper event.
`clearEvent()`	Clears the tamper event.

isEventTriggered()

Returns whether the tamper event has been triggered.

isEventAck()

Returns whether the tamper event has been acknowledged.

ackEvent()

Acknowledges the tamper event.

clearEvent()

Clears the tamper event.

Listen for tamper events

You can listen to tamper events if you register an ITamperEventListener to the TamperInterface object. Use the registerListener(ITamperEventListener) method to register for particular tamper events updates.

Tamper event updates registration

import com.digi.android.trustfence.TamperInterface;
import com.digi.android.trustfence.TrustfenceManager;

[...]

TrustfenceManager trustfenceManager = ...;
TamperInterface tamperInterface = ...;

// Create the tamper events listener.
MyTamperListener myTamperListener = ...;

// Register the tamper events listener.
tamperInterface.registerListener(myTamperListener);

[...]

The registered listener class, MyTamperListener, must implement the ITamperEventListener interface. This interface defines the eventTriggered(int) method. This method notifies about a tamper event triggered in the given interface index.

The eventTriggered(int) method receives an integer with the index of the tamper interface that triggered the event.

ITamperEventListener implementation example, MyTamperListener

import com.digi.android.trustfence.ITamperEventListener;

public class MyTamperListener implements ITamperEventListener {
    @Override
    public void eventTriggered(int interfaceIndex) {
        // This code will be executed when a tamper event is triggered.
        System.out.format("Tamper event at index %d", interfaceIndex);
    }
}

To stop receiving tamper events notifications, use the removeListener() method. If you no longer wish to receive updates, use the removeListener(ITamperEventListener) method to unsubscribe an already registered listener.

Tamper event updates unregistration

[...]

TamperInterface tamperInterface = ...;
MyTamperListener myTamperListener = ...;
tamperInterface.registerListener(myTamperListener);

[...]

// Remove the tamper event listener.
tamperInterface.removeListener(myTamperListener);

[...]

Tamper example

The TrustFence Tamper Sample Application demonstrates the usage of the tamper API. In this example, you can detect and interact with tamper events.

You can import the example using Digi’s Android Studio plugin. For more information, see Import a Digi sample application. To look at the application source code, go to the GitHub repository.