ntsec patch description (1st try)

[Corinna Vinschen <corinna@vinschen.de>]

This is my first try of a description. Please read it and tell
me your opinion. Is it understandable? Should s.th. be described
in more detail?
--------------------------------------------------------------------
------------------------------- snip -------------------------------
--------------------------------------------------------------------
NTSEC Documentation
===================

The design goal of the ntsec-patch was, to get a more UNIX-like
permission structure, based upon the security features of Windows NT.
To describe the changes, I will give a short overview of NT security
in chapter one.
Chapter two shows the change in ntsec, related to privileges on
processes.
Chapter three discusses the UNIX-like setting of file permissions.


1. NT security
--------------

The NT security allows a process, to allow or deny access of
different kind to `objects'. `Objects' are files, processes,
threads, semaphores, etc.

The central data structure of NT security is the `security descriptor'
(SD) structure. It explains the permissions, that are granted (or
denied) to an object and contains information, that is related to so
called `security identifiers' (SID).

A SID is an unique identifier for users, groups and domains. In the
ntsec patch only user and group SIDs are relevant. SIDs are comparable
to UNIX UIDs and GIDs, but more complicated.

There is a big difference between UNIX IDs and NT SIDs, the so called
`well-known groups'. For example, UNIX has no GID for the group of `all
users'. NT has a SID for them, called `Everyone' in the english
speaking versions.

Now, how are permissions given to objects? A process may attach a SD
to the object. The SD of an object consists of three parts:

  - the SID of the owner
  - the SID of the group
  - a list of SIDs with their permissions, called `access control list'
    (ACE)

UNIX is able, to create three different permissions, the permissions
of the owner, of the group and of the world. The ACL has a potentially
infinite count of members. Every member is a so called `access control
element' (ACE). An ACE contains three parts:

  - the type of the ACE
  - permissions, described via a DWORD
  - the SID, for which the above permissions are set

The two important types of ACEs are the `access allowed ACE' and the
`access denied ACE'.
The possible permissions on objects are more complicated than in
UNIX. As example, the permission, to delete an object is different
from the write permission.

With the forementioned method, NT is able, to grant or revoke
permissions to objects in a far more exact way. But what's about
cygwin? In a POSIX environment, it would be fine, to have the security
behaviour of a POSIX system. The NT security model is able, to reproduce
the POSIX model. The ntsec patch tries, to do this in cygwin.

The creation of explicit object security is a bit complicated, so
typically only two simple variations are used:

  - default permissions, computed by the operating system
  - any permission to everyone

For parameters to functions, that create or open securable objects,
another data structure is used, the `security attributes' (SA). This
structure contains a SD and a flag, that specifies whether the returned
handle to the created or opened object is inherited to child processes
or not. This property is not important for the ntsec patch, so in this
document, SDs and SAs are more or less identical.


2. Process privileges
---------------------

Any process, started under control of cygwin, has a semaphore attached
to it, which is used for signalling purposes. The creation of this
semaphore is found in sigproc.cc, function `getsem'. The first parameter
to the function call `CreateSemaphore' is a SA. Without ntsec patch,
this SA assigns default security to the semaphore. This has a simple
disadvantage: Only the owner of the process may send signals to it. Or,
in other words, if the owner of the process is not member of the
administrators group, no administrator may kill the process! This is
especially annoying if processes are started via service manager.

The ntsec patch now assigns a SA to the process control semaphore, that
has any permission set for the owner of the process and any permission
set for the administrators group. The creation of this SA is done by
the function `sec_user' that you can find in `shared.cc'. Any member
of the administrators group may now send signals to any process created
in cygwin, regardless of the process owner.


3. File permissions
-------------------

The setting of file permissions is controlled by the new CYGWIN variable
setting `[no]ntsec'. If ntsec is turned on, file permissions are
set like in UNIX. A SD is assigned to the file, containing the owner and
group and ACEs for the owner, the group and `Everyone'. If the group of
the file is not the administrators group, the administrators group get
any permission. This has the effect, that the administrators group has
permissions on files, that are equvalent to root permissions on UNIX
systems.

