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