1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
|
# Fsverify Partition
The FsVerify partition contains a header with the necessary metadata for the filesystem verification, and a bbolt database containing all File and Directory nodes to be checked.
## Partition Header
`<magic number> <untrusted signature hash> <trusted signature hash> <filesystem size> <filesystem unit> <table size> <table unit>`
Field|Size|Purpose|Value
-----|----|-------|-----
magic number|2 bytes|sanity check|0xACAB
untrusted signature hash|100 bytes|untrusted signature from minisign
trusted signature hash|88 bytes|trusted signature from minisign
filesystem size|4 bytes|size of the original filesystem in <table unit\>
filesystem unit|1 byte|unit of the filesystem size|0x0: bytes, 0x1: kilobytes, 0x2: megabytes, 0x3: gigabytes, 0x4: terabytes, 0x5: petabytes
table size|4 bytes| size of the table in <table unit\>
table unit|1 byte|unit of the table size|0x0: bytes, 0x1: kilobytes, 0x2: megabytes, 0x3: gigabytes, 0x4: terabytes, 0x5: petabytes
Due to the filesystem and table size field, which can go up to 0xFFFFFFFF (16777215), the maximum supported partition size and table size is 16777215pb
The entire Head should be a total of 200 bytes long, reaching from 0x0 to 0xC8
## Partition Contents / Database
The main database containing the checksums is a [bbolt](https://github.com/etcd-io/bbolt) datbase consisting of a single bucket called `Nodes`
Each element in this Bucket is a json serialization of the `Node` struck:
```go
type Node struct {
BlockStart int
BlockEnd int
BlockSum string
PrevNodeSum string
}
```
Field|Purpose
----|----
BlockStart|The Hex offset at which the block begins
BlockEnd|The Hex offset at which the block ends
BlockSum|The checksum of the block
PrevNodeSum|The checksum of all the fields of the previous field as a checksum and the identifier of the node
Each block is 4kb big, if the partition size does not allow an even split in 4kb sectors, the partition will be split as good as possible, with a smaller block as the last sector.
Beyond beign signed with minisign, each Node is verified through the PrevNodeSum Field, which gets generated by adding all fields of the previous block together and calculating the checksum of the resulting string:
```
+-----+ +------+ +------+ +------+
|0x000| |0xFA0 | |0x1F40| |0x3E80|
|0xFA0| --> |0x1F40| --> |0x3E80| -----> |0x4E20|
|aFcDb| |cDfaB | |4aD01 | |2FdCa |
| | |adBfa | |1Ab3d | |bAd31 |
+-----+ +------+ +------+ +------+
```
through this, the slightest change in one of the nodes will result in a wrong hash for every node following the modified one:
```
Checksum do not match
|
+-----+ +------+ +------+ | +------+
|0x000| |0xFA0 | |0x1F40| | |0x3E80|
|0xFA0| --> |0x1F40| --> |0x3E80| --|--> |0x4E20|
|aFcDb| |AAAAA | <-+ |4aD01 | | |2FdCa |
| | |adBfa | | |1Ab3d | <-+--> |bAd31 |
+-----+ +------+ | +------+ +------+
|
Modified value
```
The first Node will have `PrevNodeSum` as "Entrypoint" since the PrevNodeSum field is also used to access each node, using EntryPoint allows fsverify to start the verification by always being able to read the first node
# Verification Process
The verification step consists of multiple steps:
1. Reading the signature and public key
2. Reading the database
3. Verifying the database using the previously read keys
4. Verifying the target partition using the database
## Reading the Signature and Public Key
Reading the signature is quite simple, it is part of the Fsverify partition header and is read at an offset starting at 0x4 up to 0x132 (total 302 Bytes).
The Public Key however is not stored in the partition, instead it can be stored in multiple ways
- A different partition that has been verified in a different way
- An external storage device that can always be trusted
- The TPM2
- Secureboot verified UKI
The most secure option for most average Desktop computers would be the TPM2 or a secureboot verified UKI, embedded devices however would greatly benefit from a partition that cannot be modified in any way, in which the key is stored
In the case that the hardware itself cannot be trusted, read-only external storage can be used to store the key, this can ensure that the public key is never modified, assuming the person carrying said storage device does not loose it.
## Reading the database
The Database is simply read from 0x13A until the size of the table is reached as specified in the headers. If the table would be 1mb big, it would reach from 0x13A until 0xF437A (1000000bytes/1mb)
## Verifying the database using the previously read keys
Now that the signature, public key and database are read, they can be verified using [minisign](https://jedisct1.github.io/minisign/).
If the verification fails, a protected rootfs is used to display a warning to the user and/or completely shut down the device.
## Verifying the target partition using the database
If the database was verified succesfully, it can now be used to verify the actual partition.
Each entry in the database is read and the according data in the specified offset area is verified to the hash. At the same time, the database verifies itself by using the `PrevNodeSum` property of the `Node` object.
If the verification fails, be it due to a mismatch in `PrevNodeSum` or a mismatch in the Block checksum, the same protected rootfs as with the database verification is used to display a warning to the user and/or completely shut down the device.
# When/how to run fsverify
Fsverify can theoretically be run at any point of the boot process, however it is the most useful when run
- before the init system (systemd, openrc, runit, etc.) launches, but after the initramfs is exited
- while the system is still inside the initramfs and the real system is not even mounted yet
The second option is the preffered option, as it not only makes the modification of fsverify more difficult, but also, in the case that secureboot and UKI is set up correctly, can not be modified whatsoever without failing the secureboot checks, allowing for an extra layer of verification that the fsverify binary has not been manipulated.
If neither UKI nor secureboot are implemented however, the first option will work just as well and could possibly be easier to implement, as it simply takes an init script that executes the fsverify binary before the init system launches. This order is important, to ensure that no extra binaries are executed before it is ensured that they can be trusted.
|
