[thirdparty/man-pages.git] / man2 / landlock_restrict_self.2

.\" Copyright © 2017-2020 Mickaël Salaün <mic@digikod.net>
.\" Copyright © 2019-2020 ANSSI
.\" Copyright © 2021 Microsoft Corporation
.\"
.\" SPDX-License-Identifier: Linux-man-pages-copyleft
.\"
.TH LANDLOCK_RESTRICT_SELF 2 2021-06-27 "Linux man-pages (unreleased)"
.SH NAME
landlock_restrict_self \- enforce a Landlock ruleset
.SH LIBRARY
Standard C library
.RI ( libc ", " \-lc )
.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 "            uint32_t " 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 independent 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
.B 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 ()
returns 0.
.SH ERRORS
.BR landlock_restrict_self ()
can fail for the following reasons:
.TP
.B EOPNOTSUPP
Landlock is supported by the kernel but disabled at boot time.
.TP
.B EINVAL
.I flags
is not 0.
.TP
.B EBADF
.I ruleset_fd
is not a file descriptor for the current thread.
.TP
.B EBADFD
.I ruleset_fd
is not a ruleset file descriptor.
.TP
.B EPERM
.I 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
.B 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 STANDARDS
This system call is Linux-specific.
.SH EXAMPLES
See
.BR landlock (7).
.SH SEE ALSO
.BR landlock_create_ruleset (2),
.BR landlock_add_rule (2),
.BR landlock (7)
Commit	Line	Data
3f7e4f80 MS	1	.\" Copyright © 2017-2020 Mickaël Salaün <mic@digikod.net>
	2	.\" Copyright © 2019-2020 ANSSI
	3	.\" Copyright © 2021 Microsoft Corporation
	4	.\"
5fbde956	5	.\" SPDX-License-Identifier: Linux-man-pages-copyleft
3f7e4f80	6	.\"
45186a5d	7	.TH LANDLOCK_RESTRICT_SELF 2 2021-06-27 "Linux man-pages (unreleased)"
3f7e4f80 MS	8	.SH NAME
3f7e4f80 MS	9	landlock_restrict_self \- enforce a Landlock ruleset
127d9e7f AC	10	.SH LIBRARY
127d9e7f AC	11	Standard C library
8fc3b2cf	12	.RI ( libc ", " \-lc )
3f7e4f80 MS	13	.SH SYNOPSIS
	14	.nf
	15	.BR "#include <linux/landlock.h>" " /* Definition of " LANDLOCK_* " constants */"
	16	.BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
	17	.PP
	18	.BI "int syscall(SYS_landlock_restrict_self, int " ruleset_fd ,
085a9296	19	.BI " uint32_t " flags );
3f7e4f80 MS	20	.SH DESCRIPTION
	21	Once a Landlock ruleset is populated with the desired rules, the
	22	.BR landlock_restrict_self ()
	23	system call enables enforcing this ruleset on the calling thread.
	24	See
	25	.BR landlock (7)
	26	for a global overview.
	27	.PP
085a9296 AC	28	A thread can be restricted with multiple rulesets that are then
	29	composed together to form the thread's Landlock domain.
	30	This can be seen as a stack of rulesets but
	31	it is implemented in a more efficient way.
	32	A domain can only be updated in such a way that
	33	the constraints of each past and future composed rulesets
	34	will restrict the thread and its future children for their entire life.
3f7e4f80	35	It is then possible to gradually enforce tailored access control policies
61136d55	36	with multiple independent rulesets coming from different sources
3f7e4f80 MS	37	(e.g., init system configuration, user session policy,
	38	built-in application policy).
	39	However, most applications should only need one call to
	40	.BR landlock_restrict_self ()
	41	and they should avoid arbitrary numbers of such calls because of the
	42	composed rulesets limit.
	43	Instead, developers are encouraged to build a tailored ruleset thanks to
	44	multiple calls to
	45	.BR landlock_add_rule (2).
	46	.PP
	47	In order to enforce a ruleset, either the caller must have the
	48	.B CAP_SYS_ADMIN
	49	capability in its user namespace, or the thread must already have the
	50	.I no_new_privs
	51	bit set.
	52	As for
	53	.BR seccomp (2),
085a9296 AC	54	this avoids scenarios where unprivileged processes can affect
085a9296 AC	55	the behavior of privileged children (e.g., because of set-user-ID binaries).
3f7e4f80 MS	56	If that bit was not already set by an ancestor of this thread,
	57	the thread must make the following call:
	58	.IP
	59	.EX
	60	prctl(PR_SET_NO_NEW_PRIVS, 1, 0, 0, 0);
	61	.EE
	62	.PP
	63	.I ruleset_fd
	64	is a Landlock ruleset file descriptor obtained with
	65	.BR landlock_create_ruleset (2)
	66	and fully populated with a set of calls to
	67	.BR landlock_add_rule (2).
	68	.PP
	69	.I flags
	70	must be 0.
	71	.SH RETURN VALUE
	72	On success,
	73	.BR landlock_restrict_self ()
	74	returns 0.
	75	.SH ERRORS
	76	.BR landlock_restrict_self ()
085a9296	77	can fail for the following reasons:
3f7e4f80 MS	78	.TP
	79	.B EOPNOTSUPP
	80	Landlock is supported by the kernel but disabled at boot time.
	81	.TP
	82	.B EINVAL
	83	.I flags
	84	is not 0.
	85	.TP
	86	.B EBADF
	87	.I ruleset_fd
	88	is not a file descriptor for the current thread.
	89	.TP
	90	.B EBADFD
	91	.I ruleset_fd
	92	is not a ruleset file descriptor.
	93	.TP
	94	.B EPERM
	95	.I ruleset_fd
	96	has no read access to the underlying ruleset,
	97	or the calling thread is not running with
	98	.IR no_new_privs ,
	99	or it doesn't have the
	100	.B CAP_SYS_ADMIN
	101	in its user namespace.
	102	.TP
	103	.B E2BIG
	104	The maximum number of composed rulesets is reached for the calling thread.
	105	This limit is currently 64.
	106	.SH VERSIONS
	107	Landlock was added in Linux 5.13.
3113c7f3	108	.SH STANDARDS
3f7e4f80 MS	109	This system call is Linux-specific.
	110	.SH EXAMPLES
	111	See
	112	.BR landlock (7).
	113	.SH SEE ALSO
	114	.BR landlock_create_ruleset (2),
	115	.BR landlock_add_rule (2),
	116	.BR landlock (7)