Blame README

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