The complete setting of UNIX like permissions is found in the file
`security.cc'. The two functions `get_nt_attribute' and
`set_nt_attribute' are the main code. The reading and writing of the
SDs is done by the functions `ReadSD' and `WriteSD'. They are using the
Backup API functions `BackupRead' and `BackupWrite', that have the
advantage, not to crash if they are used on non NTFS file systems!
This crashes are default behaviour of the security API, if it's used
on, e.g., FAT or SAMBA file systems :-(

Unfortunately, the settings of NT file security is only available on
NTFS. SAMBA doesn't support it.

If you create a file `foo' outside of cygwin, you will see something
like the following on `ls -ln':

If your login is member of the Administrators group:
  rwxrwxrwx 1  544  513  ... foo
if not:
  rwxrwxrwx 1  1000  513  ... foo

Notice the user and group IDs. 544 is the UID of the administrators
group. This is a `feature' :-P of WinNT. If one is member of the
administrators group, every file, that he has created is owned by the
administrators group, instead of owned by him.

The second example shows the UID of the first user, that is created in
the user adminstration tool of NT. The users and groups are sequentially
numbered, beginning with 1000. Users and groups are using the same
numbering scheme, so no user and group share the same ID.

Of special interest is in both examples the GID 513. This GID is a
well known group with the meaning `nobody', named 'None' in the
english, `Kein' in the german, `Aucun' in the french version of NT,
etc. This means, that no group ownership is assigned to the file.
If you give permissions to this group, you will wonder: Any permission,
that is assigned to this group, has the inverse effect on any other
user and group!!! So: If 'None' may write a file, in reality nobody
may write a file. This is very confusing. In function `set_nt_attribute'
a simple check is done, to avoid giving any permission to `None'.

To work fine, the ntsec patch is dependend on well formed files
/etc/passwd and /etc/group. The names and the IDs must correspond
correctly to the NT IDs! The IDs used in cygwin are the last component
of the NT SID. A SID of e.g. the user `corinna' on my NT workstation:

  S-1-5-21-165875785-1005667432-441284377-1000

You see, the SIDs are a little bit complicated. Notice the last part:
It's the number 1000, the cygwin's UID.

Unfortunately, we don't have a tool, that creates such well formed
files. mkpasswd and mkgroup are not yet adapted to the ntsec patch.
Especially two problems are worth mentioning:

  - AFAIK, no NT function returns a list of well known groups.
  - On workstations, that are not member of a domain, there is no
    attachment between users and a default group. This would be
    nice for creating a correctly passwd file.

To give help for creating correct passwd and group files, look at
the following examples, that are parts of my files. With the exception
of my personal user entry, all entries are well known entries. For
better understanding, the names are translated to english NT version:

/etc/passwd
===========
everyone:*:0:0:::
system:*:18:18:::
administrator::500:544::/home/root:/bin/bash
guest:*:501:546:::
administrators:*:544:544::/home/root:
corinna::1000:547:Corinna Vinschen:/home/corinna:/bin/tcsh

/etc/group
==========
everyone::0:
system::18:
none::513:
administrators::544:
users::545:
guests::546:
powerusers::547:

The groups, that are mentioned also in the passwd file have the
advantage, that they are attached to a file as owner and that they
are showed in `ls -l' calls.

The group `system' is the owner and the group of processes, if they
are started via service manager. The same for files, if they are
created by processes, started via service manager.
--------------------------------------------------------------------
------------------------------- snap -------------------------------
--------------------------------------------------------------------

Ok, I hope, that this short description helps, to understand
the patch. Feel free, to ask any more questions.

Best Regards,
Corinna

-- 
new mail address:
mailto:corinna@vinschen.de