* ntsec.sgml: Add description for the new setuid ability

of Cygwin since release 1.1.3.
        * overview2.sgml: Add description for new chroot functionality.
        * calls.texinfo: Add missing calls. Change comments for
        setuid, setgid, seteuid, setegid, chroot.

winsup/doc/ChangeLog

@@ -1,3 +1,11 @@
+Thu Jul 20 13:01:00 2000  Corinna Vinschen <corinna@vinschen.de>
+
+	* ntsec.sgml: Add description for the new setuid ability
+	of Cygwin since release 1.1.3.
+	* overview2.sgml: Add description for new chroot functionality.
+	* calls.texinfo: Add missing calls. Change comments for
+	setuid, setgid, seteuid, setegid, chroot.
+
 Tue May  3  0:25:00 2000  Corinna Vinschen <corinna@vinschen.de>
 
         * ntsec.sgml: Revisited description of `ntsec' according to

winsup/doc/calls.texinfo

@@ -251,8 +251,8 @@ net release.)}
 @item geteuid: P 4.2.1.1
 @item getgid: P 4.2.1.1
 @item getegid: P 4.2.1.1
-@item setuid: P 4.2.2.1 (stub, sets ENOSYS, returns zero)
+@item setuid: P 4.2.2.1 (stub on 9X, sets ENOSYS, returns zero)
-@item setgid: P 4.2.2.1 (stub, sets ENOSYS, returns zero)
+@item setgid: P 4.2.2.1 (stub on 9X, sets ENOSYS, returns zero)
 @item getgroups: P 4.2.3.1
 @item getlogin: P 4.2.4.1
 @item getlogin_r: P 4.2.4.1 -- unimplemented
@@ -583,16 +583,27 @@ in MS IP stack but may not be implemented in other vendors' stacks.
 
 @item Other
 @itemize @code
-@item chroot (stub, sets ENOSYS, returns -1)
+@item acl
+@item aclcheck
+@item aclfrommode
+@item aclfrompbits
+@item aclfromtext
+@item aclsort
+@item acltomode
+@item acltopbits
+@item acltotext
+@item chroot (with restrictions)
 @item closelog
 @item cwait
 @item cygwin_conv_to_full_posix_path
 @item cygwin_conv_to_full_win32_path
 @item cygwin_conv_to_posix_path
 @item cygwin_conv_to_win32_path
+@item cygwin_logon_user
 @item cygwin_posix_path_list_p
 @item cygwin_posix_to_win32_path_list
 @item cygwin_posix_to_win32_path_list_buf_size
+@item cygwin_set_impersonation_token
 @item cygwin_split_path
 @item cygwin_win32_to_posix_path_list
 @item cygwin_win32_to_posix_path_list_buf_size
@@ -604,6 +615,7 @@ in MS IP stack but may not be implemented in other vendors' stacks.
 @item dlsym
 @item endgrent
 @item endhostent
+@item facl
 @item ffs
 @item fstatfs
 @item ftime
@@ -638,10 +650,10 @@ in MS IP stack but may not be implemented in other vendors' stacks.
 @item regfree
 @item rexec
 @item select
-@item setegid: SVR4 (stub, sets ENOSYS, returns zero)@item endpwent
+@item setegid: SVR4 (stub on 9X, sets ENOSYS, returns zero)@item endpwent
 @item setenv
 @item seterrno
-@item seteuid (stub, sets ENOSYS, returns zero)
+@item seteuid (stub on 9X, sets ENOSYS, returns zero)
 @item sethostent
 @item setitimer
 @item setmntent

winsup/doc/ntsec.sgml

@@ -11,12 +11,13 @@ 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>.
+<EnVar>CYGWIN</EnVar> variable setting <literal>(no)ntsec</literal>.</para>
-On NT ntsec is now turned on by default.</para>
 
 <sect2 id="ntsec-common"><title>NT security</title>
 
@@ -516,4 +517,144 @@ 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 that 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
+have to care to 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>
+
 </sect1>

winsup/doc/overview2.sgml

@@ -67,18 +67,22 @@ nature.  The best example is that only NT provides a security model.</para>
 
 <sect2 id="ov-hi-perm"><title>Permissions and Security</title>
 <para>Windows NT includes a sophisticated security model based on Access
-Control Lists (ACLs).  Although some modern UNIX operating systems include
+Control Lists (ACLs).  Cygwin maps Win32 file ownership and permissions to the
-support for ACLs, Cygwin maps Win32 file ownership and permissions to the
+more standard, older UNIX model by default.  Cygwin version 1.1 introduces
-more standard, older UNIX model.  The chmod call maps UNIX-style permissions
+support for ACLs according to the system calls used on newer versions of
+Solaris. This ability is used when the `ntsec' feature is switched on which
+is described in another chapter.
+The chmod call maps UNIX-style permissions
 back to the Win32 equivalents.  Because many programs expect to be able to find
 the /etc/passwd and /etc/group files, we provide utilities that can be used to
 construct them from the user and group information provided by the operating
 system.</para>
 
 <para>Under Windows NT, the administrator is permitted to chown files.  There
-is currently no mechanism to support the setuid concept or API call.  Although
+is no mechanism to support the setuid concept or API call since Cygwin version
-we hope to support this functionality at some point in the future, in practice,
+1.1.2.  With version 1.1.3 Cygwin introduces a mechanism for setting real
-the programs we have ported have not needed it.</para>
+and effective UIDs under Windows NT/W2K. This is described in the ntsec
+section.</para>
 
 <para>Under Windows 9x, the situation is considerably different.  Since a
 security model is not provided, Cygwin fakes file ownership by making all
@@ -144,6 +148,18 @@ d_ino of the dirent structure.  It is worth noting that the number produced by
 this method is not guaranteed to be unique.  However, we have not found this to
 be a significant problem because of the low probability of generating a
 duplicate inode number.</para>
+
+<para>Chroot is supported since release 1.1.3. Note that chroot isn't
+supported native by Windows. This implies some restrictions. First of all,
+the chroot call isn't a privileged call. Each user may call it. Second, the
+chroot environment isn't safe against native windows processes. If you
+want to support a chroot environment as, for example, by allowing an
+anonymous ftp with restricted access, you'll have to care that only
+native Cygwin applications are accessible inside of the chroot environment.
+Since that applications are only using the Cygwin POSIX API to access the
+file system their access can be restricted as it is intended. This includes
+not only POSIX paths but Win32 paths (containing drive letter and/or
+backslashes) and CIFS paths (//server/share or \\server\share) as well.</para>
 </sect2>
 
 <sect2 id="ov-hi-textvsbinary"><title>Text Mode vs. Binary Mode</title>