The can2 logic analyzer CAN protocol decoder
Canis Labs has developed an open source logic analyzer decoder for CAN called can2. It has special features to warn about unusual events that could indicate a CAN protocol attack, works with low-cost hardware (less than $10!), runs on Linux, Windows and macOS and can also export decoded frames to a pcapng packet capture file for display in Wireshark.
Overview of PulseView with can2
The open source Sigrok project is a set of drivers and tools that provide a desktop oscilloscope and logic analyzer UI that can control different instruments (from Siglent, Rigol and others). The UI runs on macOS, Windows and Linux and is called PulseView (there is also a command-line tool called sigrok-cli for batch decoding, useful in an automated test environment). PulseView has an API for protocol decoders, and now there is a new decoder for CAN.
The screenshots here show the PulseView interface running on Ubuntu Linux. The logic analyzer hardware used here is a 16-channel Saleae Logic16 (but there are USB logic analyzers that cost less than $10 with 8 channels and a sample rate of up to 20MHz, easily good enough for CAN). A falling edge trigger condition is typically used with CAN (this is the sync point for the protocol) and a pre-trigger buffer so that the decoder can see at least ten recessive bits to know that the next dominant bit is a new frame.
The decoder shows four lines of details about a CAN frame:
- The raw bitstream (including stuff bits)
- The decoded CAN fields
- The decoded CAN ID and payload bytes
- An information line showing protocol events and warnings
PulseView shows as much detail as fits into an item for a given time scale, but a tooltip appears with the full data if the mouse pointer hovers over an item. For example, here the value of the 4-bit DLC field is shown with a tooltip:
The decoder also checks the frame for valid fields and marks when an error is detected. For example, it will show in the warning line when the received CRC does not match the calculated CRC, when the ACK field is not 0, when a stuff error has been detected, and so on. It also shows an active error frame (the superposition, the error delimiter, and the IFS field following an error frame).
The warning here is a Stuff error – the result of an error being signalled by another CAN controller. The decoder shows the Error Flag (which includes the superposition of dominant bits from many controllers) and the Error Delimiter. The trace also shows the frame being re-transmitted successfully.
The Double Receive event is a particularly interesting property of CAN: because a frame is received one bit time before it is transmitted, it is possible that an error in the last bit of the EOF causes the transmitter to detect an error and retransmit the frame, leading to it being received twice. This is not a bug in the CAN protocol: it is an inevitable consequence of implementing an atomic broadcast protocol (something that most other communication protocols do not even attempt to provide, which is one reason why CAN is such a superbly reliable fieldbus protocol). The decoder warns of this specific event:
This event should happen rarely (a bit error must occur exactly at the last bit of EOF). But it can be engineered to occur by an attack on the bus: by deliberately injecting a dominant bit at the last bit of EOF an attacker can force the frame to be retransmitted and received twice. If the frame being targeted contains event data then that event will be acted upon twice by receivers, which could cause all kinds of things to go wrong – the very purpose of a malicious attack.
The decoder also shows when there is an overload frame – something that should never be seen since modern CAN controllers never generate these frames. The screenshot below shows a frame that is sent but then a sequence of overload frames is injected to hold all the CAN controllers in an overload loop. This is a clear indication of a type of denial-of-service attack on the CAN bus (in this case it was carried out by the CANHack toolkit on the Raspberry Pi Pico).
The protocol decoder is designed to help spot these events from a logic analyzer trace – it can see things that a simple list of received CAN frames would not show. But it also can interface to CAN frame logging tools: the decoder has an option to export CAN frames in a packet capture format (called ‘pcapng’) that tools such as Wireshark can process. A trace of many frames can be shown in Wireshark as a conventional list of frames. For example, the screenshot below shows trace of a pair of CAN frames sent roughly every 100ms.
When the exported packet capture file is read in to Wireshark it shows as a simple list of frames:
The timestamps attached to CAN frames in the packet stream are very accurate and these are useful when hunting for a particular incident in the frame view of Wireshark (or other tools) to navigate within PulseView to find details of what was happening on the wire around an incident.
The source code to the CAN protocol decoder is available in
the Yes We CAN repository on GitHub
(the decoder is in the folder
src/can2). The best way to install the
Sigrok tools (PulseView and sigrok-cli) is to download them directly from Sigrok
More details on setting up the decoder can be found in a blog post.
Latest blog posts on can2
The Janus Attack is a low-level CAN protocol attack where a single CAN frame contains two different payloads, so that a targeted device sees a different payload to other devices. This attack could be used to transmit a frame to evade an Intrusion Detection System (IDS), or it could put two different actuators into inconsistent states (e.g. moving a pair of motors in a different directions). It breaks the atomic multicast feature of CAN (where every device sees the same frame) - an important property that lots of systems rely on (often implicitly).
We have published a short video showing the PulseView logic analyzer UI with our can2 protocol decoder. The video shows how to set PulseView up to record CAN traces, how to navigate around those traces, and how it shows unusual events on CAN (we use the CANHack toolkit to inject CAN overload frames in a loop).
Last year we published a blog post that described the new can2 CAN protocol decoder for many logic analyzers supported by Sigrok we have now updated it to include a new binary output where CAN frames (including error frames) are output in pcapng format. This is a packet capture format that the hugely popular network capture and analysis tool Wireshark uses.