Re: Proposed documentation patch to security.h

dawat_private

>David Wagner wrote:
>> In other words, I would argue that prescriptive conditions are useful
>> to have commented, but the descriptive observations can be left to IBM.
>> (I speculate that few -- if any -- hooks have prescriptive preconditions.)
>
>IBM has long been reknowned for documenting and commenting things in
>excruciating detail.  It may sometimes be hard to find stuff, or understand
>what they meant, but lack of detail is rarely a problem there.

I'm worried that I wasn't clear enough.  I'm not talking about lack
of detail; that's orthogonal to my point.  I'm talking about preconditions
on the caller of a LSM interface: if there are some requirements that
the programmer of the LSM interface had in mind (like that you must hold
lock L when calling foo()), I claim this is something that ought to be
documented in LSM code.

The IBM project does not document what callers are supposed to be doing;
they document what callers are actually doing.  There is a need for both.
This is the difference between prescriptive vs. descriptive: the former
says "you should do X"; the latter says "people are doing X".  The IBM
project is primarily descriptive, not prescriptive.

What I'm arguing is that if there are any preconditions on LSM interfaces,
then they should be written down in comments, not left to live in someone's
head.

>It would probably be a *very* good idea if somebody went back through
>afterwards, and see if what IBM's crew documented as the actual calling
>conditions matches what we thought it should be.  If we thought there was
>a "must have lock L to call this" requirement, and IBM says "can be called
>with or without L", we have a problem. ;)

Yes.  I'm suggesting we ought to write down the "must have lock L"
requirements.  If we don't know what those requirements are, we can't
do the consistency check.

And from a software engineering point of view, I'd much rather have this
documented as part of the interface, so that programmers will read it and
make sure they're using the interface correctly, rather than us having to
audit everyone else's code.  (The latter just doesn't scale, and doesn't
work well with evolving code.)

_______________________________________________
linux-security-module mailing list
linux-security-moduleat_private
http://mail.wirex.com/mailman/listinfo/linux-security-module