From: Stephen Smalley <sds@tycho.nsa.gov>
To: Edwin Zimmerman <edwin@211mainstreet.net>,
"'Al Viro'" <viro@zeniv.linux.org.uk>,
"'Denis Efremov'" <efremov@ispras.ru>
Cc: "'Casey Schaufler'" <casey@schaufler-ca.com>,
"'Eric W. Biederman'" <ebiederm@xmission.com>,
"'Eric Paris'" <eparis@parisplace.org>,
"'Kees Cook'" <keescook@chromium.org>,
"'John Johansen'" <john.johansen@canonical.com>,
"'James Morris'" <jmorris@namei.org>,
"'Serge E. Hallyn'" <serge@hallyn.com>,
"'Paul Moore'" <paul@paul-moore.com>,
"'Kentaro Takeda'" <takedakn@nttdata.co.jp>,
linux-security-module@vger.kernel.org,
linux-kernel@vger.kernel.org
Subject: Re: [PATCH 06/10] security: fix documentation for the path_chmod hook
Date: Thu, 7 Feb 2019 09:55:34 -0500 [thread overview]
Message-ID: <f55bddd5-fdf5-8e43-cff4-553dcb96393f@tycho.nsa.gov> (raw)
In-Reply-To: <71ce1b98-a69c-470c-d887-6f7405886aca@tycho.nsa.gov>
On 2/7/19 9:32 AM, Stephen Smalley wrote:
> On 2/7/19 9:09 AM, Edwin Zimmerman wrote:
>> On Thursday, February 07, 2019 8:50 AM Al Viro wrote:
>>> On Thu, Feb 07, 2019 at 03:44:54PM +0300, Denis Efremov wrote:
>>>> The path_chmod hook was changed in the commit
>>>> "switch security_path_chmod() to struct path *" (cdcf116d44e7).
>>>> The argument @mnt was removed from the hook, @dentry was changed
>>>> to @path. This patch updates the documentation accordingly.
>>>>
>>>> Signed-off-by: Denis Efremov <efremov@ispras.ru>
>>>> ---
>>>> include/linux/lsm_hooks.h | 3 +--
>>>> 1 file changed, 1 insertion(+), 2 deletions(-)
>>>>
>>>> diff --git a/include/linux/lsm_hooks.h b/include/linux/lsm_hooks.h
>>>> index cb93972257be..5d6428d0027b 100644
>>>> --- a/include/linux/lsm_hooks.h
>>>> +++ b/include/linux/lsm_hooks.h
>>>> @@ -304,8 +304,7 @@
>>>> * Return 0 if permission is granted.
>>>> * @path_chmod:
>>>> * Check for permission to change DAC's permission of a file or
>>>> directory.
>>>> - * @dentry contains the dentry structure.
>>>> - * @mnt contains the vfsmnt structure.
>>>> + * @path contains the path structure.
>>>
>>> May I politely inquire about the value of these comments? How much
>>> information
>>> is provided by refering to an argument as "the dentry structure" or
>>> "the path
>>> structure", especially when there's nothing immediately above that
>>> would introduce
>>> either. "Type of 'dentry' argument is somehow related to struct dentry,
>>> try and guess what the value might be - we don't care, we just need
>>> every
>>> argument commented"?
>>>
>>> Who needs that crap in the first place?
>>
>> The comments fill a valuable place to folks like me who are new to the
>> linux security modules.
>> In my spare time, I'm writing a new LSM specifically geared for
>> parental controls uses, and the
>> comments in lsm_hooks.h have helped me out more than once. Perhaps
>> the comments could
>> be inproved by changing them to something like this:
>> "@[arg] contains the [type] structure, defined in linux/[?].h"
>
> I don't think so. The point is not what type of structure but what
> object is being passed and why is it relevant to the hook, e.g.
>
> + @path contains the path structure for the file whose permissions are
> being modified
>
> or similar.
It would probably be better to amend the description too to refer to the
argument in context, e.g.
* @path_chmod:
* Check for permission to change the mode of the file referenced by
@path.
* @path the file whose mode would be modified
or similar.
I'd suggest looking to kerneldoc comments in fs/*.c or elsewhere as
better examples.
next prev parent reply other threads:[~2019-02-07 14:56 UTC|newest]
Thread overview: 20+ messages / expand[flat|nested] mbox.gz Atom feed top
2019-02-07 12:44 [PATCH 00/10] LSM documentation update Denis Efremov
2019-02-07 12:44 ` [PATCH 01/10] security: fix documentation for the sb_copy_data hook Denis Efremov
2019-02-07 12:44 ` [PATCH 02/10] security: fix documentation for the syslog hook Denis Efremov
2019-02-07 12:44 ` [PATCH 03/10] security: fix documentation for the socket_post_create hook Denis Efremov
2019-02-07 12:44 ` [PATCH 04/10] security: fix documentation for the task_setscheduler hook Denis Efremov
2019-02-07 12:44 ` [PATCH 05/10] security: fix documentation for the socket_getpeersec_dgram hook Denis Efremov
2019-02-07 12:44 ` [PATCH 06/10] security: fix documentation for the path_chmod hook Denis Efremov
2019-02-07 13:49 ` Al Viro
2019-02-07 14:09 ` Edwin Zimmerman
2019-02-07 14:32 ` Stephen Smalley
2019-02-07 14:55 ` Stephen Smalley [this message]
2019-02-07 14:46 ` Al Viro
2019-02-17 18:45 ` efremov
2019-02-07 12:44 ` [PATCH 07/10] security: fix documentation for the audit_* hooks Denis Efremov
2019-02-07 12:44 ` [PATCH 08/10] security: fix documentation for the msg_queue_* hooks Denis Efremov
2019-02-07 12:44 ` [PATCH 09/10] security: fix documentation for the sem_* hooks Denis Efremov
2019-02-07 12:44 ` [PATCH 10/10] security: fix documentation for the shm_* hooks Denis Efremov
2019-02-11 19:28 ` [PATCH 00/10] LSM documentation update Kees Cook
2019-02-17 18:04 ` efremov
2019-02-17 22:15 ` Kees Cook
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=f55bddd5-fdf5-8e43-cff4-553dcb96393f@tycho.nsa.gov \
--to=sds@tycho.nsa.gov \
--cc=casey@schaufler-ca.com \
--cc=ebiederm@xmission.com \
--cc=edwin@211mainstreet.net \
--cc=efremov@ispras.ru \
--cc=eparis@parisplace.org \
--cc=jmorris@namei.org \
--cc=john.johansen@canonical.com \
--cc=keescook@chromium.org \
--cc=linux-kernel@vger.kernel.org \
--cc=linux-security-module@vger.kernel.org \
--cc=paul@paul-moore.com \
--cc=serge@hallyn.com \
--cc=takedakn@nttdata.co.jp \
--cc=viro@zeniv.linux.org.uk \
/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
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
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).