From 032f304bf9b08d4bdff77e6940bd23ea60755aed Mon Sep 17 00:00:00 2001 From: Henry Gabryjelski Date: Tue, 31 Jan 2023 01:03:56 -0800 Subject: [PATCH 1/4] Enable use under WSL2 w/Kali Linux distribution * Assign group ownership and permissions in udev rules * Add documentation on WSL2 installation and use --- .../Windows-WSL2-Installation-Instructions.md | 224 ++++++++++++++++++ driver/77-pm3-usb-device-blacklist.rules | 6 +- 2 files changed, 227 insertions(+), 3 deletions(-) create mode 100644 doc/md/Installation_Instructions/Windows-WSL2-Installation-Instructions.md diff --git a/doc/md/Installation_Instructions/Windows-WSL2-Installation-Instructions.md b/doc/md/Installation_Instructions/Windows-WSL2-Installation-Instructions.md new file mode 100644 index 000000000..9519b4849 --- /dev/null +++ b/doc/md/Installation_Instructions/Windows-WSL2-Installation-Instructions.md @@ -0,0 +1,224 @@ + + +# 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. + diff --git a/driver/77-pm3-usb-device-blacklist.rules b/driver/77-pm3-usb-device-blacklist.rules index d939468f2..8d699faca 100644 --- a/driver/77-pm3-usb-device-blacklist.rules +++ b/driver/77-pm3-usb-device-blacklist.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}=="9ac4" ATTRS{idProduct}=="4b8f", ENV{ID_MM_DEVICE_IGNORE}="1" SYMLINK+="pm3-%n" -ATTRS{idVendor}=="502d" ATTRS{idProduct}=="502d", 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="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" From bfc3a53ea262f755295a3b1fb1afa359b614ad13 Mon Sep 17 00:00:00 2001 From: Henry Gabryjelski Date: Tue, 31 Jan 2023 09:45:44 -0800 Subject: [PATCH 2/4] Modify Makefile to copy group-specific udev rules --- Makefile | 9 +++++++- ...77-pm3-usb-device-blacklist-dialout.rules} | 0 driver/77-pm3-usb-device-blacklist-uucp.rules | 22 +++++++++++++++++++ 3 files changed, 30 insertions(+), 1 deletion(-) rename driver/{77-pm3-usb-device-blacklist.rules => 77-pm3-usb-device-blacklist-dialout.rules} (100%) create mode 100644 driver/77-pm3-usb-device-blacklist-uucp.rules diff --git a/Makefile b/Makefile index 0cb778ec6..9d3e509f8 100644 --- a/Makefile +++ b/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 ifneq ($(wildcard /etc/fedora-release),) +# 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. diff --git a/driver/77-pm3-usb-device-blacklist.rules b/driver/77-pm3-usb-device-blacklist-dialout.rules similarity index 100% rename from driver/77-pm3-usb-device-blacklist.rules rename to driver/77-pm3-usb-device-blacklist-dialout.rules diff --git a/driver/77-pm3-usb-device-blacklist-uucp.rules b/driver/77-pm3-usb-device-blacklist-uucp.rules new file mode 100644 index 000000000..101381d95 --- /dev/null +++ b/driver/77-pm3-usb-device-blacklist-uucp.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="uucp" +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" MODE="660" GROUP="uucp" + +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" From 1a214b389c1485f90684608fa40352c0ecb72b5d Mon Sep 17 00:00:00 2001 From: Henry Gabryjelski Date: Tue, 31 Jan 2023 09:49:59 -0800 Subject: [PATCH 3/4] changelog --- CHANGELOG.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index ba2f8f322..82954446e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,7 +5,8 @@ This project uses the changelog in accordance with [keepchangelog](http://keepac ## [unreleased][unreleased] - 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) ## [Nitride.4.16191][2023-01-29] - Changed `build_all_firmwares.sh` to fit GENERIC 256kb firmware images (@doegox) @@ -52,7 +53,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) From 99f24b23b8b9b82e6f0b96b0cf605604dedbed88 Mon Sep 17 00:00:00 2001 From: Henry Gabryjelski Date: Tue, 31 Jan 2023 09:55:46 -0800 Subject: [PATCH 4/4] fix copy/paste error --- Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Makefile b/Makefile index 9d3e509f8..6c31157e2 100644 --- a/Makefile +++ b/Makefile @@ -259,7 +259,7 @@ udev: 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 ifneq ($(wildcard /etc/fedora-release),) +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