From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from smtp-190c.mail.infomaniak.ch (smtp-190c.mail.infomaniak.ch [185.125.25.12]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 58D2B17F for ; Mon, 12 Jul 2021 15:57:42 +0000 (UTC) Received: from smtp-3-0001.mail.infomaniak.ch (unknown [10.4.36.108]) by smtp-3-3000.mail.infomaniak.ch (Postfix) with ESMTPS id 4GNpLk5BplzMpnmp; Mon, 12 Jul 2021 17:57:34 +0200 (CEST) Received: from localhost (unknown [23.97.221.149]) by smtp-3-0001.mail.infomaniak.ch (Postfix) with ESMTPA id 4GNpLk3CtFzlmrrX; Mon, 12 Jul 2021 17:57:34 +0200 (CEST) From: =?UTF-8?q?Micka=C3=ABl=20Sala=C3=BCn?= To: Alejandro Colomar , Michael Kerrisk Cc: =?UTF-8?q?Micka=C3=ABl=20Sala=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=20Sala=C3=BCn?= Subject: [PATCH v2 2/4] landlock_create_ruleset.2: Document new syscall Date: Mon, 12 Jul 2021 17:57:43 +0200 Message-Id: <20210712155745.831580-3-mic@digikod.net> X-Mailer: git-send-email 2.32.0 In-Reply-To: <20210712155745.831580-1-mic@digikod.net> References: <20210712155745.831580-1-mic@digikod.net> Precedence: bulk X-Mailing-List: landlock@lists.linux.dev List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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/20210712155745.831580-3-mic@digikod.net --- Changes since v1: * Replace all ".I" with ".IR", except when used for titles. * Append punctuation to ".IR" and ".BR" when it makes sense (requested by Alejandro Colomar). * Cut lines according to the semantic newline rules (requested by Alejandro Colomar). * Remove roman style from ".TP" section titles (requested by Alejandro Colomar). * Add comma after "i.e." and "e.g.". * Add a "CONFORMING TO" section. * Replace "(2)" with "()" for the described syscall name. --- man2/landlock_create_ruleset.2 | 136 +++++++++++++++++++++++++++++++++ 1 file changed, 136 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..38029c2cc48a --- /dev/null +++ b/man2/landlock_create_ruleset.2 @@ -0,0 +1,136 @@ +.\" 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 () +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 +.IR 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 +.IR 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 +.IR size +must be specified as +.IR "sizeof(struct landlock_ruleset_attr)" +for compatibility reasons. +.PP +.IR flags +must be 0 if +.IR attr +is used. +Otherwise, +.IR flags +can be set to: +.TP +.B LANDLOCK_CREATE_RULESET_VERSION +If +.IR attr +is NULL and +.IR 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 () +returns a new Landlock ruleset file descriptor, or a Landlock ABI version +according to +.IR flags . +.SH ERRORS +.BR landlock_create_ruleset () +can failed for the following reasons: +.TP +.B EOPNOTSUPP +Landlock is supported by the kernel but disabled at boot time. +.TP +.B EINVAL +Unknown +.IR flags , +or unknown access, or too small +.IR size . +.TP +.B E2BIG +.IR size +is too big. +.TP +.B EFAULT +.IR attr +was not a valid address. +.TP +.B ENOMSG +Empty accesses (i.e., +.IR attr->handled_access_fs +is 0). +.SH VERSIONS +Landlock was added in Linux 5.13. +.SH CONFORMING TO +This system call is Linux-specific. +.SH SEE ALSO +.BR landlock (7), +.BR landlock_add_rule (2), +.BR landlock_restrict_self (2) -- 2.32.0