Skip to content

Latest commit

 

History

History
168 lines (127 loc) · 9.62 KB

fsverify-paper.md

File metadata and controls

168 lines (127 loc) · 9.62 KB
Raw

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 datbase consisting of a single bucket called Nodes

Each element in this Bucket is a json serialization of the Node struck:

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 2kb big, if the partition size does not allow an even split in 2kb 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:

                         Checksums 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

Storing the Public key

The public key can be stored in multiple ways:

  • Partition which has the key directly flashed onto it
  • A text file
  • TPM2
  • A device that prints the key over usb serial

Fsverify does not verify the integrity or trustworthiness of these storage forms, so the integrity will have to be verified manually.

Partition which has the key directly flashed onto it

This is quite simple, all thats required is to write the key directly into a block device: Assuming that sda1 is the block device which should be used, it can be as simple as:

echo -n "public key" > /dev/sda1

It is important to make sure that only the public key is written, no extra newlines (hence the -n) or whitespace surrounding the key.

Once this is done, config/config.go can be modified to set the KeyStore value to 1 and KeyLocation to /dev/sda1

Any form of accessing the block device directly is viable, but it is recommended to specify the uuid of the device instead of using a label or name, as that would always verify that the right block device is used and makes spoofing the device harder.

Text file

The simplest form, and only recommended to be used in a secureboot verified UKI or a device/partition that can always be trusted (i.e. it is always read-only)

All that is required is to write the public key into a text file:

echo -n "public key" > /path/to/publickey

It is important to make sure that only the public key is written, no extra newlines (hence the -n) or whitespace surrounding the key.

Once this is done, config/config.go can be modified to set the KeyStore value to 0 and KeyLocation to /path/to/publickey

TPM2

to be done

Device that prints the key over usb serial

This is the safest form of storing the key, if done properly.

Any device, like a microcontroller, that has the option to write into a serial tty (/dev/ttyACM*) with the baud rate 9600 can be used for this. It is recommended to make sure that the microcontroller cannot be reflashed once the key is written successfully, to ensure that the device does not get overwritten with the key of an attacker.

An (unsafe) example using an arduino can look like this:

// fsverify-serial.ino

void setup() {
    Serial.begin(9600); // set up a serial tty with the baud rate 9600
    Serial.print("\tpublic key\t"); // Write the public key to the tty
}

void loop() {}

This will print the public key once the arduino is connected to the device, make sure that the public key is always surrounded by a \t, as the tab sequence is used by fsverify to figure out where a key starts and where it ends.

To ensure the safety of using this method, in addition to having the microcontroller be read only, it also has to be made sure that the microcontroller is embedded in the device in a way where it cannot be easily replaced since using an external arduino makes no checks to see if the ttyACM device being accessed is actually the legitimate device.

Reading the Signature and Public Key

The header only contains parts of the signature, the Trusted Hash and the Untrusted Hash, using this a complete signature is constructed, this allows for easier storage of the signature as the full signature contains data that can change over time (but is not required for signing) and break the header by becoming too big.

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 is 1mb big, it would reach from 0xC8 until 0xF4308 (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.

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.