man2/landlock_create_ruleset.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_CREATE_RULESET 2 2022-09-09 "Linux man-pages (unreleased)"
   8 .SH NAME
   9 landlock_create_ruleset \- create a new 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 .B int syscall(SYS_landlock_create_ruleset,
  19 .BI "            const struct landlock_ruleset_attr *" attr ,
  20 .BI "            size_t " size " , uint32_t " flags );
  21 .fi
  22 .SH DESCRIPTION
  23 A Landlock ruleset identifies a set of rules (i.e., actions on objects).
  24 This
  25 .BR landlock_create_ruleset ()
  26 system call enables creating a new file descriptor identifying a ruleset.
  27 This file descriptor can then be used by
  28 .BR landlock_add_rule (2)
  29 and
  30 .BR landlock_restrict_self (2).
  31 See
  32 .BR landlock (7)
  33 for a global overview.
  34 .PP
  35 .I attr
  36 specifies the properties of the new ruleset.
  37 It points to the following structure:
  38 .IP
  39 .in +4n
  40 .EX
  41 struct landlock_ruleset_attr {
  42     __u64 handled_access_fs;
  43 };
  44 .EE
  45 .in
  46 .IP
  47 .I handled_access_fs
  48 is a bitmask of actions that is handled by this ruleset and
  49 should then be forbidden if no rule explicitly allows them
  50 (see
  51 .B Filesystem actions
  52 in
  53 .BR landlock (7)).
  54 This enables simply restricting ambient rights
  55 (e.g., global filesystem access) and is needed for compatibility reasons.
  56 .PP
  57 .I size
  58 must be specified as
  59 .I sizeof(struct landlock_ruleset_attr)
  60 for compatibility reasons.
  61 .PP
  62 .I flags
  63 must be 0 if
  64 .I attr
  65 is used.
  66 Otherwise,
  67 .I flags
  68 can be set to:
  69 .TP
  70 .B LANDLOCK_CREATE_RULESET_VERSION
  71 If
  72 .I attr
  73 is NULL and
  74 .I size
  75 is 0, then the returned value is the highest supported Landlock ABI version
  76 (starting at 1).
  77 This version can be used for a best-effort security approach,
  78 which is encouraged when user space is not pinned to a specific kernel
  79 version.
  80 All features documented in these man pages are available with the version
  81 1.
  82 .SH RETURN VALUE
  83 On success,
  84 .BR landlock_create_ruleset ()
  85 returns a new Landlock ruleset file descriptor,
  86 or a Landlock ABI version,
  87 according to
  88 .IR flags .
  89 .SH ERRORS
  90 .BR landlock_create_ruleset ()
  91 can fail for the following reasons:
  92 .TP
  93 .B EOPNOTSUPP
  94 Landlock is supported by the kernel but disabled at boot time.
  95 .TP
  96 .B EINVAL
  97 Unknown
  98 .IR flags ,
  99 or unknown access, or too small
 100 .IR size .
 101 .TP
 102 .B E2BIG
 103 .I size
 104 is too big.
 105 .TP
 106 .B EFAULT
 107 .I attr
 108 was not a valid address.
 109 .TP
 110 .B ENOMSG
 111 Empty accesses (i.e.,
 112 .I attr->handled_access_fs
 113 is 0).
 114 .SH VERSIONS
 115 Landlock was added in Linux 5.13.
 116 .SH STANDARDS
 117 This system call is Linux-specific.
 118 .SH EXAMPLES
 119 See
 120 .BR landlock (7).
 121 .SH SEE ALSO
 122 .BR landlock_add_rule (2),
 123 .BR landlock_restrict_self (2),
 124 .BR landlock (7)