README.md 4.21 KB
Newer Older
1
![NexMon logo](https://github.com/seemoo-lab/bcm-public/raw/master/logo/nexmon-logo-color.png)
Daniel Wegemer's avatar
Daniel Wegemer committed
2

3
## What is NexMon?
Daniel Wegemer's avatar
Daniel Wegemer committed
4

Daniel Wegemer's avatar
Daniel Wegemer committed
5
NexMon is a firmware patching framework for the BCM4339 WiFi firmware of Nexus 5 smartphones. It's main intension was to enable monitor mode and frame injection, which is already working quite well. Nevertheless, we also publish many example patches that allow to dive into firmware reverse engineering and firmware patching. Especially, the ability to write firmware patches in C makes it easy to use, also for beginners.
Daniel Wegemer's avatar
Daniel Wegemer committed
6

7
If you only intend to activate monitor mode on a device using the bcmdhd driver, take a look at the following commit: [ed11c18](https://github.com/seemoo-lab/bcm-public/commit/ed11c18aa89cd0374a3ce7655337cc0e4d1cdd0a)
Matthias Schulz's avatar
Matthias Schulz committed
8

Matthias Schulz's avatar
Matthias Schulz committed
9
10
## News

11
* We moved to **[GitHub!](https://github.com/seemoo-lab/bcm-public)**
12
* You can now follow us on twitter: [@nexmon_dev](https://twitter.com/nexmon_dev)
Matthias Schulz's avatar
Matthias Schulz committed
13

14
## Related Projects
15
* Monitor Mode for the Raspberry Pi 3: [rpi3.nexmon.org](http://rpi3.nexmon.org)
16

Matthias Schulz's avatar
Matthias Schulz committed
17
18
19
20
## WARNING

Our software may damage your hardware and may void your hardware’s warranty! You use our tools at your own risk and responsibility! If you don't like these terms, don't use nexmon!

Daniel Wegemer's avatar
Daniel Wegemer committed
21
22
23
24
25
## What this Repo contains

* A bootable boot ROM for Android
* Everything needed to build the ROM by yourself

26
27
28
## Requirements

* Nexus 5 with bcm4339 chipset
Matthias Schulz's avatar
Matthias Schulz committed
29
* Your bootloader needs to be unlocked (no root required)
30
31
32
* Android 6.0 or 6.0.1
* Android Tools (adb + fastboot)

Matthias Schulz's avatar
Matthias Schulz committed
33
34
35
36
37
### To build your own patches

* Xubuntu 14.04.4 64-Bit (do not use a different version to avoid compilation problems)
* set the environment variable `NDK_ROOT` to an installation of android-ndk-r11c (using exactly this version allows to build all tools without problems)

38
39
## Steps needed to run the boot.img on your phone

40
* Download the [boot.img](https://github.com/seemoo-lab/bcm-public/raw/master/boot.img) (this project is still in heavy development, the monitor mode should work on the boot.img in this commit though: [2c39825](https://github.com/seemoo-lab/bcm-public/raw/2c3982518c89eb9580f868b2337c944d8405bf4a/boot.img))
41
42
43
44
45
* `adb reboot bootloader`
* `fastboot boot boot.img`
  * without the `flash` parameter, this boot image will be reset to the previous one on the next reboot
* `fastboot reboot`
* `adb shell`
Matthias Schulz's avatar
Matthias Schulz committed
46
* `su`
47
* `insmod /nexmon/bcmdhd.ko`
48
* `ifconfig wlan0 up`
49
* `nexutil -m true` this tells the firmware to activate monitor mode
Matthias Schulz's avatar
Matthias Schulz committed
50
51
* do whatever you want, e.g. run tcpdump: `/nexmon/bin/tcpdump -i wlan0 -s0`

52
53
54
55
56
## Steps to build your own boot.img
* `source setup_env.sh`
* `make cleanboot`
* `make boot.img`

Daniel Wegemer's avatar
Daniel Wegemer committed
57
## Steps to create your own firmware patches
58
* see the [firmware patching folder](https://github.com/seemoo-lab/bcm-public/tree/master/firmware_patching)
Daniel Wegemer's avatar
Daniel Wegemer committed
59

60
## Caveats
61
* ~~The current patch is unable to handle aggregated frames (A-MSDU's). This makes it impossible to receive frames in an 802.11n/802.11ac enabled environment.~~
Daniel Wegemer's avatar
Daniel Wegemer committed
62
 * Current Monitor Mode was tested and works for 802.11n with 20MHz wide channels (2.4 as well as 5GHz), ~~40MHz channels seems to be a problem. We keep working on it ;-)~~
63
 * Using this [patch](https://github.com/seemoo-lab/bcm-public/blob/90bed6e1c3ad70ddc23ccf44033b152e0db300b6/kernel_patches/40mhz_channels_5GHz.patch) should enalbe `iw` to set 40MHz channels. It currently only works for 5GHz frequencies. 
Daniel Wegemer's avatar
Daniel Wegemer committed
64
   Capturing WiFi packets which use mutliple spatial streams is still not possible, this is caused by a hardware limitation of the Nexus 5
65

Matthias Schulz's avatar
Matthias Schulz committed
66
## Read our papers
Matthias Schulz's avatar
Matthias Schulz committed
67

Matthias Schulz's avatar
Matthias Schulz committed
68
69
70
71
Feel free to read and reference our papers on the development of this project 

* M. Schulz, D. Wegemer and M. Hollick. [NexMon: A Cookbook for Firmware 
Modifications on Smartphones to Enable Monitor Mode]
Matthias Schulz's avatar
Matthias Schulz committed
72
(http://arxiv.org/abs/1601.07077), CoRR, vol. abs/1601.07077, December 2015. 
Matthias Schulz's avatar
Matthias Schulz committed
73
[bibtex](http://dblp.uni-trier.de/rec/bibtex/journals/corr/SchulzWH16)
Matthias Schulz's avatar
Matthias Schulz committed
74
* M. Schulz, D. Wegemer, M. Hollick. [DEMO: Using NexMon, the C-based WiFi 
Matthias Schulz's avatar
Matthias Schulz committed
75
76
77
firmware modification framework](https://dl.acm.org/citation.cfm?id=2942419), 
Proceedings of the 9th ACM Conference on Security and Privacy in Wireless and 
Mobile Networks, WiSec 2016, July 2016.
Daniel Wegemer's avatar
Daniel Wegemer committed
78
79
80

## Contact

Matthias Schulz's avatar
Matthias Schulz committed
81
82
* [Matthias Schulz](https://seemoo.tu-darmstadt.de/mschulz) <mschulz@seemoo.tu-darmstadt.de>
* Daniel Wegemer <dwegemer@seemoo.tu-darmstadt.de>