send_hid/README.md

   1 # hardpass
   2 A hardware password manager, built around a Paspberry Pi Zero and [`pass`, the UNIX password manager](https://passwordstore.org).
   3
   4 This is also an entry for [Hackaday.io](https://hackaday.io)'s Pi Zero Contest.
   5
   6 This repo shall also provide code for your own hid-gadgets - the code is meant to be easy to change to suit your needs.
   7
   8 ## Hardware
   9 I am using a Raspberry Pi Zero, since it has USB-OTG support and a lot of GPIO to interface an OLED screen, a button matrix for input and maybe even an ESP8266 for WiFi.
  10 The OLED I am intending to use has an I²C interface and a screen diagonal of .96".
  11
  12 ## using the driver
  13 The neccessary drivers are available only in the Raspbian 4.4 Kernel, which you can install using
  14 ```
  15 sudo BRANCH=next rpi-update
  16 ```
  17 You also need to activate the device tree overlay `dwc2` and load the corresponding kernel module:
  18 ```
  19 echo "dtoverlay=dwc2" | sudo tee -a /boot/config.txt
  20 echo "dwc2" | sudo tee -a /etc/modules
  21 ```
  22
  23 To use this program, you have to enable the `libcomposite` driver on the Raspberry Pi and create a USB HID gadget.
  24 You can use this bash script:
  25 ```
  26 #!/bin/bash
  27 # this is a stripped down version of https://github.com/ckuethe/usbarmory/wiki/USB-Gadgets - I don't claim any rights
  28
  29 modprobe libcomposite
  30 cd /sys/kernel/config/usb_gadget/
  31 mkdir -p g1
  32 cd g1
  33 echo 0x1d6b > idVendor # Linux Foundation
  34 echo 0x0104 > idProduct # Multifunction Composite Gadget
  35 echo 0x0100 > bcdDevice # v1.0.0
  36 echo 0x0200 > bcdUSB # USB2
  37 mkdir -p strings/0x409
  38 echo "fedcba9876543210" > strings/0x409/serialnumber
  39 echo "girst" > strings/0x409/manufacturer
  40 echo "Hardpass" > strings/0x409/product
  41 N="usb0"
  42 mkdir -p functions/hid.$N
  43 echo 1 > functions/hid.usb0/protocol
  44 echo 1 > functions/hid.usb0/subclass
  45 echo 8 > functions/hid.usb0/report_length
  46 echo -ne \\x05\\x01\\x09\\x06\\xa1\\x01\\x05\\x07\\x19\\xe0\\x29\\xe7\\x15\\x00\\x25\\x01\\x75\\x01\\x95\\x08\\x81\\x02\\x95\\x01\\x75\\x08\\x81\\x03\\x95\\x05\\x75\\x01\\x05\\x08\\x19\\x01\\x29\\x05\\x91\\x02\\x95\\x01\\x75\\x03\\x91\\x03\\x95\\x06\\x75\\x08\\x15\\x00\\x25\\x65\\x05\\x07\\x19\\x00\\x29\\x65\\x81\\x00\\xc0 > functions/hid.usb0/report_desc
  47 C=1
  48 mkdir -p configs/c.$C/strings/0x409
  49 echo "Config $C: ECM network" > configs/c.$C/strings/0x409/configuration
  50 echo 250 > configs/c.$C/MaxPower
  51 ln -s functions/hid.$N configs/c.$C/
  52 ls /sys/class/udc > UDC
  53 ```
  54
  55 ## modifying `pass`
  56 The version of (pass)[https://passwordstore.org] doesn't format the output as nice, so it is easier to work with. Using the `pass-installer.sh` will automatically clone from the original repository, apply the patch and install it (make sure, `patch` and `sudo` is installed).
  57
  58 You can then check out `hardpass-demo.sh` to see how to supply a passphrase directly from the command line (without gpg-agent). Keep in mind, that it will show up in your history file!
  59
  60 ## internals of this code
  61 whenever you need to add (or remove) a new keyboard layout, the following changes have to be made:
  62
  63 ### adding a new keyboard layout (example)
  64 1. in `scancodes.h` add the layout to `keysym`-struct:
  65 this identifier does not need to be used outside of scancodes.{h,c}.
  66 ```
  67 struct keysym {
  68         // ...
  69         struct layout de_dv; //dvorak layout
  70         // ...
  71 };
  72 ```
  73 2. the enum `kbd1` has to be ammended:
  74 ```
  75 enum kbdl {  //keyboard layouts:
  76         // ...
  77         de_DV //de_AT-Dvorak
  78 };
  79 ```
  80 3. in `scancodes.c` you need to add a new column (containing more columns) to the big `keysyms[]` table:
  81 It is suggested to explicitly name `.is_dead` and `.unicode` to avoid confusion. Also notice that `.is_dead` is part of the layout (and goes within the inner braces), while `.unicode` resides in the keysym-struct.
  82 if you want to add new keys, the following must be kept in mind: `toscan()` will use the nth line of the table, if n is larger than 32 (aka. will use the ascii code to look up chars). symbols not in the 7-bit ascii standard can be put on the first 32 positions as utf-8 encoded strings, although keeping [0] to the release all chars is recommended. (some text editors will convert files to older encodings - this might break things)
  83 ```
  84 struct keysym keysyms[] = {
  85         //...
  86         {"#", {0x20, 0x02}, {0x31, 0x00}, {0x31, 0x00}, {KEY, MODIFIER}},
  87         {"^", {0x23, 0x02}, {0x35, 0x00}, {0x35, 0x00}, {KEY, MODIFIER, .is_dead = 1}},
  88         {"&", {0x24, 0x02}, {0x23, 0x02}, {0x23, 0x02}, {KEY, MODIFIER}, .unicode=OxHEX},
  89         //...
  90 };
  91 ```
  92 4. `tolay()` needs a new case to its switch statement:
  93 This is the only place where the `layout`-idenitfier from `keysym` needs to be used.
  94 ```
  95 struct layout* tolay (struct keysym* s, enum kbdl layout) {
  96         switch (layout) {
  97         // ...
  98         case de_DV: return &(s->de_dv);
  99         default: return NULL;
 100         }
 101 }
 102 ```
 103 5. finally, your code must understand the new layout, represented by the `enum kbd1`-entry, `de_DV` in this example.
 104
 105 ## License
 106 Copyright 2015-2016 Tobias Girstmair, own work released under the GNU GPL v3