From: "Mickaël Salaün" <email@example.com> To: Alejandro Colomar <firstname.lastname@example.org>, Michael Kerrisk <email@example.com> Cc: "Mickaël Salaün" <firstname.lastname@example.org>, "Jann Horn" <email@example.com>, "Jonathan Corbet" <firstname.lastname@example.org>, "Kees Cook" <email@example.com>, "Randy Dunlap" <firstname.lastname@example.org>, "Vincent Dagonneau" <email@example.com>, firstname.lastname@example.org, email@example.com, firstname.lastname@example.org, email@example.com, "Mickaël Salaün" <firstname.lastname@example.org> Subject: [PATCH v2 4/4] landlock_restrict_self.2: Document new syscall Date: Mon, 12 Jul 2021 17:57:45 +0200 [thread overview] Message-ID: <email@example.com> (raw) In-Reply-To: <firstname.lastname@example.org> From: Mickaël Salaün <email@example.com> This is an adaptation of https://www.kernel.org/doc/html/v5.13/userspace-api/landlock.html Signed-off-by: Mickaël Salaün <firstname.lastname@example.org> Link: https://email@example.com --- 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_restrict_self.2 | 130 ++++++++++++++++++++++++++++++++++ 1 file changed, 130 insertions(+) create mode 100644 man2/landlock_restrict_self.2 diff --git a/man2/landlock_restrict_self.2 b/man2/landlock_restrict_self.2 new file mode 100644 index 000000000000..41b21278905a --- /dev/null +++ b/man2/landlock_restrict_self.2 @@ -0,0 +1,130 @@ +.\" Copyright © 2017-2020 Mickaël Salaün <firstname.lastname@example.org> +.\" 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_RESTRICT_SELF 2 2021-06-27 Linux "Linux Programmer's Manual" +.SH NAME +landlock_restrict_self \- enforce a Landlock ruleset +.SH SYNOPSIS +.nf +.BR "#include <linux/landlock.h>" " /* Definition of " LANDLOCK_* " constants */" +.BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */" +.PP +.BI "int syscall(SYS_landlock_restrict_self, int " ruleset_fd , +.BI " __u32 " flags ); +.SH DESCRIPTION +Once a Landlock ruleset is populated with the desired rules, the +.BR landlock_restrict_self () +system call enables enforcing this ruleset on the calling thread. +See +.BR landlock (7) +for a global overview. +.PP +A thread can be restricted with multiple rulesets that are then composed +together to form the thread's Landlock domain. +This can be seen as a stack of rulesets but it is implemented in a more +efficient way. +A domain can only be updated in such a way that the constraints of each +past and future composed rulesets will restrict the thread and its future +children for their entire life. +It is then possible to gradually enforce tailored access control policies +with multiple independant rulesets coming from different sources +(e.g., init system configuration, user session policy, +built-in application policy). +However, most applications should only need one call to +.BR landlock_restrict_self () +and they should avoid arbitrary numbers of such calls because of the +composed rulesets limit. +Instead, developers are encouraged to build a tailored ruleset thanks to +multiple calls to +.BR landlock_add_rule (2). +.PP +In order to enforce a ruleset, either the caller must have the +.BR CAP_SYS_ADMIN +capability in its user namespace, or the thread must already have the +.IR no_new_privs +bit set. +As for +.BR seccomp (2), +this avoids scenarios where unprivileged processes can affect the behavior +of privileged children (e.g., because of set-user-ID binaries). +If that bit was not already set by an ancestor of this thread, +the thread must make the following call: +.IP +.EX +prctl(PR_SET_NO_NEW_PRIVS, 1, 0, 0, 0); +.EE +.PP +.IR ruleset_fd +is a Landlock ruleset file descriptor obtained with +.BR landlock_create_ruleset (2) +and fully populated with a set of calls to +.BR landlock_add_rule (2). +.PP +.IR flags +must be 0. +.SH RETURN VALUE +On success, +.BR landlock_restrict_self () +returns 0. +.SH ERRORS +.BR landlock_restrict_self () +can failed for the following reasons: +.TP +.B EOPNOTSUPP +Landlock is supported by the kernel but disabled at boot time. +.TP +.B EINVAL +.IR flags +is not 0. +.TP +.B EBADF +.IR ruleset_fd +is not a file descriptor for the current thread. +.TP +.B EBADFD +.IR ruleset_fd +is not a ruleset file descriptor. +.TP +.B EPERM +.IR ruleset_fd +has no read access to the underlying ruleset, +or the calling thread is not running with +.IR no_new_privs , +or it doesn't have the +.BR CAP_SYS_ADMIN +in its user namespace. +.TP +.B E2BIG +The maximum number of composed rulesets is reached for the calling thread. +This limit is currently 64. +.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_create_ruleset (2), +.BR landlock_add_rule (2) -- 2.32.0
prev parent reply other threads:[~2021-07-12 15:57 UTC|newest] Thread overview: 17+ messages / expand[flat|nested] mbox.gz Atom feed top 2021-07-12 15:57 [PATCH v2 0/4] Add Landlock man pages Mickaël Salaün 2021-07-12 15:57 ` [PATCH v2 1/4] landlock.7: Add a new page to introduce Landlock Mickaël Salaün 2021-07-29 14:56 ` Alejandro Colomar (man-pages) 2021-07-29 22:01 ` G. Branden Robinson 2021-07-29 22:34 ` Alejandro Colomar (man-pages) 2021-07-30 12:15 ` Mickaël Salaün 2021-07-30 12:41 ` Alejandro Colomar (man-pages) 2021-07-30 12:59 ` Alejandro Colomar (man-pages) 2021-07-30 14:32 ` Mickaël Salaün 2021-07-31 0:15 ` G. Branden Robinson 2021-07-31 11:02 ` Alejandro Colomar (man-pages) 2021-07-30 23:39 ` G. Branden Robinson 2021-07-31 10:51 ` Alejandro Colomar (man-pages) 2021-07-31 13:48 ` G. Branden Robinson 2021-07-12 15:57 ` [PATCH v2 2/4] landlock_create_ruleset.2: Document new syscall Mickaël Salaün 2021-07-12 15:57 ` [PATCH v2 3/4] landlock_add_rule.2: " Mickaël Salaün 2021-07-12 15:57 ` Mickaël Salaün [this message]
Reply instructions: You may reply publicly to this message via plain-text email using any one of the following methods: * Save the following mbox file, import it into your mail client, and reply-to-all from there: mbox Avoid top-posting and favor interleaved quoting: https://en.wikipedia.org/wiki/Posting_style#Interleaved_style * Reply using the --to, --cc, and --in-reply-to switches of git-send-email(1): git send-email \ --email@example.com \ --firstname.lastname@example.org \ --email@example.com \ --firstname.lastname@example.org \ --email@example.com \ --firstname.lastname@example.org \ --email@example.com \ --firstname.lastname@example.org \ --email@example.com \ --firstname.lastname@example.org \ --email@example.com \ --firstname.lastname@example.org \ --email@example.com \ --firstname.lastname@example.org \ --subject='Re: [PATCH v2 4/4] landlock_restrict_self.2: Document new syscall' \ /path/to/YOUR_REPLY https://kernel.org/pub/software/scm/git/docs/git-send-email.html * If your mail client supports setting the In-Reply-To header via mailto: links, try the mailto: link
This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for NNTP newsgroup(s).