# HID-IO Interface Spec

TODO


# HID-IO Interface Outline/Requirements

* Ability to register many different external programs/scripts at the same time
  + Each external script should not talk to another one through HID-IO
  + External scripts should not interfere with existing HID-IO protocol communications with devices
* Support multiple devices at the same time (2 keyboards, keyboard + mouse, etc.)
* Direct HID-IO protocol communication for some IDs
  + Three levels of access
    - Root/secure access (possibly key-presses?)
    - Userspace access (specific macro key was triggered, call animation, etc.)
    - Debug root access (directly communicate using HID-IO protocol with no restrictions, not enabled by default)
  + Three levels of control
    - Listen (wait for a specific macro event, can be listened by multiple scripts)
    - Request (request information from a keyboard, information is only sent back to requester)
    - Snoop (debug ability to monitor per Id request, not enabled by default)
* Support commands for requesting information from the HID-IO daemon (not necessarily just a pass-through to the HID device)


## Requirements for RPC/Scripting Interface

* Supports a wide variety of languages, preferably scripting
  + Python is a good starting point
* Relatively straightforward to write a script to listen or request data from a keyboard
* Cross-platform
* Uses sockets
  + 7185 (0x1c11) - Not currently assigned to anything
  + Only allows connections from localhost (127.0.0.1)
* Authentication
  + Thoughts? (not really settled on doing it this way, but some sort of authentication is needed for more sensitive operations)
  + Request a run-time key from the HID-IO daemon
    - hid-io --userspace-key
    - hid-io --secure-key # Requires root priviledges
  + Should use some sort of TLS for traffic
    - Key would be used to establish the tunnel


## Authentication

Thoughts about authentication.

For the initial implementation, I'll restrict elevated functions to debug mode (so I can get something up and running).


### Device

* Authorized functions on device
  + Token generation
* Uses
  + Jumping to bootloader
  + Reading keypresses directly
  + Features that can be dangerous if miss-used
* Token is granted per "Usage"
  + Selection of commands that comprise an action
* Should be valid, with an expiry due to:
  + Restarting HID-IO daemon
  + Restarting device
  + New connection to interface
  + Specific amount of time
  + At device request
  + At daemon request
* Device will only support a limited number of simultaneous tokens


### Daemon

* Authorized functions in daemon
  + Using requires generated token, physical device may not be available, or support token generation (bootloader mode)
* Uses
  + Unicode output
  + Simulated keyboard
  + Features that normally require system root priviledges
* Token is granted per "Usage"
  + Selection of commands that comprise an action
* Should be valid, with an expiry due to:
  + Restarting HID-IO daemon
  + New connection to interface
  + Specific amount of time
  + At daemon request


### Usage (is there a technical term already coined for this?)

A Usage is a collection of RPC functions that can define authentication terms.
* How long the authentication is valid
* Which RPC/functions may be called with the Usage
* Possibly the order in which functions are called
  + Calling out of order results in immediate revoking of the token
* Possibly revoking token if any RPC functions fail