Access Protocol

Overview

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

Hardware

• Arduino/ESP8266 Firmware GitHub link
• RFID Hardware link will go here

Future

• 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 as an integer.
• 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 - it's case-insensitive everywhere, but I use uppercase.
  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.