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

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?

Thanks,

KaiGai Kohei wrote:
> Heikki Linnakangas wrote:
>> KaiGai Kohei wrote:
>>> When we create a new object, we can provide an explicit security context
>>> to be assigned on the new object, instead of the default one.
>> To get started, do we really need that feature? It would make for a
>> significantly smaller patch if there was no explicit security labels on
>> objects.
>
> The importance of the feature is relatively minor than MAC itself.
> So, I can agree to omit code corresponding to statement support
> from the first patch. (IIRC, about 300-400 lines can be reduced.)
> But it will be necessary feature at the next step, because DBA cannot
> create a special purpose table without statement support.
>
> For example, if security policy allows DBA to create read-writable
> table (in default) and read-only table. He cannot set up read-only
> table without explicit security label support.
>
>>>>> On the other hand, the default PG model allows to bypass checks on
>>>>> certain objects. For example, column-level privileges are only checked
>>>>> when a user does not have enough permissions on the target table.
>>>>> If "SELECT a,b FROM t" is given, pg_attribute_aclcheck() may not invoked
>>>>> when user has needed privileges on the table t.
>>>> Hmm, I see. Yes, it does seem like we'd need to change such permission
>>>> checks to accommodate both models.
>>> I'm not clear why we need to rework the permission checks here.
>>> DAC and MAC perform orthogonally and independently.
>>> DAC allows to override column-level privileges by table-level privileges
>>> according to the default PG's model. It seems to me fine.
>>> On the other hand, MAC checks both of permissions. It is also fine.
>> I meant we need to refactor the code doing the permission checks. The
>> existing checks are doing the right thing for DAC, but as you point out,
>> if the MAC checks are within pg_*_aclcheck() functions,
>> pg_attribute_aclcheck() needs to be called even if you have privilege on
>> the table.
>
> I think we already learned refactoring DAC checks need widespread code
> changes and pushes a burden to reviewers.
>
> In this case, I think the point just after invocation of ExecCheckRTEPerms()
> in ExecCheckRTPerms() is the best point to put SE-PgSQL's checks.
> Needless to say, its specification should be clearly documented.
>
> Thanks,

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