ESF 7 provides tamper detection related Java APIs, REST APIs and MQTT request handler.
The framework supports registering TamperDetectionService instances that monitor the device status for detecting intrusion attempts:

The following TamperDetectionService implementations are available:

• ReliaGATE 10-14 hardware tamper detection
• AIDE Intrusion Detection

A TamperDetectionService can be queried for the current status, that contains a boolean flag indicating if the device is considered tampered and some properties reporting additional information about the event.

It also is possible to request to a TamperDetectionService to reset the tamper status.

Web UI

ESF Web UI provides the Security -> Tamper Detection tab that allows to review and reset the tamper status reported by the TamperDetectionService instances:

This section is visible only if the following prerequisites are satisfied:

• The current identity has either the kura.admin or kura.maintenance permissions.
• At least one TamperDetectionService instance is registered within the framework

# Java APIs

Tamper detection related Java APIs are exported by the org.eclipse.kura.security.tamper.detection package.

TAMPER-V1 MQTT namespace

TAMPER-V1 can be used to retrieve and reset the tamper status reported by the registered TamperDetectionService instances from the cloud.

Some requests exchange data using the JSON format in the message body. All parameters are mandatory unless otherwise specified.

Request/response definitions

GET/list

• description : Gets the list of registered TamperDetectionService instances
• responses :
  • 200
    • description : The pids of the currently available Tamper Detection Service instances.
    • response body :
      The Tamper Detection Service instance list.
      • type : array, element description:
        • TamperDetectionServiceInfo
  • 500
    • description : An unexpected internal error occurred

GET/pid/${pid}

• description : Gets the status reported by a specific TamperDetectionService
• path parameters :
  • pid : The TamperDetectionService pid
• responses :
  • 200
    • description : The current tamper status reported by the requested TamperDetectionService
    • response body :
      • TamperStatusInfo
  • 404
    • description : The specified TamperDetectionService could not be found
  • 500
    • description : An unexpected internal error occurred

EXEC/pid/${pid}/_reset

• description : Resets the tamper status for a specific TamperDetectionService
• path parameters :
  • pid : The TamperDetectionService pid
• responses :
  • 200
    • description : The TamperDetectionService received the reset status request. The operation may complete asynchronously
  • 404
    • description : The specified TamperDetectionService could not be found
  • 500
    • description : An unexpected internal error occurred

JSON definitions

TamperDetectionServiceInfo

An object describing a TamperDetectionService instance

• type : object
  
  Properties:

• pid
  The TamperDetectionService identifier

  • type : string

• displayName
  A user friendly name for the TamperDetectionService

  • type : string

{
	"pid": "com.eurotech.framework.security.aide.AideTamperDetectionService",
	"displayName": "AIDE Integrity Check"
}

TamperStatusInfo

An object describing the status returned by a TamperDetectionService

• type : object
  
  Properties:

• isDeviceTampered
  A boolean indicating if the device is considered to be tampered by the TamperDetectionService

  • type : boolean

• properties
  The TamperStatus properties

  • type : object
    
    Properties: the properties depend on the TamperDetectionService implementation, the value type can be either a boolean, a number, a string or a number array.

{
	"isDeviceTampered": true,
	"properties": {
		"timestamp": 1617697013000
	}
}

REST APIs

Tamper detection rest APIs are available at the /services/tamper/v1 relative URI. The contract is the same as the TAMPER-V1 MQTT namespace, with the following exception:

• The POST method must be used instead of EXEC for the reset tamper status call

The kura.admin or rest.tamper.detection permissions are required to use the REST APIs.

Birth Certificate

The device can be configured to republish the birth certificate if the tamper status changes (either due to a tamper attempt or by the tamper status reset). This behavior is enabled by default and can be disabled using the Republish Mqtt Birth Cert On Tamper Event of the CloudService.

The tamper status boolean flag will be reported as the tamper_status birth certificate metric.