The following description assumes you're comfortable with the concept of Windows SIDs and RIDs. For a brief introduction, see the section called “Brief overview of Windows security”.

Cygwin's mapping between SIDs and uid/gid values works in two ways.

At least, that's the default behaviour now. It will be configurable using a file /etc/nsswitch.conf, which is discussed in the section called “The /etc/nsswitch.conf file”. Let's explore the default for now.

If the passwd or group files are present, they will be scanned on demand as soon as a mapping from SIDs to uid/gid or account names is required. The new mechanism will never read the entire file into memory, but only scan for the requested entry and cache this one in memory.

If no entry is found, or no passwd or group file was present, Cygwin will ask the OS.

So if we've drawn a blank reading the files, we're going to ask the OS. First thing, we ask the local machine for the SID or the username. The OS functions LookupAccountSid and LookupAccountName are pretty intelligent. They have all the stuff built in to ask for any account of the local machine, the Active Directory domain of the machine, the Global Catalog of the forest of the domain, as well as any trusted domain of our forest for the information. One OS call and we're practically done...

Except, the calls only return the mapping between SID, account name and the account's domain. We don't have a mapping to POSIX uid/gid and we're missing information on the user's home dir and login shell.

Let's discuss the SID<=>uid/gid mapping first. Here's how it works.

Now we have a semi-bijective mapping between SIDs and POSIX uid/gid values, but given that we have potentially users and groups in different domains having the same name, how do we uniquely distinguish between them by name? Well, we can do that by making their names unique in a per-machine way. Dependent on the domain membership of the account, and dependent of the machine being a domain member or not, the user and group names will be generated using a domain prefix and a separator character between domain and account name. The separator character is the plus sign, +.

The information fetched from the Windows account database or the /etc/passwd and /etc/group files is cached by the process. The cached information is inherited by Cygwin child processes. A Cygwin process invoked from a Windows command, such as CMD.exe, will start a new Cygwin process tree and the caching starts from scratch (unless cygserver is running, but read on).

While usually working fine, this has some drawbacks. Consider a shell calling id. id fetches all group information from the current token and caches them. Unfortunately id doesn't start any child processes, so the information is lost as soon as id exits.

But there's another caching mechanism available. If cygserver is running it will provide passwd and group entry caching for all processes in every Cygwin process tree started after cygserver. So, if you start a Cygwin Terminal and cygserver is running at the time, mintty, the shell, and all child processes will use cygserver caching. If you start a Cygwin Terminal and cygserver is not running at the time, none of the processes started inside this terminal window will use cygserver caching.

The advantage of cygserver caching is that it's system-wide and, as long as cygserver is running, unforgetful. Every Cygwin process on the system will have the cygserver cache at its service. Additionally, all information requested from cygserver once, will be cached inside the process itself and, again, propagated to child processes.

If you automatically start Cygwin processes as Windows services at system startup, you may wish to consider starting cygserver first in order to take advantage of this system-wide caching. To assure that cygserver has started prior to starting sshd or other Cygwin processes, you may wish to create service startup dependencies. Cygserver should probably wait for Windows TCPIP and AFD services before it starts, and then other Cygwin process should start after cygserver. Example Windows commands to accomplish this (after the services already exist) are shown below. You will need an administrative prompt to run the sc config commands.

  # Delay Cygserver until TCPIP and AFD have started
  # Note the (odd) required space character after "depend="

  sc config cygserver depend= tcpip/afd

  # Delay sshd until after Cygserver has started
  # Again note the (odd) required space character after "depend="

  sc config sshd depend= cygserver

  # View the Cygserver service details

  sc qc cygserver

Note that this sc config command replaces any existing dependencies. The above changes will not impact the running instance, only future instances.

  # To remove all dependencies from the cygserver service

  sc config cygserver depend= /

Obviously, if you don't maintain passwd and group files, you need to have a way to maintain the other fields of a passwd entry as well. A couple of things come to mind:

For simple needs you can create /etc/passwd and/or /etc/group files with entries for your account and tweak that.

For bigger installations, maintaining per-client files is rather troublesome. Also, no two environments are the same, so the needs are pretty different. Therefore Cygwin supports configuring how to fetch home directory, login shell, and gecos information in /etc/nsswitch.conf. See the next section for detailed information how to configure Cygwin's account handling.

On Linux and some other UNIXy OSes, we have a file called /etc/nsswitch.conf. Among other things, it determines how passwd and group entries are generated. That's what Cygwin now provides as well.

The /etc/nsswitch.conf file is optional. If you don't have one, Cygwin uses sensible defaults.

