update README to include adafruit license
[hardpass.git] / send_hid / README.md
CommitLineData
56339ab6 1# hardpass
2A hardware password manager, built around a Paspberry Pi Zero and [`pass`, the UNIX password manager](https://passwordstore.org).
3
4This is also an entry for [Hackaday.io](https://hackaday.io)'s Pi Zero Contest.
5
6This 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
9I 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.
10The OLED I am intending to use has an I²C interface and a screen diagonal of .96".
11
12## using the driver
13The neccessary drivers are available only in the Raspbian 4.4 Kernel, which you can install using
14```
15sudo BRANCH=next rpi-update
16```
17You also need to activate the device tree overlay `dwc2` and load the corresponding kernel module:
18```
19echo "dtoverlay=dwc2" | sudo tee -a /boot/config.txt
20echo "dwc2" | sudo tee -a /etc/modules
21```
22
23To use this program, you have to enable the `libcomposite` driver on the Raspberry Pi and create a USB HID gadget.
24You 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
29modprobe libcomposite
30cd /sys/kernel/config/usb_gadget/
31mkdir -p g1
32cd g1
33echo 0x1d6b > idVendor # Linux Foundation
34echo 0x0104 > idProduct # Multifunction Composite Gadget
35echo 0x0100 > bcdDevice # v1.0.0
36echo 0x0200 > bcdUSB # USB2
37mkdir -p strings/0x409
38echo "fedcba9876543210" > strings/0x409/serialnumber
39echo "girst" > strings/0x409/manufacturer
40echo "Hardpass" > strings/0x409/product
41N="usb0"
42mkdir -p functions/hid.$N
43echo 1 > functions/hid.usb0/protocol
44echo 1 > functions/hid.usb0/subclass
45echo 8 > functions/hid.usb0/report_length
46echo -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
47C=1
48mkdir -p configs/c.$C/strings/0x409
49echo "Config $C: ECM network" > configs/c.$C/strings/0x409/configuration
50echo 250 > configs/c.$C/MaxPower
51ln -s functions/hid.$N configs/c.$C/
52ls /sys/class/udc > UDC
53```
54
55## modifying `pass`
56The 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
58You 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
61whenever 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)
641. in `scancodes.h` add the layout to `keysym`-struct:
65this identifier does not need to be used outside of scancodes.{h,c}.
66```
67struct keysym {
68 // ...
69 struct layout de_dv; //dvorak layout
70 // ...
71};
72```
732. the enum `kbd1` has to be ammended:
74```
75enum kbdl { //keyboard layouts:
76 // ...
77 de_DV //de_AT-Dvorak
78};
79```
803. in `scancodes.c` you need to add a new column (containing more columns) to the big `keysyms[]` table:
81It 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.
82if 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```
84struct 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```
924. `tolay()` needs a new case to its switch statement:
93This is the only place where the `layout`-idenitfier from `keysym` needs to be used.
94```
95struct 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```
1035. finally, your code must understand the new layout, represented by the `enum kbd1`-entry, `de_DV` in this example.
104
105## License
106Copyright 2015-2016 Tobias Girstmair, own work released under the GNU GPL v3
Imprint / Impressum