Kernel Level File Integrity Checker



Student (+contact information)



This project will focus on providing file integrity checking capabilities to pefs. The file integrity checker will compare cryptographic checksums of files against a static signed checksum list at access time. The files are thought to be immutable and use of securelevel will guarantee that lower filesystems will protect those files. Securelevel will be extended to only permit execution of files with immutable flag set.


April 24 – May 20: Evaluate design choices with mentor and study pefs codebase.

May 21 - June 3: Extend sbin/pefs so that it creates checksum file with dummy tags/tweaks which is then read during pefs_mount. pf_nodes are properly marked upon creation.

June 4 - June 17: Extend sbin/pefs so that it accepts secret key from userland and that proper tags/tweaks are created for checksum file. At this point test with one HMAC algorithm.

June 18 – July 1: Integrity checks in Vnode Operations.

July 2 - July 12: Excessive testing of new features and review code with mentor. If there's enough time, add extra HMACs or even option for simple hash and test those as well.

July 13: Midterm Evaluations

July 14 - July 30: Implement authentication checks for checksum files during mount.

July 31 – August 13: Extension of securelevel and perhaps rtld.

August 13 - August 20: More testing, write documentation.

Final shipping to Google.


Feel free to share any thoughts!

Design/Test plan

The design, as described in my original gsoc proposal may be found in the attached pdf file. I've appended the technical comparison of my gsoc proposal and mac_chkexec to the end of the file.



I'll try to keep a sort of developer's documentation using this wiki, updating it during the summer as relative features find their way into the source tree.

Source Code

Code Samples

These diff files were procuded at the end of GSoC: gpf_head.diff contains changes in the base system and gpf_pefs.diff contains changes in the pefs module.
last update: August 20 2012



Let's assume that we have already created/populated a pefs filesystem following the steps that can be found here.

1. Generate set of keys for the signing algorithm

The DSA algorithm is used by pefs in order to sign and verify the contents of the .pefs.checksum file. The following is an example of how a set of keys can be created using the openssl tool.

# openssl dsaparam -out dsaparam.pem 2048
# openssl gendsa -des3 -out privkey.pem dsaparam.pem
# openssl dsa -in privkey.pem -pubout -out pubkey.pem

This will provide the pubkey.pem and privkey.pem files that contain the public key and the private key respectively.

2. Create list of files that require integrity checking

The syntax of the file that contains the list of files that will be checked for integrity is simple: one fullpath per line.



These files must be either regular files or symlink files. If a file has several hardlinks, then the list should contain all of them. Symlinks are not traversed; pefs only checks the integrity of the symbolic link itself, not the file it points to. Therefore both the symlink file and any other files in the symlink chain should have entries in the above list.

3. Mount file system with saved encryption key

In order to set up integrity checking, we have to mount the pefs filesystem and add the respective key so that filenames are decrypted.

# pefs mount /home/user/private.enc /home/user/private
# pefs addkey -c /home/user/private
Enter passphrase:

4. Create the .pefs.checksum file

# pefs addchecksum -k ~/privkey.pem -i ~/list.txt /home/user/private

-k option provides the file that contains the private key in PEM format that will be used by the DSA signing algorithm.
-i option provides the file that contains the list of filenames that require integrity checking.

This command will create the .pefs.checksum file under the current working directory. This file will contain the checksums for all the files that require integrity checking.

5. Mount file system with integrity checking

The .pefs.checksum file should be placed under the filesystem root of the unmounted pefs filesystem, so as to avoid encrypting it.

# pefs unmount /home/user/private
# cp .pefs.checksum /home/user/private.enc/

Mounting of the filesystem with integrity checks enabled can then be performed easily:

# pefs mount -o checksum /home/user/private.enc /home/user/private

6. verify the contents of .pefs.checksum

If at any time we wish to verify .pefs.checksum, we may use the verify action.

# pefs verify -k ~/pubkey.pem /home/user/private

This action verifies the checksums for all the files in .pefs.checksum, checks the file's signature and performs other semantic checks as well.


Please refer to the updated man page of pefs(8) for further information.


SummerOfCode2012/EfstratiosKaratzas (last edited 2021-03-28T08:35:16+0000 by KubilayKocak)