So, what settings can we perform with /etc/nsswitch.conf? Let's start with an example /etc/nsswitch.conf file set up to all default values:

  # /etc/nsswitch.conf
  passwd: files db
  group:  files db
  db_enum:  cache builtin
  db_home:  /home/%U
  db_shell: /bin/bash
  db_gecos: <empty>

  foo:  bar # baz

  foo: bar

  foo  :  bar

  passwd: files

  group: db

  group: files # db

  passwd: files db

  group: db files

  db_enum:  source1 source2 ...

  db_enum: none

  db_enum: cache files

  db_enum: cache local primary

  db_enum: local primary alltrusted

  db_enum: primary domain1.corp sub.domain.corp domain2.net

  db_enum: all

  db_home: schema...     # Define how to fetch the pw_dir entry.
  db_shell: schema...    # Define how to fetch the pw_shell entry.
  db_gecos: schema...    # Define how to fetch the pw_gecos entry.

  db_FOO: schema1 schema2 ...

  db_home: /home/%U

  db_shell: /bin/bash

  $ cd /usr/share/cygwin
  $ ldifde -i -f cygwin.ldif -k -c "CN=schema,CN=Configuration,DC=X" #schemaNamingContext

<cygwin key="value" key="value" [...] />

net user corinna /comment:"<cygwin home=\"/home/foo\"/>"

net user corinna /comment:'<cygwin home="/home/foo"/>'

Microsoft's NFS client does not map the uid/gid values on the NFS shares to SIDs. There's no such thing as a (fake) security descriptor returned to the application. Rather, via an undocumented API an application can fetch RFC 1813 compatible NFSv3 stat information from the share. This is what Cygwin is using to show stat information for files on NFS shares.

The problem is, while all other information in this stat record, like timestamps, file size etc., can be used by Cygwin, Cygwin had no way to map the values of the st_uid and st_gid members to a Windows SID for a long time. So it just faked the file owner info and claimed that it's you.

However, SFU has, over time, developed multiple methods to map UNIX uid/gid values on NFS shares to Windows SIDs. You'll find the full documentation of the mapping methods in NFS Identity Mapping in Windows Server 2012

Cygwin now utilizes the RFC 2307 mapping for this purpose. This is most of the time provided by an AD domain, but it could also be a standalone LDAP mapping server. Per RFC 2307, the uid is in the attribute uidNumber. For groups, the gid is in the gidNumber attribute. See the section called “The unix schema”.

When Cygwin stat()s files on an NFS share, it asks the mapping server via LDAP in two different ways, depending on the role of the mapping server.

The mapping will be cached for the lifetime of the process, and inherited by child processes.

A fully set up Samba file server with domain integration is running winbindd to map Windows SIDs to artificially created UNIX uids and gids, and this mapping is transparent within the domain, so Cygwin doesn't have to do anything special.

However, setting up winbindd isn't for everybody, and it fails to map Windows accounts to already existing UNIX users or groups. In contrast to NFS, Samba returns security descriptors, but unmapped UNIX accounts get special SIDs:

As you can see, even though we have SIDs, they just reflect the actual uid/gid values on the UNIX box in the RID value. It's only marginally different from the NFS method, so why not just use the same method as for NFS?

That's what Cygwin will do. If it encounters a S-1-22-x-y SID, it will perform the same RFC 2307 mapping as for NFS shares.

For home users without any Windows domain or LDAP server per RFC 2307, but with a Linux machine running Samba, just add this information to your SAM account. Assuming the uid of your Linux user account is 505 and the gid of your primary group is, say, 100, just add the values to your SAM user and group accounts. The following example assumes you didn't already add something else to the comment field.

To your user's SAM comment (remember: called Description in the GUI), add:

  <cygwin group="Users" unix="505"/>

To the Users group SAM comment add:

  <cygwin unix="100"/>

This should be sufficient to work on your Samba share and to see all files owned by your Linux user account as your files.

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 function LogonUser with the user name and the user's cleartext password as arguments. If the user exists and the password was specified correctly, the access token is returned and either used in ImpersonateLoggedOnUser to change the user context of the current thread, or in CreateProcessAsUser to change the user context of a spawned child process.

Later versions of Windows define new functions in this context and there are also functions to manipulate existing access tokens (usually only to restrict them). Windows Vista also adds subtokens which are 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.

Back to this logon with password, how can this be used to implement set(e)uid? Well, it requires modification of the calling application. Two Cygwin functions have been introduced to support porting setuid applications which only require login with passwords. You only give Cygwin the right access token and then you can call seteuid or setuid as usual in POSIX applications. Porting such a setuid application is illustrated by a short example:

/* First include all needed cygwin stuff. */
#ifdef __CYGWIN__
#include <windows.h>
#include <sys/cygwin.h>
#endif

[...]

  struct passwd *user_pwd_entry = getpwnam (username);
  char *cleartext_password = getpass ("Password:");

[...]

