mirror of
https://github.com/RfidResearchGroup/ChameleonUltra.git
synced 2026-04-25 13:12:12 +00:00
05ea03d31c
* doc: Add box net and vectortraced boxart * doc: add troubleshooting entry and python notice * fix: compress images
206 lines
6.0 KiB
Markdown
206 lines
6.0 KiB
Markdown
# CLI
|
|
|
|
The CLI (**C**ommand **L**ine **I**nterface) is the official way to control your Chameleon.
|
|
|
|
It requires at least **Python 3.9** version.
|
|
|
|
## Installing
|
|
|
|
There are multiple ways to install the CLI, depending on your OS.
|
|
|
|
### Windows
|
|
|
|
Windows users have the choice of 4 options:
|
|
|
|
#### ProxSpace
|
|
|
|
Using ProxSpace to build the CLI is the easiest and most comfortable way to get started.
|
|
|
|
1. Download ProxSpace from the [official GitHub](https://github.com/Gator96100/ProxSpace/releases/latest)
|
|
|
|
2. [Download 7zip](https://www.7-zip.org/) to extract the archive
|
|
|
|
3. Install 7zip by double clicking the Installer and clicking `Install`
|
|
|
|
4. Right-click on the downloaded archive and select `7zip -> Unpack to "ProxSpace"`
|
|
|
|
5. Open a terminal in the proxspace folder. If you are on a new Windows install, you should be able to just right-click and select `Open in Terminal`. If that option is not visible and the ProxSpace folder is still in your downloads folder, press `win+r` and type `powershell` followed by enter. In Powershell now type `cd ~/Downloads/ProxSpace`
|
|
|
|
6. Run the command `.\runme64.bat`. After successful completion, you should be dropped to the `pm3 ~ $` shell.
|
|
|
|
7. Clone the Repository by typing `git clone https://github.com/RfidResearchGroup/ChameleonUltra.git`
|
|
|
|
8. Now go into the newly created folder with `cd ChameleonUltra/software/src`
|
|
|
|
9. Prepare for package installation with `pacman-key --init; pacman-key --populate; pacman -S msys2-keyring --noconfirm; pacman-key --refresh`
|
|
|
|
10. Proceed by installing Ninja with `pacman -S ninja --noconfirm`
|
|
|
|
11. Build the required config by running `cmake .`
|
|
|
|
12. And the binaries with `cmake --build .`
|
|
|
|
13. Go into the script folder with `cd ~/ChameleonUltra/software/script/`
|
|
|
|
14. Install python requirements with `pip install -r requirements.txt`
|
|
|
|
15. Finally run the CLI with `python chameleon_cli_main.py`
|
|
|
|
To use after installing, just do the following:
|
|
|
|
1. Run `runme64.bat`
|
|
|
|
2. Go into the script folder with `cd ~/ChameleonUltra/software/script/`
|
|
|
|
3. Run the CLI with `python chameleon_cli_main.py`
|
|
|
|
#### WSL2
|
|
|
|
Coming Soon
|
|
|
|
#### WSL1
|
|
|
|
Coming Soon
|
|
|
|
#### Build Natively
|
|
|
|
Building natively is a bit more advanced and not recommended for beginners
|
|
|
|
1. Download and install [Visual Studio Community](https://visualstudio.microsoft.com/de/downloads/)
|
|
|
|
2. On the workload selection screen, choose the `Desktop development with C++` workload. Click `Download and Install`
|
|
|
|
3. Download and install [git](https://git-scm.com/download). When asked, add to your path
|
|
|
|
4. Download and install [cmake](https://cmake.org/download/). Again, when asked, add to your path
|
|
|
|
5. Download and install [python](https://www.python.org/downloads/). When asked, add to your path (small checkbox in the bottom left). Python 3.9 or above is required.
|
|
|
|
6. Choose a suitable location and open a terminal. Clone the repository with `git clone https://github.com/RfidResearchGroup/ChameleonUltra.git`
|
|
|
|
7. Change into the binaries folder with `cd ChameleonUltra/software/src`
|
|
|
|
8. Build the required config by running `cmake .`
|
|
|
|
9. And the binaries with `cmake --build .`
|
|
|
|
10. Copy the binaries by running `cp -r ../bin/Debug/* ../script/`
|
|
|
|
11. Go into the script folder with `cd ../script/`
|
|
|
|
12. Create a python virtual environment with `python -m venv venv`
|
|
|
|
13. Activate it by running `.\venv\Scripts\Activate.ps1`
|
|
|
|
14. Install python requirements with `pip install -r requirements.txt`
|
|
|
|
15. Finally run the CLI with `python chameleon_cli_main.py`
|
|
|
|
To run again after installing, just do the following:
|
|
|
|
1. Activate venv by running `.\venv\Scripts\Activate.ps1`
|
|
|
|
2. Run the CLI with `python chameleon_cli_main.py`
|
|
|
|
### Linux
|
|
|
|
Install the dependencies
|
|
- Ubuntu / Debian:
|
|
`sudo apt install git cmake build-essential python3-venv`
|
|
- Arch:
|
|
`sudo pacman -S git cmake base-devel python3`
|
|
|
|
Python 3.9 or above is required.
|
|
|
|
Run the following script to clone the Repository, compile the tools and install Python dependencies in a virtual environment.
|
|
|
|
```sh
|
|
#!/bin/bash
|
|
|
|
git clone https://github.com/RfidResearchGroup/ChameleonUltra.git
|
|
(
|
|
cd ChameleonUltra/software/src
|
|
mkdir -p out
|
|
(
|
|
cd out
|
|
cmake ..
|
|
cmake --build . --config Release
|
|
)
|
|
)
|
|
(
|
|
cd ChameleonUltra/software/script
|
|
python3 -m venv venv
|
|
source venv/bin/activate
|
|
pip3 install -r requirements.txt
|
|
deactivate
|
|
)
|
|
```
|
|
|
|
To run the client after installing, do the following:
|
|
|
|
```sh
|
|
cd ChameleonUltra/software/script
|
|
source venv/bin/activate
|
|
python3 chameleon_cli_main.py
|
|
deactivate
|
|
```
|
|
|
|
### MacOS
|
|
|
|
*Coming Soon*
|
|
|
|
## Usage
|
|
|
|
When in the CLI, plug in your Chameleon and connect with `hw connect`. If autodetection fails, get the Serial Port used by your Chameleon and run `hw connect -p COM11` (Replace `COM11` with your serial port, on Linux it may be `/dev/ttyACM0`)
|
|
|
|
### MFKEY32v2 walk-through
|
|
Make sure to be in the `software/` directory and run the Python CLI from there.
|
|
|
|
```sh
|
|
# Connect to the CLI
|
|
hw connect
|
|
# Check which slot can be used
|
|
hw slot list
|
|
# Change the slot type, here using slot 8 for a MFC 1k emulation
|
|
hw slot type -s 8 -t MIFARE_1024
|
|
# Init the slot content
|
|
hw slot init -s 8 -t MIFARE_1024
|
|
# or load an existing dump and set UID and anticollision data,
|
|
# cf 'hf mf eload' and 'hf mf econfig'
|
|
# Enable the slot
|
|
hw slot enable -s 8 --hf
|
|
# Change to the new slot
|
|
hw slot change -s 8
|
|
# Activate the authentication logs
|
|
hf mf econfig --enable-log
|
|
```
|
|
Now disconnect, go to a reader and swipe it a few times
|
|
|
|
Come back
|
|
|
|
```sh
|
|
# connect to the CLI
|
|
hw connect
|
|
# See if nonces were collected. We need 2 nonces per key to recover
|
|
hf mf elog
|
|
# Recover the key(s) based on the collected nonces
|
|
hf mf elog --decrypt
|
|
# Clean the logged detection nonces
|
|
hf mf econfig --disable-log
|
|
```
|
|
Output example:
|
|
```
|
|
- MF1 detection log count = 6, start download.
|
|
- Download done (144bytes), start parse and decrypt
|
|
- Detection log for uid [DEADBEEF]
|
|
> Block 0 detect log decrypting...
|
|
> Block 1 detect log decrypting...
|
|
> Result ---------------------------
|
|
> Block 0, A key result: ['a0a1a2a3a4a5', 'aabbccddeeff']
|
|
> Block 1, A key result: ['010203040506']
|
|
|
|
```
|
|
|
|
|
|
*More examples coming soon*
|