linux-man.vger.kernel.org archive mirror
 help / color / mirror / Atom feed
From: "Mickaël Salaün" <mic@digikod.net>
To: "Alejandro Colomar (man-pages)" <alx.manpages@gmail.com>
Cc: "Jann Horn" <jannh@google.com>,
	"Jonathan Corbet" <corbet@lwn.net>,
	"Kees Cook" <keescook@chromium.org>,
	"Randy Dunlap" <rdunlap@infradead.org>,
	"Vincent Dagonneau" <vincent.dagonneau@ssi.gouv.fr>,
	landlock@lists.linux.dev, linux-kernel@vger.kernel.org,
	linux-man@vger.kernel.org, linux-security-module@vger.kernel.org,
	"Mickaël Salaün" <mic@linux.microsoft.com>,
	"Michael Kerrisk" <mtk.manpages@gmail.com>,
	"G. Branden Robinson" <g.branden.robinson@gmail.com>
Subject: Re: [PATCH v2 1/4] landlock.7: Add a new page to introduce Landlock
Date: Fri, 30 Jul 2021 16:32:20 +0200	[thread overview]
Message-ID: <e0f0a037-268d-04df-91bf-e3ade4968f12@digikod.net> (raw)
In-Reply-To: <1a698059-d9dd-5aa0-2765-42e704c3a697@gmail.com>

Thanks Alejandro for the detailed explanations, that's useful!

