Access Protocol

From Hive13 Wiki
Revision as of 19:00, 26 July 2017 by Greg J Arnold (talk | contribs) (Created page with " = Overview = == Catalyst App == * [ GitHub link] * Actually do something with the temperatures presented to it. * Add in OpenID Support ** F...")
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search


Catalyst App

  • GitHub link
  • Actually do something with the temperatures presented to it.
  • Add in OpenID Support
    • Facebook/Foursquare Checkins to the hive on entry
    • Twitter updates on entry
  • IRC Notifications



  • Screen to display information
  • Current measurement to measure how long a tool is on.
  • Log temperature readings for any number of devices
  • Log soda sold out information
  • Log general stuff

current use cases

  • Doors
  • Tools
    • How to end use
      • Timeout
      • Current monitoring
      • "Finish" button
      • Least controversial method so far is tap card to enable tool, push a button to disable tool when finished. No timeout.
  • Vending machines
    • Need to deduct credits/dollars from a stored value securely.
  • Member registration/payment terminal
    • Need to securely add credits/dollars to a stored value.
    • Need to also be able to associate a card ID with an account. Maybe multiple card/phone IDs? PIN as well

Protocol and Database Info

Server <-> RFID reader protocol

  • Each request is sent from the RFID to the server as a POST with a JSON body.
  • Each device has a key pre-shared with the server to mutually authenticate w/o SSL, which some of our MCUs have no hope of doing.
  • The body object contains a "device" key with the name of the device requesting access - if the server doesn't know about this device, it'll fail.
  • The data object also contains an operation - if not', 'access' is assumed. Other options are 'vend' and 'log'. Currently, 'log' does nothing but return a success.
  • Finally, for "vend" or "access", the data object contains a "badge" key, containing the presented badge number.
  • The checksum is computed like this: (Here's where it's done on the server.)
    1. Sort all of the keys recursively on the data object.
    2. Remove all unnecessary whitespace.
    3. Prepend the device's shared key.
    4. Take the SHA-512 checksum of that string - encode as a hex string using uppercase letters (It shouldn't matter, but I can't remember if the RFID MCUs do a strcasecmp() or not)
    5. Create an object with keys of data, device, and checksum - that object is the body of the request or response.
  • Each data object has a "random" field - this is random per-packet data to stop replay attacks
  • Each request should contain a "random_response" field - this must be copied from the request to the response if present; this solves a different subset of replay attacks.

General-purpose logging

  • JSON body with data, device, and checksum as described above - TBD what to do about an unknown device.
  • Data field has key "option" set to "log"
  • An optional keys is "current_timestamp" in milliseconds, to batch several logs and let the server figure out the timesamps - millis() in Arduino-land works here.
  • Key "messages" is an array of message objects, containing keys as below:
    • "absolute_timestamp" has the server compare it to "current_timestamp" to figure out when the message was generated. Optional.
    • "relative_timestamp" is how long ago (this number is only positive) the message was generated. Optional.
    • If neither are specified, the server will timestamp the message with when it hit the DB.
    • "data" is the message text. No reasonable length limit. Required; the array member will be silently discarded without it.
    • "severity" is the 0-7 standard syslog values (panic, alert, crit, error, warn, notice, info, debug). Optional; defaults to info.
  • Key "temperatures" is an array of temperature reading objects to log, containing keys as below:
    • "absolute_timestamp" and "relative_timestamp" function as in "messages".
    • "temperature" is the reading, in ***tenths*** of a degree Fahrenheit. This is done to remove the need for floating-point libraries on microcontrollers, as they are large. Required.
    • "item" is which item the temperature is measuring. Note that a device must have permission to that item to log temperatures for it. Required; the array member will be silently discarded if missing or unauthorized.

Current protocol weaknesses and notes

  • You can capture a packet going to the server and replay it again and again and the server will accept it and process it.
    • This could add junk log entries to the access log.
    • This could also drain someone's soda credits.
    • Solution is the server tells the client what nonce it expects back in the next packet, and stores that in the DB. We'd also need an operation to get that nonce if the MCU lost it, and a "wrong nonce" error.
  • You CANNOT replay the response to a successful badge swipe and open the door, because
    1. The MCU only listens after a badge is presented (or a temperature is logged, but it won't call door_open() from that function).
    2. The MCU generates a new "random_response" field
    3. The MCU verifies that the response packet's field matches what it sent.

Database Layout

  • Conventions
    • All tables have a ${table_name}_id column that's a UUID as the primary key
    • Many-to-many tables have the two tables they connect in alpha order
      • They do not have their own, separate ID field
      • They have the primary key as the two tables in alpha order
      • There is a second key of the two columns reversed (this way is needed for the other foreign key)
    • Table names are singular
    • Catalyst convention is to use Pascal case for table names.
    • Postgres convention is to use Snake case for table names.
  • "members" stores member information.
    • It needs renamed to "member" for consistency, though the app calls it "Member" with a name override.
    • It also needs old fields blown away.
  • "badge" stores a badge number and which member it belongs to - you can have multiple badges per account
  • "mgroup" stores the names and IDs of various groups, such as members, leadership, laser certified, &c. It's called mgroup because "group" is an SQL reserved word.
  • "member_mgroup" is a many-to-many association table to join members to groups.
  • "device" stores information about a device - its shared key and name right now.
  • "item" stores information about items that can be accessed - doors, tools, and so on.
  • "device_item" is a many-to-many showing which devices can service which items.
  • "item_mgroup" is a many-to-many granting access to an item to a group.