From patchwork Tue Jul 6 18:22:14 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: =?utf-8?q?Micka=C3=ABl_Sala=C3=BCn?= X-Patchwork-Id: 12361087 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-21.8 required=3.0 tests=BAYES_00, HEADER_FROM_DIFFERENT_DOMAINS,INCLUDES_CR_TRAILER,INCLUDES_PATCH, MAILING_LIST_MULTI,MENTIONS_GIT_HOSTING,SPF_HELO_NONE,SPF_PASS,URIBL_BLOCKED, USER_AGENT_GIT autolearn=ham autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 86F6AC07E9C for ; Tue, 6 Jul 2021 18:23:12 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 58E9561C6A for ; Tue, 6 Jul 2021 18:23:12 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S231254AbhGFSZu (ORCPT ); Tue, 6 Jul 2021 14:25:50 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:56306 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S231208AbhGFSZt (ORCPT ); Tue, 6 Jul 2021 14:25:49 -0400 Received: from smtp-42a9.mail.infomaniak.ch (smtp-42a9.mail.infomaniak.ch [IPv6:2001:1600:3:17::42a9]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 7213CC061760 for ; Tue, 6 Jul 2021 11:23:10 -0700 (PDT) Received: from smtp-3-0000.mail.infomaniak.ch (unknown [10.4.36.107]) by smtp-2-3000.mail.infomaniak.ch (Postfix) with ESMTPS id 4GK9sS3RcVzMqGqs; Tue, 6 Jul 2021 20:23:08 +0200 (CEST) Received: from localhost (unknown [23.97.221.149]) by smtp-3-0000.mail.infomaniak.ch (Postfix) with ESMTPA id 4GK9sS10Nyzlh8T3; Tue, 6 Jul 2021 20:23:08 +0200 (CEST) From: =?utf-8?q?Micka=C3=ABl_Sala=C3=BCn?= To: Alejandro Colomar , Michael Kerrisk Cc: =?utf-8?q?Micka=C3=ABl_Sala=C3=BCn?= , Jann Horn , Jonathan Corbet , Kees Cook , Randy Dunlap , Vincent Dagonneau , landlock@lists.linux.dev, linux-kernel@vger.kernel.org, linux-man@vger.kernel.org, linux-security-module@vger.kernel.org, =?utf-8?q?Micka=C3=ABl_Sala=C3=BCn?= Subject: [PATCH v1 1/4] landlock.7: Add a new page to introduce Landlock Date: Tue, 6 Jul 2021 20:22:14 +0200 Message-Id: <20210706182217.32338-2-mic@digikod.net> X-Mailer: git-send-email 2.32.0 In-Reply-To: <20210706182217.32338-1-mic@digikod.net> References: <20210706182217.32338-1-mic@digikod.net> MIME-Version: 1.0 Precedence: bulk List-ID: From: Mickaël Salaün From the user point of view, Landlock is a set of system calls enabling to build and enforce a set of access-control rules. A ruleset can be created with landlock_create_ruleset(2), populated with landlock_add_rule(2) and enforced with landlock_restrict_self(2). This man page gives an overview of the whole mechanism. Details of these system calls are documented in their respective man pages. This is an adaptation of https://www.kernel.org/doc/html/v5.13/userspace-api/landlock.html Signed-off-by: Mickaël Salaün Link: https://lore.kernel.org/r/20210706182217.32338-2-mic@digikod.net --- man7/landlock.7 | 354 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 354 insertions(+) create mode 100644 man7/landlock.7 diff --git a/man7/landlock.7 b/man7/landlock.7 new file mode 100644 index 000000000000..32127d3b2061 --- /dev/null +++ b/man7/landlock.7 @@ -0,0 +1,354 @@ +.\" Copyright © 2017-2020 Mickaël Salaün +.\" 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 7 2021-06-27 Linux "Linux Programmer's Manual" +.SH NAME +Landlock \- security sandboxing +.SH DESCRIPTION +Landlock is a sandboxing mechanism that enables any processes to securely +restrict themselves and their future children. +Because Landlock is a stackable LSM, it makes possible to create safe +security sandboxes as new security layers in addition to the existing +system-wide access-controls. This kind of sandbox is expected to help +mitigate the security impact of bugs, and unexpected or malicious behaviors +in applications. +.PP +A Landlock security policy is a set of access rights (e.g., open a file in +read-only, make a directory, etc.) tied to a file hierarchy. Such policy +can be configured and enforced by processes for themselves using three +system calls: +.IP \(bu 2 +.BR landlock_create_ruleset (2) +creates a new ruleset; +.IP \(bu +.BR landlock_add_rule (2) +adds a new rule to a ruleset; +.IP \(bu +.BR landlock_restrict_self (2) +enforces a ruleset on the calling thread. +.PP +To be able to use these system calls, the running kernel must support +Landlock and it must be enabled at boot time. +.\" +.SS Landlock rules +A Landlock rule describes an action on an object. An object is currently a +file hierarchy, and the related filesystem actions are defined with access +rights (see +.BR landlock_add_rule (2) +). A set of rules is aggregated in a ruleset, which can +then restrict the thread enforcing it, and its future children. +.\" +.SS Defining and enforcing a security policy +We first need to create the ruleset that will contain our rules. For this +example, the ruleset will contain rules that only allow read actions, but +write actions will be denied. The ruleset then needs to handle both of +these kind of actions. See below for the description of filesystem +actions. +.PP +.in +4n +.EX +int ruleset_fd; +struct landlock_ruleset_attr ruleset_attr = { + .handled_access_fs = + LANDLOCK_ACCESS_FS_EXECUTE | + LANDLOCK_ACCESS_FS_WRITE_FILE | + LANDLOCK_ACCESS_FS_READ_FILE | + LANDLOCK_ACCESS_FS_READ_DIR | + LANDLOCK_ACCESS_FS_REMOVE_DIR | + LANDLOCK_ACCESS_FS_REMOVE_FILE | + LANDLOCK_ACCESS_FS_MAKE_CHAR | + LANDLOCK_ACCESS_FS_MAKE_DIR | + LANDLOCK_ACCESS_FS_MAKE_REG | + LANDLOCK_ACCESS_FS_MAKE_SOCK | + LANDLOCK_ACCESS_FS_MAKE_FIFO | + LANDLOCK_ACCESS_FS_MAKE_BLOCK | + LANDLOCK_ACCESS_FS_MAKE_SYM, +}; + +ruleset_fd = landlock_create_ruleset(&ruleset_attr, sizeof(ruleset_attr), 0); +if (ruleset_fd < 0) { + perror("Failed to create a ruleset"); + return 1; +} +.EE +.in +.PP +We can now add a new rule to this ruleset thanks to the returned file +descriptor referring to this ruleset. The rule will only allow reading the +file hierarchy +.I /usr +\&. Without another rule, write actions would then be denied by the +ruleset. To add +.I /usr +to the ruleset, we open it with the +.I O_PATH +flag and fill the +.I struct landlock_path_beneath_attr +with this file descriptor. +.PP +.in +4n +.EX +int err; +struct landlock_path_beneath_attr path_beneath = { + .allowed_access = + LANDLOCK_ACCESS_FS_EXECUTE | + LANDLOCK_ACCESS_FS_READ_FILE | + LANDLOCK_ACCESS_FS_READ_DIR, +}; + +path_beneath.parent_fd = open("/usr", O_PATH | O_CLOEXEC); +if (path_beneath.parent_fd < 0) { + perror("Failed to open file"); + close(ruleset_fd); + return 1; +} +err = landlock_add_rule(ruleset_fd, LANDLOCK_RULE_PATH_BENEATH, + &path_beneath, 0); +close(path_beneath.parent_fd); +if (err) { + perror("Failed to update ruleset"); + close(ruleset_fd); + return 1; +} +.EE +.in +.PP +We now have a ruleset with one rule allowing read access to +.I /usr +while denying all other handled accesses for the filesystem. The next step +is to restrict the current thread from gaining more privileges (e.g., +thanks to a set-user-ID binary). +.PP +.in +4n +.EX +if (prctl(PR_SET_NO_NEW_PRIVS, 1, 0, 0, 0)) { + perror("Failed to restrict privileges"); + close(ruleset_fd); + return 1; +} +.EE +.in +.PP +The current thread is now ready to sandbox itself with the ruleset. +.PP +.in +4n +.EX +if (landlock_restrict_self(ruleset_fd, 0)) { + perror("Failed to enforce ruleset"); + close(ruleset_fd); + return 1; +} +close(ruleset_fd); +.EE +.in +.PP +If the +.BR landlock_restrict_self (2) +system call succeeds, the current thread is now restricted and this policy +will be enforced on all its subsequently created children as well. Once a +thread is landlocked, there is no way to remove its security policy; only +adding more restrictions is allowed. These threads are now in a new +Landlock domain, merge of their parent one (if any) with the new ruleset. +.PP +Full working code can be found in +.UR https://git.kernel.org\:/pub\:/scm\:/linux\:/kernel\:/git\:/stable\:/linux.git\:/tree\:/samples\:/landlock\:/sandboxer.c +.UE +.\" +.SS Filesystem actions +These flags enable to restrict a sandboxed process to a set of actions on +files and directories. Files or directories opened before the sandboxing +are not subject to these restrictions. See +.BR landlock_add_rule (2) +and +.BR landlock_create_ruleset (2) +for more context. +.PP +A file can only receive these access rights: +.TP +.BR LANDLOCK_ACCESS_FS_EXECUTE +Execute a file. +.TP +.BR LANDLOCK_ACCESS_FS_WRITE_FILE +Open a file with write access. +.TP +.BR LANDLOCK_ACCESS_FS_READ_FILE +Open a file with read access. +.PP +A directory can receive access rights related to files or directories. The +following access right is applied to the directory itself, and the +directories beneath it: +.TP +.BR LANDLOCK_ACCESS_FS_READ_DIR +Open a directory or list its content. +.PP +However, the following access rights only apply to the content of a +directory, not the directory itself: +.TP +.BR LANDLOCK_ACCESS_FS_REMOVE_DIR +Remove an empty directory or rename one. +.TP +.BR LANDLOCK_ACCESS_FS_REMOVE_FILE +Unlink (or rename) a file. +.TP +.BR LANDLOCK_ACCESS_FS_MAKE_CHAR +Create (or rename or link) a character device. +.TP +.BR LANDLOCK_ACCESS_FS_MAKE_DIR +Create (or rename) a directory. +.TP +.BR LANDLOCK_ACCESS_FS_MAKE_REG +Create (or rename or link) a regular file. +.TP +.BR LANDLOCK_ACCESS_FS_MAKE_SOCK +Create (or rename or link) a UNIX domain socket. +.TP +.BR LANDLOCK_ACCESS_FS_MAKE_FIFO +Create (or rename or link) a named pipe. +.TP +.BR LANDLOCK_ACCESS_FS_MAKE_BLOCK +Create (or rename or link) a block device. +.TP +.BR LANDLOCK_ACCESS_FS_MAKE_SYM +Create (or rename or link) a symbolic link. +.\" +.SS Layers of file path access rights +Each time a thread enforces a ruleset on itself, it updates its Landlock +domain with a new layer of policy. Indeed, this complementary policy is +composed with the potentially other rulesets already restricting this +thread. A sandboxed thread can then safely add more constraints to itself +with a new enforced ruleset. +.PP +One policy layer grants access to a file path if at least one of its rules +encountered on the path grants the access. A sandboxed thread can only +access a file path if all its enforced policy layers grant the access as +well as all the other system access controls (e.g., filesystem DAC, other +LSM policies, etc.). +.\" +.SS Bind mounts and OverlayFS +Landlock enables restricting access to file hierarchies, which means that +these access rights can be propagated with bind mounts (cf. +.BR mount_namespaces (7) +) but not with OverlayFS. +.PP +A bind mount mirrors a source file hierarchy to a destination. The +destination hierarchy is then composed of the exact same files, on which +Landlock rules can be tied, either via the source or the destination path. +These rules restrict access when they are encountered on a path, which +means that they can restrict access to multiple file hierarchies at the +same time, whether these hierarchies are the result of bind mounts or not. +.PP +An OverlayFS mount point consists of upper and lower layers. These layers +are combined in a merge directory, result of the mount point. This merge +hierarchy may include files from the upper and lower layers, but +modifications performed on the merge hierarchy only reflects on the upper +layer. From a Landlock policy point of view, each OverlayFS layers and +merge hierarchies are standalone and contains their own set of files and +directories, which is different from bind mounts. A policy restricting an +OverlayFS layer will not restrict the resulted merged hierarchy, and vice +versa. Landlock users should then only think about file hierarchies they +want to allow access to, regardless of the underlying filesystem. +.\" +.SS Inheritance +Every new thread resulting from a +.BR clone (2) +inherits Landlock domain restrictions from its parent. This is similar to +the +.BR seccomp (2) +inheritance or any other LSM dealing with task's +.BR credentials (7) +\&. For instance, one process's thread may apply Landlock rules to itself, +but they will not be automatically applied to other sibling threads (unlike +POSIX thread credential changes, cf. +.BR nptl (7) +). +.PP +When a thread sandboxes itself, we have the guarantee that the related +security policy will stay enforced on all this thread's descendants. This +allows creating standalone and modular security policies per application, +which will automatically be composed between themselves according to their +runtime parent policies. +.\" +.SS Ptrace restrictions +A sandboxed process has less privileges than a non-sandboxed process and +must then be subject to additional restrictions when manipulating another +process. To be allowed to use +.BR ptrace (2) +and related syscalls on a target process, a sandboxed process should have a +subset of the target process rules, which means the tracee must be in a +sub-domain of the tracer. +.SH VERSIONS +Landlock was added in Linux 5.13. +.SH NOTES +Landlock is enabled by CONFIG_SECURITY_LANDLOCK. +The +.I lsm=lsm1,...,lsmN +command line parameter controls the sequence of the initialization of +Linux Security Modules. +It must contain the string +.I landlock +to enable Landlock. +If the command line parameter is not specified, +the initialization falls back to the value of the deprecated +.I security= +command line parameter and further to the value of CONFIG_LSM. +We can check that Landlock is enabled by looking for +.I +landlock: Up and running. +in kernel logs. +.\" +.PP +It is currently not possible to restrict some file-related actions +accessible through these syscall families: +.BR chdir (2) +, +.BR truncate (2) +, +.BR stat (2) +, +.BR flock (2) +, +.BR chmod (2) +, +.BR chown (2) +, +.BR setxattr (2) +, +.BR utime (2) +, +.BR ioctl (2) +, +.BR fcntl (2) +, +.BR access (2) +\&. +Future Landlock evolutions will enable to restrict them. +.SH SEE ALSO +.BR landlock_create_ruleset (2), +.BR landlock_add_rule (2), +.BR landlock_restrict_self (2) +.PP +.UR https://landlock.io\:/ +.UE From patchwork Tue Jul 6 18:22:15 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: =?utf-8?q?Micka=C3=ABl_Sala=C3=BCn?= X-Patchwork-Id: 12361089 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-16.8 required=3.0 tests=BAYES_00, HEADER_FROM_DIFFERENT_DOMAINS,INCLUDES_CR_TRAILER,INCLUDES_PATCH, MAILING_LIST_MULTI,SPF_HELO_NONE,SPF_PASS,URIBL_BLOCKED,USER_AGENT_GIT autolearn=ham autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 0C147C07E9E for ; Tue, 6 Jul 2021 18:23:13 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id DA44061C6D for ; Tue, 6 Jul 2021 18:23:12 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S229992AbhGFSZu (ORCPT ); Tue, 6 Jul 2021 14:25:50 -0400 Received: from smtp-8fa8.mail.infomaniak.ch ([83.166.143.168]:54589 "EHLO smtp-8fa8.mail.infomaniak.ch" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S229954AbhGFSZt (ORCPT ); Tue, 6 Jul 2021 14:25:49 -0400 Received: from smtp-3-0001.mail.infomaniak.ch (unknown [10.4.36.108]) by smtp-3-3000.mail.infomaniak.ch (Postfix) with ESMTPS id 4GK9sT588hzMprg6; Tue, 6 Jul 2021 20:23:09 +0200 (CEST) Received: from localhost (unknown [23.97.221.149]) by smtp-3-0001.mail.infomaniak.ch (Postfix) with ESMTPA id 4GK9sT2nkGzlmrrg; Tue, 6 Jul 2021 20:23:09 +0200 (CEST) From: =?utf-8?q?Micka=C3=ABl_Sala=C3=BCn?= To: Alejandro Colomar , Michael Kerrisk Cc: =?utf-8?q?Micka=C3=ABl_Sala=C3=BCn?= , Jann Horn , Jonathan Corbet , Kees Cook , Randy Dunlap , Vincent Dagonneau , landlock@lists.linux.dev, linux-kernel@vger.kernel.org, linux-man@vger.kernel.org, linux-security-module@vger.kernel.org, =?utf-8?q?Micka=C3=ABl_Sala=C3=BCn?= Subject: [PATCH v1 2/4] landlock_create_ruleset.2: Document new syscall Date: Tue, 6 Jul 2021 20:22:15 +0200 Message-Id: <20210706182217.32338-3-mic@digikod.net> X-Mailer: git-send-email 2.32.0 In-Reply-To: <20210706182217.32338-1-mic@digikod.net> References: <20210706182217.32338-1-mic@digikod.net> MIME-Version: 1.0 Precedence: bulk List-ID: From: Mickaël Salaün This is an adaptation of https://www.kernel.org/doc/html/v5.13/userspace-api/landlock.html Signed-off-by: Mickaël Salaün Link: https://lore.kernel.org/r/20210706182217.32338-3-mic@digikod.net --- man2/landlock_create_ruleset.2 | 134 +++++++++++++++++++++++++++++++++ 1 file changed, 134 insertions(+) create mode 100644 man2/landlock_create_ruleset.2 diff --git a/man2/landlock_create_ruleset.2 b/man2/landlock_create_ruleset.2 new file mode 100644 index 000000000000..5fe0f8fd808e --- /dev/null +++ b/man2/landlock_create_ruleset.2 @@ -0,0 +1,134 @@ +.\" Copyright © 2017-2020 Mickaël Salaün +.\" 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_CREATE_RULESET 2 2021-06-27 Linux "Linux Programmer's Manual" +.SH NAME +landlock_create_ruleset \- create a new Landlock ruleset +.SH SYNOPSIS +.nf +.BR "#include " " /* Definition of " LANDLOCK_* " constants */" +.BR "#include " " /* Definition of " SYS_* " constants */" +.PP +.BI "int syscall(SYS_landlock_create_ruleset, +.BI " const struct landlock_ruleset_attr " attr , +.BI " size_t " size " , __u32 " flags ); +.SH DESCRIPTION +A Landlock ruleset identifies a set of rules (i.e. actions on objects). +This +.BR landlock_create_ruleset (2) +system call enables creating a new file descriptor identifying a ruleset. +This file descriptor can then be used by +.BR landlock_add_rule (2) +and +.BR landlock_restrict_self (2) +\&. See +.BR landlock (7) +for a global overview. +.PP +.I attr +specifies the properties of the new ruleset. It points to the following +structure: +.IP +.in +4n +.EX +struct landlock_ruleset_attr { + __u64 handled_access_fs; +}; +.EE +.in +.IP +.I handled_access_fs +is a bitmask of actions that is handled by this ruleset and should then be +forbidden if no rule explicitly allow them +(see +.BR "Filesystem actions" +in +.BR landlock (7) +). +This enables simply restricting ambient rights (e.g., global filesystem +access) and is needed for compatibility reasons. +.PP +.I size +must be specified as +.I sizeof(struct landlock_ruleset_attr) +for compatibility reasons. +.PP +.I flags +must be 0 if +.I attr +is used. Otherwise, +.I flags +can be set to: +.TP +.BR LANDLOCK_CREATE_RULESET_VERSION +If +.I attr +is NULL and +.I size +is 0, then the returned value is the highest supported Landlock ABI version +(starting at 1). This version can be used for a best-effort security +approach, which is encouraged when user space is not pinned to a specific +kernel version. All features documented in these man pages are available +with the version 1. +.SH RETURN VALUE +On success, +.BR landlock_create_ruleset (2) +returns a new Landlock ruleset file descriptor, or a Landlock ABI version +according to +.I flags +\&. +.SH ERRORS +.BR landlock_create_ruleset (2) +can failed for the following reasons: +.TP +.BR EOPNOTSUPP +Landlock is supported by the kernel but disabled at boot time. +.TP +.BR EINVAL +Unknown +.I flags +, or unknown access, or too small +.I size +\&. +.TP +.BR E2BIG +.I size +is too big. +.TP +.BR EFAULT +.I attr +was not a valid address. +.TP +.BR ENOMSG +Empty accesses (i.e. +.I attr->handled_access_fs +is 0). +.SH VERSIONS +Landlock was added in Linux 5.13. +.SH SEE ALSO +.BR landlock (7), +.BR landlock_add_rule (2), +.BR landlock_restrict_self (2) From patchwork Tue Jul 6 18:22:16 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: =?utf-8?q?Micka=C3=ABl_Sala=C3=BCn?= X-Patchwork-Id: 12361091 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-16.8 required=3.0 tests=BAYES_00, HEADER_FROM_DIFFERENT_DOMAINS,INCLUDES_CR_TRAILER,INCLUDES_PATCH, MAILING_LIST_MULTI,SPF_HELO_NONE,SPF_PASS,URIBL_BLOCKED,USER_AGENT_GIT autolearn=ham autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id AF440C11F68 for ; Tue, 6 Jul 2021 18:23:14 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 8D65461C6B for ; Tue, 6 Jul 2021 18:23:14 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S231318AbhGFSZv (ORCPT ); Tue, 6 Jul 2021 14:25:51 -0400 Received: from smtp-8fae.mail.infomaniak.ch ([83.166.143.174]:56237 "EHLO smtp-8fae.mail.infomaniak.ch" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S231309AbhGFSZv (ORCPT ); Tue, 6 Jul 2021 14:25:51 -0400 Received: from smtp-2-0000.mail.infomaniak.ch (unknown [10.5.36.107]) by smtp-3-3000.mail.infomaniak.ch (Postfix) with ESMTPS id 4GK9sV6qMNzMprrq; Tue, 6 Jul 2021 20:23:10 +0200 (CEST) Received: from localhost (unknown [23.97.221.149]) by smtp-2-0000.mail.infomaniak.ch (Postfix) with ESMTPA id 4GK9sV4gQSzlh8TL; Tue, 6 Jul 2021 20:23:10 +0200 (CEST) From: =?utf-8?q?Micka=C3=ABl_Sala=C3=BCn?= To: Alejandro Colomar , Michael Kerrisk Cc: =?utf-8?q?Micka=C3=ABl_Sala=C3=BCn?= , Jann Horn , Jonathan Corbet , Kees Cook , Randy Dunlap , Vincent Dagonneau , landlock@lists.linux.dev, linux-kernel@vger.kernel.org, linux-man@vger.kernel.org, linux-security-module@vger.kernel.org, =?utf-8?q?Micka=C3=ABl_Sala=C3=BCn?= Subject: [PATCH v1 3/4] landlock_add_rule.2: Document new syscall Date: Tue, 6 Jul 2021 20:22:16 +0200 Message-Id: <20210706182217.32338-4-mic@digikod.net> X-Mailer: git-send-email 2.32.0 In-Reply-To: <20210706182217.32338-1-mic@digikod.net> References: <20210706182217.32338-1-mic@digikod.net> MIME-Version: 1.0 Precedence: bulk List-ID: From: Mickaël Salaün This is an adaptation of https://www.kernel.org/doc/html/v5.13/userspace-api/landlock.html Signed-off-by: Mickaël Salaün Link: https://lore.kernel.org/r/20210706182217.32338-4-mic@digikod.net --- man2/landlock_add_rule.2 | 139 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 139 insertions(+) create mode 100644 man2/landlock_add_rule.2 diff --git a/man2/landlock_add_rule.2 b/man2/landlock_add_rule.2 new file mode 100644 index 000000000000..66da2c142a03 --- /dev/null +++ b/man2/landlock_add_rule.2 @@ -0,0 +1,139 @@ +.\" Copyright © 2017-2020 Mickaël Salaün +.\" 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_ADD_RULE 2 2021-06-27 Linux "Linux Programmer's Manual" +.SH NAME +landlock_add_rule \- add a new Landlock rule to a ruleset +.SH SYNOPSIS +.nf +.BR "#include " " /* Definition of " LANDLOCK_* " constants */" +.BR "#include " " /* Definition of " SYS_* " constants */" +.PP +.BI "int syscall(SYS_landlock_add_rule, int " ruleset_fd , +.BI " enum landlock_rule_type " rule_type , +.BI " const void * " rule_attr ", __u32 " flags ); +.SH DESCRIPTION +A Landlock rule describes an action on an object. An object is currently a +file hierarchy, and the related filesystem actions are defined with a set +of access rights. This +.BR landlock_add_rule (2) +system call enables adding a new Landlock rule to an existing ruleset +created with +.BR landlock_create_ruleset (2) +\&. See +.BR landlock (7) +for a global overview. +.PP +.I ruleset_fd +is a Landlock ruleset file descriptor obtained with +.BR landlock_create_ruleset (2) +\&. +.PP +.I rule_type +identifies the structure type pointed to by +.I rule_attr +\&. Currently, Linux supports the following +.I rule_type +value: +.TP +.BR LANDLOCK_RULE_PATH_BENEATH +This defines the object type as a file hierarchy. +In this case, +.I rule_attr +points to the following structure: +.IP +.in +4n +.EX +struct landlock_path_beneath_attr { + __u64 allowed_access; + __s32 parent_fd; +} __attribute__((packed)); +.EE +.in +.IP +.I allowed_access +contains a bitmask of allowed filesystem actions for this file hierarchy +(see +.BR "Filesystem actions" +in +.BR landlock (7) +). +.IP +.I parent_fd +is an opened file descriptor, preferably with the +.I O_PATH +flag, which identifies the parent directory of the file hierarchy or a just +file. +.PP +.I flags +must be 0. +.SH RETURN VALUE +On success, +.BR landlock_add_rule (2) +returns 0. +.SH ERRORS +.BR landlock_add_rule (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, or the rule accesses are inconsistent (i.e. +.I rule_attr->allowed_access +is not a subset of the ruleset handled accesses). +.TP +.BR ENOMSG +Empty accesses (i.e. +.I rule_attr->allowed_access +is 0). +.TP +.BR EBADF +.I ruleset_fd +is not a file descriptor for the current thread, or a member of +.I rule_attr +is not a file descriptor as expected. +.TP +.BR EBADFD +.I ruleset_fd +is not a ruleset file descriptor, or a member of +.I rule_attr +is not the expected file descriptor type. +.TP +.BR EPERM +.I ruleset_fd +has no write access to the underlying ruleset. +.TP +.BR EFAULT +.I rule_attr +was not a valid address. +.SH VERSIONS +Landlock was added in Linux 5.13. +.SH SEE ALSO +.BR landlock (7), +.BR landlock_create_ruleset (2), +.BR landlock_restrict_self (2) From patchwork Tue Jul 6 18:22:17 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: =?utf-8?q?Micka=C3=ABl_Sala=C3=BCn?= X-Patchwork-Id: 12361093 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-16.8 required=3.0 tests=BAYES_00, HEADER_FROM_DIFFERENT_DOMAINS,INCLUDES_CR_TRAILER,INCLUDES_PATCH, MAILING_LIST_MULTI,SPF_HELO_NONE,SPF_PASS,URIBL_BLOCKED,USER_AGENT_GIT autolearn=ham autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id B365CC07E96 for ; Tue, 6 Jul 2021 18:23:15 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 9764A61C69 for ; Tue, 6 Jul 2021 18:23:15 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S231341AbhGFSZx (ORCPT ); Tue, 6 Jul 2021 14:25:53 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:56328 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S231328AbhGFSZx (ORCPT ); Tue, 6 Jul 2021 14:25:53 -0400 Received: from smtp-bc0b.mail.infomaniak.ch (smtp-bc0b.mail.infomaniak.ch [IPv6:2001:1600:3:17::bc0b]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 6B603C06175F for ; Tue, 6 Jul 2021 11:23:14 -0700 (PDT) Received: from smtp-3-0001.mail.infomaniak.ch (unknown [10.4.36.108]) by smtp-2-3000.mail.infomaniak.ch (Postfix) with ESMTPS id 4GK9sX163QzMqJf4; Tue, 6 Jul 2021 20:23:12 +0200 (CEST) Received: from localhost (unknown [23.97.221.149]) by smtp-3-0001.mail.infomaniak.ch (Postfix) with ESMTPA id 4GK9sW69gqzlmrrn; Tue, 6 Jul 2021 20:23:11 +0200 (CEST) From: =?utf-8?q?Micka=C3=ABl_Sala=C3=BCn?= To: Alejandro Colomar , Michael Kerrisk Cc: =?utf-8?q?Micka=C3=ABl_Sala=C3=BCn?= , Jann Horn , Jonathan Corbet , Kees Cook , Randy Dunlap , Vincent Dagonneau , landlock@lists.linux.dev, linux-kernel@vger.kernel.org, linux-man@vger.kernel.org, linux-security-module@vger.kernel.org, =?utf-8?q?Micka=C3=ABl_Sala=C3=BCn?= Subject: [PATCH v1 4/4] landlock_restrict_self.2: Document new syscall Date: Tue, 6 Jul 2021 20:22:17 +0200 Message-Id: <20210706182217.32338-5-mic@digikod.net> X-Mailer: git-send-email 2.32.0 In-Reply-To: <20210706182217.32338-1-mic@digikod.net> References: <20210706182217.32338-1-mic@digikod.net> MIME-Version: 1.0 Precedence: bulk List-ID: From: Mickaël Salaün This is an adaptation of https://www.kernel.org/doc/html/v5.13/userspace-api/landlock.html Signed-off-by: Mickaël Salaün Link: https://lore.kernel.org/r/20210706182217.32338-5-mic@digikod.net --- 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 +.\" 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 " " /* Definition of " LANDLOCK_* " constants */" +.BR "#include " " /* 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)