linux-kernel - Re: [PATCH 06/10] security: fix documentation for the path

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite for Android: free password hash cracker in your pocket

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <71ce1b98-a69c-470c-d887-6f7405886aca@tycho.nsa.gov>
Date:   Thu, 7 Feb 2019 09:32:58 -0500
From:   Stephen Smalley <sds@...ho.nsa.gov>
To:     Edwin Zimmerman <edwin@...mainstreet.net>,
        "'Al Viro'" <viro@...iv.linux.org.uk>,
        "'Denis Efremov'" <efremov@...ras.ru>
Cc:     "'Casey Schaufler'" <casey@...aufler-ca.com>,
        "'Eric W. Biederman'" <ebiederm@...ssion.com>,
        "'Eric Paris'" <eparis@...isplace.org>,
        "'Kees Cook'" <keescook@...omium.org>,
        "'John Johansen'" <john.johansen@...onical.com>,
        "'James Morris'" <jmorris@...ei.org>,
        "'Serge E. Hallyn'" <serge@...lyn.com>,
        "'Paul Moore'" <paul@...l-moore.com>,
        "'Kentaro Takeda'" <takedakn@...data.co.jp>,
        linux-security-module@...r.kernel.org, linux-kernel@...r.kernel.org
Subject: Re: [PATCH 06/10] security: fix documentation for the path_chmod hook

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@...ras.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.