From patchwork Tue Jul 6 18:22:15 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: =?utf-8?q?Micka=C3=ABl_Sala=C3=BCn?= X-Patchwork-Id: 12361089 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-16.8 required=3.0 tests=BAYES_00, HEADER_FROM_DIFFERENT_DOMAINS,INCLUDES_CR_TRAILER,INCLUDES_PATCH, MAILING_LIST_MULTI,SPF_HELO_NONE,SPF_PASS,URIBL_BLOCKED,USER_AGENT_GIT autolearn=ham autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 0C147C07E9E for ; Tue, 6 Jul 2021 18:23:13 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id DA44061C6D for ; Tue, 6 Jul 2021 18:23:12 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S229992AbhGFSZu (ORCPT ); Tue, 6 Jul 2021 14:25:50 -0400 Received: from smtp-8fa8.mail.infomaniak.ch ([83.166.143.168]:54589 "EHLO smtp-8fa8.mail.infomaniak.ch" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S229954AbhGFSZt (ORCPT ); Tue, 6 Jul 2021 14:25:49 -0400 Received: from smtp-3-0001.mail.infomaniak.ch (unknown [10.4.36.108]) by smtp-3-3000.mail.infomaniak.ch (Postfix) with ESMTPS id 4GK9sT588hzMprg6; Tue, 6 Jul 2021 20:23:09 +0200 (CEST) Received: from localhost (unknown [23.97.221.149]) by smtp-3-0001.mail.infomaniak.ch (Postfix) with ESMTPA id 4GK9sT2nkGzlmrrg; Tue, 6 Jul 2021 20:23:09 +0200 (CEST) From: =?utf-8?q?Micka=C3=ABl_Sala=C3=BCn?= To: Alejandro Colomar , Michael Kerrisk Cc: =?utf-8?q?Micka=C3=ABl_Sala=C3=BCn?= , Jann Horn , Jonathan Corbet , Kees Cook , Randy Dunlap , Vincent Dagonneau , landlock@lists.linux.dev, linux-kernel@vger.kernel.org, linux-man@vger.kernel.org, linux-security-module@vger.kernel.org, =?utf-8?q?Micka=C3=ABl_Sala=C3=BCn?= Subject: [PATCH v1 2/4] landlock_create_ruleset.2: Document new syscall Date: Tue, 6 Jul 2021 20:22:15 +0200 Message-Id: <20210706182217.32338-3-mic@digikod.net> X-Mailer: git-send-email 2.32.0 In-Reply-To: <20210706182217.32338-1-mic@digikod.net> References: <20210706182217.32338-1-mic@digikod.net> MIME-Version: 1.0 Precedence: bulk List-ID: From: Mickaël Salaün This is an adaptation of https://www.kernel.org/doc/html/v5.13/userspace-api/landlock.html Signed-off-by: Mickaël Salaün Link: https://lore.kernel.org/r/20210706182217.32338-3-mic@digikod.net --- man2/landlock_create_ruleset.2 | 134 +++++++++++++++++++++++++++++++++ 1 file changed, 134 insertions(+) create mode 100644 man2/landlock_create_ruleset.2 diff --git a/man2/landlock_create_ruleset.2 b/man2/landlock_create_ruleset.2 new file mode 100644 index 000000000000..5fe0f8fd808e --- /dev/null +++ b/man2/landlock_create_ruleset.2 @@ -0,0 +1,134 @@ +.\" Copyright © 2017-2020 Mickaël Salaün +.\" Copyright © 2019-2020 ANSSI +.\" Copyright © 2021 Microsoft Corporation +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH LANDLOCK_CREATE_RULESET 2 2021-06-27 Linux "Linux Programmer's Manual" +.SH NAME +landlock_create_ruleset \- create a new Landlock ruleset +.SH SYNOPSIS +.nf +.BR "#include " " /* Definition of " LANDLOCK_* " constants */" +.BR "#include " " /* Definition of " SYS_* " constants */" +.PP +.BI "int syscall(SYS_landlock_create_ruleset, +.BI " const struct landlock_ruleset_attr " attr , +.BI " size_t " size " , __u32 " flags ); +.SH DESCRIPTION +A Landlock ruleset identifies a set of rules (i.e. actions on objects). +This +.BR landlock_create_ruleset (2) +system call enables creating a new file descriptor identifying a ruleset. +This file descriptor can then be used by +.BR landlock_add_rule (2) +and +.BR landlock_restrict_self (2) +\&. See +.BR landlock (7) +for a global overview. +.PP +.I attr +specifies the properties of the new ruleset. It points to the following +structure: +.IP +.in +4n +.EX +struct landlock_ruleset_attr { + __u64 handled_access_fs; +}; +.EE +.in +.IP +.I handled_access_fs +is a bitmask of actions that is handled by this ruleset and should then be +forbidden if no rule explicitly allow them +(see +.BR "Filesystem actions" +in +.BR landlock (7) +). +This enables simply restricting ambient rights (e.g., global filesystem +access) and is needed for compatibility reasons. +.PP +.I size +must be specified as +.I sizeof(struct landlock_ruleset_attr) +for compatibility reasons. +.PP +.I flags +must be 0 if +.I attr +is used. Otherwise, +.I flags +can be set to: +.TP +.BR LANDLOCK_CREATE_RULESET_VERSION +If +.I attr +is NULL and +.I size +is 0, then the returned value is the highest supported Landlock ABI version +(starting at 1). This version can be used for a best-effort security +approach, which is encouraged when user space is not pinned to a specific +kernel version. All features documented in these man pages are available +with the version 1. +.SH RETURN VALUE +On success, +.BR landlock_create_ruleset (2) +returns a new Landlock ruleset file descriptor, or a Landlock ABI version +according to +.I flags +\&. +.SH ERRORS +.BR landlock_create_ruleset (2) +can failed for the following reasons: +.TP +.BR EOPNOTSUPP +Landlock is supported by the kernel but disabled at boot time. +.TP +.BR EINVAL +Unknown +.I flags +, or unknown access, or too small +.I size +\&. +.TP +.BR E2BIG +.I size +is too big. +.TP +.BR EFAULT +.I attr +was not a valid address. +.TP +.BR ENOMSG +Empty accesses (i.e. +.I attr->handled_access_fs +is 0). +.SH VERSIONS +Landlock was added in Linux 5.13. +.SH SEE ALSO +.BR landlock (7), +.BR landlock_add_rule (2), +.BR landlock_restrict_self (2)