c9725d0bef
Currently the P2P code requires you to trust every remote you have configured to the same extent, because a remote controlled by a malicious actor can serve updates to refs (such as Flatpak apps) installed from other remotes.[1] The way this attack would play out is that the malicious remote would deploy the same collection ID as the victim remote, and would then be able to serve updates for it. One possible remedy would be to make it an error to configure remotes such that two have the same collection ID but differing GPG keys. I attempted to do that in Flatpak[2] but it proved difficult because it is valid to configure two remotes with the same collection ID, and they may then each want to update their keyrings which wouldn't happen atomically. Another potential solution I've considered is to add a `trusted-remotes` option to ostree_repo_find_remotes_async() which would dictate which keyring to use when pulling each ref. However the ostree_repo_finder_resolve_async() API would still remain vulnerable, and changing that would require rewriting a large chunk of libostree's P2P support. So this commit represents a third attempt at mitigating this security hole, namely to have the client specify which remote to use for GPG verification at pull time. This way the pull will fail if the commits are signed with anything other than the keys we actually trust to serve updates. This is implemented as an option "ref-keyring-map" for ostree_repo_pull_from_remotes_async() and ostree_repo_pull_with_options() which dictates the remote to be used for GPG verification of each collection-ref. I think specifying a keyring remote for each ref is better than specifying a remote for each OstreeRepoFinderResult, because there are some edge cases where a result could serve updates to refs which were installed from more than one remote. The PR to make Flatpak use this new option is here[3]. [1] https://github.com/flatpak/flatpak/issues/1447 [2] https://github.com/flatpak/flatpak/pull/2601 [3] https://github.com/flatpak/flatpak/pull/2705 Closes: #1810 Approved by: cgwalters |
||
|---|---|---|
| apidoc | ||
| bash | ||
| bsdiff@1edf9f6568 | ||
| build-aux | ||
| buildutil | ||
| ci | ||
| coccinelle | ||
| docs | ||
| libglnx@b1cb19b6b2 | ||
| man | ||
| manual-tests | ||
| rust | ||
| src | ||
| tests | ||
| .dir-locals.el | ||
| .editorconfig | ||
| .gitmodules | ||
| .papr-ex.yaml | ||
| .papr.yml | ||
| .travis.yml | ||
| .vimrc | ||
| CONTRIBUTING.md | ||
| COPYING | ||
| GNUmakefile | ||
| Makefile-bash.am | ||
| Makefile-boot.am | ||
| Makefile-decls.am | ||
| Makefile-libostree-defines.am | ||
| Makefile-libostree.am | ||
| Makefile-man.am | ||
| Makefile-ostree.am | ||
| Makefile-otutil.am | ||
| Makefile-switchroot.am | ||
| Makefile-tests.am | ||
| Makefile.am | ||
| README-historical.md | ||
| README.md | ||
| TODO | ||
| autogen.sh | ||
| cfg.mk | ||
| configure.ac | ||
| git.mk | ||
| maint.mk | ||
| mkdocs.yml | ||
| ostree.doap | ||
README.md
libostree
New! See the docs online at Read The Docs (OSTree)
This project is now known as "libostree", though it is still appropriate to use the previous name: "OSTree" (or "ostree"). The focus is on projects which use libostree's shared library, rather than users directly invoking the command line tools (except for build systems). However, in most of the rest of the documentation, we will use the term "OSTree", since it's slightly shorter, and changing all documentation at once is impractical. We expect to transition to the new name over time.
As implied above, libostree is both a shared library and suite of command line tools that combines a "git-like" model for committing and downloading bootable filesystem trees, along with a layer for deploying them and managing the bootloader configuration.
The core OSTree model is like git in that it checksums individual files and has a content-addressed-object store. It's unlike git in that it "checks out" the files via hardlinks, and they thus need to be immutable to prevent corruption. Therefore, another way to think of OSTree is that it's just a more polished version of Linux VServer hardlinks.
Features:
- Transactional upgrades and rollback for the system
- Replicating content incrementally over HTTP via GPG signatures and "pinned TLS" support
- Support for parallel installing more than just 2 bootable roots
- Binary history on the server side (and client)
- Introspectable shared library API for build and deployment systems
- Flexible support for multiple branches and repositories, supporting projects like flatpak which use libostree for applications, rather than hosts.
Projects using OSTree
meta-updater is a layer available for OpenEmbedded systems.
QtOTA is Qt's over-the-air update framework which uses libostree.
rpm-ostree is a next-generation hybrid package/image system for Fedora and CentOS, used by the Atomic Host project. By default it uses libostree to atomically replicate a base OS (all dependency resolution is done on the server), but it supports "package layering", where additional RPMs can be layered on top of the base. This brings a "best of both worlds"" model for image and package systems.
flatpak uses libostree for desktop application containers. Unlike most of the other systems here, flatpak does not use the "libostree host system" aspects (e.g. bootloader management), just the "git-like hardlink dedup". For example, flatpak supports a per-user OSTree repository.
Endless OS uses libostree for their host system as well as flatpak. See their eos-updater and deb-ostree-builder projects.
GNOME Continuous is where OSTree was born - as a high performance continuous delivery/testing system for GNOME.
The BuildStream build and integration tool uses libostree as a caching system to store and share built artifacts.
Liri OS has the option to install their distribution using ostree.
Language bindings
libostree is accessible via GObject Introspection; any language which has implemented the GI binding model should work. For example, Both pygobject and gjs are known to work and further are actually used in libostree's test suite today.
Some bindings take the approach of using GI as a lower level and write higher level manual bindings on top; this is more common for statically compiled languages. Here's a list of such bindings:
Building
Releases are available as GPG signed git tags, and most recent versions support extended validation using git-evtag.
However, in order to build from a git clone, you must update the submodules. If you're packaging OSTree and want a tarball, I recommend using a "recursive git archive" script. There are several available online; this code in OSTree is an example.
Once you have a git clone or recursive archive, building is the same as almost every autotools project:
git submodule update --init
env NOCONFIGURE=1 ./autogen.sh
./configure --prefix=...
make
make install DESTDIR=/path/to/dest
More documentation
New! See the docs online at Read The Docs (OSTree)
Contributing
See Contributing.
Licensing
The licensing for the code of libostree can be canonically found in the individual files; and the overall status in the COPYING file in the source. Currently, that's LGPLv2+. This also covers the man pages and API docs.
The license for the manual documentation in the doc/ directory is:
SPDX-License-Identifier: (CC-BY-SA-3.0 OR GFDL-1.3-or-later)
This is intended to allow use by Wikipedia and other projects.
In general, files should have a SPDX-License-Identifier and that is canonical.