A Sample Authorization Protocol for X Overview The following note describes a very simple mechanism for providing individual access to an X Window System display. It uses existing core protocol and library hooks for specifying authorization data in the connection setup block to restrict use of the display to only those clients that show that they know a server-specific key called a "magic cookie". This mechanism is *not* being proposed as an addition to the Xlib standard; among other reasons, a protocol extension is needed to support more flexible mechanisms. We have implemented this mechanism already; if you have comments, please send them to us. This scheme involves changes to the following parts of the sample release: o xdm - generate random magic cookie and store in protected file - pass name of magic cookie file to server - when user logs in, add magic cookie to user's auth file - when user logs out, generate a new cookie for server o server - a new command line option to specify cookie file - check client authorization data against magic cookie - read in cookie whenever the server resets - do not add local machine to host list if magic cookie given o Xlib - read in authorization data from file - find data for appropriate server - send authorization data if found o xauth [new program to manage user auth file] - add entries to user's auth file - remove entries from user's auth file This mechanism assumes that the superuser and the transport layer between the client and the server is secure. Description The sample implementation will use the xdm Display Manager to set up and control the server's authorization file. Sites that do not run xdm will need to build their own mechanisms. Xdm uses a random key (seeded by the system time and check sum of /dev/kmem) to generate a unique sequence of characters at 16 bytes long. This sequence will be written to a file which is made readable only by the server. The server will then be started with a command line option instructing it to use the contents of the file as the magic cookie for connections that include authorization data. This will also disable the server from adding the local machine's address to the initial host list. Note that the actual cookie must not be stored on the command line or in an environment variable, to prevent it from being publicly obtainable by the "ps" command. If a client presents an authorization name of "MIT-MAGIC-COOKIE-1" and authorization data that matches the magic cookie, that client is allowed access. If the name or data does not match and the host list is empty, that client will be denied access. Otherwise, the existing host-based access control will be used. Since any client that is making a connection from a machine on the host list will be granted access even if their authorization data is incorrect, sites are strongly urged not to set up any default hosts using the /etc/X*.hosts files. Granting access to other machines should be done by the user's session manager instead. Assuming the server is configured with an empty host list, the existence of the cookie is sufficient to ensure there will be no unauthorized access to the display. However, xdm will (continue to) work to minimize the chances of spoofing on servers that do not support this authorization mechanism. This will be done by grabbing the server and the keyboard after opening the display. This action will be surrounded by a timer which will kill the server if the grabs cannot be done within several seconds. [This level of security is now implemented in patches already sent out.] After the user logs in, xdm will add authorization entries for each of the server machine's network addresses to the user's authorization file (the format of which is described below). This file will usually be named .Xauthority in the users's home directory; will be owned by the user (as specified by the pw_uid and pw_gid fields in the user's password entry), and will be accessible only to the user (no group access). This file will contain authorization data for all of the displays opened by the user. When the session terminates, xdm will generate and store a new magic cookie for the server. Then, xdm will shutdown its own connection and send a SIGHUP to the server process, which should cause the server to reset. The server will then read in the new magic cookie. To support accesses (both read and write) from multiple machines (for use in environments that use distributed file systems), file locking is done using hard links. This is done by creat'ing (sic) a lock file and then linking it to another name in the same directory. If the link-target already exists, the link will fail, indicating failure to obtain the lock. Linking is used instead of just creating the file read-only since link will fail even for the superuser. Problems and Solutions There are a few problems with .Xauthority as described. If no home directory exists, or if xdm cannot create a file there (disk full), xdm stores the cookie in a file in a resource-specified back-up directory, and sets an environment variable in the user's session (called XAUTHORITY) naming this file. There is also the problem that the locking attempts will need to be timed out, due to a leftover lock. Xdm, again, creates a file and set an environment variable. Finally, the back-up directory might be full. Xdm, as a last resort, provides a function key binding that allows a user to log in without having the authorization data stored, and with host-based access control disabled. Xlib XOpenDisplay in Xlib was enhanced to allow specification of authorization information. As implied above, Xlib looks for the data in the .Xauthority file of the home directory, or in the file pointed at by the XAUTHORITY environment variable instead if that is defined. This required no programmatic interface change to Xlib. In addition, a new Xlib routine is provided to explicitly specify authorization. XSetAuthorization(name, namelen, data, datalen) int namelen, datalen; char *name, *data; There are three types of input: name NULL, data don't care - use default authorization mechanism. name non-NULL, data NULL - use the named authorization; get data from that mechanism's default. name non-NULL, data non-NULL - use the given authorization and data. This interface is used by xdm and might also be used by any other applications that wish to explicitly set the authorization information. Authorization File The .Xauthority file is a binary file consisting of a sequence of entries in the following format: 2 bytes Family value (second byte is as in protocol HOST) 2 bytes address length (always MSB first) A bytes host address (as in protocol HOST) 2 bytes display "number" length (always MSB first) S bytes display "number" string 2 bytes name length (always MSB first) N bytes authorization name string 2 bytes data length (always MSB first) D bytes authorization data string The format is binary for easy processing, since authorization information usually consists of arbitrary data. Host addresses are used instead of names to eliminate potentially time-consuming name resolutions in XOpenDisplay. Programs, such as xdm, that initialize the user's authorization file will have to do the same work as the server in finding addresses for all network interfaces. If more than one entry matches the desired address, the entry that is chosen is implementation-dependent. In our implementation, it is always the first in the file. The Family is specified in two bytes to allow out-of-band values (i.e. values not in the Protocol) to be used. In particular, two new values "FamilyLocal" and "FamilyWild" are defined. FamilyLocal refers to any connections using a non-network method of connetion from the local machine (Unix domain sockets, shared memory, loopback serial line). In this case the host address is specified by the data returned from gethostname() and better be unique in a collection of machines which share NFS directories. FamilyWild is currently used only by xdm to communicate authorization data to the server. It matches any family/host address pair. For FamilyInternet, the host address is the 4 byte internet address, for FamilyDecnet, the host address is the byte decnet address, for FamilyChaos the address is also two bytes. The Display Number is the ascii representation of the display number portion of the display name. It is in ascii to allow future expansion to PseudoRoots or anything else that might happen. A utility called "xauth" will be provided for editing and viewing the contents of authorization files. Note that the user's authorization file is not the same as the server's magic cookie file.