Access Protocol: Difference between revisions

Jump to navigation Jump to search
231 bytes added ,  08:45, 9 April 2019
no edit summary
(Added in API version 2.)
No edit summary
 
(3 intermediate revisions by the same user not shown)
Line 16: Line 16:
* Screen to display information
* Screen to display information
* Current measurement to measure how long a tool is on.
* Current measurement to measure how long a tool is on.
* Log soda sold out information
* Log general stuff
* Log general stuff


Line 39: Line 38:
* 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.
* 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 <code>device</code> key with the name of the device requesting access - if the server doesn't know about this device, it'll fail.
* The body object contains a <code>device</code> 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, <code>access</code> is assumed.  Other options are <code>vend</code> and <code>log</code>. Currently, <code>log</code> does nothing but return a success.
* The body object contains a <code>data</code> object with the body of the request.  It can have several fields in it.
* Finally, for <code>vend</code> or <code>access</code>, the data object contains a <code>badge</code> key, containing the presented badge number as an integer.
** <code>version</code> - integer - 1 is assumed if not specified.  Version of the API to use.
** <code>operation</code> - string - <code>access</code> is assumed if not specified.  Other options are <code>vend</code> and <code>log</code>.
** <code>badge</code> - integer - for <code>vend</code> or <code>access</code>.  Contains the presented badge number.
** <code>random</code> - array of integers - this is random per-packet data to stop replay attacks
** <code>random_response</code> - array of integers - this must be copied from the request to the response if present; this solves a different subset of replay attacks.
* The checksum is computed like this: ([https://github.com/Hive13/HiveWeb/blob/master/lib/HiveWeb/View/ChecksummedJSON.pm Here's where it's done on the server.])
* The checksum is computed like this: ([https://github.com/Hive13/HiveWeb/blob/master/lib/HiveWeb/View/ChecksummedJSON.pm Here's where it's done on the server.])
*# Sort all of the keys recursively on the data object.
*# Sort all of the keys recursively on the data object.
Line 47: Line 50:
*# Take the SHA-512 checksum of that string - encode as a hex string - it's case-insensitive everywhere, but I use uppercase.
*# Take the SHA-512 checksum of that string - encode as a hex string - it's case-insensitive everywhere, but I use uppercase.
*# Create an object with keys of <code>data</code>, <code>device</code>, and <code>checksum</code> - that object is the body of the request or response.
*# Create an object with keys of <code>data</code>, <code>device</code>, and <code>checksum</code> - that object is the body of the request or response.
* Each data object has a <code>random</code> field - this is random per-packet data to stop replay attacks
* Each request should contain a <code>random_response</code> field - this must be copied from the request to the response if present; this solves a different subset of replay attacks.


=== Changes in Version 2 ===
=== Changes in Version 2 ===
* Version 2 of the API stops replay attacks from the client to the server.  The server has a 16-byte nonce it expects the client to send with the packet or else it'll fail.
* Version 2 of the API stops replay attacks from the client to the server.  The server has a 16-byte nonce it expects the client to send with the packet or else it'll fail.
* A "get_nonce" operation has been added to the operations.  It'll silently succeed on version 1 packets, but will return the expected nonce for the next packet otherwise.
* A <code>get_nonce</code> operation has been added to the operations.  It'll silently succeed on version 1 packets, but will return the expected nonce for the next packet otherwise.
* The nonce must be submitted in the data object as "nonce".
* The nonce must be submitted in the data object as <code>nonce</code>.
* Instead of a "response" Boolean and an "error" text to indicate error condition, there are several Booleans added for each part of the verification process.
* Instead of a <code>response</code> Boolean and an <code>error</code> text to indicate error condition, there are several Booleans added for each part of the verification process.
** The order in which they are generated - and in which they should be checked - is "checksum_valid", "version_valid", "nonce_valid", and "operation_valid".  Subsequent fields may not be present in a response if a field is set to false.  The "error" and "response" fields are now used by the individual operations to indicate success and provide operation-specific errors.
** The order in which they are generated - and in which they should be checked - is <code>checksum_valid</code>, <code>version_valid</code>, <code>nonce_valid</code>, and <code>operation_valid</code>.  Subsequent fields may not be present in a response if a field is set to false.  The <code>error</code> and <code>response</code> fields are now used by the individual operations to indicate success and provide operation-specific errors.


== General-purpose logging ==
== General-purpose logging ==
* JSON body with data, device, and checksum as described above - TBD what to do about an unknown device.
* JSON body with data, device, and checksum as described above - TBD what to do about an unknown device.
* Data field has key <code>option</code> set to <code>log</code>
* Data field has key <code>option</code> set to <code>log</code>
* An optional keys is <code>current_timestamp</code> in milliseconds, to batch several logs and let the server figure out the timesamps - <code>millis()</code> in Arduino-land works here.
* An optional key is <code>current_timestamp</code> in milliseconds, to batch several logs and let the server figure out the timesamps - <code>millis()</code> in Arduino-land works here.
* Key <code>messages</code> is an array of message objects, containing keys as below:
* Key <code>messages</code> is an array of message objects, containing keys as below:
** <code>absolute_timestamp</code> has the server compare it to <code>current_timestamp</code> to figure out when the message was generated. Optional.
** <code>absolute_timestamp</code> has the server compare it to <code>current_timestamp</code> to figure out when the message was generated. Optional.
Line 92: Line 93:
** Catalyst convention is to use Pascal case for table names.
** Catalyst convention is to use Pascal case for table names.
** Postgres convention is to use Snake case for table names.
** Postgres convention is to use Snake case for table names.
** Use <code>TIMESTMAP WITH TIME ZONE</code> for all timestamp columns.
* <code>members</code> stores member information.
* <code>members</code> stores member information.
** It needs renamed to <code>member</code> for consistency, though the app calls it <code>Member</code> with a name override.
** It needs renamed to <code>member</code> for consistency, though the app calls it <code>Member</code> with a name override.
Line 101: Line 103:
* <code>item</code> stores information about items that can be accessed - doors, tools, and so on.
* <code>item</code> stores information about items that can be accessed - doors, tools, and so on.
* <code>device_item</code> is a many-to-many showing which devices can service which items.
* <code>device_item</code> is a many-to-many showing which devices can service which items.
* <code>item_mgroup"</code> is a many-to-many granting access to an item to a group.
* <code>item_mgroup</code> is a many-to-many granting access to an item to a group.


[[Category:RFID]]
[[Category:RFID]]
973

edits

Navigation menu