Grapevine Package




This package implements a subset of the client protocols  for accessing
the Grapevine registration services.  The top-level facilities included
are user name/password authentication, group  membership determination,
and resource  location.  The  package does  not include  operations for
updating the Grapevine data  base or for transporting  electronic mail.
However,  lower-level primitives  are  accessible, out  of  which those
operations could be constructed.

For  information  on  the   organization  and  use  of   the  Grapevine
registration services  and the protocols  used to access  them, consult
"The     Grapevine    Interface",     by    Andrew     Birrell,    file
[Indigo]<Grapevine>Docs>Interface.press.



1. Organization and requirements


The Grapevine package is distributed as file  <Alto>Grapevine.dm, which
contains    the    following    binary    files:   GrapevineEnquire.br,
GrapevineLocate.br, GrapevineNameInfo.br, and GrapevineProtocol.br.  In
normal use, all four modules are required.

All  modules  of the  Grapevine  package may  be  loaded  into overlays
(managed by  the BCPL  Overlays package); such  overlays will  swap out
when calls to Grapevine are not in progress.  The initialization module
GrapevineOEP.br declares  Overlay Entry Points  (OEPs) required  by the
package.

The Grapevine package depends on the Pup package and all its supporting
packages.  The following is a complete list of the modules  required on
a normal Alto:

Grapevine package       GrapevineEnquire, GrapevineLocate,
                        GrapevineNameInfo, GrapevineProtocol (from
                        Grapevine.dm)

Pup package             PupBSPOpenClose, PupBSPProt, PupBSPStreams,
                        PupBSPBlock, PupBSPa, PupRTPOpenClose, PupRTP,
                        PupNetDirLookup, Pup1OpenClose, Pup1b, PupAl1a,
                        PupRoute, PupAlEthb, PupAlEtha, Pup1Init,
                        PupDummyGate, PupAlEthInit (from PupPackage.dm)

Context package         Context, ContextInit (from Context.dm)

Interrupt package       Interrupt, InterruptInit (from Interrupt.dm)

Queue package           AltoQueue

Timer package           AltoTimer

Strings package         StringUtil (from Strings.dm)

                             ------------
                   Copyright Xerox Corporation 1983


Grapevine Package         September 20, 1983                          2




ByteBlt package         AltoByteBlt

File Grapevine.decl  is a "get"  file containing definitions  needed by
clients  of the  package.  These  definitions consist  of  various data
structures and error codes, including the following:

An   RName   is   a   Grapevine   registered   name,   in    the   form
"simpleName.registry".   It  has  the  same  representation  as  a BCPL
String.

A Password is a 64-bit encryption key, straightforwardly derived from a
text password.  A procedure exists to convert a String to a Password.

A TimeStamp consists of a net address and a standard Alto  packed time.
All  objects in  the Grapevine  data base  are marked  with TimeStamps,
which are used to determine  the validity of cached information  and to
control the propagation of updates.

An RList represents  the contents of a  Grapevine group (or  other list
maintained by Grapevine).  It contains a TimeStamp and is the head of a
queue of RItems, each of which contains an RName.



2. Initialization and general operation


The Grapevine package must be initialized by calling:

InitGrapevine(zone, testing [false])
    Initializes the global state of  the package.  "zone" is a  zone to
    be used for all storage allocations by the  package.  InitGrapevine
    permanently extracts  only a four-word  block from zone;  but other
    operations make heavy temporary use of zone.

    If testing  is true, the  Grapevine package communicates  only with
    servers that are running  in "testing" mode.  InitGrapevine  may be
    called  multiple  times to  change  testing; the  zone  argument is
    ignored during all but the first call.

The  Pup  package  must  be  initialized  (InitPupLevel1)   before  the
Grapevine package may be called; and calls to Grapevine procedures must
be  from within  the confines  of  a Context  (as managed  by  the BCPL
Context package).

The Grapevine  package caches  some global  state between  calls.  Most
significantly, a  BSP stream  to the  most recently  accessed Grapevine
server is usually left open; in most cases this substantially speeds up
a  subsequent  request if  it  is made  within  the  Grapevine server's
connection timeout interval  (currently one minute).  If  desired, this
global state may be flushed by calling GVDestroyStream().

Procedures  in  the  Grapevine  package  may  be  called  from multiple
contexts (processes).  The  package maintains an internal  interlock so
that only one Grapevine protocol  interaction will be in progress  at a
time.


