Add go project

Signed-off-by: axtloss <axtlos@getcryst.al>

1 files changed, 107 insertions, 0 deletions

diff --git a/fsverify-paper.md b/fsverify-paper.md
new file mode 100644
index 0000000..6093752
--- /dev/null
+++ b/fsverify-paper.md
@@ -0,0 +1,107 @@
+# 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> <signature> <filesystem size> <table size>`
+
+Field|Size|Purpose|Value
+-----|----|-------|-----
+magic number|2 bytes|sanity check|0xACAB
+signature|302 bytes|minisign signature|
+filesystem size|4 bytes|size of the original filesystem in gb
+table size|4 bytes| size of the table in mb
+
+Due to the filesystem and table size field, which can go up to 0xFFFFFFFF (16777215), the maximum supported partition size and table size is 16777215gb (~16pb)
+
+The entire Head should be a total of 312 bytes long, reaching from 0x0 to 0x138
+
+## 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
+
+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
+```
+
+
+# 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.