1. Introduction
2. Aim
3. Approach
   1. Device Functionality Overview
      1. Capability
      2. Protocol information
   2. Integration Plans
      1. Design Specifications
4. Usage
   1. Steps on how to deploy and configure the driver
   2. Device Configuration Example and Walkthrough
   3. Available Commander Endpoints
   4. GUI Example
5. External References
6. Release Notes

Introduction

iCrypto is a cloud-based service that confirms people’s true identity with stringent processes, associating that identity with the mobile device, and then allowing a secure software token to transact with all applications and workflows.

Figure 1 - iCrypto logo

Aim

The aim is to be able to link the true identity of a field engineer to a specific location/site through a secret token generated via that persons mobile device, combined with a 3rd party security system so that it can automatically exclude authorised field technicians/engineers from triggering high security area alarms.

Cell sites

Approach

Device Functionality Overview

Field engineers requesting access to cell sites have to SMS or send a message from their personal mobile device to the iCrypto backend to notify that they are about to enter the site. Once this is done, iCrypto verifies that the user is authorised to enter the site and they send an access granted or rejected message to us over http. This is then used to mute alarms while the field engineer is on site, and reduce the number of false positive alarms for site intruders.

Figure 2 - iCrypto overview

Capability

The iCrypto backend service receives site access request from field engineers and then performs access authorisation and relays that information to our V-Raptor driver.

Protocol information

iCrypto send us JSON telemetry packets over HTTP with API-Key authorisation.

The raw packets are split into two categories:

1. Event telemetry packets
2. Heartbeat packets

The Event telemetry packets are further split into two other types

• Access Request

{
  "type": "accessRequest",
  "time": 1667397630734,
  "data": {
    "audit-action": "TRUESA-REPORT-CIIMS-ISSUES",
    "timestamp": "2022-11-02T14:00:30.03+00:00",
    "audit-uid": "a8358633-6a23-4be7-98e8-f8e0f1b159fd",
    "audit-msisdn": "+919986011443",
    "audit-site-request": "SAR000000721422",
    "audit-site-id": "0155875",
    "audit-site-area": null
  }
}

• Access Alert

{
  "type": "accessAlert",
  "time": 1667452099,
  "data": {
    "audit-action": "SAR Not Executed",
    "timestamp": "2022-11-03T05:08:19.019+00:00",
    "audit-uid": "a8358633-6a23-4be7-98e8-f8e0f1b159fd",
    "audit-msisdn": "+919986011443",
    "audit-site-request": null,
    "audit-site-id": "0147091",
    "audit-site-area": null
  }
}

• Heartbeat

{
  "Id": "a8338653-6abb-4b12-58e8-abe444222111",
  "TimeStamp": 1667452059
}

Integration Plans

Design Specifications

This driver is a receptor device and will receive telemetry packets sent to it over an HTTP POST request. Furthermore, the drivers POST request is protected with an API Key.

The routes exposed on this V-Raptor driver for the two categories from above are (see swagger page for more info).

Here is a run down of the drivers device configuration. Take note, this iCrypto driver will ONLY support 1 device instance per driver.

Device configuration options

{
  "Devices": {
    "Device1": {
      "Enabled": true,
      "DeviceType": "ACCESSEVENT",
      "Debug": true,
      "GatewaySuffix": "",
      "DeviceAuthorizationDefaultGatewayId":"NULL",
      "GroupName": "DATA",
      "EnableAuthorization": false,      
      "AllowedAuditActions": [ "*" ],
      "ProcessMaxDegreeOfParallelism": 1000,
      "ProcessBoundedCapacity": 15000,
      "PayloadProcessAbortTimeoutMs":2000
    }
  }
}

Device configuration definitions

Usage

Steps on how to deploy and configure the driver

The link below demonstrates the steps to follow when a user deploys and configures a V-Raptor driver:

Deployment Manager Application

Device Configuration Example and Walkthrough

Here is an example config, with a walkthrough below it.

{
  "Devices": {
    "ICRYPTO": {
      "Enabled": true,
      "Debug": true,
      "EnableAuthorization": false,
      "DeviceType": "ACCESSEVENT",
      "GroupName": "DATA",
      "GatewaySuffix": "-ICRYPTOEVENT",
      "AllowedAuditActions": [
        "CREATE-SAR",
        "ADHOC-SAR-REQUEST",
        "ENABLE-ACCESS",
        "OPEN-LOCK",
        "STAND-DOWN ",
        "GLOBAL-STAND-DOWN",
        "SITE-ENTRANCE",
        "SITE-EXIT",
        "DUMMY-REGISTRATION-EVENT"
      ],
      "ProcessMaxDegreeOfParallelism": 3000,
      "ProcessBoundedCapacity": 30000,
      "KeepAliveGatewayId": "iCryptoKeepAlive",
      "KeepAliveGroupName": "HeartBeat",
      "KeepAliveDeviceType": "Event"
      "UseRaptorTimeStampForKeepAliveTelemetry": true
    }
  }
}

