Git-Mirrors/tillitis-key
1
0
Fork 0
mirror of https://github.com/tillitis/tillitis-key1.git synced 2024-10-01 01:45:38 -04:00
Code Issues Packages Projects Releases Wiki Activity

docs: Remove firmware protocol description

Browse Source 
Point to Developer Handbook description.
This commit is contained in:
Michael Cardell Widerkrantz 2024-06-25 15:26:06 +02:00 committed by dehanj
parent c406b780ba
commit 058c8e970c
No known key found for this signature in database
GPG Key ID: 3707A9DBF4BB8F1A
1 changed files with 3 additions and 184 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

187
doc/system_description/software.md
View File

@ -216,8 +216,9 @@ Commands in state `run`: None.
Commands in state `fail`: None.
See [Firmware protocol](#firmware-protocol) for the definition of the
specific commands and their responses.
See [Firmware protocol in the Dev
Handbook](http://dev.tillitis.se/protocol/#firmware-protocol) for the
definition of the specific commands and their responses.
### User-supplied Secret (USS)
@ -255,188 +256,6 @@ Then we continue with the CDI computation by updating with an optional
USS and then finalizing the hash, storing the resulting digest in
`CDI`.
### Firmware protocol
The firmware commands and responses are built on top of the [Framing
Protocol](https://dev.tillitis.se/protocol/).
The commands look like this:
| *name* | *size (bytes)* | *comment* |
|------------------|----------------|------------------------------------------|
| Header | 1 | Framing protocol header including length |
| | | of the rest of the frame |
| Command/Response | 1 | Any of the below commands or responses |
| Data | n | Any additional data |
The responses might include a one byte status field where 0 is
`STATUS_OK` and 1 is `STATUS_BAD`.
Note that the integer types are little-endian (LE).
#### `FW_CMD_NAME_VERSION` (0x01)
Get the name and version of the stick.
#### `FW_RSP_NAME_VERSION` (0x02)
| *name* | *size (bytes)* | *comment* |
|---------|----------------|----------------------|
| name0 | 4 | ASCII |
| name1 | 4 | ASCII |
| version | 4 | Integer version (LE) |
In a bad response the fields will be zeroed.
#### `FW_CMD_LOAD_APP` (0x03)
| *name* | *size (bytes)* | *comment* |
|--------------|----------------|---------------------|
| size | 4 | Integer (LE) |
| uss-provided | 1 | 0 = false, 1 = true |
| uss | 32 | Ignored if above 0 |
Start an application loading session by setting the size of the
expected device application and a user-supplied secret, if
`uss-provided` is 1. Otherwise `USS` is ignored.
#### `FW_RSP_LOAD_APP` (0x04)
Response to `FW_CMD_LOAD_APP`
| *name* | *size (bytes)* | *comment* |
|--------|----------------|-----------------------------|
| status | 1 | `STATUS_OK` or `STATUS_BAD` |
#### `FW_CMD_LOAD_APP_DATA` (0x05)
| *name* | *size (bytes)* | *comment* |
|--------|----------------|---------------------|
| data | 127 | Raw binary app data |
Load 127 bytes of raw app binary into device RAM. Should be sent
consecutively over the complete raw binary. (128 == largest frame
length minus the command byte).
#### `FW_RSP_LOAD_APP_DATA` (0x06)
Response to all but the ultimate `FW_CMD_LOAD_APP_DATA` commands.
| *name* | *size (bytes)* | *comment* |
|--------|----------------|--------------------------|
| status | 1 | `STATUS_OK`/`STATUS_BAD` |
#### `FW_RSP_LOAD_APP_DATA_READY` (0x07)
The response to the last `FW_CMD_LOAD_APP_DATA` is an
`FW_RSP_LOAD_APP_DATA_READY` with the un-keyed hash digest for the
application that was loaded. It allows the host to verify that the
application was correctly loaded. This means that the CDI calculated
will be correct given that the UDS has not been modified.
| *name* | *size (bytes)* | *comment* |
|--------|----------------|--------------------------|
| status | 1 | `STATUS_OK`/`STATUS_BAD` |
| digest | 32 | BLAKE2s(app) |
#### `FW_CMD_GET_UDI` (0x08)
Ask for the Unique Device Identifier (UDI) of the device.
#### `FW_RSP_GET_UDI` (0x09)
Response to `FW_CMD_GET_UDI`.
| *name* | *size (bytes)* | *comment* |
|--------|----------------|-----------------------------------------------------|
| status | 1 | `STATUS_OK`/`STATUS_BAD` |
| udi | 4 | Integer (LE) with Reserved (4 bit), Vendor (2 byte),|
| | | Product ID (6 bit), Product Revision (6 bit) |
| udi | 4 | Integer serial number (LE) |
#### Get the name and version of the device
```
host ->
u8 CMD[1 + 1];
CMD[0].len = 1 // command frame format
CMD[1] = 0x01 // FW_CMD_NAME_VERSION
host <-
u8 RSP[1 + 32]
RSP[0].len = 32 // command frame format
RSP[1] = 0x02 // FW_RSP_NAME_VERSION
RSP[2..6] = NAME0
RSP[6..10] = NAME1
RSP[10..14] = VERSION
RSP[14..] = 0
```
#### Load an application
```
host ->
u8 CMD[1 + 128];
CMD[0].len = 128 // command frame format
CMD[1] = 0x03 // FW_CMD_LOAD_APP
CMD[2..6] = APP_SIZE
CMD[6] = USS supplied? 0 = false, 1 = true
CMD[7..39] = USS
CMD[40..] = 0
host <-
u8 RSP[1 + 4];
RSP[0].len = 4 // command frame format
RSP[1] = 0x04 // FW_RSP_LOAD_APP
RSP[2] = STATUS
RSP[3..] = 0
repeat ceil(APP_SIZE / 127) times:
host ->
u8 CMD[1 + 128];
CMD[0].len = 128 // command frame format
CMD[1] = 0x05 // FW_CMD_LOAD_APP_DATA
CMD[2..] = APP_DATA (127 bytes of app data, pad with zeros)
host <-
u8 RSP[1 + 4]
RSP[0].len = 4 // command frame format
RSP[1] = 0x06 // FW_RSP_LOAD_APP_DATA
RSP[2] = STATUS
RSP[3..] = 0
```
Except response from last chunk of app data which is:
```
host <-
u8 RSP[1 + 128]
RSP[0].len = 128 // command frame format
RSP[1] = 0x07 // FW_RSP_LOAD_APP_DATA_READY
RSP[2] = STATUS
RSP[3..35] = app digest
RSP[36..] = 0
```
### Firmware services
The firmware exposes a BLAKE2s function through a function pointer