JehanneOS/newlib
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

* ntsec.sgml: Revamp parts of the doc for clearness.

Browse Source
This commit is contained in:
Corinna Vinschen 2008-12-03 11:47:27 +00:00
parent f5e7a77023
commit 5875a5e7d5
2 changed files with 86 additions and 61 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
winsup/doc/ChangeLog
View File

@ -1,3 +1,7 @@
2008-12-03 Corinna Vinschen <corinna@vinschen.de>
* ntsec.sgml: Revamp parts of the doc for clearness.
2008-12-02 Corinna Vinschen <corinna@vinschen.de> 2008-12-02 Corinna Vinschen <corinna@vinschen.de>
* ntsec.sgml: Fix a few typos. * ntsec.sgml: Fix a few typos.

143
winsup/doc/ntsec.sgml
View File

@ -1,11 +1,11 @@
<sect1 id="ntsec"><title>Using Windows security in Cygwin</title> <sect1 id="ntsec"><title>Using Windows security in Cygwin</title>
<para>This paragraph discusses how the Windows security model is <para>This section discusses how the Windows security model is
utilized in Cygwin to implement POSIX-like permissions, as well as how utilized in Cygwin to implement POSIX-like permissions, as well as how
the authentication model is used to allow to switch the user context in the Windows authentication model is used to allow cygwin applications
a POSIX-like fashion.</para> to switch users in a POSIX-like fashion.</para>
<para>The setting of POSIX like file and directory permissions is <para>The setting of POSIX-like file and directory permissions is
controlled by the <link linkend="mount-table">mount</link> option controlled by the <link linkend="mount-table">mount</link> option
<literal>(no)acl</literal> which is set to <literal>acl</literal> by <literal>(no)acl</literal> which is set to <literal>acl</literal> by
default.</para> default.</para>
@ -14,9 +14,10 @@ default.</para>
be necessarily short. If you want to learn more about the Windows security be necessarily short. If you want to learn more about the Windows security
model, see the <ulink url="http://msdn.microsoft.com/en-us/library/aa374860(VS.85).aspx">Access Control</ulink> article in MSDN documentation.</para> model, see the <ulink url="http://msdn.microsoft.com/en-us/library/aa374860(VS.85).aspx">Access Control</ulink> article in MSDN documentation.</para>
<para>The POSIX security model is not discussed here, but assumed to be <para>POSIX concepts and specificially the POSIX security model are not
understood by the reader. If you don't know the POSIX security model, discussed here, but assumed to be understood by the reader. If you
search the web for beginner documentation.</para> don't know the POSIX security model, search the web for beginner
documentation.</para>
<sect2 id="ntsec-common"><title>Overview</title> <sect2 id="ntsec-common"><title>Overview</title>
@ -25,8 +26,8 @@ search the web for beginner documentation.</para>
<para>Every object has a data structure attached, called a "security <para>Every object has a data structure attached, called a "security
descriptor" (SD). The SD contains all information necessary to control descriptor" (SD). The SD contains all information necessary to control
who can how access an object. The SD of an object consists of five who can access an object, and to determine what they are allowed to do
parts:</para> to or with it. The SD of an object consists of five parts:</para>
<itemizedlist spacing="compact"> <itemizedlist spacing="compact">
<listitem><para>Flags which control several aspects of this SD. This is <listitem><para>Flags which control several aspects of this SD. This is
@ -43,11 +44,13 @@ not discussed here.</para></listitem>
other stuff which is explained a bit later. Let's talk about the SID first. other stuff which is explained a bit later. Let's talk about the SID first.
</para> </para>
<para>A SID is a unique identifier for users, groups, computers and AD <para>A SID is a unique identifier for users, groups, computers and
domains. SIDs are basically comparable to POSIX UIDs and GIDs, but are Active Directory (AD) domains. SIDs are basically comparable to POSIX
more complicated because they are unique across multiple machines or user ids (UIDs) and group ids (GIDs), but are more complicated because
domains. A SID is a structure of multiple numerical values. There's they are unique across multiple machines or domains. A SID is a
a convenient convention to type SIDs. Here's an example:</para> structure of multiple numerical values. There's a convenient convention
to type SIDs, as a string of numerical fields separated by hyphen
characters. Here's an example:</para>
<para>SID of a machine "foo":</para> <para>SID of a machine "foo":</para>
@ -61,15 +64,18 @@ a convenient convention to type SIDs. Here's an example:</para>
S-1-5-21-165875785-1005667432-441284377-1023 S-1-5-21-165875785-1005667432-441284377-1023
</screen> </screen>
<para>The leading "S" has no further meaning except to show that this is <para>The first field is always "S", which is just a notational convention
a SID. The next number is a version number which is always 1 so far. to show that this is a SID. The second field is the version number of
The next two numbers are the authority which shows the initiated what the SID structure, So far there exists only one version of SIDs, so this
kind of SID this is. There are a couple of builtin accounts and field is always 1. The third and fourth fields represent the "authority"
accounts with very special meaning. However, computer and domain SIDs which can be thought of as a type or category of SIDs. There are a
always start with "S-1-5-21". The next three numbers, all 32 bit values, couple of builtin accounts and accounts with very special meaning which
are the unique 96 bit identifier of the computer system. This is have certain well known values in these third and fourth fields.
hopefully unique all over the world, but in practice it's sufficient if However, computer and domain SIDs always start with "S-1-5-21". The
the computer SIDs are unique within a single Windows network.</para> next three fields, all 32 bit values, represent the unique 96 bit
identifier of the computer system. This is a hopefully unique value all
over the world, but in practice it's sufficient if the computer SIDs are
unique within a single Windows network.</para>
<para>As you can see in the above example, SIDs of users (and groups) <para>As you can see in the above example, SIDs of users (and groups)
are identical to the computer SID, except for an additional part, the are identical to the computer SID, except for an additional part, the
@ -101,11 +107,11 @@ controller and you would like to create a domain account "johndoe":</para>
created on the machine "foo", one created in the domain "bar.local". created on the machine "foo", one created in the domain "bar.local".
Both have different SIDs and not even the RID is the same. How do Both have different SIDs and not even the RID is the same. How do
the systems know it's the same account? After all, the name is the systems know it's the same account? After all, the name is
the same, right? The answer is, these accounts are NOT identical. the same, right? The answer is, these accounts are <emphasis
For all the machines know there are two different accounts, one is role='bold'>not</emphasis> identical. All machines on the network will
treat these SIDs as identifying two separate accounts. One is
"FOO\johndoe", the other one is "BAR\johndoe" or "johndoe@bar.local". "FOO\johndoe", the other one is "BAR\johndoe" or "johndoe@bar.local".
Different SID, different account. Full stop. Different SID, different account. Full stop. </para>
</para>
<para>The last part of the SID, the so called "Relative IDentifier" (RID), <para>The last part of the SID, the so called "Relative IDentifier" (RID),
is by default used as UID and/or GID under Cygwin when you create the is by default used as UID and/or GID under Cygwin when you create the
@ -118,12 +124,12 @@ an option in both tools to change the offset...</para>
<para>Do you still remember the SIDs with special meaning? In offical <para>Do you still remember the SIDs with special meaning? In offical
notation they are called "well-known SIDs". For example, POSIX has no GID notation they are called "well-known SIDs". For example, POSIX has no GID
for the group of "all users" or "world" or "others". The last three rwx for the group of "all users" or "world" or "others". The last three rwx
bits in a permission value just represent the permissions for "everyone bits in a unix-style permission value just represent the permissions for
who is not the owner or is member of the owning group". Windows has a "everyone who is not the owner or is member of the owning group".
SID for these poor souls, the "Everyone" SID. Other well-known SIDs Windows has a SID for these poor souls, the "Everyone" SID. Other
represent circumstances under which a process is running, rather than well-known SIDs represent circumstances under which a process is
actual users or groups. Here are a few examples for well-known running, rather than actual users or groups. Here are a few examples
SIDs:</para> for well-known SIDs:</para>
<screen> <screen>
Everyone S-1-1-0 Simply everyone... Everyone S-1-1-0 Simply everyone...
@ -141,9 +147,13 @@ SYSTEM S-1-5-18 A special account which has all
an uber-root account. an uber-root account.
</screen> </screen>
<para>For a full list please refer to the MSDN document <para>For a full list please refer to the MSDN document <ulink
<ulink url="http://msdn.microsoft.com/en-us/library/aa379649.aspx">Well-known SIDs</ulink>. url="http://msdn.microsoft.com/en-us/library/aa379649.aspx">Well-known
Naturally well-known SIDs are the same on each machine, so they are SIDs</ulink>. The Cygwin package called "csih" provides a tool,
/usr/lib/csih/getAccountName.exe, which can be used to print the
(possibly localized) name for the various well-known SIDS.</para>
<para>Naturally well-known SIDs are the same on each machine, so they are
not unique to a machine or domain. They have the same meaning across not unique to a machine or domain. They have the same meaning across
the Windows network.</para> the Windows network.</para>
@ -489,22 +499,33 @@ aren't able (or willing) to deal with that order.</para>
</sect2> </sect2>
<sect2 id="ntsec-setuid-overview"><title id="ntsec-setuid-overview.title">Switching the user context</title> <sect2 id="ntsec-setuid-overview"><title id="ntsec-setuid-overview.title">Switching the user context</title>
<para>POSIX applications which have to switch the user context are using <para>Since Windows XP, Windows users have been accustomed to the
the <command>setuid</command> and <command>seteuid</command> calls. "Switch User" feature, which switches the entire desktop to another user
Windows doesn't support the concept of these calls in a simple while leaving the original user's desktop "suspended". Another Windows
fashion and switching the user context in Windows is generally a tricky feature (since Windows 2000) is the "Run as..." context menu entry,
process with lots of "behind the scenes" magic involved.</para> which allows to start an application using another user account when
right-clicking on applications and shortcuts.</para>
<para>On POSIX systems, this operation can be performed by processes
running under the privileged user accounts (usually the "root" user
account) on a per-process basis. This is called "switching the user
context" for that process, and is performed using the POSIX
<command>setuid</command> and <command>seteuid</command> system
calls.</para>
<para>While this sort of feature is available on Windows as well,
Windows does not support the concept of these calls in a simple fashion.
Switching the user context in Windows is generally a tricky process with
lots of "behind the scenes" magic involved.</para>
<para>Windows uses so-called `access tokens' to identify a user and its <para>Windows uses so-called `access tokens' to identify a user and its
permissions. Usually the access token is created at logon time and then permissions. Usually the access token is created at logon time and then
it's attached to the starting process. Every new process within a session it's attached to the starting process. Every new process within a session
inherits the access token from its parent process. Every thread can inherits the access token from its parent process. Every thread can
get its own access token, which allows to define threads with restricted get its own access token, which allows, for instance, to define threads
permissions. To switch the user context the process has to request such with restricted permissions.</para>
an access token for the new user.</para>
</sect2> </sect2>
@ -512,17 +533,20 @@ an access token for the new user.</para>
<para>To switch the user context the process has to request such an access <para>To switch the user context the process has to request such an access
token for the new user. This is typically done by calling the Win32 API token for the new user. This is typically done by calling the Win32 API
function <command>LogonUser</command>. The access token is returned and function <command>LogonUser</command> with the user name and the user's
either used in <command>ImpersonateLoggedOnUser</command> to change the cleartext password as arguments. If the user exists and the password was
user context of the current thread, or in specified correctly, the access token is returned and either used in
<command>CreateProcessAsUser</command> to change the user context of a <command>ImpersonateLoggedOnUser</command> to change the user context of
spawned child process. Later versions of Windows define new functions the current thread, or in <command>CreateProcessAsUser</command> to
in this context and there are also functions to manipulate existing change the user context of a spawned child process.</para>
access tokens (usually only to restrict them). Windows Vista also adds
subtokens which are attached to other access tokens which plays an <para>Later versions of Windows define new functions in this context and
important role in the UAC (User Access Control) facility of Vista and there are also functions to manipulate existing access tokens (usually
later. However, none of these extensions are really important for only to restrict them). Windows Vista also adds subtokens which are
this documentation.</para> attached to other access tokens which plays an important role in the UAC
(User Access Control) facility of Vista and later. However, none of
these extensions to the original concept are important for this
documentation.</para>
<para>Back to this logon with password, how can this be used to <para>Back to this logon with password, how can this be used to
implement <command>set(e)uid</command>? Well, it requires to patch the implement <command>set(e)uid</command>? Well, it requires to patch the
@ -539,8 +563,6 @@ application is illustrated by a short example:</para>
#ifdef __CYGWIN__ #ifdef __CYGWIN__
#include <windows.h> #include <windows.h>
#include <sys/cygwin.h> #include <sys/cygwin.h>
/* Use the following define to determine the Windows version */
#define is_winnt (GetVersion() < 0x80000000)
#endif #endif
[...] [...]
@ -559,10 +581,9 @@ application is illustrated by a short example:</para>
token = cygwin_logon_user (user_pwd_entry, cleartext_password); token = cygwin_logon_user (user_pwd_entry, cleartext_password);
if (token == INVALID_HANDLE_VALUE) if (token == INVALID_HANDLE_VALUE)
error_exit; error_exit;
/* Inform Cygwin about the new impersonation token. /* Inform Cygwin about the new impersonation token. */
Cygwin is able now, to switch to that user context by
setuid or seteuid calls. */
cygwin_set_impersonation_token (token); cygwin_set_impersonation_token (token);
/* Cygwin is now able, to switch to that user context by setuid or seteuid calls. */
} }
#else #else
/* Use standard method on non-Cygwin systems. */ /* Use standard method on non-Cygwin systems. */