On 30/07/2021 14:59, Alejandro Colomar (man-pages) wrote:
> Hi Mickaël,
> 
> On 7/30/21 2:41 PM, Alejandro Colomar (man-pages) wrote:
> [...]
>>
>>
>>
>> I hope this was helpful :)
>>
>> Cheers,
>>
>> Alex
>>
>>
>>
>>
>> But, let's use .I
> 
> I hit send too soon.  Let's continue.
> 
> As for current usage, yes, there are many uses of .IR to mean .I, but
> for new code, we're only using .I (or .B) when possible.
> 
>>
>>
>> CC: Branden
>>
>>>
>>>>
>>>> If there was a misunderstanding about this, I'm sorry.
>>>>
>>>>> * Append punctuation to ".IR" and ".BR" when it makes sense (requested
>>>>>     by Alejandro Colomar).
>>>>> * Cut lines according to the semantic newline rules (requested by
>>>>>     Alejandro Colomar).
>>>>> * Remove roman style from ".TP" section titles (requested by Alejandro
>>>>>     Colomar).
>>>>> * Add comma after "i.e." and "e.g.".
>>>>> * Move the example in a new EXAMPLES section.
>>>>> * Improve title.
>>>>> * Explain the LSM acronym at first use.
>>>>> ---
>>>>>    man7/landlock.7 | 356
>>>>> ++++++++++++++++++++++++++++++++++++++++++++++++
>>>>>    1 file changed, 356 insertions(+)
>>>>>    create mode 100644 man7/landlock.7
>>>>>
>>>>> diff --git a/man7/landlock.7 b/man7/landlock.7
>>>>> new file mode 100644
>>>>> index 000000000000..c89f5b1cabb6
>>>>> --- /dev/null
>>>>> +++ b/man7/landlock.7
>>>>> @@ -0,0 +1,356 @@
>>>>> +.\" Copyright © 2017-2020 Mickaël Salaün <mic@digikod.net>
>>>>> +.\" 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 \- unprivileged access-control
>>>>> +.SH DESCRIPTION
>>>>> +Landlock is an access-control system that enables any processes to //
>>>>> securely /J/
>>>
>>> Why adding a line break here? This line is 75 columns as stated by the
>>> documentation: https://man7.org/linux/man-pages/man7/man-pages.7.html
>>> I guess it helps for semantic newlines, right? If so, what are the
>>> rules?
> 
> Yes, they were because of semantic newlines.
> 
> The "rules" are:
> 
> Follow mainly "semantic newlines" style (forgetting about the line
> length), which will give you a text that (mostly) fits into 75 or 80
> columns.
> 
> If after doing that there are some lines that exceed the 75 or 80 column
> right margin, consider fixing that line by breaking it at a different
> point or maybe breaking it further.  The 80 column limit is a hard limit
> (I can't read anything past the 80 col), while the 75 limit is a bit
> softer (that's for allowing quotes in reviews) (if fitting a line into
> col 75 would break it in a weird way, don't do it).
> 
> If I didn't explain myself enough, please tell me.
> 
>>>>> +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.
>>>>
>>>>
>>>> Incorrect mix of singular and plural, I think.
>>> >> Is it OK with s/contains/contain/?
> 
> I think so.
> 
>>>
>>>>
>>>>> +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
>>>>
>>>> Not sure:
>>>>
>>>> s/task/a task/
>>>> or
>>>> s/task's/tasks'/
>>>
>>> I'll take "tasks'".
> 
> Okay.
> 
>>>
>>>>
>>>>> +.BR credentials (7).
>>>>> +For instance, one process's thread may apply Landlock rules to
>>>>> itself,
>>>>
>>>> s/process's/process'/
>>>
>>> As pointed out by Branden, this is correct.
> 
> That's right. :)
> 
>>>
>>>>
>>>>> +.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 EXAMPLES
>>>> I'd prefer a complete example with a main function, if you can come up
>>>> with such one.  If not, this will be ok.
>>>
>>> I think it is clearer to not to use a full main to explain these basic
>>> steps. A full working example is linked though.
> 
> Ahh sorry, I didn't see the link.
> I'll have a look at it.
> 
>>>
>>>>
>>>>
>>>>> +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
>>>>> +.IR /usr .
>>>
>>> Why ".IR" is correct here?
> 
> "/usr" needs to be formatted, but "." not.
> 
> [
> .I /usr
> .
> ]
> 
> Would add a space: /usr .
> So we need a solution that formats only part of a space-separated token;
> that's what .IR does.  I hope the last email explained that well.
> 
> Thanks,
> 
> Alex
> 
> 

  reply	other threads:[~2021-07-30 14:30 UTC|newest]

Thread overview: 18+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2021-07-12 15:57 [PATCH v2 0/4] Add Landlock man pages Mickaël Salaün
2021-07-12 15:57 ` [PATCH v2 1/4] landlock.7: Add a new page to introduce Landlock Mickaël Salaün
2021-07-29 14:56   ` Alejandro Colomar (man-pages)
2021-07-29 22:01     ` G. Branden Robinson
2021-07-29 22:34       ` Alejandro Colomar (man-pages)
2021-07-30 12:15     ` Mickaël Salaün
2021-07-30 12:41       ` Alejandro Colomar (man-pages)
2021-07-30 12:59         ` Alejandro Colomar (man-pages)
2021-07-30 14:32           ` Mickaël Salaün [this message]
2021-07-31  0:15           ` G. Branden Robinson
2021-07-31 11:02             ` Alejandro Colomar (man-pages)
2021-08-01  9:28               ` G. Branden Robinson
2021-07-30 23:39       ` G. Branden Robinson
2021-07-31 10:51         ` Alejandro Colomar (man-pages)
2021-07-31 13:48           ` G. Branden Robinson
2021-07-12 15:57 ` [PATCH v2 2/4] landlock_create_ruleset.2: Document new syscall Mickaël Salaün
2021-07-12 15:57 ` [PATCH v2 3/4] landlock_add_rule.2: " Mickaël Salaün
2021-07-12 15:57 ` [PATCH v2 4/4] landlock_restrict_self.2: " Mickaël Salaün

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=e0f0a037-268d-04df-91bf-e3ade4968f12@digikod.net \
    --to=mic@digikod.net \
    --cc=alx.manpages@gmail.com \
    --cc=corbet@lwn.net \
    --cc=g.branden.robinson@gmail.com \
    --cc=jannh@google.com \
    --cc=keescook@chromium.org \
    --cc=landlock@lists.linux.dev \
    --cc=linux-kernel@vger.kernel.org \
    --cc=linux-man@vger.kernel.org \
    --cc=linux-security-module@vger.kernel.org \
    --cc=mic@linux.microsoft.com \
    --cc=mtk.manpages@gmail.com \
    --cc=rdunlap@infradead.org \
    --cc=vincent.dagonneau@ssi.gouv.fr \
    --subject='Re: [PATCH v2 1/4] landlock.7: Add a new page to introduce Landlock' \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).