man2/landlock_restrict_self.2

   1 .\" Copyright © 2017-2020 Mickaël Salaün <mic@digikod.net>
   2 .\" Copyright © 2019-2020 ANSSI
   3 .\" Copyright © 2021 Microsoft Corporation
   4 .\"
   5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   6 .\"
   7 .TH LANDLOCK_RESTRICT_SELF 2 (date) "Linux man-pages (unreleased)"
   8 .SH NAME
   9 landlock_restrict_self \- enforce a Landlock ruleset
  10 .SH LIBRARY
  11 Standard C library
  12 .RI ( libc ", " \-lc )
  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 ,
  19 .BI "            uint32_t " flags );
  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
  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.
  35 It is then possible to gradually enforce tailored access control policies
  36 with multiple independent rulesets coming from different sources
  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),
  54 this avoids scenarios where unprivileged processes can affect
  55 the behavior of privileged children (e.g., because of set-user-ID binaries).
  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 ()
  77 can fail for the following reasons:
  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.
 108 .SH STANDARDS
 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)