Skip to content

API

Jump to bottom
TyIsI edited this page Jul 29, 2020 · 2 revisions

A brief overview of the API.

State Interface

Requests

Lockout devices query the publicly accessible state URI /api/devices/state/:deviceid.

The state query will return a JSON response with a success field set to true and with a powered field value of either 0 for not-armed or 1 for armed.

Once armed, the powered value will return to its default zero value within a configurable, limited amount of time.

Notes

  • The TACOS server is expected to be protected by HTTPS and therefor assumed to be trusted.
  • The powered value cannot and should not be used to determine the current state. The powered value should only be used to determine the power state for a device when a user primes the device on use.

Authentication Interface

Requests

Within the scope of TACOS, Terminals are considered to be authentication terminals through which a particular device can be put in a powered state.

Authentication is a little more complicated. While the TACOS server is assumed to be trusted, authenticating Terminals have no (secure) default means of being authenticated. In the initial design process client certificates were considered to be in an infantile state and at the same time this could prove to be arduous in its implementation. Instead TACOS was designed with strong, multi-factor HMAC authentication.

Terminal authentication is done by posting the authentication request to /terminals/authenticate/rfid/:deviceid.

The post data contains the card ID, a nonce, timestamp and hash. On receipt, the server verifies the hash, then finds the terminal's target device, verifies user access to the target device, and finally updates the powered state.

Security

Requirements

  • Terminal devices need to be time synced

Hash

  1. The Terminal generates a 16-byte nonce (UUID v4)
  2. The Terminal saves the current timestamp (EPOCH)
  3. The Terminal generates a single-line JSON data packet containing (in order):
  • Card ID (card_id)
  • Timestamp (ts as a string)
  • Nonce (nonce)
  1. The Terminal generates the packet key (nonce+ts(string)+DEVICE_SECRET)
  2. The Terminal generates an SHA256 HMAC hash based on the data packet and the packet key
  3. As needed, the Terminal converts the hash to a hexadecimal string
  4. The Terminal generates the url encoded request packet with the following fields:
  • data[card_id]
  • data[ts]
  • data[nonce]
  • hash
  1. The Terminal sends the request packet to the TACOS server on /api/terminals/authenticate/rfid/:deviceid
  2. The Server verifies the request and returns a JSON response with either result set to OK, or ERROR with an error message

Notes

  • The nonce is included in the packet to increase cryptographic strength
  • The timestamp is included in the packet and hash to prevent replay attacks
Clone this wiki locally