• Lets start by creating a new device called ‘ICRYPTO’
• We want this device to be enabled, so we make set ‘enabled’ to true
• We want to see the device logging, so we set ‘Debug’ to true. Note - logging still needs to be turned on via the config ‘Logging.json’
• We want a specific gateway path in commander, so set the ‘DeviceType’ to ‘ACCESSEVENT’
• We don’t have to define a GatewayId because this driver is forced to use the raw packet property ‘audit-site-id’ as the GatewayId
• We set the GroupName to ‘DATA’ (again, because we want a specific gateway path in commander)
• The gateway path is constructed as follows: GatewayID.GroupName:DeviceType|DeviceName, this means that at this point with our config our telemetry will be sent as ‘.DATA:ACCESSEVENT\|ICRYPTO'.
• We set ‘GatewaySuffix’ to ‘-ICRYPTOEVENT’ meaning that we change the above gateway path to ‘-ICRYPTOEVENT.DATA:ACCESSEVENT\|ICRYPTO'
• We want to filter out all raw packets except those that have the ‘audit-action’ property matching one of these: “CREATE-SAR”, “ADHOC-SAR-REQUEST”, “ENABLE-ACCESS”, “OPEN-LOCK”, “STAND-DOWN “, “GLOBAL-STAND-DOWN”, “SITE-ENTRANCE”, “SITE-EXIT”, “DUMMY-REGISTRATION-EVENT” Thus we add this list to the ‘AllowedAuditActions’ array
• We want multiple packets to be processed in parallel, so we set ‘ProcessMaxDegreeOfParallelism’ to 3000, meaning we can have up to 3000packets running simultaneously
• We want to limit the amount of items that we queue for processing, so we set ‘ProcessBoundedCapacity’ to 30000
• Next we want to setup the way the Heart Beat endpoints get created, so the following gateway path is constructed for the iCrypto backend sending us data: GatewayID.GroupName:DeviceType|DeviceName. In our case, we want it to be constructed like this - iCryptoKeepAlive.HeartBeat:Event|ICRYPTO. To achieve this, we do the following
• We set the KeepAliveGatewayId to ‘iCryptoKeepAlive’
• We set the KeepAliveGroupName to ‘HeartBeat’
• We set the KeepAliveDeviceType to ‘Event’
• The device name is already set to ‘ICRYPTO’
• Next, we want our Heart Beat Telemetry to all have the timestamp of when the V-Raptor Driver received the Heart Beat opposed to the actual heart Beat timestamp that iCrypto sends us, thus, we set ‘UseRaptorTimeStampForKeepAliveTelemetry’ to true.

Available Commander Endpoints

Standard Gateway Path: GatewayID.GroupName:DeviceType|DeviceName

• Event Category Endpoints

The routing keys for the event category packets sent by iCrypto are constructed as follows:

deviceInfo.SetGatewayId(gatewayId);
deviceInfo.SetDeviceName(DeviceName);
deviceInfo.SetDeviceType(DeviceType);
deviceInfo.SetGroupName(Options.GroupName);

* where 'gatewayId' = payload.data.AuditSiteId
  or string.Concat(payload.data.AuditSiteId, Options.GatewaySuffix)
  or Options.GatewayId (if payload.data.AuditSiteId = NULL)

And the available properties are constructed as follows:

CreateProperty("string", nameof(ICryptoPacket.Type));
CreateProperty("long", nameof(ICryptoPacket.Time));
CreateProperty("string", nameof(ICryptoPacket.data.AuditAction));
CreateProperty("string", nameof(ICryptoPacket.data.TimeStamp));
CreateProperty("string", nameof(ICryptoPacket.data.AuditUid));
CreateProperty("string", nameof(ICryptoPacket.data.AuditLoc));
CreateProperty("string", nameof(ICryptoPacket.data.AuditMsisdn));
CreateProperty("string", nameof(ICryptoPacket.data.AuditSiteRequest));
CreateProperty("string", nameof(ICryptoPacket.data.AuditSiteId));
CreateProperty("string", nameof(ICryptoPacket.data.AuditSiteArea));

Meaning these are the 10 properties to be sent:

• Heartbeat Category Endpoints

The routing keys for the Heart Beat category packet sent by iCrypto, is constructed as follows:

deviceInfo.SetGatewayId(Options.KeepAliveGatewayId);
deviceInfo.SetGroupName(Options.KeepAliveGroupName);
deviceInfo.SetDeviceType(Options.KeepAliveDeviceType);
deviceInfo.SetDeviceName(DeviceName);

And the available properties are constructed as follows:

CreateProperty("string", nameof(iCryptoKeepAlivePacket.Id))
CreateProperty("long", nameof(iCryptoKeepAlivePacket.TimeStamp) + TimeStampEpocSuffix)
CreateProperty("datetime", nameof(iCryptoKeepAlivePacket.TimeStamp) + TimeStampDateTimeSuffix)
CreateProperty("datetime", TimeStampRaptorName)

* where 'TimeStampEpocSuffix' = "Epoc"
  where 'TimeStampDateTimeSuffix' = "DateTime"
  where 'TimeStampRaptorName' = "VRaptorDateTime"

Meaning these are the 4 properties to be sent:

GUI Example

Make sure that you have setup external routing (with the ‘virtual host’ option) on the V-Raptor, so that an external source can communicate with the driver. This is done via the credential manager UI.

No example, just normal plain endpoints.

External References

iCrypto

Release Notes