Skip to content

Commit

Permalink
chore: update readme
Browse files Browse the repository at this point in the history 
Signed-off-by: Ravi Chamarthy <[email protected]>
  • Loading branch information
@rchamarthy
rchamarthy committed Aug 30, 2024
1 parent 4cd3ae5 commit 481699b
Show file tree
Hide file tree
Showing 2 changed files with 13 additions and 5 deletions.
5 changes: 1 addition & 4 deletions .gitignore
View file
Original file line number Diff line number Diff line change
Expand Up @@ -62,9 +62,6 @@ VERSION
.made-gofmt
.lint

# Test binary, build with `go test -c`
*.test
coverage.txt

# Output of the go coverage tool, specifically when used with LiteIDE
*.out
coverage.txt
13 changes: 12 additions & 1 deletion README.md
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,15 @@
# atomfs binary
# atomfs [![GoDoc](https://godoc.org/machinerun.io/atomfs?status.svg)](https://godoc.org/machinerun.io/atomfs) [![build](https://github.com/project-machine/atomfs/actions/workflows/build.yaml/badge.svg?branch=main)](https://github.com/project-machine/atomfs/actions/workflows/build.yaml) [![codecov](https://codecov.io/gh/project-machine/atomfs/graph/badge.svg?token=175HCB255L)](https://codecov.io/gh/project-machine/atomfs) [![Apache 2 licensed](https://img.shields.io/badge/license-Apache2-blue.svg)](https://raw.githubusercontent.com/gojini/signal/main/LICENSE)

`atomfs` is a tool that can mount OCI images built in the `squashfs` format as
as read-only `overlay` filesystem that can be used by a container runtime. In
addition to setting up the mount, `atomfs` can also set up a verity check on the
squashfs image to ensure that the image is not tampered with during the runtime.

This comment has been minimized.

Sign in to view

Copy link
@mikemccracken

mikemccracken Aug 30, 2024

Contributor

The verity description could be clearer - it's not so much about being tampered with during runtime as it is verifying that the image we mount is the image we expect (verified using the root hash that's stored as an OCI annotation).

So maybe the second sentence should read "for OCI-squashfs images that were created with dm-verity data appended, which stacker does by default, then atomfs will mount each individual squashfs layer using dm-verity before constructing the final overlayfs stack. This ensures the integrity of the contents of the image when mounted, and the use of squashfs removes the window of time between tar extraction and image mounting when an image could be tampered with.

This comment has been minimized.

Sign in to view

Copy link
@raharper

raharper Sep 1, 2024

The verity description could be clearer - it's not so much about being
tampered with during runtime as it is verifying that the image we mount is
the image we expect (verified using the root hash that's stored as an OCI
annotation).

Note that no verification of the image w.r.t dm-verity happens until a block
is read. Just mounting a verity device will not determine if your image has
been modified. It really is defense at runtime, after reading a block, the
hash is computed and if that doesn't validate with the pre-computed hash, then
kernel return failure on READ.

So we never run with tampered data; but we cannot tell until we start to
use the block device.

So maybe the second sentence should read "for OCI-squashfs images that were
created with dm-verity data appended, which stacker does by default, then
atomfs will mount each individual squashfs layer using dm-verity before
constructing the final overlayfs stack. This ensures the integrity of the
contents of the image when mounted

s/when mounted/when accessed/ - the kernel prevents reading any corrupted
data.

, and the use of squashfs removes the

window of time between tar extraction and image mounting when an image could
be tampered with.

squashfs is mounted and not extracted to writable storage space.

This comment has been minimized.

Sign in to view

Copy link
@mikemccracken

mikemccracken Sep 5, 2024

Contributor

so does this mean that if a squash+verity image has been tampered with in a rarely used block, then we could go happily for days and then get a verity read error at some time later?

I guess that's still acceptable behavior, but it's not exactly what you might expect

This comment has been minimized.

Sign in to view

Copy link
@raharper

raharper Sep 5, 2024

I believe so yes -- one could also schedule a cronjob that calls veritysetup verify which walks the device and does the verification.

https://github.com/project-machine/atomfs/blob/main/squashfs/verity_test.go#L128

## atomfs library

Please find the atomfs library documentation at [godoc](https://godoc.org/machinerun.io/atomfs).

## atomfs binary

This can be used to mount an OCI+squashfs image. If you are host
root, then squashfs will be mounted by the kernel. If you are
Expand Down

0 comments on commit 481699b

Please sign in to comment.