Request for adding 0017

README.md

@@ -13,9 +13,9 @@ $ pip3 install -r requirements.txt
 
 ### Automatic factory reset, pairing and firmware flashing
 
-This repo includes `validity-sensors-initializer.py`, a simple tool that
-helps initializing Validity fingerprint readers under linux, loading their
-binary firmware and initializing them.
+This repo includes `validity-sensors-tools.py`, a simple collection of
+tools that helps initializing Validity fingerprint readers under linux,
+loading their binary firmware and initializing them.
 
 This tool currently only supports these sensors:
 - 138a:0090 Validity Sensors, Inc. VFS7500 Touch Fingerprint Sensor
@@ -37,10 +37,50 @@ The procedure is quite simple:
 - The device firmware is uploaded to the device
 - The device is calibrated
 
+For 138a:0097 it's also possible to enroll fingers in the internal storage
+doing:
+`validity-sensors-tools.py --tool enroll --finger-id [0-9]`
+
 Once the chip is paired with the computer via this tool, it's possible to use
 it in libfprint using the driver at
 - https://github.com/3v1n0/libfprint/
 
+#### Installing it as [snap](https://snapcraft.io/)
+
+This tool can be easily installed [almost every linux distribution](https://snapcraft.io/docs/installing-snapd)
+with all its dependencies as snap.
+
+To do so:
+
+```bash
+sudo snap install validity-sensors-tools
+
+# Give it access to the usb devices
+sudo snap connect validity-sensors-tools:raw-usb
+sudo snap connect validity-sensors-tools:hardware-observe
+
+# Initialize the device
+sudo validity-sensors-tools.initializer
+
+# Test the device
+sudo validity-sensors-tools.led-test
+
+# See other avilable tools
+validity-sensors-tools --help
+```
+
+[![Get it from the Snap Store](https://snapcraft.io/static/images/badges/en/snap-store-black.svg)](https://snapcraft.io/validity-sensors-tools)
+
+#### Installing from AUR on Arch Linux
+
+Install [validity-sensors-tools-git<sup>[AUR]</sup>](https://aur.archlinux.org/packages/validity-sensors-tools-git/).
+
+You can run it as `validity-sensors-tools`:
+
+```bash
+sudo validity-sensors-tools -t led-dance
+```
+
 ---
 
 ### Getting the firmware

requirements.txt

@@ -1,3 +1 @@
-fastecdsa==1.7.4
-git+https://github.com/fabiant7t/pycrypto#egg=pycrypto
-pyusb==1.0.2
+.

setup.py

@@ -0,0 +1,21 @@
+from setuptools import setup
+
+setup(
+    name='python-validity',
+    version='0.5',
+    packages=['proto9x'],
+    scripts=['validity-sensors-tools'],
+    url='https://github.com/uunicorn/python-validity',
+    license='',  # TODO (upstream): pick license
+    author='uunicorn',  # TODO (upstream): update contact info if desired
+    author_email='',
+    description='Validity fingerprint sensor prototype',
+    install_requires=(
+        'fastecdsa==1.7.4',
+        'pyusb==1.0.2',
+        'pycrypto'
+    ),
+    dependency_links=(
+        'https://github.com/fabiant7t/pycrypto/tarball/master#egg=pycrypto',
+    )
+)

snap/local/snap-launcher.sh

@@ -0,0 +1,34 @@
+#!/bin/bash
+
+export PYTHONPATH=$SNAP/usr/lib/python3/dist-packages:$PYTHONPATH
+
+for p in $(ls -1d $SNAP/lib/python3*/site-packages); do
+    PYTHONPATH=$PYTHONPATH:$p
+done
+
+if ! $(command -v lsusb) -d 138a: &> /dev/null; then
+    echo "Unable to access to USB devices"
+    echo " $SNAP_NAME is installed as a snap."
+    echo " To allow it to function correctly you may need to run:"
+    echo "   sudo snap connect $SNAP_NAME:raw-usb"
+    echo "   sudo snap connect $SNAP_NAME:hardware-observe"
+    exit 1
+fi
+
+run_tool() {
+    [ -n "$VFS_TOOL" ] && \
+        local args=(--tool "$VFS_TOOL")
+
+    $SNAP/vfs-tools/validity-sensors-tools "${args[@]}" "$@"
+}
+
+run_tool "$@"
+ret=$?
+
+if [ "$ret" -eq 0 ] && [[ "$VFS_TOOL" == 'initializer' ]]; then
+    unset VFS_TOOL
+    echo "May the leds be with you...!"
+    (run_tool "$@" --tool=led-dance &> /dev/null) &
+fi
+
+exit $ret

snap/snapcraft.yaml

@@ -0,0 +1,132 @@
+name: validity-sensors-tools
+base: core20
+version: git
+summary: A Linux tool to flash and pair Validity fingerprint sensors 009x
+description: |
+  A simple tool that helps initializing Validity fingerprint readers under
+  linux, loading their binary firmware and initializing them.
+
+  This tool currently only supports these sensors:
+    - 138a:0090 Validity Sensors, Inc. VFS7500 Touch Fingerprint Sensor
+    - 138a:0097 Validity Sensors, Inc.
+  Which are present in various ThinkPad and HP laptops.
+
+  These devices communicate with the laptop via an encrypted protocol and they
+  need to be paired with the host computer in order to work and compute the
+  TLS keys.
+  Such initialization is normally done by the Windows driver, however thanks to
+  the amazing efforts of Viktor Dragomiretskyy (uunicorn), and previously of
+  Nikita Mikhailov, we have reverse-engineerd the pairing process, and so it's
+  possible to do it under Linux with only native tools as well.
+
+  The procedure is quite simple:
+    - Device is factory-reset and its flash repartitioned
+    - A TLS key is negotiated, generated via host hw ID and serial
+    - Windows driver is downloaded from Lenovo to extract the device firmware
+    - The device firmware is uploaded to the device
+    - The device is calibrated
+
+  For 138a:0097 it's also possible to enroll fingers in the internal storage
+  doing:
+    `validity-sensors-tools.enroll --finger-id [0-9]`
+
+  Once the chip is paired with the computer via this tool, it's possible to use
+  it in libfprint using the driver at
+   - https://github.com/3v1n0/libfprint/
+
+grade: stable
+confinement: strict
+
+parts:
+  python-validity:
+    plugin: python
+    source: .
+    python-packages:
+      - wheel
+    requirements:
+      - requirements.txt
+    build-packages:
+      - gcc
+      - git
+      - libgmp-dev
+    stage-packages:
+      - innoextract
+      - libusb-1.0-0
+      - usbutils
+    override-build: |
+      set -x
+      snapcraftctl build
+      git clone . $SNAPCRAFT_PART_INSTALL/vfs-tools
+      rm -rf $SNAPCRAFT_PART_INSTALL/vfs-tools/.git*
+      rm -rf $SNAPCRAFT_PART_INSTALL/vfs-tools/snap
+
+  snap-launcher:
+    plugin: dump
+    source: snap/local
+    organize:
+      snap-launcher.sh: bin/snap-launcher.sh
+
+apps:
+  validity-sensors-tools:
+    command: bin/snap-launcher.sh
+    plugs:
+      - raw-usb
+      - hardware-observe
+      - network
+
+  initializer:
+    command: bin/snap-launcher.sh
+    environment:
+      VFS_TOOL: initializer
+    plugs:
+      - raw-usb
+      - hardware-observe
+      - network
+
+  led-test:
+    command: bin/snap-launcher.sh
+    environment:
+      VFS_TOOL: led-dance
+    plugs:
+      - raw-usb
+      - hardware-observe
+
+  erase-db:
+    command: bin/snap-launcher.sh
+    environment:
+      VFS_TOOL: erase-db
+    plugs:
+      - raw-usb
+      - hardware-observe
+
+  factory-reset:
+    command: bin/snap-launcher.sh
+    environment:
+      VFS_TOOL: factory-reset
+    plugs:
+      - raw-usb
+      - hardware-observe
+
+  pair:
+    command: bin/snap-launcher.sh
+    environment:
+      VFS_TOOL: pair
+    plugs:
+      - raw-usb
+      - hardware-observe
+
+  calibrate:
+    command: bin/snap-launcher.sh
+    environment:
+      VFS_TOOL: calibrate
+    plugs:
+      - raw-usb
+      - hardware-observe
+
+  enroll:
+    command: bin/snap-launcher.sh
+    environment:
+      VFS_TOOL: enroll
+    plugs:
+      - raw-usb
+      - hardware-observe