Re: SE-PgSQL developer documentation (Re: Reworks for Access Control facilities (r2363))

Now I'm working on writing a documentation from the viewpoint of
developers as follows (It is a work in progress):

http://code.google.com/p/sepgsql/source/browse/trunk/sepgsql/src/backend/security/sepgsql/README

Is there any differences between what I want to describe and what you
want to know? If so, I'll add or modify the documentation.

As I noted before, I decided to slim up my patch on the next commit fest
to reduce the burden of reviewing.

The following functionalities will be separated from the prior version.
- no access controls on procedures.
-> so, the slim version only support checks on databases, schemas,
tables and columns.
- no statement support to specify security context.
(It makes impossible to add support in pg_dump. Is it really OK?)
- no userspace caches for access control decision
- no system catalog changes to store its security context
-> I'll adopt an approach that Stephen Frost suggested before.
It manages a pair of OID and security context in separated system catalog.

Is there any comment? Or, more detailed introductions are necessary?

Thanks,

KaiGai Kohei wrote:
> KaiGai Kohei wrote:
>> After the long trial-and-errors, we learned a few approaches which
>> use common entry points for both of DAC and MAC were rocky-path more
>> than what we initially imagined.
>> So, we came back to the original design. It deploys MAC hooks on
>> the strategic points of core routines. On the other hand, people
>> complained about this approach without clear documentation, because
>> most of people are not familiar to both of SELinux and PgSQL.
>> Heikki suggested that a clear developer documentation should be
>> provided to understand pgsql-hackers this new concept.
>> (And, Peter has also suggested before a developer documentation will
>> be a good source of user documentations.)
>>
>> I plan to submit SE-PgSQL/lite patch with developer documentations
>> on the next commit-fest.
>> I can understand what I want to develop and the purpose of codes.
>> However, it may not match with what you want to know.
>>
>> So, I'd like to ask what should be included within the developer
>> documentation at first prior to making a documentation.
>>
>> I plans the developer documentation should be put as a REAME file,
>> not a SGML documentation or a certain wiki page.
>> And I think it should contain the following items.
>>
>> * overview
>> - general overview of SE-PgSQL
>> - introduction of SELinux specific terms (such as "security context")
>>
>> * internal architecture
>> - the purpose of sub-components (such as management of security
>> context, caches of access control decision and so on)
>> - differences from similar permissions in DAC
>>
>> * object classes and permissions defined in SELinux model
>> - list of them and when/where they should be checked.
>>
>> * specification of SE-PgSQL hooks
>> (It should be put on the source code comments for easy maintenance.)
>> - what this hook does, what arguments are required, what result will
>> be returned.
>>
>> * code examples
>> - a few examples to add MAC checks within 3rd party modules.
>>
>> Do you have any comments? What should be added to? or removed from?
>
> I guess it was too abstract to suggest anything.
> Anyway, I'll begin to describe the developer documentation base on the chapters.
> If necessary, we can fix it up later.
>
> In addition, I determined the initial patch only covers access controls on
> the four object classes (database, schema, table and column) to reduce burdens
> of reviewing.
> We also can add support for other object classes (such as procedure) later.
>
> Thanks,

--
OSS Platform Development Division, NEC
KaiGai Kohei <kaigai(at)ak(dot)jp(dot)nec(dot)com>