Cocoon TPM project - cocoonfs-cli crate

CLI program to work with CocoonFS image files -- create CocoonFS images and read, write, list and remove files in existing images.

CocoonFs is a special purpose filesystem format designed for the secure storage of sensitive data in e.g. a TEE setting. In addition to its primary design focus on strong security properties, the format implements support for some features of particular relevance to the intended use-case, such as support for keyless storage volume provisiong and robustness against service interruptions by means of a journal.

For the format specification, refer to file cocoonfs-format.md distributed with the code, see here for a rendered version.

A note ahead: all operations, except for write-mkfsinfo-header, require access to the filesystem key. That may either get provided directly on the command line (via -K), which is insecure because any other user on the host may see it in a process dump, or read from a file (specified via -k), which is recommended for production usages. All examples will be shown with the -K variant with a fixed hexadecimal key of aabbcc, to allow for a quick copy&paste when playing around. Do not use in real world setups!

Furthermore, each CocoonFS filesystem instance has a maximum supported block size, the filesystem "IO Block" size, encoded in it, and the implementation will by default refuse to create or open a filesysten in case the underlying hardware's block size happens to exceeds that. The reason is that the journalling mechanism relies on that, otherwise power cuts or alike may lead to data loss. On Linux, the reported hardware IO Block size reported is typically relatively large in practice (4kB, probably due to its page cache), whereas the default CocoonFS maximum IO Block size is set to 512B. In practice, host filesystems, i.e. the filesystem the CocoonFS image file resides on, is likely to be transactional itself, so data loss is no real concern. You may use the -f command line flag to override cocoonfs' default behaviour and make it to ignore the block size constraint. All examples shown below will include that flag.

The examples demonstrate only basic usage. Especially for the filesystem creation commands, there's a plethora of fine-tuning configuration parameters.

Run

# cocoonfs help

for an overview on the available commands and

# cocoonfs help <COMMAND>

for the full details on a specific command.

Filesystem creation

There are two mutually exclusive ways of creating a CocoonFS filesystem: a "regular" one which requires access to the key at filesystem creation time, and another one which does not. The latter works by writing a special "filesystem creation info header" to the image, and the actual filesystem formatting will then be conducted at first use, i.e. on the first attempt to open it. It is intended to support confidential computing setups where the entity preparing the image volume doesn't have access to the key.

In either case,

• a set of cryptographic algorithms and overall target security strength,
• a salt / id
• and the desired filesystem image size must get specified, the latter either explicitly on the command line, or implicitly through the (preexisting) target image file's bounds.

The set of cryptographic algorithms is supplied as a combination of a hash family like sha2 and a block cipher, e.g. aes. Hash algorithms will get selected automatically from the specified family for the various internal filesystem purposes in accordance with the specified target security strenth. Likewise for the block cipher key size.

Examples

A word of caution: both filesystem creation commands will happily overwrite preexisting files, if any, there are no safeguards!

"Regular" filsystem creation of a 16MB image: sha2 hash family, aes block cipher, target security strength of 128 bits, a salt/id of hexadecimal ddeeff and a filesystem image size of 8MB:

# cocoonfs -i my-cocoonfs.img -f mkfs -H sha2 -C aes -t 128 -I 'ddeeff' -s 8M -K 'aabbcc'

Write a special "filesystem creation info header" instead, so that the filesystem will get created with the configuration parameters specified at first use:

cocoonfs -i my-cocoonfs.img -f write-mkfs-info-header -H sha2 -C aes -t 128 -I 'ddeeff' -s 8M

Writing to and reading from files in the CocoonFS image

The CocoonFS file namespace is very simple: it's flat, i.e. there is no notion of a directory hierarchy, and file "names" are merely 32bit numbers starting from 6.

The source data to write may be either provided from a file on the host, or from cocoonfs' standard input if none is specifed. Likewise, data read from a file in the CocoonFS image may be either written to a file on the host, or to cocoonfs' standard output if none is specifed.

E.g. for writing "Hello world!" to file number 42:

# echo "Hello world!" | cocoonfs -i my-cocoonfs.img -f write-file -K 'aabbcc' 42

or

echo "Hello world!" > /tmp/hello-world-data.in
# cocoonfs -i my-cocoonfs.img -f write-file -K 'aabbcc' -i /tmp/hello-world-data.in 42

And for reading

# cocoonfs -i my-cocoonfs.img -f read-file -K 'aabbcc' 42

or

# cocoonfs -i my-cocoonfs.img -f read-file -K 'aabbcc' -o /tmp/hello-world-data.out 42

Listing and deleting files

List all files stored in the CocoonFS image:

# cocoonfs -i my-cocoonfs.img -f list-files -K 'aabbcc'

And delete file number 42:

# cocoonfs -i my-cocoonfs.img -f remove-file -K 'aabbcc' 42