Skip to content

Commit

Permalink
* ntsec.sgml: Add description for the new setuid ability
Browse files Browse the repository at this point in the history 
        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.
  • Loading branch information
@github-cygwin
github-cygwin committed Jul 20, 2000
1 parent 5356bdc commit 99fd83e
Show file tree
Hide file tree
Showing 4 changed files with 190 additions and 13 deletions.
8 changes: 8 additions & 0 deletions winsup/doc/ChangeLog
View file
Original file line number Diff line number Diff line change
@@ -1,3 +1,11 @@
Thu Jul 20 13:01:00 2000 Corinna Vinschen <[email protected]>

* 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 <[email protected]>

* ntsec.sgml: Revisited description of `ntsec' according to
Expand Down
22 changes: 17 additions & 5 deletions winsup/doc/calls.texinfo
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 setgid: 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 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
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand Down
145 changes: 143 additions & 2 deletions winsup/doc/ntsec.sgml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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>.
On NT ntsec is now turned on by default.</para>
<EnVar>CYGWIN</EnVar> variable setting <literal>(no)ntsec</literal>.</para>

<sect2 id="ntsec-common"><title>NT security</title>

Expand Down Expand Up @@ -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>
28 changes: 22 additions & 6 deletions winsup/doc/overview2.sgml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
support for ACLs, Cygwin maps Win32 file ownership and permissions to the
more standard, older UNIX model. The chmod call maps UNIX-style permissions
Control Lists (ACLs). Cygwin maps Win32 file ownership and permissions to the
more standard, older UNIX model by default. Cygwin version 1.1 introduces
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
we hope to support this functionality at some point in the future, in practice,
the programs we have ported have not needed it.</para>
is no mechanism to support the setuid concept or API call since Cygwin version
1.1.2. With version 1.1.3 Cygwin introduces a mechanism for setting real
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
Expand Down Expand Up @@ -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>
Expand Down

0 comments on commit 99fd83e

Please sign in to comment.