README

   1
   2
   3                      A Sample Authorization Protocol for X
   4
   5
   6 Overview
   7
   8 The following note describes a very simple mechanism for providing individual
   9 access to an X Window System display.  It uses existing core protocol and
  10 library hooks for specifying authorization data in the connection setup block
  11 to restrict use of the display to only those clients that show that they
  12 know a server-specific key called a "magic cookie".  This mechanism is *not*
  13 being proposed as an addition to the Xlib standard; among other reasons, a
  14 protocol extension is needed to support more flexible mechanisms.  We have
  15 implemented this mechanism already; if you have comments, please send them
  16 to us.
  17
  18 This scheme involves changes to the following parts of the sample release:
  19
  20     o  xdm
  21         -  generate random magic cookie and store in protected file
  22         -  pass name of magic cookie file to server
  23         -  when user logs in, add magic cookie to user's auth file
  24         -  when user logs out, generate a new cookie for server
  25
  26     o  server
  27         -  a new command line option to specify cookie file
  28         -  check client authorization data against magic cookie
  29         -  read in cookie whenever the server resets
  30         -  do not add local machine to host list if magic cookie given
  31
  32     o  Xlib
  33         -  read in authorization data from file
  34         -  find data for appropriate server
  35         -  send authorization data if found
  36
  37     o  xauth [new program to manage user auth file]
  38         -  add entries to user's auth file
  39         -  remove entries from user's auth file
  40
  41 This mechanism assumes that the superuser and the transport layer between
  42 the client and the server is secure.
  43
  44
  45 Description
  46
  47 The sample implementation will use the xdm Display Manager to set up and
  48 control the server's authorization file.  Sites that do not run xdm will
  49 need to build their own mechanisms.
  50
  51 Xdm uses a random key (seeded by the system time and check sum of /dev/kmem)
  52 to generate a unique sequence of characters at 16 bytes long.  This sequence
  53 will be written to a file which is made readable only by the server.  The
  54 server will then be started with a command line option instructing it to use
  55 the contents of the file as the magic cookie for connections that include
  56 authorization data.  This will also disable the server from adding the local
  57 machine's address to the initial host list.  Note that the actual cookie must
  58 not be stored on the command line or in an environment variable, to prevent
  59 it from being publicly obtainable by the "ps" command.
  60
  61 If a client presents an authorization name of "MIT-MAGIC-COOKIE-1" and
  62 authorization data that matches the magic cookie, that client is allowed
  63 access.  If the name or data does not match and the host list is empty,
  64 that client will be denied access.  Otherwise, the existing host-based access
  65 control will be used.  Since any client that is making a connection from a
  66 machine on the host list will be granted access even if their authorization
  67 data is incorrect, sites are strongly urged not to set up any default hosts
  68 using the /etc/X*.hosts files.  Granting access to other machines should be
  69 done by the user's session manager instead.
  70
  71 Assuming the server is configured with an empty host list, the existence of the
  72 cookie is sufficient to ensure there will be no unauthorized access to the
  73 display.  However, xdm will (continue to) work to minimize the chances of
  74 spoofing on servers that do not support this authorization mechanism.  This
  75 will be done by grabbing the server and the keyboard after opening the display.
  76 This action will be surrounded by a timer which will kill the server if the
  77 grabs cannot be done within several seconds.  [This level of security is now
  78 implemented in patches already sent out.]
  79
  80 After the user logs in, xdm will add authorization entries for each of the
  81 server machine's network addresses to the user's authorization file (the format
  82 of which is described below).  This file will usually be named .Xauthority in
  83 the users's home directory; will be owned by the user (as specified by the
  84 pw_uid and pw_gid fields in the user's password entry), and will be accessible
  85 only to the user (no group access).  This file will contain authorization data
  86 for all of the displays opened by the user.
  87
  88 When the session terminates, xdm will generate and store a new magic cookie
  89 for the server.  Then, xdm will shutdown its own connection and send a
  90 SIGHUP to the server process, which should cause the server to reset.  The
  91 server will then read in the new magic cookie.
  92
  93 To support accesses (both read and write) from multiple machines (for use in
  94 environments that use distributed file systems), file locking is done using
  95 hard links.  This is done by creat'ing (sic) a lock file and then linking it
  96 to another name in the same directory.  If the link-target already exists,
  97 the link will fail, indicating failure to obtain the lock.  Linking is used
  98 instead of just creating the file read-only since link will fail even for
  99 the superuser.
 100
 101 Problems and Solutions
 102
 103 There are a few problems with .Xauthority as described.  If no home directory
 104 exists, or if xdm cannot create a file there (disk full), xdm stores the
 105 cookie in a file in a resource-specified back-up directory, and sets an
 106 environment variable in the user's session (called XAUTHORITY) naming this
 107 file.  There is also the problem that the locking attempts will need to be
 108 timed out, due to a leftover lock.  Xdm, again, creates a file and set an
 109 environment variable.  Finally, the back-up directory might be full.  Xdm,
 110 as a last resort, provides a function key binding that allows a user to log
 111 in without having the authorization data stored, and with host-based access
 112 control disabled.
 113
 114 Xlib
 115
 116 XOpenDisplay in Xlib was enhanced to allow specification of authorization
 117 information.  As implied above, Xlib looks for the data in the
 118 .Xauthority file of the home directory, or in the file pointed at by the
 119 XAUTHORITY environment variable instead if that is defined.  This required
 120 no programmatic interface change to Xlib.  In addition, a new Xlib routine
 121 is provided to explicitly specify authorization.
 122
 123         XSetAuthorization(name, namelen, data, datalen)
 124                 int namelen, datalen;
 125                 char *name, *data;
 126
 127 There are three types of input:
 128
 129         name NULL, data don't care      - use default authorization mechanism.
 130         name non-NULL, data NULL        - use the named authorization; get
 131                                           data from that mechanism's default.
 132         name non-NULL, data non-NULL    - use the given authorization and data.
 133
 134 This interface is used by xdm and might also be used by any other
 135 applications that wish to explicitly set the authorization information.
 136
 137 Authorization File
 138
 139 The .Xauthority file is a binary file consisting of a sequence of entries
 140 in the following format:
 141
 142         2 bytes         Family value (second byte is as in protocol HOST)
 143         2 bytes         address length (always MSB first)
 144         A bytes         host address (as in protocol HOST)
 145         2 bytes         display "number" length (always MSB first)
 146         S bytes         display "number" string
 147         2 bytes         name length (always MSB first)
 148         N bytes         authorization name string
 149         2 bytes         data length (always MSB first)
 150         D bytes         authorization data string
 151
 152 The format is binary for easy processing, since authorization information
 153 usually consists of arbitrary data.  Host addresses are used instead of
 154 names to eliminate potentially time-consuming name resolutions in
 155 XOpenDisplay.  Programs, such as xdm, that initialize the user's
 156 authorization file will have to do the same work as the server in finding
 157 addresses for all network interfaces.  If more than one entry matches the
 158 desired address, the entry that is chosen is implementation-dependent.  In
 159 our implementation, it is always the first in the file.
 160
 161 The Family is specified in two bytes to allow out-of-band values
 162 (i.e. values not in the Protocol) to be used.  In particular,
 163 two new values "FamilyLocal" and "FamilyWild" are defined.  FamilyLocal
 164 refers to any connections using a non-network method of connetion from the
 165 local machine (Unix domain sockets, shared memory, loopback serial line).
 166 In this case the host address is specified by the data returned from
 167 gethostname() and better be unique in a collection of machines
 168 which share NFS directories.  FamilyWild is currently used only
 169 by xdm to communicate authorization data to the server.  It matches
 170 any family/host address pair.
 171
 172 For FamilyInternet, the host address is the 4 byte internet address, for
 173 FamilyDecnet, the host address is the byte decnet address, for FamilyChaos
 174 the address is also two bytes.
 175
 176 The Display Number is the ascii representation of the display number
 177 portion of the display name.  It is in ascii to allow future expansion
 178 to PseudoRoots or anything else that might happen.
 179
 180 A utility called "xauth" will be provided for editing and viewing the
 181 contents of authorization files.  Note that the user's authorization file is
 182 not the same as the server's magic cookie file.