From 40615d70f57a11c38e40e356864e6e55f6eea6c8 Mon Sep 17 00:00:00 2001 From: Nicolas Stalder Date: Mon, 17 Sep 2018 23:32:01 +0200 Subject: [PATCH] :memo: add documentation on udev --- docs/{hosting.md => documenting.md} | 0 docs/udev.md | 41 +++++++++++++++++++++++++++++ mkdocs.yml | 5 ++-- 3 files changed, 44 insertions(+), 2 deletions(-) rename docs/{hosting.md => documenting.md} (100%) create mode 100644 docs/udev.md diff --git a/docs/hosting.md b/docs/documenting.md similarity index 100% rename from docs/hosting.md rename to docs/documenting.md diff --git a/docs/udev.md b/docs/udev.md new file mode 100644 index 0000000..92ee07d --- /dev/null +++ b/docs/udev.md @@ -0,0 +1,41 @@ +# How do udev rules work and why are they needed + +In Linux, `udev` (part of `systemd`, read `man 7 udev`) handles "hot-pluggable" devices, of which Solo and U2F Zero are examples. In particular, it creates nodes in the `/dev` filesystem (in Linux, everything is a file), which allow accessing the device. + +By default, for security reasons often only the `root` user can access these nodes, unless they are whitelisted using a so-called "udev rule". So depending on your system setup, such a udev rule may be necessary to allow non-root users access to the device, for instance yourself when using a browser to perform two-factor authentication. + +## What does a udev rule do? +It matches events it receives (typically, comparing with the `==` operator), and performs actions (typically, setting attributes of the node with the `=` or `+=` operators). + +## What is `hidraw`? +HID are human-interface devices (keyboards, mice, Solo keys), attached via USB. The `hidraw` system gives software direct ("raw") access to the device. + +## Which node is my Solo or U2F Zero security key? +You can either compare `ls /dev` before and after inserting, or use the `udevadm` tool, e.g., by running +``` +udevadm monitor --environment --udev | grep DEVNAME +``` +Typically, you will detect `/dev/hidraw0`. + +## How do you know if your system is configured correctly? +Try reading and writing to the device node you identified in the previous step. Assuming the node is called `/dev/hidraw0`: + +* read: try `cat /dev/hidraw0`, if you don't get "permission denied", you can access. +* write: try `echo "hello, Solo" > /dev/hidraw0`. Again, if you don't get denied permission, you're OK. + +## Which rule should I use, and how do I do it? +Simplest is probably to copy [Yubico's rule file](https://github.com/Yubico/libu2f-host/blob/master/70-u2f.rules) to `/etc/udev/rules.d/fido.rules` on your system. This contains rules for Yubico's keys, the U2F Zero, and many others. The relevant line for U2F Zero is: +``` +KERNEL=="hidraw*", SUBSYSTEM=="hidraw", ATTRS{idVendor}=="10c4", ATTRS{idProduct}=="8acf", TAG+="uaccess" +``` +It matches on the correct vendor/product IDs of 10c4/8acf, and adds the TAG `uaccess`. Older versions of udev use rules such as +``` +KERNEL=="hidraw*", SUBSYSTEM=="hidraw", ATTRS{idVendor}=="10c4", MODE="0644", GROUP="plugdev" +``` +which sets MODE of the device node to readable by anyone. + +## What about vendor and product ID for Solo? +Current prototypes reuse the IDs of the U2F Zero (10c4/8acf). The final Solo will probably be assigned new IDs; read about it here first :) + +## You got this all wrong, I can't believe it! +Are you suffering from [us being wrong](https://xkcd.com/386/)? Please, send us a [pull request](https://github.com/SoloKeysSec/solo/pulls) and prove us wrong :D diff --git a/mkdocs.yml b/mkdocs.yml index c86dfea..2a5dccd 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -8,8 +8,9 @@ copyright: 'Copyright © 2018 SoloKeys' nav: - Home: index.md - README.md: repo-readme.md - - Contributing: contributing.md - - Hosting: hosting.md + - Contributing Code: contributing.md + - Contributing Docs: documenting.md + - What the udev?!: udev.md theme: name: material