device_input 0.0.1.1 → 0.0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 6bc11d4d1313889df6c9b9ff7289bfe1dcd8fff6
-  data.tar.gz: 1e13f0c7104ad27775e606e4a7a50184a53bef97
+  metadata.gz: 42e1a1dde8d9b9884e97bef833d8890d9aaa3a23
+  data.tar.gz: 5076d4580ee666d8c82a0f9b924ed94c2890b041
 SHA512:
-  metadata.gz: 3c4ad7cf1172d6483e53604b4f94dfc1d490a1364994264acfc8691c72c044170f64d8a8fcb2a8d7518d3f41c91f97c87d4b9be24a344f67a4b3867953969f41
-  data.tar.gz: e2e275a1bcb94b0cdaeb620fc3d290d88d0f2aca5f4a082ad04d973c0a29c8d98bddd86285e5ff240261dcea60617fbb01387b577aac78acc0edc619756f4e70
+  metadata.gz: 3ae5856b3d005ea2b268e931d5c1ac3c73cc8fd1a31ce0e4264b16adc4f70841b3858e8fd5aa771df47631da111eba823ef0ca1f3089c6a6f602a866eb759f58
+  data.tar.gz: 5f4c0defc1877124d209cc424f312cd099493f84a1feab65f651210b08475f2d56f4fdfd827b172a8b6ce3527f0e4bc5a7e1ba1301f0dcf8158ec59da1d302a6

data/README.md

@@ -1,13 +1,117 @@
-# Background
+# Device Input
 
