Welcome to mirror list, hosted at ThFree Co, Russian Federation.

cygwin.com/git/newlib-cygwin.git - Unnamed repository; edit this file 'description' to name the repository.
summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
Diffstat (limited to 'winsup/doc/ntsec.sgml')
-rw-r--r--winsup/doc/ntsec.sgml734
1 files changed, 0 insertions, 734 deletions
diff --git a/winsup/doc/ntsec.sgml b/winsup/doc/ntsec.sgml
deleted file mode 100644
index 54deaf16d..000000000
--- a/winsup/doc/ntsec.sgml
+++ /dev/null
@@ -1,734 +0,0 @@
-<sect1 id="ntsec"><title>NT security and the <literal>ntsec</literal> usage</title>
-
-<para>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.</para>
-<para>Chapter two discusses the changes in ntsec related to privileges on
-processes.</para>
-<para>Chapter three shows the basics of UNIX like setting of
-file permissions.</para>
-<para>Chapter four talks about the advanced settings introduced in
-release 1.1</para>
-<para>Chapter five illustrates the permission mapping leak of Windows NT.</para>
-<para>Chapter six describes the new support of a setuid concept introduced
-with release 1.1.3.</para>
-
-<para>Chapter six describes in short the new acl API since release 1.1</para>
-
-<para>The setting of UNIX like object permissions is controlled by the new
-<EnVar>CYGWIN</EnVar> variable setting <literal>(no)ntsec</literal>.</para>
-
-<sect2 id="ntsec-common"><title>NT security</title>
-
-<para>The NT security allows a process to allow or deny access of
-different kind to `objects'. `Objects' are files, processes,
-threads, semaphores, etc.</para>
-
-<para>The main 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).</para>
-
-<para>A SID is a unique identifier for users, groups and domains.
-SIDs are comparable to UNIX UIDs and GIDs, but are more complicated
-because they are unique across networks. Example:</para>
-
-<para>SID of a system `foo':</para>
-
-<screen>
- S-1-5-21-165875785-1005667432-441284377
-</screen>
-
-<para>SID of a user `johndoe' of the system `foo':</para>
-
-<screen>
- S-1-5-21-165875785-1005667432-441284377-1023
-</screen>
-
-<para>The above example shows the convention for printing SIDs. The leading
-`S' should show that it is a SID. The next number is a version number which
-is always 1. The next number is the so called `top-level authority' that
-identifies the source that issued the SID.</para>
-
-<para>While each system in a NT network has it's own SID, the situation
-is modified in NT domains: The SID of the domain controller is the
-base SID for each domain user. If an NT user has one account as domain
-user and another account on his local machine, this accounts are under
-any circumstances DIFFERENT, regardless of the usage of the same user
-name and password!</para>
-
-<para>SID of a domain `bar':</para>
-
-<screen>
- S-1-5-21-186985262-1144665072-740312968
-</screen>
-
-<para>SID of a user `johndoe' in the domain `bar':</para>
-
-<screen>
- S-1-5-21-186985262-1144665072-740312968-1207
-</screen>
-
-<para>The last part of the SID, the so called `relative identifier' (RID),
-is by default used as UID and/or GID under cygwin. As the name and the
-above example implies, this id is unique only relative to one system or
-domain.</para>
-
-<para>Note, that it's possible, that an user has the same RID on two
-different systems. The resulting SIDs are nevertheless different, so
-the SIDs are representing different users in an NT network.</para>
-
-<para>There is a big difference between UNIX IDs and NT SIDs, the existence of
-the so called `well known groups'. For example UNIX has no GID for the
-group of `all users'. NT has an SID for them, called `Everyone' in the
-English versions. The SIDs of well-known groups are not unique across
-an NT network but their meanings are unmistakable.
-Examples of well-known groups:</para>
-
-<screen>
-everyone S-1-1-0
-creator/owner S-1-3-0
-batch process (via `at') S-1-5-3
-authenticated users S-1-5-11
-system S-1-5-18
-</screen>
-
-<para>The last important group of SIDs are the `predefined groups'. This
-groups are used mainly on systems outside of domains to simplify the
-administration of user permissions. The corresponding SIDs are not unique
-across the network so they are interpreted only locally:</para>
-
-<screen>
-administrators S-1-5-32-544
-users S-1-5-32-545
-guests S-1-5-32-546
-...
-</screen>
-
-<para>Now, how are permissions given to objects? A process may assign an SD
-to the object. The SD of an object consists of three parts:</para>
-
-<itemizedlist spacing="compact">
-<listitem><para>the SID of the owner </para></listitem>
-<listitem><para>the SID of the group </para></listitem>
-<listitem><para>a list of SIDs with their permissions, called
-`access control list' (ACL) </para></listitem>
-</itemizedlist>
-
-<para>UNIX is able to create three different permissions, the permissions
-for the owner, for the group and for the world. In contrast the ACL
-has a potentially infinite number of members. Every member is a so called
-`access control element' (ACE). An ACE contains three parts:</para>
-
-<itemizedlist spacing="compact">
-<listitem><para>the type of the ACE </para></listitem>
-<listitem><para>permissions, described with a DWORD </para></listitem>
-<listitem><para>the SID, for which the above mentioned permissions are
-set </para></listitem>
-</itemizedlist>
-
-<para>The two important types of ACEs are the `access allowed ACE' and the
-`access denied ACE'. The ntsec patch only used `access allowed ACEs' up
-to Cygwin version 1.1.0. Later versions also use `access denied ACEs'
-to reflect the UNIX permissions as well as possible.</para>
-
-<para>The possible permissions on objects are more detailed than in
-UNIX. For example, the permission to delete an object is different
-from the write permission.</para>
-
-<para>With the aforementioned method NT is able to grant or revoke permissions
-to objects in a far more specific way. But what about cygwin? In a POSIX
-environment it would be fine to have the security behavior of a POSIX
-system. The NT security model is MOSTLY able to reproduce the POSIX model.
-The ntsec patch tries to do this in cygwin.</para>
-
-<para>You ask "Mostly? Why mostly???" Because there's a leak in the NT model.
-I will describe that in detail in chapter 4.</para>
-
-<para>Creating explicit object security is not that easy so you will often
-see only two simple variations in use:</para>
-
-<itemizedlist spacing="compact">
-<listitem><para>default permissions, computed by the operating system </para></listitem>
-<listitem><para>each permission to everyone </para></listitem>
-</itemizedlist>
-
-<para>For parameters to functions that create or open securable objects another
-data structure is used, the `security attributes' (SA). This structure
-contains an SD and a flag that specifies whether the returned handle
-to the object is inherited to child processes or not.
-This property is not important for the ntsec patch description so in
-this document the difference between SDs and SAs is ignored.</para>
-
-</sect2>
-
-<sect2 id="ntsec-processes"><title>Process privileges</title>
-
-<para>Any process started under control of cygwin has a semaphore attached
-to it, that is used for signaling purposes. The creation of this semaphore
-can be found in sigproc.cc, function `getsem'. The first parameter to the
-function call `CreateSemaphore' is an SA. Without ntsec patch this SA
-assigns default security to the semaphore. There is 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 a member of the administrators' group,
-no administrator may kill the process! This is especially annoying, if
-processes are started via service manager.</para>
-
-<para>The ntsec patch now assigns an SA to the process control semaphore, that
-has each permission set for the user of the process, for the
-administrators' group and for `system', which is a synonym for the
-operating system itself. The creation of this SA is done by the function
-`sec_user', that can be found in `shared.cc'. Each member of the
-administrators' group is now allowed to send signals to any process
-created in cygwin, regardless of the process owner.</para>
-
-<para>Moreover, each process now has the appropriate security settings, when
-it is started via `CreateProcess'. You will find this in function
-`spawn_guts' in module `spawn.cc'. The security settings for starting a
-process in another user context have to add the sid of the new user, too.
-In the case of the `CreateProcessAsUser' call, sec_user creates an SA with
-an additional entry for the sid of the new user.</para>
-
-</sect2>
-
-<sect2 id="ntsec-files"><title>File permissions</title>
-
-<para>If ntsec is turned on, file permissions are set as in UNIX. An SD is
-assigned to the file containing the owner and group and ACEs for the
-owner, the group and `Everyone'.</para>
-
-<para>The complete settings of UNIX like permissions can be 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 `read_sd' and `write_sd'. `write_sd' uses the function `BackupRead'
-instead of the simpler function `SetFileSecurity' because the latter is
-unable to set owners different from the caller.</para>
-
-<para>If you are creating a file `foo' outside of cygwin, you will see something
-like the following on <command>ls -ln</command>:</para>
-
-<para>If your login is member of the administrators' group:</para>
-<screen>
- rwxrwxrwx 1 544 513 ... foo
-</screen>
-<para>if not:</para>
-<screen>
- rwxrwxrwx 1 1000 513 ... foo
-</screen>
-
-<para>Note the user and group IDs. 544 is the UID of the administrators' group.
-This is a `feature' <literal>:-P</literal> of WinNT. If one is a member of
-the administrators' group, every file, that he has created is owned by the
-administrators' group, instead by him.</para>
-
-<para>The second example shows the UID of the first user, that has been
-created with NT's the user administration tool. The users and groups are
-sequentially numbered, starting with 1000. Users and groups are using the
-same numbering scheme, so a user and a group don't share the same ID.</para>
-
-<para>In both examples the GID 513 is of special interest. This GID is a
-well known group with different naming in local systems and domains.
-Outside of domains the group is named 'None' (`Kein' in German, `Aucun'
-in French, etc.), in domains it is named 'Domain Users'. Unfortunately,
-the group `None' is never shown in the user admin tool outside of domains!
-This is very confusing but this seems to have no negative consequences.</para>
-
-<para>To work correctly the ntsec patch depends on the files
-<filename>/etc/passwd/</filename> and <filename>/etc/group</filename>.
-In cygwin release 1.0 the names and the IDs must correspond to the
-appropriate NT IDs! The IDs used in cygwin are the RID of the NT SID, as
-mentioned earlier.
-An SID of e.g. the user `corinna' on my NT workstation:</para>
-
-<screen>
- S-1-5-21-165875785-1005667432-441284377-1000
-</screen>
-
-<para>Note the last number: It's the RID 1000, the cygwin's UID.</para>
-
-<para>Unfortunately, workstations and servers outside of domains are not
-able to set primary groups! In these cases, where there is no correlation
-of users to primary groups, NT returns 513 (None) as primary group,
-regardless of the membership to existing local groups.</para>
-
-<para>When using <command>mkpasswd -l -g</command> on such systems, you
-have to change the primary group by hand if `None' as primary group is
-not what you want (and I'm sure, it's not what you want!)</para>
-
-<para>Look at the following examples, which were parts of my files before
-storing SIDs in /etc/passwd and /etc/group had been introduced (See next
-chapter for details). With the exception of my personal user entry, all
-entries are well known entries.</para>
-
-<example>
-<title>/etc/passwd</title>
-<screen>
-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
-</screen>
-</example>
-
-<example>
-<title>/etc/group</title>
-<screen>
-everyone::0:
-system::18:
-none::513:
-administrators::544:
-users::545:
-guests::546:
-powerusers::547:
-</screen>
-</example>
-
-<para>As you can see, I changed my primary group membership from 513 (None)
-to 547 (powerusers). So all files I created inside of Cygwin were now owned
-by the powerusers group instead of None. This is the way I liked it.</para>
-
-<para>Groups may be mentioned in the passwd file, too. This has two
-advantages:</para>
-<itemizedlist spacing="compact">
-<listitem><para>Because NT assigns them to files as owners, a
-<command>ls -l</command> is often more readable.</para></listitem>
-<listitem><para>Moreover it's possible to assigned them to files as
-owners with cygwin's <command>chown</command>.</para></listitem>
-</itemizedlist>
-
-<para>The group `system' is the aforementioned synonym for the operating system
-itself and is normally the owner of processes, that are started through
-service manager. The same is true for files, that are created by
-processes, which are started through service manager.</para>
-
-</sect2>
-
-<sect2 id="ntsec-release1.1"><title>New since Cygwin release 1.1</title>
-
-<para>In Cygwin release 1.1 a new technique of using the
-<filename>/etc/passwd</filename> and <filename>/etc/group</filename>
- is introduced.</para>
-
-<para>Both files may now contain SIDs of users and groups. They
-are saved in the last field of pw_gecos in <filename>/etc/passwd</filename>
-and in the gr_passwd field in <filename>/etc/group</filename>.</para>
-
-<para>This has the following advantages:</para>
-<itemizedlist spacing="compact">
-<listitem><para>ntsec works better in domain environments.</para></listitem>
-<listitem><para>Accounts (users and groups) may get another name in
-cygwin than their NT account name. The name in <filename>/etc/passwd</filename>
-or <filename>/etc/group</filename> is transparently used by cygwin
-applications (eg. <command>chown</command>, <command>chmod</command>,
-<command>ls</command>):</para>
-
-<screen>
-root::500:513::/home/root:/bin/sh
-</screen>
-
-<para>instead of</para>
-
-<screen>
-adminstrator::500:513::/home/root:/bin/sh
-</screen>
-
-<para>Caution: If you like to use the account as login account via
-<command>telnet</command> etc. you have to remain the name unchanged or
-you have to use the special version of <command>login</command> which is
-part of the standard Cygwin distribution since 1.1.</para></listitem>
-<listitem><para>Cygwin UIDs and GIDs are now not necessarily the RID
-part of the NT SID:</para>
-
-<screen>
-root::0:513:S-1-5-21-54355234-56236534-345635656-500:/home/root:/bin/sh
-</screen>
-
-<para>instead of</para>
-
-<screen>
-root::500:513::/home/root:/bin/sh
-</screen>
-
-</listitem>
-<listitem><para>As in U*X systems UIDs and GIDs numbering scheme now
-don't influence each other. So it's possible to have same Id's for a
-user and a group:</para>
-<example>
-<title>/etc/passwd:</title>
-<screen>
-root::0:0:S-1-5-21-54355234-56236534-345635656-500:/home/root:/bin/sh
-</screen>
-</example>
-
-<example>
-<title>/etc/group:</title>
-<screen>
-root:S-1-5-32-544:0:
-</screen>
-</example>
-</listitem>
-</itemizedlist>
-
-<para>The tools <command>mkpasswd</command> and <command>mkgroup</command>
-create the needed entries by default. If you don't want that you can use
-the options <literal>-s</literal> or <literal>--no-sids</literal>. I suggest
-not to do this since ntsec works better when having the SIDs available.</para>
-
-<para>Please note that the pw_gecos field in <filename>/etc/passwd</filename>
-is defined as a comma seperated list. The SID has to be the last field!</para>
-
-<para>As aforementioned you are able to use cygwin account names different
-from the NT account names. If you want to login thru `telnet' or something
-else you have to use the special <command>login</command>. You may then
-add another field to pw_gecos which contains the NT user name including
-it's domain. So you are able to login as each domain user. The syntax
-is easy: Just add an entry of the form U-ntdomain\ntusername to the pw_gecos
-field. Note that the SID must still remain the last field in pw_gecos!</para>
-
-<screen>
-the_king::1:1:Elvis Presley,U-STILLHERE\elvis,S-1-5-21-1234-5678-9012-1000:/bin/sh
-</screen>
-
-<para>For a local user just drop the domain:</para>
-
-<screen>
-the_king::1:1:Elvis Presley,U-elvis,S-1-5-21-1234-5678-9012-1000:/bin/sh
-</screen>
-
-<para>In either case the password of the user is taken from the NT user
-database, NOT from the passwd file!</para>
-
-<para>As in the previous chapter I give my personal
-<filename>/etc/passwd</filename> and <filename>/etc/group</filename> as
-examples. Please note that I've changed these files heavily! There's no
-need to change them that way, it's just for testing purposes and...
-for fun.</para>
-
-<example>
-<title>/etc/passwd</title>
-<screen>
-root:*:0:0:Administrators group,S-1-5-32-544::
-SYSTEM:*:18:18:,S-1-5-18:/home/system:/bin/bash
-admin:*:500:513:,S-1-5-21-1844237615-436374069-1060284298-500:/home/Administrator:/bin/bash
-corinna:*:100:0:Corinna Vinschen,S-1-5-21-1844237615-436374069-1060284298-1003:/home/corinna:/bin/tcsh
-Guest:*:501:546:,S-1-5-21-1844237615-436374069-1060284298-501:/home/Guest:/bin/bash
-</screen>
-</example>
-
-<example>
-<title>/etc/group</title>
-<screen>
-root:S-1-5-32-544:0:
-local:S-1-2-0:2:
-network:S-1-5-2:3:
-interactive:S-1-5-4:4:
-authenticatedusers:S-1-5-11:5:
-SYSTEM:S-1-5-18:18:
-local_svc:S-1-5-19:19:
-netwrk_svc:S-1-5-20:20:
-none:S-1-5-21-1844237615-436374069-1060284298-513:513:
-bckup_op:S-1-5-32-551:551:
-guests:S-1-5-32-546:546:
-pwrusers:S-1-5-32-547:547:
-replicator:S-1-5-32-552:552:
-users:S-1-5-32-545:545:
-</screen>
-</example>
-
-<para>If you want to do similar changes to your files, please do that only
-if you're feeling comfortably with the concepts. Otherwise don't be surprised
-if some stuff doesn't work anymore. If you screwed up things, revert to files
-created by mkpasswd and mkgroup. Especially don't change the uid or the name
-of user SYSTEM. Even if that works mostly, some Cygwin applications running
-as local service under that account could behave strangly suddenly.</para>
-
-</sect2>
-
-<sect2 id="ntsec-mapping"><title>The mapping leak</title>
-
-<para>Now its time to point out the leak in the NT permissions.
-The official documentation explains in short the following:</para>
-<itemizedlist spacing="compact">
-<listitem><para>access allow ACEs are accumulated regarding to the
-group membership of the caller.</para></listitem>
-<listitem><para>The order of ACEs is important. The system reads them
-in sequence until either any needed right is denied or all needed rights
-are granted. Later ACEs are then not taken into account.</para></listitem>
-<listitem><para>All access denied ACEs _should_ precede any
-access allowed ACE.</para></listitem>
-</itemizedlist>
-
-<para>Note that the last rule is a preference, not a law. NT will correctly
-deal with the ACL regardless of the sequence order. The second rule is
-not modified to get the ACEs in the prefered order.</para>
-
-<para>Unfortunately the security tab of the NT4 explorer is completely
-unable to deal with access denied ACEs while the explorer of W2K rearranges
-the order of the ACEs before you can read them. Thank God, the sort order
-remains unchanged if one presses the Cancel button.</para>
-
-<para>You still ask "Where is the leak?" NT ACLs are unable to reflect each
-possible combination of POSIX permissions. Example:</para>
-
-<screen>
-rw-r-xrw-
-</screen>
-
-<para>1st try:</para>
-
-<screen>
-UserAllow: 110
-GroupAllow: 101
-OthersAllow: 110
-</screen>
-
-<para>Hmm, because of the accumulation of allow rights the user may
-execute because the group may execute.</para>
-
-<para>2st try:</para>
-
-<screen>
-UserDeny: 001
-GroupAllow: 101
-OthersAllow: 110
-</screen>
-
-<para>Now the user may read and write but not execute. Better? No!
-Unfortunately the group may write now because others may write.</para>
-
-<para>3rd try:</para>
-
-<screen>
-UserDeny: 001
-GroupDeny: 010
-GroupAllow: 001
-OthersAllow: 110
-</screen>
-
-<para>Now the group may not write as intended but unfortunately the user may
-not write anymore, too. How should this problem be solved? According to
-the official rules a UserAllow has to follow the GroupDeny but it's
-easy to see that this can never be solved that way.</para>
-
-<para>The only chance:</para>
-
-<screen>
-UserDeny: 001
-UserAllow: 010
-GroupDeny: 010
-GroupAllow: 001
-OthersAllow: 110
-</screen>
-
-<para>Again: This works for both, NT4 and W2K. Only the GUIs aren't
-able to deal with that order.</para>
-
-</sect2>
-
-<sect2 id="ntsec-aclfuncs"><title>New acl API</title>
-
-<para>For dealing with ACLs Cygwin now has the acl API as it's
-implemented in newer versions of Solaris. The new data structure
-for a single ACL entry (ACE in NT terminology) is defined in
-<filename>sys/acl.h</filename> as:</para>
-
-<screen>
-typedef struct acl {
- int a_type; /* entry type */
- uid_t a_id; /* UID | GID */
- mode_t a_perm; /* permissions */
-} aclent_t;
-</screen>
-
-<para>The a_perm member of the aclent_t type contains only the bits
-for read, write and execute as in the file mode. If eg. read permission
-is granted, all read bits (S_IRUSR, S_IRGRP, S_IROTH) are set.
-CLASS_OBJ or MASK ACL entries are not fully implemented yet.</para>
-
-<para>The new API calls are</para>
-
-<screen>
-acl(2), facl(2)
-aclcheck(3),
-aclsort(3),
-acltomode(3), aclfrommode(3),
-acltopbits(3), aclfrompbits(3),
-acltotext(3), aclfromtext(3)
-</screen>
-
-<para>Like in Solaris, Cygwin has two new commands for working with
-ACLs on the command line: <command>getfacl</command> and
-<command>setfacl</command>.</para>
-
-<para>Online man pages for the aforementioned commands and API calls
-can be found on eg. http://docs.sun.com</para>
-
-</sect2>
-
-<sect2 id="ntsec-setuid"><title>New setuid concept</title>
-
-<para>UNIX applications which have to switch the user context are using
-the <command>setuid</command> and <command>seteuid</command> calls which
-are not part of the Windows API.
-Nevertheless these calls are supported under Windows NT/W2K since Cygwin
-release 1.1.3. Because of the nature of NT security an application which
-needs the ability has to be patched, though.</para>
-
-<para>NT uses so called `access tokens' to identify a user and it's
-permissions. To switch the user context the application has to request
-such an `access token'. This is typically done by calling the NT API
-function <command>LogonUser</command>. The access token is returned and
-either used in <command>ImpersonateLoggedOnUser</command> to change user
-context of the current process or in <command>CreateProcessAsUser</command>
-to change user context of a spawned child process. An important restriction
-is that the application using <command>LogonUser</command> must have special
-permissions:</para>
-
-<screen>
-"Act as part of the operating system"
-"Replace process level token"
-"Increase quotas"
-</screen>
-
-<para>Note that administrators do not have all these user rights set
-by default.</para>
-
-<para>Two new Cygwin calls are introduced to support porting
-<command>setuid</command> applications with a minimum of effort. You only
-give Cygwin the right access token and then you can call
-<command>seteuid</command> or <command>setuid</command> as usual in POSIX
-applications. The call to <command>sexec</command> is not needed
-anymore. Porting a <command>setuid</command> application is illustrated by
-a short example:</para>
-
-<screen>
-
-/* First include all needed cygwin stuff. */
-#ifdef __CYGWIN__
-#include &lt;windows.h&gt;
-#include &lt;sys/cygwin.h&gt;
-/* Use the following define to determine the Windows version */
-#define is_winnt (GetVersion() < 0x80000000)
-#endif
-
-[...]
-
- struct passwd *user_pwd_entry = getpwnam (username);
- char *cleartext_password = getpass ("Password:");
-
-[...]
-
-#ifdef __CYGWIN__
- /* Patch the typical password test. */
- if (is_winnt)
- {
- HANDLE token;
-
- /* Try to get the access token from NT. */
- token = cygwin_logon_user (user_pwd_entry, cleartext_password);
- if (token == INVALID_HANDLE_VALUE)
- error_exit;
- /* 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);
- }
- else
-#endif /* CYGWIN */
- /* Use standard method for W9X as well. */
- hashed_password = crypt (cleartext_password, salt);
- if (!user_pwd_entry ||
- strcmp (hashed_password, user_pwd_entry-&gt;pw_password))
- error_exit;
-
-[...]
-
- /* Everything else remains the same! */
-
- setegid (user_pwd_entry-&gt;pw_gid);
- seteuid (user_pwd_entry-&gt;pw_uid);
- execl ("/bin/sh", ...);
-
-</screen>
-
-<para>The new Cygwin call to retrive an access token is defined as follows:</para>
-
-<screen>
-#include &lt;windows.h&gt;
-#include &lt;sys/cygwin.h&gt;
-
-HANDLE
-cygwin_logon_user (struct passwd *pw, const char *cleartext_password)
-</screen>
-
-<para>You can call that function as often as you want for different user
-logons and remeber the access tokens for further calls to the second function.</para>
-
-<screen>
-#include &lt;windows.h&gt;
-#include &lt;sys/cygwin.h&gt;
-
-void
-cygwin_set_impersonation_token (HANDLE hToken);
-</screen>
-
-<para> is the call to inform Cygwin about the user context to which further
-calls to <command>setuid</command>/<command>seteuid</command> should switch to.
-While you need always the correct access token to do a
-<command>setuid</command>/<command>seteuid</command> to another users context,
-you are always able to use <command>setuid</command>/<command>seteuid</command>
-to return to your own user context by giving your own uid as parameter.</para>
-
-<para>If you have remembered several access tokens from calls to
-<command>cygwin_logon_user</command> you can switch to different user
-contexts by observing the following order:</para>
-
-<screen>
-
- cygwin_set_impersonation_token (user1_token);
- seteuid (user1_uid);
-
-[...]
-
- seteuid (own_uid);
- cygwin_set_impersonation_token (user2_token);
- seteuid (user2_uid);
-
-[...]
-
- seteuid (own_uid);
- cygwin_set_impersonation_token (user1_token);
- seteuid (user1_uid);
-
-etc.
-
-</screen>
-
-</sect2>
-
-<sect2 id="ntsec-release1.3.3"><title>New since Cygwin release 1.3.3</title>
-
-<para>
-Since Cygwin release 1.3.3, applications having the
-<command>Create a process level token</command> user right can switch user
-context without giving a password by just calling the usual
-<command>setuid</command>, <command>seteuid</command>,
-<command>setgid</command> and <command>setegid</command> functions. This is
-typically only given to the SYSTEM user. However, this now allows to switch
-the user context using e. g. rhosts authentication or (when running sshd
-under SYSTEM account as service) public key authentication.
-</para>
-<para>
-An important restriction of this method is, that a process started under
-SYSTEM account can't access network shares which require authentication.
-This also applies to the subprocesses which switched the user context
-without a password. People using network home drives are typically not
-able to access it when trying to login using ssh or rsh without password.
-</para>
-
-</sect2>
-
-</sect1>