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

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,
--
KaiGai Kohei <kaigai(at)kaigai(dot)gr(dot)jp>