-We want to read events from e.g. `/dev/input/event0` in Ruby.
+*for the Linux kernel*
+
+We want to read events from e.g. `/dev/input/event0` in Ruby.  For example,
+if you want to see what's happening "on the wire" when you press a special
+function key on a laptop.  While this code can be used for the purpose of
+malicious keystroke logging, it is not well suited for it and does not provide
+the root privileges in order to read `/dev/input`.  Once you've got the
+privilege to read `/dev/input` it's *game over* anyway.
+
+## Rationale
+
+`/dev/input/eventX` is just a character device.  Can't we read it with simple
+Unix tooling?  Yes and no.  First of all, a character device just means that
+it passes bytes (not necessarily characters or strings) from userspace into
+the kernel.  Secondarily, the messages (defined as C structs) are in fact
+binary and not strings or conventional characters.
+
+Since these are C structs (analagous to a binary message), we need to be able
+to delimit individual messages and decode them.  We can't simply read a byte
+at a time and try to make sense of it.  In fact, on my system,
+`/dev/input/event0` refuses any read that is not a multiple of the struct /
+message size, so we need to know the message size before even attempting a
+read(), without even a decode().
+
+To determine the message size, we need to know the data structure.  For a
+long time, it was pretty simple: events are 16 bytes:
+
+* timestamp - 8 bytes
+* type - 1 byte
+* code - 1 byte
+* value - 2 bytes
+
+However, this is only true for 32-bit platforms.  On 64-bit platforms, event
+timestamps became 16 bytes, increasing events from 16 to 24 bytes.  This is
+because a timestamp is defined as two `long`s, and `long`s are bigger on
+64-bit platforms.  It's easy to remember:
+
+* 32-bit platform: 32-bit `long` (4 bytes)
+* 64-bit platform: 64-bit `long` (8 bytes)
+
+`read(/dev/input/event0, 16)` will fail on a 64-bit machine.
+
+Your tooling must be aware of this distinction and choose the correct
+underlying data types just to be able to delimit messages and perform a
+successful read.  This software does that, decodes the message, maps the
+encoded values to friendly strings for display, and provides both library and
+executable code to assist in examining kernel input events.
+
+# Installation
+
+Install the gem:
+
+```
+$ gem install device_input # sudo as necessary
+```
+
+Or, if using [Bundler](http://bundler.io/), add to your `Gemfile`:
+
+```
+gem 'device_input', '~> 0.0'
+```
+
+# Usage
+
+## Executable
+
+```
+$ sudo devsniff /dev/input/event0
+```
+
+When the `f` key is pressed:
+
+```
+Misc:ScanCode:33
+Key:F:1
+Sync:Sync:0
+```
+
+And released:
+```
+Misc:ScanCode:33
+Key:F:0
+Sync:Sync:0
+```
+
+## Library
+
+```
+require 'device_input'
+
+DeviceInput.read_from('/dev/input/event0') do |event|
+  puts event
+end
+```
+
+An event has:
+
+* `#data` - a Struct of ints (class name Data)
+* `#time` - a Time, accurate to usecs
+* `#type` - a String, possibly UNK-X where X is the integer from `#data`
+* `#code` - a String, possibly UNK-X-Y where X and Y are from `#data`
+* `#value` - a Fixnum (signed)
+
+# Research
 
 ## Kernel docs
 
 * https://www.kernel.org/doc/Documentation/input/input.txt
 * https://www.kernel.org/doc/Documentation/input/event-codes.txt
 
-These events are defined as C structs with a fixed size in bytes.
+These events are defined as C structs with a fixed size in bytes.  See more
+about these structs towards the end of this document.
 
 ## Kernel structs
 
@@ -34,8 +138,7 @@ struct input_event {
 };
 ```
 
-What's a `timeval`?
-https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/include/uapi/linux/time.h#n15
+What's a [`timeval`](https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/include/uapi/linux/time.h#n15)?
 
 ```
 struct timeval {
@@ -44,8 +147,7 @@ struct timeval {
 };
 ```
 
-What's a `__kernel_time_t`?
-https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/include/uapi/asm-generic/posix_types.h#n88
+What's a [`__kernel_time_t`](https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/include/uapi/asm-generic/posix_types.h#n88)?
 
 ```
 typedef long            __kernel_long_t;
@@ -55,10 +157,9 @@ typedef __kernel_long_t         __kernel_suseconds_t;
 typedef __kernel_long_t __kernel_time_t;
 ```
 
-What's a `__u16`?  We're pretty sure it's an unsigned 16 bit integer.
-Likewise `__s32` should be a signed 32-bit integer:
-
-https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/include/uapi/asm-generic/int-l64.h#n23
+What's a [`__u16`](https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/include/uapi/asm-generic/int-l64.h#n23)?
+We're pretty sure it's an unsigned 16 bit integer.  Likewise `__s32` should
+be a signed 32-bit integer:
 
 ```
 typedef unsigned short __u16;
@@ -69,7 +170,7 @@ typedef __signed__ int __s32;
 Why is the value signed?  It's meant to be able to communicate an "analog"
 range, say -127 to +127 as determined by the position of a joystick.
 
-Let's review:
+## Review
 
 `input_event`
 
@@ -84,18 +185,26 @@ Flattened: `SEC` `USEC` `TYPE` `CODE` `VALUE`
 
 How many bytes is a `long`?  Well, it's platform-dependent.  On a 32-bit
 platform, you get 32 bits (4 bytes).  On a 64-bit platform you get 64 bits
-(8 bytes).
+(8 bytes).  This means that the event is 16 bytes on a 32-bit machine and
+24 bytes on a 64-bit machine.  Software will need to accommodate.
 
-This means that the event is 16 bytes on a 32-bit machine and 24 bytes on a
-64-bit machine.  Software will need to accommodate.
+## Ruby tools
 
-We can use `RbConfig` and `Array#pack` to help us read these binary structs:
+We can use `RbConfig` and `Array#pack`/`String#unpack` to help us read these
+binary structs:
 
 ```
 FIELD      C        RbConfig  Pack
-tv_usec    long     long      l!
+---        ---      ---       ---
+tv_sec     long     long      l!
 tv_usec    long     long      l!
 type       __u16    uint16_t  S
 code       __u16    uint16_t  S
 value      __s32    int32_t   l
 ```
+
+# Acknowledgments
+
+* Inspired by https://github.com/prullmann/libdevinput (don't use it)
+  - also the source of the [event code labels](lib/device_input/codes.rb)
+* Thanks to al2o3-cr from #ruby on Freenode for feedback

data/lib/device_input/{events.rb → codes.rb}

@@ -1,13 +1,13 @@
 module DeviceInput
-  EVENTS = {}
+  CODES = {}
 
   # type = Sync
-  EVENTS[0] = {
+  CODES[0] = {
     0 => 'Sync',
   }
 
   # type = Key
-  EVENTS[1] = {
+  CODES[1] = {
     0 => 'Reserved',
     1 => 'Esc',
     2 => '1',
@@ -358,7 +358,7 @@ module DeviceInput
   }
 
   # type = Relative
-  EVENTS[2] = {
+  CODES[2] = {
     0 => 'X',
     1 => 'Y',
     2 => 'Z',
@@ -369,7 +369,7 @@ module DeviceInput
   }
 
   # type = Absolute
-  EVENTS[3] = {
+  CODES[3] = {
     0 => 'X',
     1 => 'Y',
     2 => 'Z',
@@ -399,7 +399,7 @@ module DeviceInput
   }
 
   # type = Misc
-  EVENTS[4] = {
+  CODES[4] = {
     0 => 'Serial',
     1 => 'Pulseled',
     2 => 'Gesture',
@@ -408,7 +408,7 @@ module DeviceInput
   }
 
   # type = LED
-  EVENTS[17] = {
+  CODES[17] = {
     0 => 'NumLock',
     1 => 'CapsLock',
     2 => 'ScrollLock',
@@ -421,14 +421,14 @@ module DeviceInput
   }
 
   # type = Sound
-  EVENTS[18] = {
+  CODES[18] = {
     0 => 'Click',
     1 => 'Bell',
     2 => 'Tone',
   }
 
   # type = Repeat
-  EVENTS[20] = {
+  CODES[20] = {
     0 => 'Delay',
     1 => 'Period',
   }

data/lib/device_input.rb

@@ -14,8 +14,24 @@ module DeviceInput
     }
     PACK = DEFINITION.values.map { |v| PACK_MAP.fetch(v) }.join
 
+    # this defines a class, i.e. class Data ...
     Data = Struct.new(*DEFINITION.keys)
 
+    # these are just labels, not used internally
+    TYPES = {
+      0 => 'Sync',
+      1 => 'Key',
+      2 => 'Relative',
+      3 => 'Absolute',
+      4 => 'Misc',
+      17 => 'LED',
+      18 => 'Sound',
+      20 => 'Repeat',
+      21 => 'ForceFeedback',
+      22 => 'Power',
+      23 => 'ForceFeedbackStatus',
+    }
+
     # convert Event::Data to a string
     def self.encode(data)
       data.values.pack(PACK)
@@ -31,51 +47,39 @@ module DeviceInput
     end
 
     def self.code_str(type_code, code_code)
-      require 'device_input/events'
-      DeviceInput::EVENTS.dig(type_code, code_code) ||
+      require 'device_input/codes'
+      DeviceInput::CODES.dig(type_code, code_code) ||
         "UNK-#{type_code}-#{code_code}"
     end
 
     NULL_DATA = Data.new(0, 0, 0, 0, 0)
     NULL_MSG = self.encode(NULL_DATA)
+    BYTE_LENGTH = NULL_MSG.length
 
-    attr_reader :data, :time, :type, :code, :length
+    attr_reader :data, :time, :type, :code
 
     def initialize(data)
       @data = data
       @time = Time.at(data.tv_sec, data.tv_usec)
       @type = self.class.type_str(data.type)
       @code = self.class.code_str(data.type, data.code)
-      @value = data.value
     end
 
-    def to_s
-      [@type, @code, @value].join(':')
+    def value
+      @data.value
     end
 
-    TYPES = {
-      0 => 'Sync',
-      1 => 'Key',
-      2 => 'Relative',
-      3 => 'Absolute',
-      4 => 'Misc',
-      17 => 'LED',
-      18 => 'Sound',
-      20 => 'Repeat',
-      21 => 'ForceFeedback',
-      22 => 'Power',
-      23 => 'ForceFeedbackStatus',
-    }
-
-    BYTE_LENGTH = NULL_MSG.length
+    def to_s
+      [@type, @code, @data.value].join(':')
+    end
   end
 
   def self.read_from(filename)
     File.open(filename, 'r') { |f|
       loop {
         bytes = f.read(Event::BYTE_LENGTH)
-        msg = Event.decode(bytes)
-        yield Event.new(msg)
+        data = Event.decode(bytes)
+        yield Event.new(data)
       }
     }
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: device_input
 version: !ruby/object:Gem::Version
-  version: 0.0.1.1
+  version: 0.0.3.1
 platform: ruby
 authors:
 - Rick Hull
@@ -36,7 +36,7 @@ files:
 - README.md
 - bin/devsniff
 - lib/device_input.rb
-- lib/device_input/events.rb
+- lib/device_input/codes.rb
 homepage: https://github.com/rickhull/device_input
 licenses:
 - GPL-3.0