Introducing the CANHack toolkit
For the last few weeks we’ve been developing the
CANHack toolkit for CAN protocol hacking. It’s a portable
bit-banging library to emulate the minimal parts of the CAN protocol required
for hacking a CAN bus. This toolkit is a proof-of-concept to show how various attacks on the CAN bus can be done
purely in software if a microcontroller can be hijacked (we’ve not addressed how the hijacking
could occur: it might be as simple as reflashing the firmware on an OBD-II dongle that
an attacker owns, or something more complex like an exploit of a buffer overrun in a diagnostic
In most situations a microcontroller’s on-chip CAN controller is connected to a CAN transceiver and through this
transceiver to the CAN bus. If the microcontroller can be hijacked then in general the pins allocated to the CAN
controller can be re-purposed as GPIO pins. The
CANHack toolkit has minimal assumptions about the environment, which
are implemented in target-specific code that wraps the library. The basic requirements are:
- Access to CAN RX and CAN TX as GPIO pins
- Access to a timer to read the elapsed clock cycles (typically a free-running counter)
- Interrupts are disabled around key operations (the code spins on the timer waiting for events)
This can be ported to pretty much anything fast enough to bit-bang CAN (a Cortex M0 at 48MHz is probably too slow, but an ESP32 should be fast enough). The only other hardware requirement is that a CAN transceiver is connected to two GPIO pins.
CANHackfirst to the PyBoard v1.1. This is
a board using the STM32F405 microcontroller, which has a Cortex M4 CPU running at 168MHz. We’ve customized the
firmware to wrap the toolkit and make it available via a MicroPython API. MicroPython is a great
platform for CAN hacking: all kinds of scenarios can be scripted up. We’ve included the Python wrappers
in the CANHack respository.
The test rig is a card designed by Canis Automotive Labs that has a header 9-pin D-sub cable with standard CAN connector: this is the standard used by most bus analyzers and it makes it very easy to prototype a CAN bus using 10-way ribbon cable, with simple plugs at either end for bus termination.
The MicroPython API is provided as a class called
CANHack that allows a CAN frame to be defined and various attacks
to be mounted against traffic on the bus.
The toolkit is initialized with an instance of the
1 >>> ch = CANHack()
This sets up the CAN TX pins and sets a default baud rate (500kbit/sec). The pins B8 and B9 are used (this is CAN1
on the PyBoard’s STM32F405). A different
CAN bit time can be selected with the
1 >>> ch = CANHack(bit_time=CANHack.KBIT_125)
The parameters of the CAN frame are specified by calling
1 >>> ch.set_frame(0x14)
This call pre-computes the bitstream of the CAN frame (it has a C implementation very similar to the Python CAN calculator).
Identifiers default to standard IDs. Extended IDs can be set with the
1 >>> ch.set_frame(0x14, extended=True)
Remote frames can be set by the
Once the CAN frame parameters have been set the toolkit can be used to attack a frame matching the parameters. There
is also a method to transmit the frame on the bus, which is very useful to test that everything has been wired up
properly. The payload of the CAN frame can be set with the
data parameter, and the frame is set with the
1 2 >>> ch.set_frame(0x14, data=bytes()) >>> ch.send_frame()
This is the trace on the CAN RX and TX pins of the PyBoard:
The trace is produced by the Digilent Analog Discovery 2 USB scope (it has 8 channels of
digital inputs and the software has a CAN protocol decoder). Notice that the ACK field is transmitted dominant. The
CANHack toolkit does this so that a protocol decoder on the bus with just the transmitter won’t treat this as an
ACK failure and expect the transmitter to send an error frame. In the test setup used to produce this there were
other boards connected to CAN that anyway asserted a dominant bit in the ACK field. But this illustrates the power of
bit-banging CAN: the protocol can be changed to do what we want.
The Bus-Off Attack is one of the simplest attacks on the CAN protocol. The idea is to target a specific device that’s transmitting and then generate error frames when that frame emerges so that the Transmit Error Counter (TEC) in the targeted device exceeds the bus-off threshold. Various follow-up attacks are then possible, including doing nothing (knocking a device off-line is a denial-of-service attack all by itself) and stepping in to emulate the missing device by spoofing its frames. The attack was published in 2016 by Kyong-Tak Cho and Kang G. Shin (PDF).
The attack can be run on the PyBoard with
CANHack by first setting a CAN frame with the ID we wish to attack:
1 >>> ch.set_frame(0x123)
This will attack a frame with standard ID 0x123. We mount the attack by calling the
error_attack method. This waits
to see a frame with the set ID and then injects an error frame. It will stimulate further errors by injecting
an error frame into the error delimiter, causing error recovery to repeat. The
repeat parameter indicates the number
of times an error frame is injected. For example:
1 >>> ch.error_attack(repeat=3)
results in this trace:
The transmitter will have seen a total of four errors while transmitting and its TEC will have increased by 31 (8 for each attack less 1 for a successful transmission). When it exceeds 255 it will go bus-off.
An attack of 32 repeats is sufficient to drive any transmitter bus off. For example:
1 >>> ch.error_attack(repeat=32)
gives this trace:
But attacking a transmitter directly in one go is not the best approach: receivers will have their Receive Error Counter (REC) incremented too and might be pushed error passive. It is probably best to attack a transmitter over time, incrementing TEC gradually so that the disruption to the bus is minimized (particularly if there is an intrusion detection system on the bus).
A CANHack toolkit demo video shows spoofing and bus-off attacks. It also shows the toolkit used for three new unpublished CAN protocol attacks:
- The Double Receive Attack
- The Freeze Doom Loop Attack
- The Janus Frame Attack
These new attacks will be written up in their own blog posts.
See also the CANT bit-banging CAN toolkit for the Nucleo-H743ZI2 board that also can do low level attacks on the CAN protocol (H/T @ehntoo).