Re: Proposed documentation patch to security.h

From: David Wagner (dawat_private)
Date: Fri Nov 02 2001 - 10:49:40 PST

  • Next message: richard offer: "Re: Proposed documentation patch to security.h"

    >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
    >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

    This archive was generated by hypermail 2b30 : Fri Nov 02 2001 - 13:37:39 PST