On the SimpleSerial Protocol

coastalwhite · March 5, 2021, 12:04pm

This post concerns the protocol for interacting with the ChipWhisperer boards. Having emailed with Colin, I got asked to create a forum post here. So here is a post to describe the problem.

To start with some background. Currently, I am busy with a thesis on using ChipWhisperer for Hardware Security education. Part of this is writing some documentation for people who are completely new to Side-channel Analysis with some open-ended practice exercises and grade-able assignments. It was important to look at some more obscure encryption algorithms and make algorithm more adjustable. Since the current GitHub repository only covers the conventional algorithms. In my opinion the current way of interacting with and compiling the SimpleSerial protocol is just not suited for this. I am used to Rust-Lang and this made me reasonably spoiled when it comes to this process. I came to work at the implementing the SimpleSerial protocol in Rust. Here I noticed the biggest problem. There is no up-to-date or thorough documentation on this protocol, whilst I feel like it is vital if you want to implement proper implementations of new algorithms.

There are two non-code documentation sources for the protocol, the old wiki (https://wiki.newae.com/SimpleSerial) and the API reference (https://chipwhisperer.readthedocs.io/en/latest/api.html#simple-serial-target). The first contains some info on the different commands available, whilst the second only contains info on how to interact with the Python API. It is quite a lot to ask of users to read into the HAL and SimpleSerial source-code to be able to implement algorithms. Maybe a good reference documentation could also help the ChipWhisperer being easier to use for vulnerability prevention and mitigation. Maybe this could be added as a README.md to the SimpleSerial C library. From what I understood, this protocol is kind of bodgy and being updated constantly when new features are needed. This would of course require some administration when that happens. I would be willing to help on this if it is wanted. This could, in my opinion, be a proper temporary solution. I am looking into creating a pull request for this.

I heard from emailing with Colin, I heard that Alex Dewar is working on a new protocol. I would love to help on this and I suggest creating a tracking/discussion issue on GitHub. This way there is already some documentation on the process and we can use that for eventual reference.

Let me know what you think.

Alex_Dewar · March 5, 2021, 4:38pm

Hi,

Yeah, you’re definitely right that simpleserial isn’t well documented - I’m working on a README in the simpleserial directory that documents simpleserial V1 and the new V2. We might throw a page on the readthedocs in the future as well. The protocol is actually quite stable - the changes made recently are actually the first time it’s changed since 2017.

In the meantime, you may want to take a look at https://github.com/newaetech/chipwhisperer-jupyter/blob/master/1%20-%20Connecting%20to%20Hardware.ipynb.

Alex

coastalwhite · March 5, 2021, 4:52pm

Hi Alex,

This link is very useful already. If there is a pull request with the README, I would love to help. From all the work on reverse engineering the protocol I should hopefully to have some idea what is going on.

Gijs

Alex_Dewar · March 5, 2021, 6:04pm

Hi Gijs,

I’ve put some documentation in a readme file. Let me know if there’s anything that I can expand upon or explain better:

github.com

newaetech/chipwhisperer/blob/develop/hardware/victims/firmware/simpleserial/README.md

# Simpleserial Documenetation

## Simpleserial v1.1

All communication is initiated by the capture board. The capture board begins communication by sending a packet:

`[cmd, data_0, data_1, ..., data_n, '\n']`

where `cmd` is an ASCII character indicating the desired command and `data` is an ASCII representation of the data (i.e. `0xAA` will be `'A'`, `'A'`)
The length of data is fixed by the firmware.

If the target board needs to respond with data, it sends back:

`['r', data_0, data_1, ..., data_n, '\n']`

Again, `data_n` is an ASCII representation of the data.

Whether or not the device sends back data, the device will send back an ack to tell the capture board
that it is done its operation:

This file has been truncated. show original

Alex

coastalwhite · March 5, 2021, 6:16pm

Hi Alex,

This is awesome! I think this will not only be incredibly usefull to me, but to a lot of people. Only thing to maybe expand upon is the list commands, although this is target dependent. How accessible is this information?

Thank you for the fast responses!

Gijs

Alex_Dewar · March 5, 2021, 6:33pm

Hi Gijs,

The commands are indeed firmware dependent. The commands do vary quite a bit as well - simpleserial-aes has a plaintext/key command, simpleserial-rsa uses several commands to read back the full encryption result (at least on SSV1), simpleserial-glitch has several commands for different glitch situations, and simpleserial-ecc has many commands for setting up parts of ECC. The only real “standard” command is to check the simpleserial version (the 'v' command)

The best way currently to see which commands are available currently is to look at the main firmware file for each - there’s a list of simpleserial_addcmd() for each command. Now that you mention it, it might be good to have a standard command to list the available commands.

Alex

Alex_Dewar · March 14, 2021, 2:41pm

Just wanted to give a quick update on this. I’ve added the README to readthedocs: https://chipwhisperer.readthedocs.io/en/latest/simpleserial.html

coastalwhite · March 9, 2021, 10:30am

Hi Alex,

This is awesome!

I am currently writing some README’s for some of the individual victim firmware’s along with a template SimpleSerial repository to let users create SS algorithms themselves. Currently planning on finishing this on Thursday, and hopefully be creating a PR on the GitHub page for that on either Thursday or Friday. Will keep you up to date.

Gijs

coastalwhite · March 14, 2021, 2:37pm

Hi Alex,

F.Y.I.
I created a template repository for creating SimpleSerial V2 target binaries in C. It is very basic, but it should provide a good starting point for users looking to write their own binaries.

Here is the link:
https://github.com/coastalwhite/simpleserial-c-template

Gijs