updated README
[hardpass.git] / 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
Imprint / Impressum