master
Jeff Moe
3 years ago
commit
ee18b4fa97
@ -0,0 +1,84 @@
|
||||
Here's how to install new firmware on a USG without using a JTAG adapter, using the built-in DFU (Device Firmware Upgrade) protocol.
|
||||
|
||||
_**Security notice:**_ This upgrade process uses a DFU bootloader [built into the USG's microcontrollers](http://www.st.com/content/ccc/resource/technical/document/application_note/b9/9b/16/3a/12/1e/40/0c/CD00167594.pdf/files/CD00167594.pdf/jcr:content/translations/en.CD00167594.pdf) by the manufacturer, [ST Microelectronics](http://www.st.com). There is a remote chance that this bootloader (or the DFU upgrade software) is malicious, so do not perform this firmware upgrade on a sensitive computer.
|
||||
|
||||
However, do run this upgrade on a _clean_ computer. You don't want any nasties sneaking into your USG!
|
||||
|
||||
## You will need...
|
||||
One "USB A male to male" cable. It should look [like this](https://www.jaycar.co.nz/0-5m-usb-2-0-a-male-to-a-male-lead/p/WC7707), with **a plug at both ends**. You can [find them on Ebay](http://www.ebay.com/sch/i.html?_sacat=0&_nkw=usb+a+male+to+male&_frs=1) or your favorite local website. This cable is required to program the downstream half of the USG. The upstream side connects through the regular USB A-type plug or cable.
|
||||
|
||||
And one of the following DFU programmers:
|
||||
|
||||
1. **_Recommended:_ [dfu-util](http://dfu-util.sourceforge.net/)**. Linux version available from major distribution repositories, Windows version from the [releases page](http://dfu-util.sourceforge.net/releases/), Mac version via [Homebrew](http://brew.sh/) ("brew install dfu-util") or from [MacPorts](http://www.macports.org/).
|
||||
|
||||
2. [ST's DfuSe programmer](http://www.st.com/content/st_com/en/products/development-tools/software-development-tools/stm32-software-development-tools/stm32-programmers/stsw-stm32080.html). This is a Windows-only application, and free registration is required to download. I have not tested this option!
|
||||
|
||||
## Download and Verify Firmware
|
||||
Find the firmware you want on the [releases page](https://github.com/robertfisk/USG/releases). Make sure you choose the correct release for your hardware: v0.9 or v1.0. Download the two .bin files (upstream and downstream) attached to the release.
|
||||
|
||||
As a minimal check, verify the firmware's sha256sums against the release notes:
|
||||
|
||||
> sha256sum *.bin
|
||||
>
|
||||
> xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx Downstream_X.XrXX.bin
|
||||
> yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy Upstream_X.XrXX.bin
|
||||
|
||||
...where the filenames "X.XrXX" contain the hardware revision and release number.
|
||||
|
||||
Ideally, you should [verify the sha256sums against the git tag](https://git-scm.com/book/en/v2/Git-Tools-Signing-Your-Work#Verifying-Tags) signed by [the developer's PGP key](https://sks-keyservers.net/pks/lookup?op=vindex&search=0xDEB95AC015ADAEBA)!
|
||||
|
||||
## Enter DFU mode - DIY v0.9 Hardware
|
||||
|
||||
#### Upstream H405 board:
|
||||
Change the "BOOT0" jumper from low "L" to high "H" with a soldering iron. Connect the H405 board to your computer with the regular USB cable.
|
||||
|
||||
|
||||
|
||||
#### Downstream H407 board:
|
||||
|
||||
Change the "BOOT0" jumper from "0" to "1". Connect the H407 to your computer with your new male-male USB cable.
|
||||
|
||||
**However** this will not supply power to the board, so *also* connect the Upstream board with the regular USB cable to provide 5V power.
|
||||
|
||||
**However (however)** if Upstream (the H405) is still in DFU mode (BOOT0 set to "H") you now have two DFU devices and much confusion about which one you should be programming. So either change Upstream's BOOT0 back to "L", or provide power through a 5V cellphone charger instead of your computer.
|
||||
|
||||
|
||||
|
||||
Don't forget to change BOOT0 back to the "L" or "0" position when you're done!
|
||||
|
||||
## Enter DFU mode - v1.0 Hardware
|
||||
|
||||
Open the case with a blunt knife or other flat instrument:
|
||||
|
||||
|
||||
|
||||
Hold down the blue "BOOT_USB" button while connecting the USG to your computer, then release the button. To program the Upstream processor, connect the USG directly. To program the Downstream processor, use your new male-male USB cable.
|
||||
|
||||
|
||||
|
||||
## Program the Firmware
|
||||
Confirm that you have one DFU device attached to your computer:
|
||||
> sudo dfu-util -l
|
||||
|
||||
You should see four internal regions of one device:
|
||||
> Found DFU: [0483:df11] ver=2200, devnum=4, cfg=1, intf=0, path="2-1", alt=3, name="@Device Feature/0xFFFF0000/01*004 e", serial="xxxxxxxxxxxxxx"
|
||||
> Found DFU: [0483:df11] ver=2200, devnum=4, cfg=1, intf=0, path="2-1", alt=2, name="@OTP Memory /0x1FFF7800/01*512 e,01*016 e", serial="xxxxxxxxxxxxxx"
|
||||
> Found DFU: [0483:df11] ver=2200, devnum=4, cfg=1, intf=0, path="2-1", alt=1, name="@Option Bytes /0x1FFFC000/01*016 e", serial="xxxxxxxxxxxxxx"
|
||||
> Found DFU: [0483:df11] ver=2200, devnum=4, cfg=1, intf=0, path="2-1", alt=0, name="@Internal Flash /0x08000000/04*016Kg,01*064Kg,07*128Kg", serial="xxxxxxxxxxxxxx"
|
||||
|
||||
Program the firmware (choose Upstream_X.XrXX.bin or Downstream_X.XrXX.bin as appropriate):
|
||||
> sudo dfu-util -a 0 -s 0x08000000 -D Upstream_X.XrXX.bin
|
||||
|
||||
...where "-a 0" means alternate region 0 (internal flash), and 0x0800000 is the start address of flash memory. You should see a successful transfer:
|
||||
> ...
|
||||
> DFU mode device DFU version 011a
|
||||
> Device returned transfer size 2048
|
||||
> DfuSe interface name: "Internal Flash "
|
||||
> Downloading to address = 0x08000000, size = 32962
|
||||
> Download [=========================] 100% 32962 bytes
|
||||
> Download done.
|
||||
> File downloaded successfully
|
||||
|
||||
Then disconnect the USG, and repeat the operation on the other side. Remember to switch jumpers or press the "BOOT_USB" button as appropriate to enter DFU mode.
|
||||
|
||||
When programming DIY v0.9 hardware, don't forget to change BOOT0 back to the "L" or "0" position when you're done!
|
||||
@ -0,0 +1,47 @@
|
||||
The USG firmware supports mass storage devices, keyboards and mice, as well as different options for each device type. You can customize your firmware build using the options below. Because the v1.0 hardware has no user-controllable switches, this configuration must be done at compile-time. This means you will need to have a [firmware development environment](https://github.com/robertfisk/USG/wiki/Firmware-Development-Environment) set up.
|
||||
|
||||
The build configuration is stored in these files:
|
||||
|
||||
* [Upstream/Inc/build_config.h](https://github.com/robertfisk/USG/blob/USG_1.0/Upstream/Inc/build_config.h)
|
||||
* [Downstream/Inc/build_config.h](https://github.com/robertfisk/USG/blob/USG_1.0/Downstream/Inc/build_config.h)
|
||||
|
||||
Remember to set the same options in both Upstream and Downstream. See [this comment](https://github.com/robertfisk/USG/issues/3#issuecomment-286888048) for the reasons why.
|
||||
|
||||
### Device Support Options
|
||||
Comment out any devices you don't want to support.
|
||||
|
||||
```
|
||||
#define CONFIG_MASS_STORAGE_ENABLED
|
||||
#define CONFIG_KEYBOARD_ENABLED
|
||||
#define CONFIG_MOUSE_ENABLED
|
||||
```
|
||||
|
||||
### Read-Only Mode
|
||||
Comment out this option if you want to disable writes to mass storage devices.
|
||||
|
||||
```
|
||||
#define CONFIG_MASS_STORAGE_WRITES_PERMITTED
|
||||
```
|
||||
|
||||
### Read/Write indication on LEDs
|
||||
Comment out this option if you don't want the fault LEDs to rapid-blink during reads and writes to mass storage. Or change the length of time they blink after a read or write event. The default is 3 seconds (3000 ms).
|
||||
|
||||
Downstream blinks for reads, and Upstream blinks for writes.
|
||||
|
||||
```
|
||||
#define CONFIG_READ_FLASH_TIME_MS 3000
|
||||
|
||||
#define CONFIG_WRITE_FLASH_TIME_MS 3000
|
||||
```
|
||||
|
||||
### HID Bot Detection
|
||||
This option is a defense against [type 3 bad USB attacks](https://github.com/robertfisk/USG/wiki/Technical-Details-for-the-Curious#type-3-attacks-evil-functionality-in-plain-sight). It measures the randomness of inputs arriving from keyboards and mice to determine whether the user is a genuine human or a bot.
|
||||
|
||||
Bot detection is performed in the Upstream processor, so make these changes in Upstream's build_config.h.
|
||||
|
||||
```
|
||||
#define CONFIG_KEYBOARD_BOT_DETECT_ENABLED
|
||||
#define CONFIG_MOUSE_BOT_DETECT_ENABLED
|
||||
```
|
||||
|
||||
The bot detection algorithms can be tuned by adjusting KEYBOARD_BOTDETECT_ and MOUSE_BOTDETECT_ parameters if required.
|
||||
@ -0,0 +1,18 @@
|
||||
This page will help you install and configure a development environment for the USG's firmware. By now you should have a [JTAG connection](https://github.com/robertfisk/USG/wiki/JTAG-Connection) ready.
|
||||
|
||||
Note: The instructions below are written with minimal testing. I may have forgotten something!
|
||||
|
||||
## Install firmware development environment
|
||||
1. Follow the excellent documentation to [install GNU MCU Eclipse](https://gnu-mcu-eclipse.github.io/install/). You will need the ARM Toolchain, Windows Build Tools if you run Windows, OpenOCD, Eclipse CDT, and the GNU ARM Eclipse plugins. And finally set up a new workspace according to the instructions.
|
||||
|
||||
2. Clone the USG repository, and make sure you checkout the correct branch. Use the USG_0.9 branch if you have made your own v0.9 hardware, or the USG_1.0 branch if you have purchased v1.0 hardware.
|
||||
|
||||
3. Import the Upstream and Downstream folders into your Eclipse workspace. Because the USG reverses the USB paradigm of a host being 'higher' than a device, 'Upstream' refers to the processor connecting to your host computer, and 'Downstream' refers to the processor connecting to your attached USB device.
|
||||
|
||||
## Build it
|
||||
On the Eclipse toolbar next to the 'Build' hammer, from the drop-down menu choose either the Debug or Release build configuration. Since you went to the trouble of setting up a JTAG connection I'm going to assume you will be debugging the firmware, so you should probably choose the Debug configuration. The project should then build. This is where you find out if you configured your tools correctly, and whether I forgot something important!
|
||||
|
||||
## Load it
|
||||
Attach your JTAG debugger to each development board in turn, and from the debug menu choose "Upstream Debug" or "Downstream Debug" depending on which side of the USG you connect to. The firmware will be flashed permanently into the processors and you can start your debug session, or simply disconnect the debugger to run it standalone.
|
||||
|
||||
The USG has two LEDs, and you should see them flash once when the USG is powered on. If you see them do anything else, check [the LED page](https://github.com/robertfisk/USG/wiki/LED-Diagnostics) to decode what went wrong.
|
||||
@ -0,0 +1,53 @@
|
||||
While you can order pre-built USG hardware [[https://globotron.nz][from the online store]], the USG has been designed to allow anyone to build their own from readily available development boards.
|
||||
|
||||
** Build your own USG v0.9
|
||||
You will first need the following hardware directly from Olimex, or through Digikey (who usually ships quickly):
|
||||
- 1x STM32-H405 with USB device port: [[https://www.olimex.com/Products/ARM/ST/STM32-H405/][Olimex]] or [[http://www.digikey.co.nz/product-search/en/development-boards-kits-programmers/evaluation-boards-embedded-mcu-dsp/2621773?k=h405][Digikey]]
|
||||
- 1x STM32-H407 with USB host port: [[https://www.olimex.com/Products/ARM/ST/STM32-H407/][Olimex]] or [[http://www.digikey.co.nz/product-search/en/development-boards-kits-programmers/evaluation-boards-embedded-mcu-dsp/2621773?k=h407][Digikey]]
|
||||
|
||||
Other hardware:
|
||||
- 1x 0.1uF through-hole capacitor, ceramic or monolithic type
|
||||
- 20cm of 1mm diameter tinned copper wire
|
||||
- Wire cutters
|
||||
- Soldering iron, solder, and some soldering experience
|
||||
|
||||
For firmware development work:
|
||||
- 1x OpenOCD-compatible JTAG programmer, recommended: [[https://www.olimex.com/Products/ARM/JTAG/ARM-USB-TINY-H/][Olimex ARM-USB-TINY-H]], or via [[http://www.digikey.co.nz/products/en/development-boards-kits-programmers/programmers-emulators-and-debuggers/799?k=arm-usb-tiny-h][Digikey]]
|
||||
|
||||
If you don't want to develop firmware and only want to use the latest firmware image, you will need:
|
||||
- 1x USB A male to male cable. Check the [[https://github.com/robertfisk/USG/wiki/DFU-Firmware-Upgrade][DFU Firmware Upgrade]] page for more details.
|
||||
|
||||
*** Connections
|
||||
Your goal is to connect +5V, Gnd, and the SPI1 port of your two Olimex development boards together.
|
||||
|Signal name|MCU pinout|H405 pinout|H407 pinout|
|
||||
|-----------+----------+-----------+-----------|
|
||||
|+5V|-|EXT2-26|CON1 5V|
|
||||
|GND|-|EXT2-6|CON1 GND|
|
||||
|GND2|-|EXT1-6|CON4 GND|
|
||||
|nTX_OK|PA3|EXT2-10|CON3 D0|
|
||||
|SPI1_nSS|PA4|EXT2-11|CON4 D10|
|
||||
|SPI1_SCK|PA5|EXT1-18|CON4 D13|
|
||||
|SPI1_MISO|PA6|EXT1-14|CON4 D12|
|
||||
|SPI1_MOSI|PA7|EXT1-22|CON4 D11|
|
||||
|
||||
Here is the same information in pictures:
|
||||
|
||||
[[https://github.com/robertfisk/USG/blob/USG_0.9/Doc_images/STM32-H405%20pinouts.jpg]]
|
||||
[[https://github.com/robertfisk/USG/blob/USG_0.9/Doc_images/STM32-H407%20pinouts.jpg]]
|
||||
|
||||
Position the H405 board (smaller) on top of the H407 board (larger) with the USB connectors facing in opposite directions. Use the 1mm tinned copper wire to link the boards together. When all required connections are in place the wire will provide adequate mechanical support.
|
||||
|
||||
The H407 board comes with handy rubber feet, but be aware they require some determined twisting to insert. When you are done you should have something like this:
|
||||
|
||||
[[https://github.com/robertfisk/USG/blob/USG_0.9/Doc_images/USGv0.9%201.JPG]]
|
||||
[[https://github.com/robertfisk/USG/blob/USG_0.9/Doc_images/USGv0.9%202.JPG]]
|
||||
|
||||
|
||||
*** Bugfix the H405 board
|
||||
Under heavy use, the H405 board will occasionally glitch out and your USG will crash. To fix this you need to add a 0.1uF filter capacitor to the CPU's reset line. The easiest way to do so is by soldering it across the pins of the reset button, as below.
|
||||
|
||||
[[https://github.com/robertfisk/USG/blob/USG_0.9/Doc_images/H405_reset_cap.jpg]]
|
||||
|
||||
|
||||
*** Next steps
|
||||
Either set up your [[https://github.com/robertfisk/USG/wiki/JTAG-Connection][JTAG Connection]], or load in the latest firmware [[https://github.com/robertfisk/USG/wiki/DFU-Firmware-Upgrade][via DFU]].
|
||||
@ -0,0 +1,141 @@
|
||||
# The USG is Good, not Bad
|
||||
The USG is a firewall for your USB ports. It connects between your computer and an untrusted USB device, isolating the badness with an internal hardware firewall.
|
||||
|
||||
|
||||
|
||||
## Why should I use a USG?
|
||||
Say you just bought yourself a shiny new USB flash drive. You rip it out of the packaging and plug it straight into your computer. Oops, big mistake!
|
||||
|
||||
* Do you know who developed your flash drive's firmware? (It's probably not the company name printed on the packaging)
|
||||
* Has the firmware been audited for backdoors and malicious functionality?
|
||||
* Can you confirm that the firmware running on your drive hasn't been maliciously modified during or after manufacture?
|
||||
|
||||
If you can't answer 'yes' to all these questions, you should not trust that shiny new flash drive. Plugging it in gives full control of your computer to whoever wrote your drives' firmware.
|
||||
|
||||
The USG isolates [BadUSB](https://srlabs.de/badusb/) devices from your computer, while still passing through the data you need. The USG's firmware is fully open and auditable, so you can trust it. And when you use a USG, you no longer have to trust the opaque firmware of dubious origin running on every USB device you own.
|
||||
|
||||
## Antivirus will not save you
|
||||
Antivirus scanners cannot detect BadUSB because there is no virus to detect. Malicious USB commands reach directly into your USB driver stack, exploiting your computer before file-based scanners realise anything happened.
|
||||
|
||||
You can protect yourself from BadUSB by using virtualised operating systems such as [Qubes](https://www.qubes-os.org). But the USG is the only plug-and-play BadUSB protection that does not require you to switch operating systems. It can even protect your legacy and embedded systems running out-of-date software.
|
||||
|
||||
## You should be using a USG if...
|
||||
* You care about the security of your computer, and you connect USB devices to it.
|
||||
* You use [Qubes OS](https://www.qubes-os.org) with [Anti Evil Maid](https://www.qubes-os.org/doc/anti-evil-maid/) on an external flash drive.
|
||||
* You connect USB devices to embedded systems ([network switches](https://tools.cisco.com/security/center/content/CiscoSecurityAdvisory/cisco-sa-20151204-nexus), [medical equipment](https://www.wired.com/2014/04/hospital-equipment-vulnerable/), [uranium enrichment facilities...](http://arstechnica.com/tech-policy/2011/07/how-digital-detectives-deciphered-stuxnet-the-most-menacing-malware-in-history/))
|
||||
|
||||
## Supported Devices
|
||||
The USG's firmware supports the following devices, at USB 1 speeds (12Mbps).
|
||||
* Mass Storage - Flash drives and hard drives, 512byte sectors and 2TB max
|
||||
* Mice - 4 buttons with scroll wheel
|
||||
* Keyboards - 101 keys
|
||||
|
||||
## Get your own USG
|
||||
The USG v1.0 is available now from the [online store.](https://globotron.nz/)
|
||||
|
||||
You can also [build your own USG v0.9](https://github.com/robertfisk/USG/wiki/Hardware-(DIY-v0.9)) from off-the-shelf development boards. Some assembly required.
|
||||
|
||||
|
||||
|
||||
## Need More Speed?
|
||||
The USG is performance-limited due to its USB 1 hardware. If you need to transfer large files from flash drives and hard drives, you need [the Armadillo](https://globotron.nz/products/armadillo-hardware-usb-firewall) instead. Based on the USG's proven open-source technology, the Armadillo is a next-gen device operating at USB 2.0 speed. Available exclusively through the [online store.](https://globotron.nz/products/armadillo-hardware-usb-firewall)
|
||||
|
||||
|
||||
|
||||
## Made in New Zealand
|
||||
The USG is designed and assembled in New Zealand by a specialist in electronics, firmware, and secure technologies. To protect the integrity of this project the USG is manufactured locally, and production will never be outsourced to another country.
|
||||
|
||||
As the USG firmware is open source, you do not need to trust the pre-loaded firmware. The truly paranoid are welcome to build their own firmware from one of the [tagged releases.](https://github.com/robertfisk/USG/tags)
|
||||
|
||||
Contact [the USG's developer](mailto:info@globotron.nz) if you need to customize the USG for a particular application. The developer is also available on a consultancy basis for other embedded or security-focused development work.
|
||||
|
||||
## More Info
|
||||
[**Technical Details for the Curious**](https://github.com/robertfisk/USG/wiki/Technical-Details-for-the-Curious)
|
||||
|
||||
[**Firmware Development Environment**](https://github.com/robertfisk/USG/wiki/Firmware-Development-Environment)
|
||||
|
||||
[**LED Diagnostics**](https://github.com/robertfisk/USG/wiki/LED-Diagnostics)
|
||||
|
||||
# FAQ
|
||||
|
||||
### **Q.** What devices does the USG support?
|
||||
|
||||
**A.** The USG supports mass storage (flash drives), keyboards, and mice. Future firmware revisions may add extra devices and other goodies.
|
||||
|
||||
### **Q.** The USG doesn't support my device. What should I do?
|
||||
|
||||
**A.** Of course the safest course of action is to not use that device! A more realistic suggestion is to use a virtualized operating system that isolates the untrusted USB device inside a sacrificial virtual machine. [Qubes](http://www.qubes-os.org) is a good choice for those familiar with Linux.
|
||||
|
||||
### **Q.** How fast is the USG?
|
||||
|
||||
**A.** The USG uses 12Mbps hardware, so your mass storage transfers will run at around 1MByte per second.
|
||||
|
||||
If you need more speed for large file transfers, you need the Armadillo next-gen USB 2.0 firewall, available exclusively through the [online store.](https://globotron.nz/products/armadillo-hardware-usb-firewall)
|
||||
|
||||
### **Q.** What operating systems does the USG support?
|
||||
|
||||
**A.** Everything! Besides Windows, Mac OS, and Linux, embedded systems with USB ports are also likely vulnerable to BadUSB, so you should use a USG with them as well.
|
||||
|
||||
### **Q.** Can I use a hub with the USG?
|
||||
|
||||
**A.** The USG does not support hubs on it's downstream (device) side, for a very good reason. A malicious USB device can hide a hub inside itself to connect a second function, which can then do unexpected bad things to your computer. Read the [Technical Details](https://github.com/robertfisk/USG/wiki/Technical-Details-for-the-Curious#type-2-attacks-hidden-evil-functionality) page for more info.
|
||||
|
||||
So the rule is one USG, one USB device.
|
||||
|
||||
Note that you can use hubs on the USG's upstream (computer) side. However this does come with a security risk, as that hub can also be programmed as a BadUSB and attack your computer. Think twice before using a hub, particularly one that has been attached to other computers.
|
||||
|
||||
### **Q.** I have more USB devices than USGs to protect them with. Which device should I protect first?
|
||||
|
||||
**A.** You should prioritize devices that frequently move between computers, such as flash drives.
|
||||
|
||||
The USG can protect your secure computers from attacks from a bad device. It can also protect your device from attacks from infected computers (see [this question](https://github.com/robertfisk/USG/wiki/FAQ/#q-can-the-usg-protect-the-firmware-on-my-device-from-a-malicious-host-computer)). A good idea is to permanently attach your USG to a flash drive, to ensure both your device and your computers are always protected.
|
||||
|
||||
USB devices that stay in one place such as mice and keyboards are a lower risk than devices that move around. However the paranoid should protect every device attached to their computer, as any programmable device can persist a malware infection across operating system reinstallations.
|
||||
|
||||
### **Q.** Can the USG protect me from the [USB Killer](https://www.usbkill.com/)?
|
||||
|
||||
**A.** The USG was not designed to resist physical overvoltage attacks because they are obvious and easily contained. The information in your computer is more valuable than your computer itself, and the USG defends you against attacks that compromise your information.
|
||||
|
||||
But having said that, the USG will provide some protection. The voltage surge will pass through and damage two microprocessors and two ESD surge suppressors before it reaches your computer. The USG's circuits will be destroyed, but the voltage surge will probably be reduced to a safe level at your computer's port. If anyone does perform this test, you are welcome to tell me the result!
|
||||
|
||||
### **Q.** I'm super paranoid. Can I disable support for some types of USB device?
|
||||
|
||||
**A.** Yes you certainly can. This configuration currently needs to be done at firmware compile time. You can even make the USG a read-only storage device. See the instructions for setting [firmware build options.](https://github.com/robertfisk/USG/wiki/Firmware-Build-Options)
|
||||
|
||||
### **Q.** Can the USG protect the firmware on my device from a malicious host computer?
|
||||
|
||||
**A.** Yes! The USG uses two processors to create a bi-directional firewall, and only a restricted set of commands are allowed to pass through. So a malicious host cannot alter a USB device's firmware.
|
||||
|
||||
### **Q.** Can a malicious device or computer attack the USG?
|
||||
|
||||
**A.** Totally. The USG's firmware is as vulnerable as any other USB device out there. But the key point is that an infection cannot jump across the USG's internal firewall, so the other side of the USG is safe.
|
||||
|
||||
Furthermore any infection cannot persist between restarts, because writes to internal flash memory are disabled on startup. So when you reinsert your USG to a different computer or to use a different device, you are starting from a clean state every time.
|
||||
|
||||
### **Q.** What if a malicious entity intercepts my parcel and programs bad firmware into my USG?
|
||||
|
||||
**A.** You can load your own firmware into the USG before you use it. See the [DFU Firmware Upgrade](https://github.com/robertfisk/USG/wiki/DFU-Firmware-Upgrade) page for details. The truly paranoid are welcome to build their own firmware from one of the [tagged releases.](https://github.com/robertfisk/USG/tags)
|
||||
|
||||
### **Q.** If I can't trust USB devices, why should I trust your USG?
|
||||
|
||||
**A.** I'm glad you asked! By day I am an electronic engineer, and for years I have provided technical assistance to practitioners of [Falun Dafa,](http://www.faluninfo.net/) who regularly face computer attacks from [agents of the Chinese Communist Party](http://www.theepochtimes.com/n3/847520-why-the-ccp-keeps-hacking-epoch-times/).
|
||||
|
||||
The USG has 'Good' in its name for a reason. It is my way of protecting computer users against a class of attack that they currently have no defense for. It is particularly useful for individuals and organizations that face advanced threats including corporate espionage or state sponsored attacks.
|
||||
|
||||
I've put a **lot** of time and energy into this project, with the hope that more people can use it to keep themselves safe.
|
||||
|
||||
### **Q.** If I use a USG, is my computer 100% safe?
|
||||
|
||||
**A.** The USG protects you against low-level USB attacks from devices including flash drives. But it cannot protect you from viruses stored inside the drive's file system, as this is a higher software layer above the USB bus.
|
||||
|
||||
You should consider hardening your operating system, or use virtualization to isolate attacks inside a sacrificial virtual machine. Try [Qubes.](http://www.qubes-os.org)
|
||||
|
||||
### **Q.** Does it have a red flashing light to tell me when a USB device is bad?
|
||||
|
||||
**A.** No*. It is not possible to determine whether a USB device is good or bad. A bad device may 'act good' for days or weeks before launching an attack. A bad device may also use host profiling to determine whether it is connected to a vulnerable host (your computer) or not (your USG), and alter its behavior accordingly.
|
||||
|
||||
*Actually yes. The USG does have flashing error LEDs. But they can only tell you that something has gone wrong, due to buggy devices or problems with the USG's firmware. They cannot tell you with any certainty whether a BadUSB attack has been attempted. The good news is that whatever the cause of a fault, the USG will immediately shut down and disconnect itself from your computer before flashing the error LEDs. Read more about the [LED fault codes here.](https://github.com/robertfisk/USG/wiki/LED-Diagnostics)
|
||||
|
||||
If you have a device that consistently causes the USG to error out, **don't** bypass the USG and connect it directly to your computer. That would defeat the purpose of the USG! Find another USB device to perform the same function.
|
||||
|
||||
|
||||
@ -0,0 +1,27 @@
|
||||
This page shows you how to connect a JTAG adapter so you can develop or debug the USG's firmware. If you only want to install the latest firmware version, head over to the [DFU Firmware Upgrade](https://github.com/robertfisk/USG/wiki/DFU-Firmware-Upgrade) page to do it directly over USB.
|
||||
|
||||
## DIY v0.9 Hardware
|
||||
Simply order an Olimex ARM-USB-TINY-H programmer from [Olimex](https://www.olimex.com/Products/ARM/JTAG/ARM-USB-TINY-H/) or [Digikey](http://www.digikey.co.nz/products/en/development-boards-kits-programmers/programmers-emulators-and-debuggers/799?k=arm-usb-tiny-h) when you buy your development boards. Other OpenOCD-compatible programmers with a standard ARM JTAG 2x10 pin connection will also work.
|
||||
|
||||
Connect the programmer's cable to either the Upstream or Downstream board as required. The programmer will provide 5v power to the target board if USB is not connected.
|
||||
|
||||
|
||||
|
||||
## v1.0 Hardware
|
||||
You will need the following:
|
||||
* Olimex ARM-USB-TINY-H programmer from [Olimex](https://www.olimex.com/Products/ARM/JTAG/ARM-USB-TINY-H/) or [Digikey](http://www.digikey.co.nz/products/en/development-boards-kits-programmers/programmers-emulators-and-debuggers/799?k=arm-usb-tiny-h) (or other compatible programmer).
|
||||
* Olimex ARM-JTAG-20-10 adapter from [Olimex](https://www.olimex.com/Products/ARM/JTAG/ARM-JTAG-20-10/) or [Digikey](http://www.digikey.co.nz/product-detail/en/olimex-ltd/ARM-JTAG-20-10/1188-1016-ND/3471401).
|
||||
* 2x5 pin 0.05" through-hole header such as [this one from Digikey](http://www.digikey.co.nz/product-detail/en/amphenol-fci/20021111-00010T4LF/609-3712-ND/2209072). Mention you want to develop with JTAG when you order your USG, and I will add one to your order!
|
||||
|
||||
Open the USG's case with a blunt knife or other flat tool.
|
||||
|
||||
|
||||
|
||||
Insert the 2x5 pin header into the end of the JTAG cable (the long-pin side), then press the cable end down onto the USG's circuit board. Choose the Upstream or Downstream side as required. This JTAG connector does not power the board, so you will have to connect to a computer or USB power source in order to load firmware.
|
||||
|
||||
|
||||
|
||||
|
||||
## Next Steps
|
||||
Head to the [firmware page](https://github.com/robertfisk/USG/wiki/Firmware-Development-Environment) to get developing and debugging!
|
||||
|
||||
@ -0,0 +1,21 @@
|
||||
Each USG has two indicator LEDs. The colour and position of these LEDs varies between versions.
|
||||
|
||||
*USG v0.9:* Each Olimex development board has a green 'Status' LED near the USB connector.
|
||||
|
||||
*USG v1.0:* Both LEDs are positioned beside the USB socket. The downstream LED is yellow, and the upstream LED is red.
|
||||
|
||||
*** Normal Operation
|
||||
You should see both LEDs flash briefly when you apply power to the USG. They will also rapid-blink during mass storage access, Downstream (yellow) for reads and Upstream (red) for writes.
|
||||
|
||||
*** Error Conditions
|
||||
Each microcontroller (MCU) controls one fault LED, and a problem may occur with either or both of them. Find the problem with the help of this handy troubleshooting chart.
|
||||
|
||||
|LED doing this...|...means this|Try this fix:|
|
||||
|-+-+-+
|
||||
|One or both LEDs fail to blink when USG powered on|No power, unprogrammed MCU, or faulty hardware|Check your host has power. The corresponding MCU may be unprogrammed, or the circuit board may be faulty.|
|
||||
|One or both LEDs stays lit when USG powered on|Incorrect firmware version|Firmware designed for a different USG hardware revision is loaded into the MCU, so check you are building from the correct Git branch. This can also be caused by loading Upstream's firmware into the Downstream MCU, or vice versa.|
|
||||
|One or both LEDs rapidly blink (25Hz)|Mass storage access|Downstream (yellow) blinks on reads, Upstream (red) blinks on writes. Configure your firmware options [[https://github.com/robertfisk/USG/wiki/Firmware-Build-Options][here.]]
|
||||
|One or both LEDs flash quickly (5Hz) when USG powered on|FREAKOUT self-protection mechanism is triggered at bootup|Firmware is damaged or buggy, or inter-MCU SPI link is damaged causing a failed self-test|
|
||||
|One or both LEDs flash quickly (5Hz) while a USB device is attached|FREAKOUT self-protection mechanism is triggered at runtime|You may have a Bad USB device, or a bug in the USG firmware.|
|
||||
|Downstream LED (yellow on v1.0) flashes slowly (1Hz) when a USB device is attached|Unsupported device class, or weird device configuration|The USG doesn't support this device right now.|
|
||||
|Upstream LED (red on v1.0) double-flashes slowly (1Hz)|[[https://github.com/robertfisk/USG/wiki/Firmware-Build-Options#hid-bot-detection][HID bot-detect function]] is triggered|The inputs coming from the attached keyboard or mouse are not random enough, so the USG blocked it (temporarily or permanently). If you were using the keyboard or mouse at the time, try making your input actions less regular. If you weren't using the keyboard or mouse at the time, you probably have a Bad input device!|
|
||||
@ -0,0 +1,63 @@
|
||||
The USG contains two [STM32F4 microprocessors](http://www.st.com/content/st_com/en/products/microcontrollers/stm32-32-bit-arm-cortex-mcus/stm32f4-series.html) communicating over a high-speed serial link. This internal link forms a firewall barrier that effectively blocks malicious USB commands from reaching your computer.
|
||||
|
||||
|
||||
|
||||
## Why is USB insecure?
|
||||
Your computer automatically trusts every device you plug into it. But every USB device is actually a small embedded computer (microprocessor) that runs software you cannot control. There are three ways a [BadUSB](https://srlabs.de/badusb/) device can attack your computer:
|
||||
|
||||
### Type 1 Attacks: USB Driver Exploits
|
||||
USB driver exploits work by sending malformed or unexpected input to your computer's USB drivers. Your computer likely has hundreds of USB device drivers installed, and a programming error in any one of them leaves you exposed.
|
||||
|
||||
**_How the USG protects you:_** The USG blocks these attacks by passing data through an internal serial link with a very simple protocol. Only a limited number of safe commands are accepted by the receiving microprocessor, so no malformed or unexpected data is transmitted to your computer. This effectively blocks USB driver exploits.
|
||||
|
||||
### Type 2 Attacks: Hidden Evil Functionality
|
||||
What appears to be a single USB device can actually contain more than one function. The hidden function can perform any action allowed by the USB standard, including [executing system commands](http://www.netragard.com/netragards-hacker-interface-device-hid) or [intercepting network traffic](https://opensource.srlabs.de/projects/badusb/wiki/BadAndroid). Only 100% legitimate USB commands are used, so you can't defend against this by fixing driver bugs. But the USG, being a hardware device, can enforce rules designed to block hidden USB functionality:
|
||||
|
||||
- _**Only one device attached at a time:**_ By supporting only one attached device, we eliminate attacks that use a hidden device to perform unexpected actions.
|
||||
|
||||
- _**No run-time device class changes:**_ Once a USB device is enumerated through the USG, it cannot re-enumerate itself as a different device class until power is removed and reapplied to the USG. This stops attacks where a device unexpectedly changes its functionality to perform malicious actions.
|
||||
|
||||
### Type 3 Attacks: Evil Functionality in Plain Sight
|
||||
Type 3 attacks are where the attached device abuses its position of trust even while performing the function you want. This attack involves no malformed or unusual commands, so it is the most difficult to defend against. For example, a malicious keyboard may enter commands to install malware while you are away from the computer. Or a malicious flash drive may insert viruses on-the-fly as they are read by the host computer.
|
||||
|
||||
**_How the USG protects you:_** USG firmware version r04 includes an HID 'bot detect' feature that monitors attached keyboards and mice for malicious input. If the input looks too much like a bot (insufficiently random) then the USG will temporarily lock for 4 seconds and you will see a red LED double-flash every second. Repeated bot detection will cause a permanent lock.
|
||||
|
||||
Protection against a type 3 malicious flash drive can be achieved by encrypting the user's data on-the-fly before it reaches the flash drive. This feature may be added to a future version of the USG's firmware.
|
||||
|
||||
## FAQ
|
||||
|
||||
### Which version of USB is used?
|
||||
|
||||
USB version 1
|
||||
|
||||
### Can a USB2 / USB3 flash drive be used with this (at USB 1.0 speeds)?
|
||||
|
||||
Every device I tested has worked, although I did receive reports of one USB3 flash drive and one USB3 motherboard that didn't. So I estimate that 95% of USB3 devices are compatible.
|
||||
|
||||
### How exactly does the "firewall" protects against malware like BadUSB?
|
||||
|
||||
The firewall operates on a limited whitelist of known-safe commands.
|
||||
This eliminates all the techniques malicious USB firmware could use to
|
||||
exploit your operating system - buffer overflows, malformed device
|
||||
descriptors, packets out of sequence, etc. This interface is vastly
|
||||
simpler than USB, and therefore checking for unexpected input is
|
||||
actually possible. Each packet received on the SPI interface needs to
|
||||
pass a series of checks based on the firewall's current state, expected
|
||||
command and reply sequence, and expected packet length. Any mismatch on
|
||||
the received data will trigger the various FREAKOUT macros, which
|
||||
immediately halt all traffic and flash an error LED.
|
||||
|
||||
One place to start would be reading the firewall's
|
||||
header files defining commands and packet structure below. Each packet
|
||||
contains a command class (interface commands, mass storage commands,
|
||||
etc) and a command (read, write, etc). The downstream side has identical
|
||||
corresponding definitions:
|
||||
|
||||
* [SPI packet defines](https://github.com/robertfisk/USG/blob/USG_1.0/Upstream/Inc/upstream_spi.h)
|
||||
* [command class & command defines](https://github.com/robertfisk/USG/blob/USG_1.0/Upstream/Inc/upstream_interface_def.h)
|
||||
|
||||
### Since the firmware is writable, is there not a danger that the USG device itself might become infected by malware (just like any other USB device)?
|
||||
|
||||
The firmware is stored in writable memory. And yes either side of the firewall could be exploited. However this is actually expected behavior, as the internal isolation barrier prevents an infection from propagating to the other side.
|
||||
|
||||
To prevent malware persistence, when the USG starts up it uses a hardware write-lock feature to disable writes to flash memory effective until the next restart. Theoretically this prevents exploited USB code from persisting between restarts, although the hardware write lock may be bypassable with an unknown exploit. Therefore I consider the write-lock feature slightly less reliable than the firewall's primary feature of isolation between upstream and downstream.
|
||||
Loading…
Reference in new issue