diff options
Diffstat (limited to 'winsup/doc/ntsec.sgml')
| -rw-r--r-- | winsup/doc/ntsec.sgml | 660 |
1 files changed, 0 insertions, 660 deletions
diff --git a/winsup/doc/ntsec.sgml b/winsup/doc/ntsec.sgml deleted file mode 100644 index 7d2eb5b..0000000 --- a/winsup/doc/ntsec.sgml +++ /dev/null @@ -1,660 +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 uses `access allowed ACEs'.</para> - -<para>The possible permissions on objects are more complicated 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>The creation of explicit object security is a bit complicated, so -typically only two simple variations are used:</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 created or opened object is inherited to child processes or not. -This property is not important for the ntsec patch description, so in -this document SDs and SAs are more or less identical.</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 it seems that this has no negativ influences.</para> - -<para>To work correctly the ntsec patch depends on reasoned 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>To get help in creating correct passwd and group files, look at -the following examples, that are part of my files. With the exception -of my personal user entry, all entries are well known entries. For a -better understanding, the names are translated to the equivalents of the -English NT version.</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>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 better 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 that 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 a special version of <command>login</command> which will -be part of the release 1.1 soon.</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>. In this -case ntsec behaves like the previous version.</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 each case the password of the user is taken from the NT user -database, NOT from the passwd file!</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 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 <windows.h> -#include <sys/cygwin.h> -/* 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->pw_password)) - error_exit; - -[...] - - /* Everything else remains the same! */ - - setegid (user_pwd_entry->pw_gid); - seteuid (user_pwd_entry->pw_uid); - execl ("/bin/sh", ...); - -</screen> - -<para>The new Cygwin call to retrive an access token is defined as follows:</para> - -<screen> -#include <windows.h> -#include <sys/cygwin.h> - -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 <windows.h> -#include <sys/cygwin.h> - -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> |