From e9e1ead66cd5d788e0e98945ac6983c233a1a8b9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micka=C3=ABl=20Sala=C3=BCn?= Date: Thu, 14 Sep 2023 12:36:27 +0200 Subject: [PATCH] compat: Improve the ABI documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Explain more clearly why sticking to a specific Landlock ABI version to infer access rights is highly recommended. Add links to the landlock-test-tools repository and related CI changes. Signed-off-by: Mickaël Salaün --- src/compat.rs | 31 +++++++++++++++++++++++-------- src/fs.rs | 10 +++++----- 2 files changed, 28 insertions(+), 13 deletions(-) diff --git a/src/compat.rs b/src/compat.rs index 4017b6c7..e08ceead 100644 --- a/src/compat.rs +++ b/src/compat.rs @@ -9,21 +9,36 @@ use strum_macros::{EnumCount as EnumCountMacro, EnumIter}; /// Version of the Landlock [ABI](https://en.wikipedia.org/wiki/Application_binary_interface). /// -/// `ABI` enables to get the features supported by a specific Landlock ABI. +/// `ABI` enables getting the features supported by a specific Landlock ABI +/// (without relying on the kernel version which may not be accessible or patched). /// For example, [`AccessFs::from_all(ABI::V1)`](Access::from_all) /// gets all the file system access rights defined by the first version. /// /// Without `ABI`, it would be hazardous to rely on the the full set of access flags /// (e.g., `BitFlags::::all()` or `BitFlags::ALL`), /// a moving target that would change the semantics of your Landlock rule -/// when migrating to a newer version of this crate -/// (i.e. non-breaking change with new supported features). -/// This usage should then be considered indeterministic because requested features -/// (e.g., access rights) -/// could not be tied to the application source code. +/// when migrating to a newer version of this crate. +/// Indeed, a simple `cargo update` or `cargo install` run by any developer +/// can result in a new version of this crate (fixing bugs or bringing non-breaking changes). +/// This crate cannot give any guarantee concerning the new restrictions resulting from +/// these unknown bits (i.e. access rights) that would not be controlled by your application but by +/// a future version of this crate instead. +/// Because we cannot know what the effect on your application of an unknown restriction would be +/// when handling an untested Landlock access right (i.e. denied-by-default access), +/// it could trigger bugs in your application. /// -/// Such `ABI` is also convenient to get the features supported by a specific Linux kernel -/// without relying on the kernel version (which may not be accessible or patched). +/// This crate provides a set of tools to sandbox as much as possible +/// while guaranteeing a consistent behavior thanks to the [`Compatible`] methods. +/// You should also test with different relevant kernel versions, +/// see [landlock-test-tools](https://github.com/landlock-lsm/landlock-test-tools) and +/// [CI integration](https://github.com/landlock-lsm/rust-landlock/pull/41). +/// +/// This way, we can have the guarantee that the use of a set of tested Landlock ABI works as +/// expected because features brought by newer Landlock ABI will never be enabled by default +/// (cf. [Linux kernel compatibility contract](https://docs.kernel.org/userspace-api/landlock.html#compatibility)). +/// +/// In a nutshell, test the access rights you request on a kernel that support them and +/// on a kernel that doesn't support them. #[cfg_attr( test, derive(Debug, PartialEq, Eq, PartialOrd, EnumIter, EnumCountMacro) diff --git a/src/fs.rs b/src/fs.rs index ec1954ee..3ebf9c08 100644 --- a/src/fs.rs +++ b/src/fs.rs @@ -44,11 +44,11 @@ use strum::IntoEnumIterator; /// /// # Warning /// -/// To avoid compile time behavior at run time, -/// which may look like undefined behavior, -/// don't use `BitFlags::::all()` nor `BitFlags::ALL`, -/// but [`AccessFs::from_all(ABI::V1)`](Access::from_all) instead. -/// See [`ABI`] for the rational. +/// To avoid unknown restrictions **don't use `BitFlags::::all()` nor `BitFlags::ALL`**, +/// but use a version you tested and vetted instead, +/// for instance [`AccessFs::from_all(ABI::V1)`](Access::from_all). +/// Direct use of **the [`BitFlags`] API is deprecated**. +/// See [`ABI`] for the rationale and help to test it. #[bitflags] #[repr(u64)] #[derive(Copy, Clone, Debug, PartialEq, Eq)]