ntsec documentation, 2nd try

[Corinna Vinschen <corinna@vinschen.de>]

Hi!

I have changed this and that in the documentation. Some errors,
strange English language, etc.
Please read it and send opinions, error reports, patches to me.

Regards,
Corinna

-- 
new mail address:
mailto:corinna@vinschen.de
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 discusses the change in ntsec, related to privileges on
processes.
Chapter three shows the UNIX like setting of file permissions.

The setting of UNIX like object permissions is controlled by the new
CYGWIN variable setting `[no]ntsec'.

On NT, ntsec is now turned on by default.


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'
(ACL)

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 ntsec patch only uses `access allowed ACEs'.

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 behavior 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
  - every 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 signaling 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 every permission set for the user of the process and every 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'. Every member
of the administrators group may now send signals to any process created
in cygwin, regardless of the process owner.

Moreover, every process now has the appropriate security settings, when
it's started via `CreateProcess'. You will find this in function
`spawn_guts' in module `spawn.cc'. The security setting of starting a
process in another user context isn't correct yet, the call to
`CreateProcessAsUser' not changed. The simple settings of `sec_user'
are not sufficient in this case.


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

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 every permission.
This has the effect, that the administrators group has permissions on
files, that are equivalent 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
behavior 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 every 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 dependent 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, workstations and serves outside of domains are not
able, to set primary groups! In these cases, where there is no attachment
of users to primary groups, NT returns 513 (None) as primary group,
regardless of the membership to regular groups of these users.

The tools 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.
    mkgroup should do this automatically. Today, it only lists
    the `Everyone' entry automatically. Unfortunately it lists
    the english entry, regardless of the native language version
    of NT. E.g. the german name is `Jeder'.

  - On workstations and servers, that are not member of a domain,
    there is no attachment between users and a primary group. This
    would be nice for creating a correctly passwd file but...
    Ok, you have to change it by hand if `None' as primary group is
    not what you want.

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.