| Message ID | 20210818155931.484070-1-mic@digikod.net (mailing list archive) |
|---|---|
| Headers | show |
| Series | Add Landlock man pages | expand |
Alejandro, is there something more to do or is it OK for you? On 18/08/2021 17:59, Mickaël Salaün wrote: > From: Mickaël Salaün <mic@linux.microsoft.com> > > Hi, > > These four documents give a global overview of Landlock and explain each > system calls. This is mainly a formatting of the current kernel > documentation with some new additional details. > > This fourth patch series fixes spelling issues pointed out by Alejandro > Colomar and Branden Robinson. I also removed some recipients. > > This patch series can be found in a Git repository: > https://github.com/landlock-lsm/man-pages/commits/landlock-v4 > > Previous version: > https://lore.kernel.org/landlock/20210730144116.332091-1-mic@digikod.net/ > > Regards, > > Mickaël Salaün (4): > landlock.7: Add a new page to introduce Landlock > landlock_create_ruleset.2: Document new syscall > landlock_add_rule.2: Document new syscall > landlock_restrict_self.2: Document new syscall > > man2/landlock_add_rule.2 | 144 +++++++++++++ > man2/landlock_create_ruleset.2 | 139 +++++++++++++ > man2/landlock_restrict_self.2 | 133 ++++++++++++ > man7/landlock.7 | 361 +++++++++++++++++++++++++++++++++ > 4 files changed, 777 insertions(+) > create mode 100644 man2/landlock_add_rule.2 > create mode 100644 man2/landlock_create_ruleset.2 > create mode 100644 man2/landlock_restrict_self.2 > create mode 100644 man7/landlock.7 > > > base-commit: 7127973e0c8ca36fda1f5d2d0adae04d61fa0d01 >
Hi Mickaël, On 11/3/21 13:07, Mickaël Salaün wrote: > Alejandro, is there something more to do or is it OK for you? I applied the patchset, plus a few minor fixes (see below). Thanks! Alex > > On 18/08/2021 17:59, Mickaël Salaün wrote: >> From: Mickaël Salaün <mic@linux.microsoft.com> >> >> Hi, >> >> These four documents give a global overview of Landlock and explain each >> system calls. This is mainly a formatting of the current kernel >> documentation with some new additional details. >> >> This fourth patch series fixes spelling issues pointed out by Alejandro >> Colomar and Branden Robinson. I also removed some recipients. >> >> This patch series can be found in a Git repository: >> https://github.com/landlock-lsm/man-pages/commits/landlock-v4 >> >> Previous version: >> https://lore.kernel.org/landlock/20210730144116.332091-1-mic@digikod.net/ >> >> Regards, >> >> Mickaël Salaün (4): >> landlock.7: Add a new page to introduce Landlock >> landlock_create_ruleset.2: Document new syscall >> landlock_add_rule.2: Document new syscall >> landlock_restrict_self.2: Document new syscall >> >> man2/landlock_add_rule.2 | 144 +++++++++++++ >> man2/landlock_create_ruleset.2 | 139 +++++++++++++ >> man2/landlock_restrict_self.2 | 133 ++++++++++++ >> man7/landlock.7 | 361 +++++++++++++++++++++++++++++++++ >> 4 files changed, 777 insertions(+) >> create mode 100644 man2/landlock_add_rule.2 >> create mode 100644 man2/landlock_create_ruleset.2 >> create mode 100644 man2/landlock_restrict_self.2 >> create mode 100644 man7/landlock.7 >> >> >> base-commit: 7127973e0c8ca36fda1f5d2d0adae04d61fa0d01 >> --- landlock_add_rule.2, landlock_create_ruleset.2, landlock_restrict_self.2, landlock.7: Minor tweaks to Mickaël's patches - exit(EXIT_FAILURE) instead of return 1, for consistency with the rest of the manual pages. - Use old declarations: variables defined at the top, separate from code. Initialization other than zero doesn't belong there. - Don't break URIs in weird ways (a trailing slash on a new line would be weird). - Break URIs after the slash; not before. Per Branden's advise. - Use uint32_t instead of __u32 in prototypes. - tfix - A few semantic newline improvements. - ffix Cc: Mickaël Salaün <mic@digikod.net> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com> diff --git a/man2/landlock_add_rule.2 b/man2/landlock_add_rule.2 index eafb8f820..c3f6e84e0 100644 --- a/man2/landlock_add_rule.2 +++ b/man2/landlock_add_rule.2 @@ -34,10 +34,12 @@ landlock_add_rule \- add a new Landlock rule to a ruleset .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 ); +.BI " const void *" rule_attr ", uint32_t " flags ); +.fi .SH DESCRIPTION A Landlock rule describes an action on an object. -An object is currently a file hierarchy, and the related filesystem actions +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 () @@ -114,13 +116,15 @@ is 0). .TP .B EBADF .I ruleset_fd -is not a file descriptor for the current thread, or a member of +is not a file descriptor for the current thread, +or a member of .I rule_attr is not a file descriptor as expected. .TP .B EBADFD .I ruleset_fd -is not a ruleset file descriptor, or a member of +is not a ruleset file descriptor, +or a member of .I rule_attr is not the expected file descriptor type. .TP diff --git a/man2/landlock_create_ruleset.2 b/man2/landlock_create_ruleset.2 index e1ca4bcf8..11a8f08de 100644 --- a/man2/landlock_create_ruleset.2 +++ b/man2/landlock_create_ruleset.2 @@ -34,7 +34,8 @@ landlock_create_ruleset \- create a new Landlock ruleset .PP .BI "int syscall(SYS_landlock_create_ruleset, .BI " const struct landlock_ruleset_attr *" attr , -.BI " size_t " size " , __u32 " flags ); +.BI " size_t " size " , uint32_t " flags ); +.fi .SH DESCRIPTION A Landlock ruleset identifies a set of rules (i.e., actions on objects). This @@ -55,14 +56,14 @@ It points to the following structure: .in +4n .EX struct landlock_ruleset_attr { - __u64 handled_access_fs; + __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 +is a bitmask of actions that is handled by this ruleset and +should then be forbidden if no rule explicitly allows them (see .B Filesystem actions in @@ -98,12 +99,13 @@ All features documented in these man pages are available with the version .SH RETURN VALUE On success, .BR landlock_create_ruleset () -returns a new Landlock ruleset file descriptor, or a Landlock ABI version +returns a new Landlock ruleset file descriptor, +or a Landlock ABI version, according to .IR flags . .SH ERRORS .BR landlock_create_ruleset () -can failed for the following reasons: +can fail for the following reasons: .TP .B EOPNOTSUPP Landlock is supported by the kernel but disabled at boot time. diff --git a/man2/landlock_restrict_self.2 b/man2/landlock_restrict_self.2 index 4b10997e2..77c71bbf8 100644 --- a/man2/landlock_restrict_self.2 +++ b/man2/landlock_restrict_self.2 @@ -33,7 +33,7 @@ landlock_restrict_self \- enforce a Landlock ruleset .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */" .PP .BI "int syscall(SYS_landlock_restrict_self, int " ruleset_fd , -.BI " __u32 " flags ); +.BI " uint32_t " flags ); .SH DESCRIPTION Once a Landlock ruleset is populated with the desired rules, the .BR landlock_restrict_self () @@ -42,13 +42,13 @@ 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. +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, @@ -68,8 +68,8 @@ capability in its user namespace, or the thread must already have the 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). +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 @@ -91,7 +91,7 @@ On success, returns 0. .SH ERRORS .BR landlock_restrict_self () -can failed for the following reasons: +can fail for the following reasons: .TP .B EOPNOTSUPP Landlock is supported by the kernel but disabled at boot time. diff --git a/man7/landlock.7 b/man7/landlock.7 index 710e7feb7..80d9f2bf1 100644 --- a/man7/landlock.7 +++ b/man7/landlock.7 @@ -31,8 +31,9 @@ Landlock \- unprivileged access-control Landlock is an access-control system that enables any processes to securely restrict themselves and their future children. Because Landlock is a stackable Linux Security Module (LSM), -it makes it possible to create safe security sandboxes as new security -layers in addition to the existing system-wide access-controls. +it makes it 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. @@ -128,8 +129,8 @@ 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. +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 @@ -165,8 +166,8 @@ From a Landlock policy point of view, each of the OverlayFS layers and merge hierarchies is standalone and contains its own set of files and directories, which is different from a bind mount. -A policy restricting an OverlayFS layer will not restrict the resulted -merged hierarchy, and vice versa. +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. .\" @@ -244,9 +245,10 @@ See below for the description of filesystem actions. .PP .in +4n .EX +struct landlock_ruleset_attr ruleset_attr = {0}; int ruleset_fd; -struct landlock_ruleset_attr ruleset_attr = { - .handled_access_fs = + +ruleset_attr.handled_access_fs = LANDLOCK_ACCESS_FS_EXECUTE | LANDLOCK_ACCESS_FS_WRITE_FILE | LANDLOCK_ACCESS_FS_READ_FILE | @@ -259,13 +261,12 @@ struct landlock_ruleset_attr ruleset_attr = { LANDLOCK_ACCESS_FS_MAKE_SOCK | LANDLOCK_ACCESS_FS_MAKE_FIFO | LANDLOCK_ACCESS_FS_MAKE_BLOCK | - LANDLOCK_ACCESS_FS_MAKE_SYM, -}; + LANDLOCK_ACCESS_FS_MAKE_SYM; ruleset_fd = landlock_create_ruleset(&ruleset_attr, sizeof(ruleset_attr), 0); -if (ruleset_fd < 0) { +if (ruleset_fd == -1) { perror("Failed to create a ruleset"); - return 1; + exit(EXIT_FAILURE); } .EE .in @@ -285,19 +286,19 @@ with this file descriptor. .PP .in +4n .EX +struct landlock_path_beneath_attr path_beneath = {0}; int err; -struct landlock_path_beneath_attr path_beneath = { - .allowed_access = + +path_beneath.allowed_access = LANDLOCK_ACCESS_FS_EXECUTE | LANDLOCK_ACCESS_FS_READ_FILE | - LANDLOCK_ACCESS_FS_READ_DIR, -}; + LANDLOCK_ACCESS_FS_READ_DIR; path_beneath.parent_fd = open("/usr", O_PATH | O_CLOEXEC); -if (path_beneath.parent_fd < 0) { +if (path_beneath.parent_fd == -1) { perror("Failed to open file"); close(ruleset_fd); - return 1; + exit(EXIT_FAILURE); } err = landlock_add_rule(ruleset_fd, LANDLOCK_RULE_PATH_BENEATH, &path_beneath, 0); @@ -305,7 +306,7 @@ close(path_beneath.parent_fd); if (err) { perror("Failed to update ruleset"); close(ruleset_fd); - return 1; + exit(EXIT_FAILURE); } .EE .in @@ -322,7 +323,7 @@ privileges if (prctl(PR_SET_NO_NEW_PRIVS, 1, 0, 0, 0)) { perror("Failed to restrict privileges"); close(ruleset_fd); - return 1; + exit(EXIT_FAILURE); } .EE .in @@ -334,7 +335,7 @@ The current thread is now ready to sandbox itself with the ruleset. if (landlock_restrict_self(ruleset_fd, 0)) { perror("Failed to enforce ruleset"); close(ruleset_fd); - return 1; + exit(EXIT_FAILURE); } close(ruleset_fd); .EE @@ -342,20 +343,20 @@ close(ruleset_fd); .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. +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 +.UR https://git.kernel.org/\:pub/\:scm/\:linux/\:kernel/\:git/\:stable/\:linux.git/\:tree/\:samples/\:landlock/\:sandboxer.c .UE .SH SEE ALSO .BR landlock_create_ruleset (2), .BR landlock_add_rule (2), .BR landlock_restrict_self (2) .PP -.UR https://landlock.io\:/ +.UR https://landlock.io/ .UE
From: Mickaël Salaün <mic@linux.microsoft.com> Hi, These four documents give a global overview of Landlock and explain each system calls. This is mainly a formatting of the current kernel documentation with some new additional details. This fourth patch series fixes spelling issues pointed out by Alejandro Colomar and Branden Robinson. I also removed some recipients. This patch series can be found in a Git repository: https://github.com/landlock-lsm/man-pages/commits/landlock-v4 Previous version: https://lore.kernel.org/landlock/20210730144116.332091-1-mic@digikod.net/ Regards, Mickaël Salaün (4): landlock.7: Add a new page to introduce Landlock landlock_create_ruleset.2: Document new syscall landlock_add_rule.2: Document new syscall landlock_restrict_self.2: Document new syscall man2/landlock_add_rule.2 | 144 +++++++++++++ man2/landlock_create_ruleset.2 | 139 +++++++++++++ man2/landlock_restrict_self.2 | 133 ++++++++++++ man7/landlock.7 | 361 +++++++++++++++++++++++++++++++++ 4 files changed, 777 insertions(+) create mode 100644 man2/landlock_add_rule.2 create mode 100644 man2/landlock_create_ruleset.2 create mode 100644 man2/landlock_restrict_self.2 create mode 100644 man7/landlock.7 base-commit: 7127973e0c8ca36fda1f5d2d0adae04d61fa0d01