[PATCH v1 4/4] landlock_restrict_self.2: Document new syscall

[Mickaël Salaün]

From: Mickaël Salaün <mic@xxxxxxxxxxxxxxxxxxx>

This is an adaptation of
https://www.kernel.org/doc/html/v5.13/userspace-api/landlock.html

Signed-off-by: Mickaël Salaün <mic@xxxxxxxxxxxxxxxxxxx>
Link: https://lore.kernel.org/r/20210706182217.32338-5-mic@xxxxxxxxxxx
---
 man2/landlock_restrict_self.2 | 125 ++++++++++++++++++++++++++++++++++
 1 file changed, 125 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..589fe972487c
--- /dev/null
+++ b/man2/landlock_restrict_self.2
@@ -0,0 +1,125 @@
+.\" Copyright © 2017-2020 Mickaël Salaün <mic@xxxxxxxxxxx>
+.\" 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 (2)
+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 (2)
+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
+.I 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
+.I 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
+.I flags
+must be 0.
+.SH RETURN VALUE
+On success,
+.BR landlock_restrict_self (2)
+returns 0.
+.SH ERRORS
+.BR landlock_restrict_self (2)
+can failed for the following reasons:
+.TP
+.BR EOPNOTSUPP
+Landlock is supported by the kernel but disabled at boot time.
+.TP
+.BR EINVAL
+.I flags
+is not 0.
+.TP
+.BR EBADF
+.I ruleset_fd
+is not a file descriptor for the current thread.
+.TP
+.BR EBADFD
+.I ruleset_fd
+is not a ruleset file descriptor.
+.TP
+.BR EPERM
+.I ruleset_fd
+has no read access to the underlying ruleset, or the calling thread is not
+running with
+.I no_new_privs
+, or it doesn't have the
+.BR CAP_SYS_ADMIN
+in its user namespace.
+.TP
+.BR 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 SEE ALSO
+.BR landlock (7),
+.BR landlock_create_ruleset (2),
+.BR landlock_add_rule (2)
-- 
2.32.0