Update the user space documentation for the new LANDLOCK_ACCESS_FS_READ_METADATA and LANDLOCK_ACCESS_FS_WRITE_METADATA access rights: add them to the example ruleset attributes, extend the ABI version fallback switch to remove them for ABI < 13, and document their semantics in a new "File metadata" section, including the fact that only explicit metadata changes requested by user space are restricted.
The new section also warns that most of the time, LANDLOCK_ACCESS_FS_READ_METADATA should be granted together with LANDLOCK_ACCESS_FS_READ_FILE and LANDLOCK_ACCESS_FS_READ_DIR: programs commonly read metadata alongside file contents and directory listings (e.g. with stat(2)) and do not expect such calls to fail, while denying only READ_FILE or READ_DIR does not hide metadata. Assisted-by: opencode: glm-5.3 Signed-off-by: Cai Xinchen <[email protected]> --- Documentation/userspace-api/landlock.rst | 47 +++++++++++++++++++++++- 1 file changed, 46 insertions(+), 1 deletion(-) diff --git a/Documentation/userspace-api/landlock.rst b/Documentation/userspace-api/landlock.rst index 3d45b956b640..62fe39a8b61e 100644 --- a/Documentation/userspace-api/landlock.rst +++ b/Documentation/userspace-api/landlock.rst @@ -87,7 +87,9 @@ to be explicit about the denied-by-default access rights. LANDLOCK_ACCESS_FS_REFER | LANDLOCK_ACCESS_FS_TRUNCATE | LANDLOCK_ACCESS_FS_IOCTL_DEV | - LANDLOCK_ACCESS_FS_RESOLVE_UNIX, + LANDLOCK_ACCESS_FS_RESOLVE_UNIX | + LANDLOCK_ACCESS_FS_READ_METADATA | + LANDLOCK_ACCESS_FS_WRITE_METADATA, .handled_access_net = LANDLOCK_ACCESS_NET_BIND_TCP | LANDLOCK_ACCESS_NET_CONNECT_TCP | @@ -159,6 +161,10 @@ version, and only use the available subset of access rights: ruleset_attr.handled_permissions &= ~(LANDLOCK_PERMISSION_NAMESPACE_USE | LANDLOCK_PERMISSION_CAPABILITY_USE); + /* Removes metadata rights for ABI < 13 */ + ruleset_attr.handled_access_fs &= + ~(LANDLOCK_ACCESS_FS_READ_METADATA | + LANDLOCK_ACCESS_FS_WRITE_METADATA); } This enables the creation of an inclusive ruleset that will contain our rules. @@ -669,6 +675,45 @@ for writing, sidestepping the ``LANDLOCK_ACCESS_FS_TRUNCATE`` right. The truncate right is associated with the opened file (see below). +File metadata +------------- + +The ``LANDLOCK_ACCESS_FS_READ_METADATA`` right governs reading file and +directory metadata: :manpage:`stat(2)` and friends, +:manpage:`getxattr(2)`, :manpage:`listxattr(2)` and friends, and POSIX ACL +reads. + +The ``LANDLOCK_ACCESS_FS_WRITE_METADATA`` right governs explicit changes to +file and directory metadata: :manpage:`chmod(2)` and friends, +:manpage:`chown(2)` and friends, :manpage:`utimensat(2)`, +:manpage:`setxattr(2)`, :manpage:`removexattr(2)` and friends, and POSIX ACL +changes. Both rights apply to files and directories alike. + +Implicit metadata changes performed by the kernel are not restricted by +``LANDLOCK_ACCESS_FS_WRITE_METADATA``: reading a file may update its access +time, writing a file updates its modification and change times and may change +the file size, and writing to or truncating a file with a set-user-ID or +set-group-ID bit clears these bits. File size changes through +:manpage:`truncate(2)` and friends are governed by +``LANDLOCK_ACCESS_FS_TRUNCATE`` instead. Metadata change requests that do +not change any attribute (e.g. :manpage:`chown(2)` with owner and group +``-1``) are not restricted either. + +.. warning:: + + Many programs read metadata as part of reading file contents or listing + directories (e.g. calling :manpage:`stat(2)` before or after + :manpage:`open(2)`), and do not expect such calls to fail with + ``EACCES``. Most of the time, ``LANDLOCK_ACCESS_FS_READ_METADATA`` + should therefore be granted together with + ``LANDLOCK_ACCESS_FS_READ_FILE`` and ``LANDLOCK_ACCESS_FS_READ_DIR``. + Conversely, denying only ``LANDLOCK_ACCESS_FS_READ_FILE`` or + ``LANDLOCK_ACCESS_FS_READ_DIR`` does not hide metadata: it remains + readable through :manpage:`stat(2)` and friends unless + ``LANDLOCK_ACCESS_FS_READ_METADATA`` is denied as well. Tailored + programs that do not read metadata at all can still deny this right to + further restrict their sandbox. + Rights associated with file descriptors --------------------------------------- -- 2.18.0.huawei.25