#ifdef __CYGWIN__
  /* Patch the typical password test. */
  {
    HANDLE token;

    /* Try to get the access token from Windows. */
    token = cygwin_logon_user (user_pwd_entry, cleartext_password);
    if (token == INVALID_HANDLE_VALUE)
       error_exit;
    /* Inform Cygwin about the new impersonation token. */
    cygwin_set_impersonation_token (token);
    /* Cygwin is now able, to switch to that user context by setuid or seteuid calls. */
  }
#else
    /* Use standard method on non-Cygwin systems. */
    hashed_password = crypt (cleartext_password, salt);
    if (!user_pwd_entry ||
        strcmp (hashed_password, user_pwd_entry->pw_passwd))
      error_exit;
#endif /* CYGWIN */

[...]

  /* Everything else remains the same! */

  setegid (user_pwd_entry->pw_gid);
  seteuid (user_pwd_entry->pw_uid);
  execl ("/bin/sh", ...);

An unfortunate aspect of the implementation of set(e)uid is the fact that the calling process requires the password of the user to switch to. Applications such as sshd wishing to switch the user context after a successful public key authentication, or the cron application which, again, wants to switch the user without any authentication are stuck here. But there are other ways to get new user tokens.

Starting with Cygwin 3.0, Cygwin tries to create a token by using Windows S4U authentication by default. For a quick description, see this blog posting. Cygwin versions prior to 3.0 tried to creat a user token from scratch using an officially undocumented function NtCreateToken which is now disabled.

So we just start the servers which have to switch the user context (sshd, inetd, cron, ...) as Windows services under the SYSTEM (or LocalSystem in the GUI) account and everything just works. Unfortunately that's too simple. Using S4U has a drawback.

Annoyingly, you don't have the usual comfortable access to network shares. The reason is that the token has been created without knowing the password. The password are your credentials necessary for network access. Thus, if you logon with a password, the password is stored hidden as "token credentials" within the access token and used as default logon to access network resources. Since these credentials are missing from the token created with S4U or NtCreateToken, you only can access network shares from the new user's process tree by using explicit authentication, on the command line for instance:

bash$ net use '\\server\share' /user:DOMAIN\my_user my_users_password

Note that, on some systems, you can't even define a drive letter to access the share, and under some circumstances the drive letter you choose collides with a drive letter already used in another session. Therefore it's better to get used to accessing these shares using the UNC path as in

bash$ grep foo //server/share/foofile

Not being able to access network shares without having to specify a cleartext password on the command line or in a script is a harsh problem for automated logons for testing purposes and similar stuff.

Fortunately there is a solution, but it has its own drawbacks. But, first things first, how does it work? The title of this section says it all. Instead of trying to logon without password, we just logon with password. The password gets stored two-way encrypted in a hidden, obfuscated area of the registry, the LSA private registry area. This part of the registry contains, for instance, the passwords of the Windows services which run under some non-default user account.

So what we do is to utilize this registry area for the purpose of set(e)uid. The Cygwin command passwd -R allows a user to specify his/her password for storage in this registry area. When this user tries to login using ssh with public key authentication, Cygwin's set(e)uid examines the LSA private registry area and searches for a Cygwin specific key which contains the password. If it finds it, it calls LogonUser under the hood, using this password. If that works, LogonUser returns an access token with all credentials necessary for network access.

For good measure, and since this way to implement set(e)uid is not only used by Cygwin but also by Microsoft's SFU (Services for Unix), we also look for a key stored by SFU (using the SFU command regpwd) and use that if it's available.

We got it. A full access token with its own logon session, with all network credentials. Hmm, that's heaven...

Back on earth, what about the drawbacks?

First, adding a password to the LSA private registry area requires administrative access. So calling passwd -R as a normal user will fail! Cygwin provides a workaround for this. If cygserver is started as a service running under the SYSTEM account (which is the default way to run cygserver) you can use passwd -R as normal, non-privileged user as well.

Second, as aforementioned, the password is two-way encrypted in a hidden, obfuscated registry area. Only SYSTEM has access to this area for listing purposes, so, even as an administrator, you can't examine this area with regedit. Right? No. Every administrator can start regedit as SYSTEM user, the Internet is your friend here.

Additionally, if an administrator knows under which name the private key is stored (which is well-known since the algorithms used to create the Cygwin and SFU keys are no secret), every administrator can access the password of all keys stored this way in the registry.

Conclusion: If your system is used exclusively by you, and if you're also the only administrator of your system, and if your system is adequately locked down to prevent malicious access, you can safely use this method. If your machine is part of a network which has dedicated administrators, and you're not one of these administrators, but you (think you) can trust your administrators, you can probably safely use this method.

In all other cases, don't use this method. You have been warned.

Now we learned about three different ways to switch the user context using the set(e)uid system call, but how does set(e)uid really work? Which method does it use now?

The answer is, all three of them. So here's a brief overview what set(e)uid does under the hood: