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.