mirror of
https://github.com/ostreedev/ostree.git
synced 2025-01-05 13:18:17 +03:00
c29f4193cd
If requested, by specifying ot-composefs=signed=/path/to/pub.key then the commit object is validated against the specified ed25519 public key, and if valid, the composefs digest from the commit object is used to ensure we boot the right digest.
114 lines
4.3 KiB
Markdown
114 lines
4.3 KiB
Markdown
---
|
|
nav_order: 10
|
|
---
|
|
|
|
# Using composefs with OSTree
|
|
{: .no_toc }
|
|
|
|
1. TOC
|
|
{:toc}
|
|
|
|
## composefs
|
|
|
|
The [composefs](https://github.com/containers/composefs) project is a new
|
|
hybrid Linux stacking filesystem that provides many benefits when
|
|
used for bootable host systems, such as a strong story for integrity.
|
|
|
|
At the current time, integration of composefs and ostree is experimental.
|
|
[This issue](https://github.com/ostreedev/ostree/issues/2867) tracks the latest status.
|
|
|
|
### Enabling composefs (unsigned)
|
|
|
|
When building a disk image *or* to transition an existing system, run:
|
|
|
|
```
|
|
ostree config --repo=/ostree/repo set ex-integrity.composefs true
|
|
```
|
|
|
|
This will ensure that any future deployments (e.g. created by `ostree admin upgrade`)
|
|
have a `.ostree.cfs` file in the deployment directory which is a mountable
|
|
composefs metadata file, with a "backing store" directory that is
|
|
shared with the current `/ostree/repo/objects`.
|
|
|
|
### Kernel argument ot-composefs
|
|
|
|
The `ostree-prepare-root` binary will look for a kernel argument called `ot-composefs`.
|
|
|
|
The default value is `maybe` (this will likely become a build and initramfs-configurable option)
|
|
in the future too.
|
|
|
|
The possible values are:
|
|
|
|
- `off`: Never use composefs
|
|
- `maybe`: Use composefs if supported and there is a composefs image in the deployment directory
|
|
- `on`: Require composefs
|
|
- `digest=<sha256>`: Require the mounted composefs image to have a particular digest
|
|
- `signed=<path>`: Require that the commit is signed as validated by the ed25519 public key specified
|
|
by `path` (the path is resolved in the initrd).
|
|
|
|
### Injecting composefs digests
|
|
|
|
When generating an OSTree commit, there is a CLI switch `--generate-composefs-metadata`
|
|
and a corresponding C API `ostree_repo_commit_add_composefs_metadata`. This will
|
|
inject the composefs digest as metadata into the ostree commit under a metadata
|
|
key `ostree.composefs.v0`. Because an OSTree commit can be signed, this allows
|
|
covering the composefs fsverity digest with a signature.
|
|
|
|
### Signatures
|
|
|
|
If a commit is signed with a ed25519 private key (see `ostree
|
|
--sign`), and `signed=/path/to/public.key` is specified on the
|
|
commandline, then the initrd will find the commit being booted in the
|
|
system repo and validate its signature against the public key. It will
|
|
then ensure that the composefs digest being booted has an fs-verity
|
|
digest matching the one in the commit. This allows a fully trusted
|
|
read-only /usr.
|
|
|
|
The exact usage of the signature is up to the user, but a common way
|
|
to use it with transien keys. This is done like this:
|
|
* Generate a new keypair before each build
|
|
* Embed the public key in the initrd that is part of the commit.
|
|
* Ensure the kernel commandline has `ot-signed=/path/to/key`
|
|
* After commiting, run `ostree --sign` with the private key.
|
|
* Throw away the private key.
|
|
|
|
When a transient key is used this way, that ties the initrd with the
|
|
userspace part from the commit. This means each initrd can only boot
|
|
the very same userspace it was made for. For example, if an older
|
|
version of the OS has a security flaw, you can't boot a new fixed
|
|
(signed) initrd and have it boot the older userspace with the flaw.
|
|
|
|
## Requirements
|
|
|
|
The current default composefs integration in ostree does not have any
|
|
requirements from the underlying kernel and filesystem other than
|
|
having the following kernel options set:
|
|
|
|
- `CONFIG_OVERLAY_FS`
|
|
- `CONFIG_BLK_DEV_LOOP`
|
|
- `CONFIG_EROFS_FS`
|
|
|
|
At the current time, there are no additional userspace runtime requirements.
|
|
|
|
## Status
|
|
|
|
**IMPORTANT** The integration with composefs is experimental and subject to change. Please
|
|
try it and report issues but do not deploy to production systems yet.
|
|
|
|
## Comparison with other approaches
|
|
|
|
There is also support for using [IMA](ima.md) with ostree. In short, composefs
|
|
provides much stronger and more efficient integrity:
|
|
|
|
- composefs validates an entire filesystem tree, not just individual files
|
|
- composefs makes files actually read-only, whereas IMA does not by default
|
|
- composefs uses fs-verity which does on-demand verification (IMA by default does a full readahead of every file accessed, though IMA can also use fs-verity as a backend)
|
|
|
|
## Further references
|
|
|
|
- https://github.com/containers/composefs
|
|
- https://www.kernel.org/doc/html/next/filesystems/fsverity.html
|
|
|
|
<!-- SPDX-License-Identifier: (CC-BY-SA-3.0 OR GFDL-1.3-or-later) -->
|
|
|