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.