Merge pull request #1894 from henrygab/wsl2_docs

Enable use under WSL2 w/Kali Linux distribution

CHANGELOG.md

@@ -3,12 +3,13 @@ All notable changes to this project will be documented in this file.
 This project uses the changelog in accordance with [keepchangelog](http://keepachangelog.com/). Please use this to write notable changes, which is not the same as git commit log...
 
 ## [unreleased][unreleased]
- - Fixed broken `lf em 4x70 brute` command (@adite)
+ - Fixed `lf em 4x70 brute` - now works as expected (@adite)
  - Fixed the lf sampling when bits_per_sample is less than 8 (@wh201906)
  - Added `lf em 4x70 brute` command (@adite)
+ - Added documentation for usage of Proxmark3 under WSL2 (@henrygab)
+ - Fixed device permissions via updated `udev` rules (@henrygab)
  - Added `--back` option to `clear` command to clear the scrollback buffer (@wh201906)
 
-
 ## [Nitride.4.16191][2023-01-29]
  - Changed `build_all_firmwares.sh` to fit GENERIC 256kb firmware images (@doegox)
  - Fixed some coverity fixes (@iceman1001)
@@ -54,7 +55,6 @@ This project uses the changelog in accordance with [keepchangelog](http://keepac
  - Fixed `trace list -c` - annotation of CRC bytes now is colored or squared if no ansi colors is supported (@iceman1001)
  - Fixed `trace list -t mf` - now also finds UID if anticollision is partial captured, to be used for mfkey (@iceman1001)
 
-
 ## [Radium.4.15864][2022-10-29]
  - Changed `lf indala sim` - now accepts fc / cn (@iceman1001)
  - Added `lf indala brute`- brute forcing of 64b Indala ID (@iceman1001)

Makefile

@@ -256,8 +256,15 @@ endif
 # configure system to ignore PM3 device as a modem (ModemManager blacklist, effective *only* if ModemManager is not using _strict_ policy)
 # Read doc/md/ModemManager-Must-Be-Discarded.md for more info
 udev:
-	$(SUDO) cp -rf driver/77-pm3-usb-device-blacklist.rules $(DESTDIR)$(UDEV_PREFIX)/77-pm3-usb-device-blacklist.rules
+ifneq ($(wildcard /etc/arch-release),)
+# If user is running ArchLinux, use group 'uucp'
+	$(SUDO) cp -rf driver/77-pm3-usb-device-blacklist-uucp.rules    $(DESTDIR)$(UDEV_PREFIX)/77-pm3-usb-device-blacklist.rules
+else
+# Else, use group 'dialout'
+	$(SUDO) cp -rf driver/77-pm3-usb-device-blacklist-dialout.rules $(DESTDIR)$(UDEV_PREFIX)/77-pm3-usb-device-blacklist.rules
+endif
 	$(SUDO) udevadm control --reload-rules
+	$(SUDO) udevadm trigger --action=change
 
 # configure system to add user to the dialout group and if bluetooth group exists,  add user to it
 # you need to logout, relogin to get this access right correct.

doc/md/Installation_Instructions/Windows-WSL2-Installation-Instructions.md

@@ -0,0 +1,224 @@
+<a id="top"></a>
+
+# WSL2 Installation instructions
+
+## Table of Contents
+- [WSL2 Installation instructions](#wsl2-installation-instructions)
+  - [Table of Contents](#table-of-contents)
+  - [Requirements](#requirements)
+  - [Install Kali Linux distribution](#install-kali-linux-distribution)
+  - [Driver installation (Windows 11)](#driver-installation-windows-11)
+  - [USBIPD hints](#usbipd-hints)
+  - [WSL2 / Kali Linux Installation](#wsl2--kali-linux-installation)
+  - [X Server Installation](#x-server-installation)
+  - [Clone the Iceman repository](#clone-the-iceman-repository)
+  - [Compile the project](#compile-the-project)
+  - [Install the udev rules](#install-the-udev-rules)
+  - [Inform udev that it really, really should work](#inform-udev-that-it-really-really-should-work)
+  - [Verify Device Exists](#verify-device-exists)
+  - [Using the client...](#using-the-client)
+  - [Done!](#done)
+
+This provides instructions on how to install, build, and use Proxmark3
+on Windows 11, using WSL2 (and Kali Linux).
+
+## Requirements
+^[Top](#top)
+
+This WSL 2 method requires Windows 11 (Build 22000 or later),
+WSL installed and [set to WSL2](https://learn.microsoft.com/en-us/windows/wsl/basic-commands#set-wsl-version-to-1-or-2),
+
+While WSL 2 does not itself support passing through USB or
+serial devices, it can work by using the USB/IP open-source
+project, [`usbipd-win`](https://github.com/dorssel/usbipd-win).
+
+
+## Install Kali Linux distribution
+^[Top](#top)
+
+Open the Windows App Store, and install Kali Linux.
+
+For WSL configuration, see [Manage and configure Windows Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/wsl-config).
+
+Start the Kali Linux distribution at least once, to ensure it's fully installed.
+
+## Driver installation (Windows 11)
+^[Top](#top)
+
+On the Windows (host) machine, install the
+[latest release](https://github.com/dorssel/usbipd-win/releases)
+of `usbpid-win` (typically an `.MSI` file).
+
+## USBIPD hints
+^[Top](#top)
+
+This is *NOT* intended to be a full description of how to use USBIPD.
+Rather, this is intended only to give a starting point, as ***the values
+shown here are extremely likely to differ per machine***.
+
+It's presumed that you've already installed USBIPD.  Plug the Proxmark
+device into a USB port.  Then, from a `cmd.exe` or `wt.exe` ***launched
+with administrative permissions***:
+
+Get a list of attached devices.  Example (NOTE: VID/PID for non-proxmark devices redacted)
+
+```cmd
+C:\qwert> usbipd list
+
+Connected:
+BUSID  VID:PID    DEVICE                                                        STATE
+1-2    xxxx:xxxx  USB Input Device                                              Not shared
+2-3    xxxx:xxxx  USB Mass Storage Device                                       Not shared
+5-3    9ac4:4b8f  USB Serial Device (COM31)                                     Not shared
+
+Persisted:
+GUID                                  DEVICE
+```
+
+Take note of the `BUSID` for the proxmark device, which should show as a USB Serial Device.
+
+Setup that bus ID to always be redirected to the WSL distribution named `kali-linux`:
+
+```cmd
+C:\qwert> usbipd wsl attach --busid 5-3 --distribution kali-linux --auto-attach
+usbipd: info: Starting endless attach loop; press Ctrl+C to quit.
+Attached
+```
+
+NOTE: You must leave that running in the background, to allow the device to automatically
+re-attach to the WSL2 instance.
+
+
+
+## WSL2 / Kali Linux Installation
+^[Top](#top)
+
+Start the Kali Linux distribution you installed.  First, make sure
+the distribution is up-to-date:
+
+```sh
+sudo apt-get update
+sudo apt-get upgrade -y
+sudo apt-get auto-remove -y
+```
+
+then, install proxmark dependencies:
+
+```sh
+sudo apt-get install --no-install-recommends \
+  git ca-certificates build-essential pkg-config \
+  libreadline-dev gcc-arm-none-eabi libnewlib-dev \
+  libbz2-dev libpython3-dev qtbase5-dev libssl-dev
+```
+
+_note_
+If you don't need the graphical components of the Proxmark3 client, you can skip the installation of `qtbase5-dev`.  
+If you don't need support for Python3 scripts in the Proxmark3 client, you can skip the installation of `libpython3-dev`.
+
+## X Server Installation
+^[Top](#top)
+
+TBD -- Installing [`Win-KeX`](https://www.kali.org/docs/wsl/win-kex/) has worked
+to provide a fully integrated experience, with three distinct modes.....
+However, WSL2 may have some functionality already built-in?
+
+## Clone the Iceman repository
+^[Top](#top)
+
+```sh
+cd ~/
+git clone https://github.com/RfidResearchGroup/proxmark3.git
+```
+
+## Compile the project
+^[Top](#top)
+
+```sh
+cd ~/proxmark3
+make clean && make -j
+```
+
+## Install the udev rules
+
+```sh
+sudo make accessrights
+sudo make udev
+```
+
+On Kali, the above does two things:
+1. Ensures the user is a member of the `dialout` group
+2. Copies the `./driver/77-pm3-usb-device-blacklist.rules` file to the `/etc/udev/rules.d/` directory
+
+This presumes that the file includes `MODE="660" GROUP="dialout"` at the end of the three match lines.
+The goal is that Kali Linux will automatically apply the proper permissions when the device is attached.
+
+However, it may be necessary to give the `udev` service a kind reminder:
+
+## Inform udev that it really, really should work
+
+The following workaround appears to work to get udev to apply the permissions
+appropriately.  Note that this may need to be run again, such as when the WSL2
+distributions have been restarted.  I don't know why ... but it's a small hiccup.
+
+```sh
+sudo udevadm trigger --action=change
+```
+
+General instructions suggested to use `sudo udevadm control --reload-rules`.  However,
+this may simply result in the following cryptic error message:
+
+```sh
+$ sudo udevadm control --reload-rules
+[sudo] password for root:
+Failed to send reload request: No such file or directory
+```
+
+_Note that the following should **NOT** be required:_
+
+```sh
+sudo service udev restart
+```
+
+## Verify Device Exists
+
+Verify the device exists, and has a symbolic link created:
+
+```sh
+ls -lFA /dev/ttyACM*
+ls -lFA /dev/pm3*
+```
+
+
+The first should show the `rw` permissions for both owner
+and group, and show the group as `dialout`:
+
+```sh
+┌──(qwert㉿host)-[~]
+└─$ ls -lFA /dev/ttyACM*
+crw-rw---- 1 root dialout 166, 0 Jan 22 11:28 /dev/ttyACM0
+```
+
+The second command should show that a symbolic link exists
+from the friendly name `/dev/pm3-0` to the TTY device:
+
+```sh
+┌──(qwert㉿host)-[~]
+└─$ ls -lFA /dev/pm3*
+lrwxrwxrwx 1 root root 7 Jan 17 19:46 /dev/pm3-0 -> ttyACM0
+```
+
+## Using the client...
+
+```sh
+┌──(qwert㉿host)-[~]
+└─$ pushd ~/proxmark3
+
+┌──(qwert㉿host)-[~]
+└─$ ./pm3
+```
+
+## Done!
+^[Top](#top)
+
+Full [compilation instructions](/doc/md/Use_of_Proxmark/0_Compilation-Instructions.md) may be helpful.
+

driver/77-pm3-usb-device-blacklist-dialout.rules

@@ -0,0 +1,22 @@
+# Proxmark3 linux modem-manager de-confliction file
+#
+# copy this file to /etc/udev/rules.d (or add the entry to the end of an existing file)
+# and restart udev hotplug:
+#
+#  'sudo udevadm control --reload-rules'
+#
+
+# proxmark3
+ACTION!="add|change", GOTO="pm3_usb_device_blacklist_end"
+SUBSYSTEM!="tty", GOTO="pm3_ignore"
+
+ATTRS{idVendor}=="2d2d" ATTRS{idProduct}=="504d", ENV{ID_MM_DEVICE_IGNORE}="1" SYMLINK+="pm3-%n" MODE="660" GROUP="dialout"
+ATTRS{idVendor}=="9ac4" ATTRS{idProduct}=="4b8f", ENV{ID_MM_DEVICE_IGNORE}="1" SYMLINK+="pm3-%n" MODE="660" GROUP="dialout"
+ATTRS{idVendor}=="502d" ATTRS{idProduct}=="502d", ENV{ID_MM_DEVICE_IGNORE}="1" SYMLINK+="pm3-%n" MODE="660" GROUP="dialout"
+
+LABEL="pm3_ignore"
+ATTRS{idVendor}=="2d2d" ATTRS{idProduct}=="504d", ENV{ID_MM_DEVICE_IGNORE}="1"
+ATTRS{idVendor}=="9ac4" ATTRS{idProduct}=="4b8f", ENV{ID_MM_DEVICE_IGNORE}="1"
+ATTRS{idVendor}=="502d" ATTRS{idProduct}=="502d", ENV{ID_MM_DEVICE_IGNORE}="1"
+
+LABEL="pm3_usb_device_blacklist_end"

driver/77-pm3-usb-device-blacklist-uucp.rules

@@ -10,9 +10,9 @@
 ACTION!="add|change", GOTO="pm3_usb_device_blacklist_end"
 SUBSYSTEM!="tty", GOTO="pm3_ignore"
 
-ATTRS{idVendor}=="2d2d" ATTRS{idProduct}=="504d", ENV{ID_MM_DEVICE_IGNORE}="1" SYMLINK+="pm3-%n"
+ATTRS{idVendor}=="2d2d" ATTRS{idProduct}=="504d", ENV{ID_MM_DEVICE_IGNORE}="1" SYMLINK+="pm3-%n" MODE="660" GROUP="uucp"
-ATTRS{idVendor}=="9ac4" ATTRS{idProduct}=="4b8f", ENV{ID_MM_DEVICE_IGNORE}="1" SYMLINK+="pm3-%n"
+ATTRS{idVendor}=="9ac4" ATTRS{idProduct}=="4b8f", ENV{ID_MM_DEVICE_IGNORE}="1" SYMLINK+="pm3-%n" MODE="660" GROUP="uucp"
-ATTRS{idVendor}=="502d" ATTRS{idProduct}=="502d", ENV{ID_MM_DEVICE_IGNORE}="1" SYMLINK+="pm3-%n"
+ATTRS{idVendor}=="502d" ATTRS{idProduct}=="502d", ENV{ID_MM_DEVICE_IGNORE}="1" SYMLINK+="pm3-%n" MODE="660" GROUP="uucp"
 
 LABEL="pm3_ignore"
 ATTRS{idVendor}=="2d2d" ATTRS{idProduct}=="504d", ENV{ID_MM_DEVICE_IGNORE}="1"