Overview

A lot of scenarios require to publish events from the camera and to consume this data remotely. An event in this case can be any type of data produced by an app running on a device. Typically this will be a json or xml payload containing metadata such as "detected object of type xx at position yy" or similar. This metadata could also be combined with the video stream for example to highlight detected objects.

With the "Remote Metadata streaming" solution the events are pushed from the device to the cloud automatically without further interaction necessary and can be further processed or displayed remotely without any direct network access.

Examples use cases are:

Notification about a detected object
Entrance counters sent to a dashboard
Alarms sent to a monitoring center
Overlays on top of the video stream

Remote Metadata Tool

The Remote Metadata Tool is a tool developed and maintained by Azena. It needs to be installed on the device through the Application Store. After installation it will automatically connect to the message broker that is already present on the device.

By default there is no further configuration necessary, it will immediately subscribe to the message broker and it will start receiving all events that are sent by other apps to the message broker.

It is possible to configure what metadata will be published, it can be filtered by topic or app-id. The details are documented in the API Documentation.

Cloud API

see API Documentation

Security

Authentication

The device is authenticated with a client certificate present on the device, this allows to identify it uniquely and authenticate it. This process is completely automatic and no configuration necessary.

On the user side the data and configuration api can only be accessed if the camera is claimed in the company account and the access is authorized with user-credentials. See Claiming cameras for more details on how the claiming process works.

Transport encryption

All data transfer and configuration is transport-encrypted with TLS or SSL.

End-to-End encryption

Additionally end-to-end encryption can be activated by encrypting the whole event with a public key in the remote-metadata app.

Metadata is being encrypted directly in the metadata app. The data is encrypted according to the JWE (RFC 7516) standard. The encryption algorithm that is used in the JWE standard and by the Metadata app is a hybrid encryption using RSA to encrypt a random message key and AES-128 to encrypt the payload itself.

In order to activate this process a public key needs to be configured using the Cloud API. Once the key has been configured it will be used automatically by all devices where remote metadata is installed.

Quality-of-service

The MQTT client and all transport services are configured with QoS1 (at least once). Also all components are always designed to be high available and robust. However there are certain situations where a message might not be delivered. These situations include: the device does not have network access, cpu or memory of the device is overloaded or errors in the software handling the messages.

If 100% delivery guarantee is required (e.g. for alarm events), this needs to be considered in the design of messages. Depending on the requirements this can be a careful designed retry strategy or some type of inactivity alerting.

The number of messages per device per topic is limited to 2 per second.

Examples

Installing remote metadata

installing the remote metadata tool on the device

PUT https://api.integrator.live.securityandsafetythings.com/software/v1/apps/com.securityandsafetythings.remotemetadata/devices/exampledeviceid
{ "licenseType": "TOOL" }

subscribing app to topic "exampletopic"

PUT https://api.integrator.live.securityandsafetythings.com/metadata/v1/devices/exampledeviceid/subscriptions
{ "applicationIds": [], "topics": ["exampletopic" ] }

Original event sent by an app to topic "exampletopic"

"alert1"

message with event as payload

GET https://api.integrator.live.securityandsafetythings.com/metadata/v1/devices/exampledeviceid?topic=exampletopic
[{
   "deviceId": "exampledeviceid",
   "topic": "exampletopic",
   "timestamp": "2022-02-04T17:05:10.122Z",
   "value": "alert1"
}]

Activating encryption

Activating encryption and configuration of the public key

PUT https://api.integrator.live.securityandsafetythings.com/metadata/v1/keys/testkey2 Content-Type: text/plain' 
-----BEGIN CERTIFICATE-----
MIIDozCCAougAwIBAgIUBEywSePt9OLe+HVau01vXlS/gOEwDQYJKoZIhvcNAQEL
BQAwYTELMAkGA1UEBhMCREUxCzAJBgNVBAgMAkJZMQ8wDQYDVQQHDAZNdW5pY2gx
DTALBgNVBAoMBFNBU1QxDDAKBgNVBAsMA0RNUDEXMBUGA1UEAwwOZG1wLXRlc3Rj
ZXJ0LTEwHhcNMjIwMjAyMDkwMjIxWhcNMzIwMTMxMDkwMjIxWjBhMQswCQYDVQQG
EwJERTELMAkGA1UECAwCQlkxDzANBgNVBAcMBk11bmljaDENMAsGA1UECgwEU0FT
VDEMMAoGA1UECwwDRE1QMRcwFQYDVQQDDA5kbXAtdGVzdGNlcnQtMTCCASIwDQYJ
KoZIhvcNAQEBBQADggEPADCCAQoCggEBAL+L1qpdJlnPAS35+oCqp5UasohWzxLN
tP593Pub2pdHVWsSMvJxbgqiI4RRB0TGMcybaO9jQbyOKg2RqaUPgl0Fm1CJKTZI
8vgGFAM/QU5HleB4KXOU5wVJI4gA3iTvOd7vOau0sKt6HlKZhIJPtcRXaZKF5mT/
7jgouUDFQzcv3cLAPwY3DeNuY+aTApFR8p9rHgSmEa+vFdcm/1mqg0UFjRclUbD9
u/ytzVUtm9p+WVx9VBuYmng9gr4VYdRCub1Is/9iUpVmQkUghzCs/jkIN2ASCnEd
h8fPdZHr/0yATjYdVxuYkeAChVhcrJ0savPKhwSVtohPDRd1vvLq6hECAwEAAaNT
MFEwHQYDVR0OBBYEFCz9nYbzAoCSSLwbJPxVMIXoMQZ+MB8GA1UdIwQYMBaAFCz9
nYbzAoCSSLwbJPxVMIXoMQZ+MA8GA1UdEwEB/wQFMAMBAf8wDQYJKoZIhvcNAQEL
BQADggEBAGepD46Fz5/6D5Um4+qQKDb1S/4UsoxcZ0J+jYb+yn6t7hggwbjz5gkB
FSu10UNNEt28jSXc0Gz0/nTNx9SM2y88X8f5oCFFIMxEeFkzi7OvIxvrmPQxIFMb
89SwYfNMvT727WzsIjJHbW5JY+VTHFByo5fhi9mF8SAn8ZZZ6mkz06f4OCFtFg4g
a/6qoJGpyy0J0HO0KgX1y1VyIcZlec/UelNQ9k8qDNZ5qiQFagbsqhB8Dh7HJzsm
p3R01BejkS4hJA7leqoI5/zrWPtBWdKx+VDW2q55DfiYe4PkMd45MUDd3Vs9KvcZ
uPSHDyeOK6XbGBdMXK5MRdgshNlI03M=
-----END CERTIFICATE-----