Grapevine Package         September 20, 1983                          3




3. High-level operations


These operations are sufficient for authentication, access control, and
resource location.

Authenticate(name, password) = code
    Checks "name" (an RName) and "password" (a 64-bit Password  key) in
    the Grapevine data base, and returns a code describing  the outcome
    (from Grapevine.decl):

    ecIndividual   name is an individual and password is correct.
    ecBadPassword  incorrect password.
    ecBadRName     name does not exist or is not an individual.
    ecAllDown      can't contact any R-Server for name's registry.

MakeKey(string, key)
    Converts  a  text  password  pointed to  by  "string"  to  a 64-bit
    encryption key pointed to by "key".  The result is suitable  as the
    "password" argument of Authenticate.

IsMemberClosure(group, name) = code
    Determines whether "name" appears anywhere in the tree that results
    from expanding "group"; both arguments are RNames.  Returns  a code
    describing the outcome:

    ecIsMember     name is a member of group.
    ecIsNotMember  name is not a member of group.
    ecBadRName     name or group does not exist or is of wrong type.
    ecAllDown      can't contact any R-Server for group's registry.

FindServer(serverName, pollingSocket, proc, arg)
    Attempts  to  find  an  instance of  a  service  identified  by the
    specified  name. If  serviceName contains  a ".",  treats it  as an
    RName (which must be a Grapevine group) and attempts to  locate the
    nearest  functioning  instance  of the  service  among  the group's
    members (which  must be individuals  whose connect sites  are valid
    Pup address  constants).  If  serviceName does  not contain  a ".",
    treats it as a Name Lookup Server (NLS) name and attempts to locate
    the nearest functioning instance of the service  without consulting
    Grapevine (a local broadcast is also issued).

    In either case, for  each potential instance of the  service, calls
    proc(port, arg), which should  attempt to open a connection  to the
    given port and return true if successful and false if not  (arg may
    be used to communicate additional parameters and/or results).  Proc
    should at least default and perhaps unconditionally set  the port's
    socket  field to  the appropriate  well-known socket  number before
    using it, since in general the service socket is distinct  from the
    polling socket.   Note that  proc will  be called  repeatedly until
    either  it  returns true  or  the list  of  potential  instances is
    exhausted.

    If FindServer is successful,  it returns zero; if  unsuccessful, it
    returns one of ecBadRName  (there is no such service)  or ecAllDown
    (can't contact any instance of the service).

    The service  to be  located must  respond to  EchoMe requests  on a
    well-known  socket,  the  low  16  bits  of  which  are   given  as


Grapevine Package         September 20, 1983                          4




    pollingSocket and the high 16  bits of which are zero  (except when
    the Grapevine package is in testing mode).  Any  service (Grapevine
    or  non-Grapevine)   obeying  this   convention  may   be  located,
    regardless of whether it is named by an RName or an NLS name.



4. Higher-level primitives


These  procedures may  be  used to  perform  most of  the  querying (as
opposed to  updating) operations provided  by Grapevine.   Calling them
requires definitions from GrapevineProtocol.decl, which may be obtained
from <AltoSource>GrapevineSources.dm.

IsInACL(name, member, descriptor) = code
    Determines membership  in an  access control  list.  "name"  is the
    RName of a group with which the access control list  is associated,
    "member" is the RName to be tested for membership in that list, and
    "descriptor" encodes  one of a  large collection of  access control
    list checking options.  "descriptor" is composed by adding together
    three constants, one from each of the following groups:

    The  R-Name  with  which  the  access  control  list   is  actually
    associated:
    dItself            the group "name" itself.
    dItsRegistry       "name"s registry (i.e., "reg.GV").

    What access control list (associated with "name") is to be checked:
    dMembers           the membership list of the group.
    dOwners            the owners list of the group.
    dFriends           the friends list of the group.

    How the list is to be enumerated:
    dDirect            just check for membership in the list itself.
    dClosure           expand any names that are groups, and  check for
                       membership  in  those groups  as  well  (do this
                       recursively to as many levels as necessary).
    dUpArrow           as for  dClosure, but  expand only  those groups
                       whose names contain  "^"; in many cases  this is
                       considerably faster than dClosure.

    For example, the  IsMemberClosure procedure, described  earlier, is
    implemented as IsInACL(name, member, dItself+dMember+dClosure).

    IsInACL returns  one of the  codes described  under IsMemberClosure
    (above).

ReadRList(name, op, lvEC []) = rList or 0
    Reads  a list  associated with  "name" (an  RName) as  specified by
    "op":

    opReadMembers       the (direct) membership of the group "name".
    opReadOwners        the (direct) Owner list for "name".
    opReadFriends       the (direct) Friends list for "name".

    If this  is successful,  ReadRList returns a  pointer to  an RList,
    which heads  a queue  of RItems  each of  which contains  an RName.
    This  RList  is  allocated  from  the  zone  that  was   passed  to


Grapevine Package         September 20, 1983                          5




    InitGrapevine;  note  that  an  indefinite  amount  of  storage  is
    required, depending on the size of the list.

    If ReadRList  is unsuccessful, it  returns zero after  storing into
    @lvEC (if specified) one of the following codes:

    ecBadRName     name does not exist or is not a group.
    ecAllDown      can't contact any R-Server for group's registry.

DestroyRList(rList)
    Destroys (i.e., frees the storage occupied by) an RList returned by
    ReadRList.

ReadRString(name, op, lvEC []) = string or 0
    Reads a string  associated with "name"  (an RName) as  specified by
    "op":

    opReadConnect  the Connect site for the individual "name".
    opReadRemark   the Remark for the group "name".

    If this is successful, ReadRString returns a BCPL  String allocated
    from the zone  that was passed  to InitGrapevine.  The  caller must
    Free the string to that zone when done with it.



5. Lower-level primitives


These are the procedures  out of which the higher-level  operations are
composed; they may be used to compose other Grapevine  operations (both
queries and updates)  not provided by the  package.  If you  use these,
you should  read the code  in GrapevineNameInfo.bcpl to  understand how
they are intended to  be called.  Calling these procedures  may require
definitions     from     GrapevineInternal.decl     as      well     as
GrapevineProtocol.decl and Grapevine.decl.

Enquire(name, proc, arg) = returnCode
    Attempts to establish  a BSP stream  to a registration  server that
    has a copy  of the registry for  "name" (an RName), and  then calls
    proc(stream,  name,   arg).   Proc   should  return   a  ReturnCode
    describing the outcome; any additional results may  be communicated
    via storage  pointed to by  "arg".  Enquire returns  the ReturnCode
    returned  by  proc  if  proc was  actually  called,  or  a locally-
    manufactured ReturnCode otherwise.  See  GrapevineProtocol.decl and
    the  "Grapevine  Interface"  document  for  the  interpretation  of
    ReturnCodes.

    Enquire's function is simply to establish contact with  the correct
    registration  server; it  is proc's  responsibility to  perform the
    actual desired query, update, or whatever.  That is, proc must send
    the  protocol  command  over  stream  and  interpret   the  result.
    Auxiliary  procedures   that  facilitate  this   include  SendWord,
    SendRName, ReceiveWord, ReceiveRName, and ReceiveRList.

    The  first  word  of  a Grapevine  server's  response  is  always a
    ReturnCode;  and it  is this  ReturnCode that  proc is  expected to
    return.  Additionally,  if ReturnCode.code  equals rcDone,  proc is
    expected  to  consume  any  additional  results  that   follow  the
    ReturnCode before returning.


Grapevine Package         September 20, 1983                          6




    Proc may be called more than  once, if the first call results  in a
    ReturnCode indicating that  the wrong registration server  has been
    contacted.  Also, any I/O to the BSP stream may result in  a stream
    error,  which  causes  control  to be  ripped  away  from  proc and
    returned  to  Enquire.   Consequently, proc  must  not  acquire any
    resources  (e.g., allocated  storage) not  known to  the  caller of
    Enquire, else those resources may be lost.

EnquireWithStamp(stream, op, name, stamp [nullStamp]) = returnCode
    Sends a protocol command of the form [name, op, stamp]  and returns
    the  resulting  ReturnCode.  This  constitutes  the  major protocol
    interaction of  many Grapevine commands;  it should be  called only
    from within a "proc" passed to Enquire.



6. Revision history


January 6, 1982

The  third  argument of  IsInACL  is now  a  "descriptor"  encoding all
possible  combinations of  ACL checking  options.  InitGrapevine  has a
"testing" option.

September 20, 1983

A procedure FindServer has been added for locating servers by  means of
the Grapevine resource location algorithm.  A few minor bugs are fixed.