Merge branch 'main' into software-capabilities

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,50 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+***Things to try before submitting a bug report***
+
+* read the [troubleshooting guide](https://github.com/RfidResearchGroup/ChameleonUltra/blob/main/docs/troubleshooting.md)
+* check existing [issues](https://github.com/RfidResearchGroup/ChameleonUltra/issues)
+* use the latest firmware and CLI
+* for issues specific to another client than the Python CLI, use the corresponding issue tracker. E.g. [here](https://github.com/GameTec-live/ChameleonUltraGUI/issues) for the ChameleonUltraGUI
+
+***Compilation problems***
+Try compiling with verbose. Use `make VERBOSE=1` for the firmware and the software/src tools.
+Include the verbose compilation logs.
+
+***flashing problems***
+Have you followed the instructions properly?
+
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**To Reproduce**
+Steps to reproduce the behavior.  
+Explain it as you would do to someone not familiar with the problematic feature.  
+What is the abnormal behavior you observed?  
+E.g.
+1. Connect '....'
+2. Execute '....'
+3. Press button '....'
+4. See error '....'
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Screenshots**
+If applicable, add screenshots to help explain your problem. For console text and logs, better to dump them as text than image. Attach files if too long.
+
+**Host (please complete the following information):**
+ - OS and version
+ - for compilation issues, the toolchain version
+ - inside CLI run `hw version` and paste the output here
+
+**Additional context**
+Add any other context about the problem here.

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Official channels Chameleon Ultra Community
+    url: https://github.com/RfidResearchGroup/ChameleonUltra#official-channels
+    about: Got questions? Ask in *official channels*, not in an issue

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,25 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: "[idea]"
+labels: Request, enhancement
+assignees: ''
+
+---
+
+Please keep in mind we are still at the infancy of the project and a lot has still to be done.
+
+Have first a look at the [Whitepaper](https://github.com/RfidResearchGroup/ChameleonUltra/blob/main/docs/technical_whitepaper.md), the Wiki [Roadmap](https://github.com/RfidResearchGroup/ChameleonUltra/wiki/Public-Roadmap) and [Wishlist](https://github.com/RfidResearchGroup/ChameleonUltra/wiki/Wishlist).  
+No need for creating issues for well known missing supports, we are already aware :)
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**
+Add any other context or screenshots about the feature request here.

CHANGELOG.md

@@ -3,6 +3,9 @@ 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]
+ - ChameleonLite emulation bug fixed (@spp2000)
+ - Fixed MFC emulation issues with OEM readers, also temporarily disabling NFC_MF1_FAST_SIM (@xianglin1998)
+ - Fixed Chameleon crash during BLE pairing (@Foxushka)
  - Fixed CLI takes into account Lite refusing to enter Reader mode (@doegox)
  - Security BLE implemented (@xianglin1998)
  - Added `hw settings blekey` to get and set ble connect key (@xianglin1998)
@@ -19,7 +22,7 @@ This project uses the changelog in accordance with [keepchangelog](http://keepac
  - Added offline copy EM card uid for btnpress (@nemanjan00)
  - Added offline copy ic card uid for btnpress (@xianglin1998)
  - Added `hw settings btnpress` to get and set button press function (@xianglin1998)
- - Added `hw battery` to get battery informartion (@xianglin1998)
+ - Added `hw battery` to get battery information (@xianglin1998)
  - Added `hw slot delete` to delete HF or LF out of a HF+LF slot (@augustozanellato)
  - Changed CLI prompt autocompletion, saved history and internal cmd registration (@szymex73)
  - Fixed SDK NFC IRQ handler busy loop (@doegox)

README.md

@@ -20,9 +20,15 @@ Read the [available documentation](docs/README.md).
 
 # Videos
 
-*Beware some of the instructions might have changed since recording, theck the current documentation in doubt!*
+*Beware some of the instructions might have changed since recording, check the current documentation when in doubt!*
 
 * [Downloading and compiling the official CLI](https://www.youtube.com/watch?v=VGpAeitNXH0)
 * [Downloading ChameleonUltraGUI](https://www.youtube.com/watch?v=rHH7iqbX3nY)
 
+# Official channels
 
+Where do you find the community?
+
+* [RFID Hacking community discord server](https://t.ly/d4_C)
+  * Software/chameleon-dev for firmware and clients development discussions
+  * Devices/chameleon-ultra for usage discussions

docs/README.md

@@ -4,22 +4,32 @@ This guide goal is to guide you through setting up and using your Chameleon Ultr
 
 This Guide is split up into multiple "subguides":
 
-- ["Whitepaper"](./technical_whitepaper.md): Discover what the Chameleon Ultra is capable of
+### About the device
 
-- ["Hardware"](./hardware.md): Learn to know the hardware of your Chameleon
+- [Whitepaper](./technical_whitepaper.md): Discover what the Chameleon Ultra is capable of.
 
-- ["Firmware"](./firmware.md): Your Chameleon runs a firmware, learn what it can do and how to use it
+- [Hardware](./hardware.md): Learn to know the hardware of your Chameleon.
 
-- ["CLI"](./cli.md): The official way to control your Chameleon is via the **C**ommand **L**ine **I**nterface (CLI) . Learn how to install and master the CLI.
+- [Firmware](./firmware.md): Your Chameleon runs a firmware, learn what it can do and how to use it.
 
-- ["GUIs"](./gui.md): Some people also develop **G**raphical **U**ser **I**nterfaces (GUIs), these may be a good start for people that do not want to deal with a CLI.
+### Interacting with the device
 
-- ["Troubleshooting"](./troubleshooting.md): For when things go wrong, here are some common tips to maybe fix whatever issue you might have.
+- [Quickstart](./quickstart.md): For the impatient people to just get you up and running with anything.
 
-- ["FAQ"](./faq.md): Frequently asked questions, if you have a question, it might already be answered here.
+- [CLI](./cli.md): The official way to control your Chameleon is via the **C**ommand **L**ine **I**nterface (CLI). Learn how to install and master the CLI.
 
-- ["Quickstart"](./quickstart.md): for the impatient people to just get you up and running with anything.
+- [GUIs](./gui.md): Some people also develop **G**raphical **U**ser **I**nterfaces (GUIs), these may be a good start for people that do not want to deal with a CLI.
 
-- ["Development"](./development.md): for all developers. This covers how to build firmware from source and set up a development environment.
+- [Troubleshooting](./troubleshooting.md): For when things go wrong, here are some common tips to maybe fix whatever issue you might have.
 
-- ["Protocol"](./protocol.md): the gory details of the communication protocol, useful if you want to develop your own client.
+### For developers
+
+- [Development](./development.md): For all developers. This covers how to build firmware from source and set up a development environment.
+
+- [Protocol](./protocol.md): The gory details of the communication protocol, useful if you want to develop your own client.
+
+### Miscellaneous 
+
+- [Modding](./modding.md): Third party moddings worth mentioning.
+
+- [FAQ](./faq.md): **F**requently **A**sked **Q**uestions, if you have a question, it might already be answered here.

docs/chameleonultragui.md

@@ -0,0 +1,15 @@
+## Get ChameleonUltraGUI
+
+- [on Google Play](https://play.google.com/store/apps/details?id=io.chameleon.ultra) / [APK](https://nightly.link/GameTec-live/ChameleonUltraGUI/workflows/buildapp/main/apk.zip)
+- [on iOS](https://apps.apple.com/dk/app/chameleon-ultra-gui/id6462919364)
+- [on Windows](https://nightly.link/GameTec-live/ChameleonUltraGUI/workflows/buildapp/main/windows-installer.zip) ([or without installer](https://nightly.link/GameTec-live/ChameleonUltraGUI/workflows/buildapp/main/windows.zip))
+- [on Linux](https://nightly.link/GameTec-live/ChameleonUltraGUI/workflows/buildapp/main/linux.zip)
+- [on macOS](https://apps.apple.com/app/chameleon-ultra-gui/id6462919364)
+
+
+## How to use MFKEY32
+
+- set slot to mifare classic (by uploading an empty dump)
+- enable mfkey32 for that slot (toggle in slot settings)
+- select slot and present ultra repeatedly to the reader in order to collect nonces
+- after collecting some nonces, go back into slot settings and click recover keys

docs/cli.md

@@ -32,7 +32,7 @@ Using ProxSpace to build the CLI is the easiest and most comfortable way to get
 
 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`
+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`
 
@@ -118,16 +118,43 @@ When in the CLI, plug in your Chameleon and connect with `hw connect`. If autode
 
 ### Common activities
 
-- Change slot: hw slot change -s [1-8]
+- Connect to the CLI: `hw connect`
+- Change slot: `hw slot change -s [1-8]`
 
 *More examples coming soon*
 
-### Available Commands
+### MFKEY32v2 walk-through
+Make sure to be in the `software/` directory and run the Python CLI from there.
 
-In `()` is the argument description, `[]` are possible entries for that argument (eg `[1-8]`)
+- 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 -s8 -t3`
+- Init the slot content: `hw slot init -s8 -t3`
+  - or load an existing dump and set UID and anticollision data, cf `hf mf eload -h` and `hf mf sim -h`
+- Enable the slot: `hw slot enable -s8 -e1`
+- Change to the new slot: `hw slot change -s8`
+- Activate the detection: `hf detection enable -e1`
 
-| Command          | Arguments                                                                 | Description                               |
-|:----------------:|:-------------------------------------------------------------------------:|:-----------------------------------------:|
-| `hw factory_reset` | `--i-know-what-im-doing` (Make sure you really want to wipe your Chameleon) | Returns the Chameleon to factory settings |
-|                  |                                                                           |                                           |
-|                  |                                                                           |                                           |
+Now disconnect, go to a reader and swipe it a few times
+
+- Come back and connect to the CLI: `hw connect`
+- See if nonces were collected: `hf detection count`
+  - We need 2 nonces per key to recover
+- Recover the key(s) based on the collected nonces: `hf detection decrypt`. 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']
+
+```
+
+- To clean the logged detection nonces: `hf detection enable -e0` then `hf detection enable -e1`
+
+
+
+*More examples coming soon*

docs/firmware.md

@@ -102,6 +102,11 @@ The Chameleon also shows the following LED effects:
 
 The device enters sleep mode after about 5s unless it is plugged in USB or if a client is connected over BLE. You can use the buttons to wake it up again. You can also press quickly a button during the sleep animation to keep the device awake.
 
+## Write Modes
+- **Normal**: Behaves like any normal card
+- **Denied**: Read-only card, send NACK to write attempts
+- **Deceive**: Accepts write commands but don't change any data (reader thinks write was successful but when reading back, nothing changed)
+- **Shadow**: Accepts writes but reverts changes when device goes to sleep (reader can read and write like a normal card but changes are kept in RAM and are lost when the chameleon goes to sleep) 
 
 ## The SoftDevice
 

docs/gui.md

@@ -4,4 +4,4 @@ There are multiple GUIs to control your Chameleon, two are featured in this docu
 
 - [Chameleon Ultra GUI](./chameleonultragui.md) ([github](https://github.com/GameTec-live/ChameleonUltraGUI))
 
-- [MTools](https://shop.mtoolstec.com/mifare-classic-tool-for-ios)
+- [MTools for iOS](https://shop.mtoolstec.com/mifare-classic-tool-for-ios)

docs/modding.md

@@ -0,0 +1,4 @@
+# Third party moddings
+
+* [ChameleonUltra Keyring](https://www.printables.com/model/552739-chameleonultra-keyring), an extended frame for ChameleonUltra with a sturdy keyring loop.
+* [ChameleonUltra Wristband](https://www.thingiverse.com/thing:6153027), allows the user to wear the ChameleonUltra as a wristband.

docs/protocol.md

@@ -6,11 +6,18 @@
 
 The communication with the application is not the easiest but is structured as follows:
 
-`MAGIC BYTE(0x11) LRC(Magic Byte) COMMAND STATUS(0x00) DATA LRC(COMMAND + STATUS + DATA)`
-
-You build the Packet by first adding 0x11, this is the "Magic Byte" to say that there is something coming. This is followed by the LRC ([**L**ongitudinal **R**edundancy **C**heck](https://en.wikipedia.org/wiki/Longitudinal_redundancy_check)) of the "Magic Byte". Then you put in the command in [Big Endian](https://en.wikipedia.org/wiki/Endianness). Each command gets assigned a unique number (e.g. `factoryReset(1020)`), this is what you are sending to the device. Append the status, also in Big Endian. The status is always 0x00. Then you add your Data, this could be anything, for example sending the card keys when reading a block.
-
-For receiving, it is the exact same in reverse.
+![](images/protocol-packet.png)
+
+- **SOF**: `1 Byte`, the "Magic Byte" represent the start of a packet, must be `0x11`.
+- **LRC1**: `1 Byte`, the LRC ([**L**ongitudinal **R**edundancy **C**heck](https://en.wikipedia.org/wiki/Longitudinal_redundancy_check)) of the `SOF`, must be `0xEF`.
+- **CMD**: `2 Bytes` in unsigned [Big Endian](https://en.wikipedia.org/wiki/Endianness) format, each command have been assigned a unique number (e.g. `factoryReset(1020)`), this is what you are sending to the device.
+- **STATUS**: `2 Bytes` in unsigned [Big Endian](https://en.wikipedia.org/wiki/Endianness) format. If the direction is from APP to hardware, the status is always `0x0000`. If the direction is from hardware to APP, the status is the result of the command.
+- **LEN**: `2 Bytes` in unsigned [Big Endian](https://en.wikipedia.org/wiki/Endianness) format, the length of the data, maximum is `512`.
+- **LRC2**: `1 Byte`, the LRC ([**L**ongitudinal **R**edundancy **C**heck](https://en.wikipedia.org/wiki/Longitudinal_redundancy_check)) of the `CMD`, `STATUS` and `LEN`.
+- **DATA**: `LEN Bytes`, the data to send or receive, maximum is `512 Bytes`. This could be anything, for example you should sending key type, block number, and the card keys when reading a block.
+- **LRC3**: `1 Byte`, the LRC ([**L**ongitudinal **R**edundancy **C**heck](https://en.wikipedia.org/wiki/Longitudinal_redundancy_check)) of the `DATA`.
+
+The total length of the packet is `LEN + 10` Bytes. For receiving, it is the exact same format.
 
 ## Packet payloads
 

docs/quickstart.md

@@ -2,20 +2,17 @@
 
 Quickly get up and running with your Chameleon and no technical skill
 
-1. Download GUI
+1. Download any of those applications
 
-   - [Playstore ](https://play.google.com/store/apps/details?id=io.chameleon.ultra)/ [APK](https://nightly.link/GameTec-live/ChameleonUltraGUI/workflows/buildapp/main/apk.zip)
-
-   - [Windows](https://nightly.link/GameTec-live/ChameleonUltraGUI/workflows/buildapp/main/windows-installer.zip)
-
-   - [Linux](https://nightly.link/GameTec-live/ChameleonUltraGUI/workflows/buildapp/main/linux.zip)
-
-   - [IOS](https://apps.apple.com/at/app/mtools-ble-rfid-reader/id1531345398)(MTools)
+   - [ChameleonUltraGUI on Google Play](https://play.google.com/store/apps/details?id=io.chameleon.ultra) / [APK](https://nightly.link/GameTec-live/ChameleonUltraGUI/workflows/buildapp/main/apk.zip)
+   - [ChameleonUltraGUI on iOS](https://apps.apple.com/dk/app/chameleon-ultra-gui/id6462919364)
+   - [ChameleonUltraGUI on Windows](https://nightly.link/GameTec-live/ChameleonUltraGUI/workflows/buildapp/main/windows-installer.zip) ([or without installer](https://nightly.link/GameTec-live/ChameleonUltraGUI/workflows/buildapp/main/windows.zip))
+   - [ChameleonUltraGUI on Linux](https://nightly.link/GameTec-live/ChameleonUltraGUI/workflows/buildapp/main/linux.zip)
+   - [ChameleonUltraGUI on macOS](https://apps.apple.com/app/chameleon-ultra-gui/id6462919364)
+   - [MTools on iOS](https://apps.apple.com/app/mtools-ble-rfid-reader/id1531345398)
 
-2. Plug in or connect via Bluetooth your Chameleon
+2. Connect your Chameleon via USB or BLE
 
-3. Open GUI
+3. Open application
 
 4. Enjoy
-
-

docs/troubleshooting.md

@@ -1,12 +1,31 @@
 # Hardware
 
+## Difficulties to get emulation working properly
+
+Try with waking up the Chameleon by pressing a button before presenting it to the reader. Try with keeping some 2-3 cm distance to the reader.
+
 ## Difficulties to get the LF working properly
 
 The LF antenna is on a second PCB attached to the main PCB via little screws which also serve as electric connection.
-It has reported that on some devices the electric connection is not good, some glue or resin residues mai interfere.
+It has reported that on some devices the electric connection is not good, some glue or resin residues may interfere.
 You can try to dismantle very gently the screws and PCB, clean them and put them back in place.
 Be very careful the screws have been reported to be quite fragile so be gentle with them!
 
+# BLE
+
+## Difficulties connecting using BLE
+
+On Android make sure your location is turned, as that allows for scanning of bluetooth devices.
+
+## Difficulties to use BLE
+
+After BLE pairing, both the phone and ChameleonUltra will save a secret key for encrypted communication. If either party deletes the pairing record, it will result in communication failure. If Bluetooth cannot be connected, clearing the pairing information on the other side can solve the problem:
+
+* Find the Bluetooth settings in the phone's system settings and cancel pairing with the ChameleonUltra.
+* In the CLI of ChameleonUltra, execute the `hw ble bonds clear` command to clear all pairing records.
+
+Default BLE connect key(passkey) is `123456`
+
 # DFU
 
 ## Communication issues between CLI and Chameleon
@@ -54,5 +73,5 @@ pacman -S mingw-w64-x86_64-ninja --noconfirm
 
 ## InvalidException: Device unsupported cmd
 
-You need to update the firmware of you Chameleon.
+You need to update the firmware of your Chameleon.
 

firmware/application/src/app_cmd.c

@@ -233,23 +233,6 @@ data_frame_tx_t *cmd_processor_mf1_darkside_acquire(uint16_t cmd, uint16_t statu
     return data_frame_make(cmd, status, length, data);
 }
 
-data_frame_tx_t *cmd_processor_detect_nested_dist(uint16_t cmd, uint16_t status, uint16_t length, uint8_t *data) {
-    NestedDist nd;
-    if (length == 8) {
-        status = nested_distance_detect(data[1], data[0], &data[2], &nd);
-        if (status == HF_TAG_OK) {
-            length = sizeof(NestedDist);
-            data = (uint8_t *)(&nd);
-        } else {
-            length = 0;
-        }
-    } else {
-        status = STATUS_PAR_ERR;
-        length = 0;
-    }
-    return data_frame_make(cmd, status, 0, NULL);
-}
-
 data_frame_tx_t *cmd_processor_mf1_nt_distance(uint16_t cmd, uint16_t status, uint16_t length, uint8_t *data) {
     NestedDist nd;
     if (length == 8) {