@Comment{$Header: protocol.mss,v 1.6 89/05/05 16:27:39 jtkohl Exp $}
@Comment{$Source: /mit/zephyr/doc/techplan/RCS/protocol.mss,v $}
@Comment{$Author: jtkohl $}
@Comment{$Revision: 1.6 $}
@Comment{Copyright 1987,1988 Massachusetts Institute of Technology}
@Part[protocol, Root "zephyr.mss"]

@Begin(Comment)
Random Editorial Comments ---------------------------------------------------

-----------------------------------------------------------------------------
@End(Comment)
@process(PageHeadings)

@Chap{The Zephyr Protocol}
@Label(protocol)

This chapter describes the current Zephyr protocol, version ZEPH0.2.  A
description of the protocol used for database transfers between servers
is given below in section @ref(bdumpproto).

@Section(Overview)

The Zephyr Protocol is implemented on UDP/IP, providing authenticated
subscription-based multicast and ZID to ZID message delivery.  The
Zephyr Protocol is used both for messages delivered to end users of the
system and for control and maintenance of the message transport system.

Notices may be sent from a client program to a Zephyr server,
from one Zephyr server to another, or from a Zephyr server
to a client program; they are not intended to be sent directly from
one client to another.  Instead, a Zephyr server always acts as
a relay for the message.

Each datagram may contain either part of a notice or a complete notice;
separate notices must be transmitted in separate datagrams.
Transmission and reception of notices is modular and
properly abstracted.  Zephyr clients and servers utilize a
common Zephyr Client Library that provides routines for such
operations as datagram port setup and shutdown, notice
transmission, and notice reception.

All notices share a common header format followed by a client specific
data area.  All notices are routed, queued, parsed and acted upon by
examining this header.  In this way the client specific data area need
never be examined except by the destination Zephyr client(s).

It is intended that Zephyr be usable as a "rendezvous" system; thus,
higher-level protocols can be built using Zephyr as a transport
mechanism.  The rendezvous can be accomplished by using Zephyr to
exchange internet addresses and port numbers.

@Section(Notice Datagram Format)

The datagram is in two parts.  The first part is a variable length
header, followed by a client data area. 
All header fields are represented in net ASCII.  Those header fields
with multiple-byte integer values are translated into network byte order
before conversion to net ASCII.
Each field is terminated by a NUL (character code zero).
Non-string values are represented in net ASCII as @t("0xaabbccdd
0xeeffgghh..."), where @t(aa) is the hexadecimal representation of the first
byte of data, @t(bb) is the representation of the second byte, etc.

In order, the datagram fields are:

@Begin(Description, Above 1 lines)

Version String@\This consists of a unique identifying string
(initially "ZEPH") followed by a major version number, a period, and a
minor version number.  Changes in the major version number will cause
the Zephyr Client Library to report that a packet was formatted
using an incompatible version of the Zephyr protocol.  A change
in the minor version number is used to indicate that the overall
format is compatible, but certain pieces of data may need to be
treated differently.

Number of Header Fields@\4 byte integer.  This field is included so
that future extensions to the Zephyr protocol may be made by
appending additional fields to the header.  The Zephyr library
will ignore fields it is not expecting.  This count includes the
Version String and Number of Header Fields fields.

@begin{multiple}
Notice Kind@\4 byte integer.  This field contains the kind
of notice, using one of the named values below.

UNSAFE (code 0) - The notice is simply transmitted.  No acknowledgment from
the local HostManager or a server is expected.

UNACKED (code 1) - The notice is acknowledged by the HostManager, but 
the HostManager does not forward the server acknowledgment to the client.
The HostManager acknowledgment will be handled internally by
the Zephyr Client Library.

ACKED (code 2) - The notice is acknowledged by both the HostManager and the
server.  The HostManager acknowledgment will be handled internally by
the Zephyr Client Library.  The application must handle the
server acknowledgment itself.

HMACK (code 3) - The notice is an acknowledgment from the HostManager to the
client application.

HMCTL (code 4) - The notice is a HostManager control message.

SERVACK (code 5) - The notice is a server acknowledgment indicating that the
notice was received and handled successfully.

SERVNAK (code 6) - The notice is a server acknowledgment indicating that
something went wrong during the handling of the notice.  This normally
indicates that there was an authentication failure.

CLIENTACK (code 7) - The notice is an acknowledgment from a client.
These notices are generated automatically by the Zephyr Client Library.

STAT (code 8) - The notice is requesting the destination HostManager or server
to return statistics about itself.
@end{multiple}

Unique packet ID@\12 bytes. 4 bytes internet address, 8 bytes host-generated
timestamp.

Port@\2 bytes.  This is the return port that should be
used to respond to this notice, if such a response is necessary.  The
port from which the message was received (as reported by the operating
system) should be @i(ignored), since it will typically be the port of a
Zephyr HostManager or server.

Authentication@\@multiple{4 byte integer.  A code representing the
type of authentication that was used while formatting this packet.
The currently defined codes are:

0 - No authentication

1 - Kerberos authentication
}

Authenticator length @\4 byte integer.  The length in bytes of the following
authenticator field.

Authenticator@\Variable length character data.  The authenticator used
to determine the authentication of the packet.

Class@\NUL-terminated ASCII string identifying a notice's class.  The
notice's class specifies the service class of notice's originating
Zephyr client.  Class is the highest level of notice
classification.  Examples of classes are: LOGIN, ZEPHYR_CTL,
MESSAGE, FILSRV.

Class Instance@\NUL-terminated ASCII string containing the particular
instance of the class with which this notice deals.  Examples of class
instances are: rfrench@@ATHENA.MIT.EDU, SUBSCRIBE, PERSONAL,
HELEN.MIT.EDU:/filesystem.

Opcode@\NUL-terminated ASCII string identifying the particular
operation which the notice's originating Zephyr client has
performed or expects the target(s) to perform.  Opcodes are class
specific.  Examples of opcodes are: USER_LOGIN, USER_LOGOUT,
SUBSCRIBE, UNSUBSCRIBE.

Sender@\NUL-terminated ASCII string identifying the ZID of the sender of
the notice.

Recipient@\NUL-terminated ASCII string containing the ZID
of the desired recipient of the notice.  If the recipient is
the null string then the target(s) are determined by the notice's
class and class instance as outlined in the Server Chapter (Chapter
@ref(server)).

Default Display Format@\NUL-terminated ASCII string that is used by
the WindowGram client to display the notice if it has no other rules
regarding the notice's particular class and class instance.

Checksum@\4 byte integer.  This field is for authentication.
When Kerberos is in use, this field is built by the Zephyr server using the
quad_cksum routine in the DES library to cryptographically checksum the
previous header fields using the DES session key.  It is assumed that
the byte order of the checksum generated by the DES library is invariant
across all machine architectures.

Fragmentation count@\NUL-terminated ASCII string.  This string is in the
format "part/partof", such as "707/8000", indicating the data area of
this packet contains a block of data starting at byte 707, and the total
data size of the unfragmented notice is 8000 bytes.  If this field is
empty, the packet was not fragmented during transmission.  A more
detailed description of packet fragmentation can be found in the Library
Chapter (Chapter @ref(library)).

Unique notice ID@\12 bytes. 4 bytes internet address, 8 bytes host-generated
timestamp.  All fragments of a fragmented notice will have identical
Unique notice ID's.

Other fields@\Other fields will be placed here when the protocol is
expanded.

@End(Description)

@Begin(FlushLeft, FaceCode P, Above 2 lines, Below 0 lines)
Variable length client data:
@End(FlushLeft)
@Begin(Description, Above 0 lines)

Data@\Byte stream data.  The format of this data is specific to the
particular communicating clients.  It normally consists of one or more
NUL-terminated strings containing ASCII data.

@End(Description)

@Begin(Group)
@Begin(FlushLeft, FaceCode P, Above 2 lines, Below 0 lines)
Sample datagram (268 bytes long): 
@End(FlushLeft)
@Begin(ProgramExample, Above 0 lines, Below 2 lines, Longlines Keep)
@TabClear()
@TabSet(0.5 inch, 4.0 inches)
0:@\"ZEPH0.2\0"@\Version string
8:@\"0x00000011\0"@\Number of fields (17)
19:@\"0x00000002\0"@\Kind - "ACKED"
30:@\"0x1248008D 0x22FA1319 0x000AEA49\0"@\Unique packet ID
63:@\"0x004b\0"@\Port
70:@\"0x00000000\0"@\Authentication (None)
81:@\"0x00000000\0"@\Authenticator length
92:@\"\0"@\Authenticator (None)
93:@\"MESSAGE\0"@\Class
101:@\"PERSONAL\0"@\Class instance
110:@\"\0"@\Opcode (None)
111:@\"rfrench@@ATHENA.MIT.EDU\0"@\Sender
134:@\"tony@@ATHENA.MIT.EDU\0"@\Recipient
154:@\"Message from $sender at"@\Default format
@\" $time:\n\n$message\0"
195:@\"0x12345678\0"@\Checksum
206:@\"\0"@\Fragmentation count
207:@\"0x1248008D 0x22FA1319 0x000AEA49\0"@\Unique notice ID
240:@\"Hello - This is an example!\0"@\Message
@End(ProgramExample)
@end(Group)

@Section(Naming Conventions)

Users and daemons share the same ZID namespace.

@Section(Predefined Class Operations)

The following table describes the predefined classes and their effects
when received by servers, HostManagers, and WindowGram clients.

@label(resclass)
@Begin(Center, TableColumns BodyRowFmt, Use Box)
@TableID(Classes)
@TableHeading(
	Immediate,
	RowFormat TableHeadFmt,
	Line="Reserved Class Definitions"
)
@TableHeading(
	Continued,
	RowFormat TableHeadFmt,
	Line="Reserved Class Definitions (continued)"
)
@TableHeading(
	Immediate, Continued,
	RowFormat ColumnHeadFmt,
	Line="Class@\Instance@\Opcode@\Effect"
)

ZEPHYR_CTL@\CLIENT@\SUBSCRIBE@\Client -> Server.  Subscribe the client
indicated by the port number in the notice to the class, class instance,
and recipient triples listed in the message section of the notice.  If
this notice establishes the first subscriptions for the client, also
subscribe the client to the server default subscriptions.  This notice
must be authenticated.

@\@\SUBSCRIBE_NODEFS@\Client -> Server.  Subscribe the client
indicated by the port number in the notice to the class, class
instance, and recipient triples listed in the message section of the
notice.  This notice must be authenticated.

@\@\UNSUBSCRIBE@\Client -> Server.  Unsubscribe the client indicated
by the port number in the notice from the class, class instance, and
recipient triples listed in the message section of the notice.  This
notice must be authenticated.

@\@\CLEARSUB@\Client -> Server.  Clear all subscriptions relating to
the port number specified in the notice.  This notice may be
authenticated.  If it isn't, the server will attempt to verify that
the client at the specified port has actually gone away.

@\@\GIMME@\Client -> Server.  Return subscriptions
associated with the specified port.  This notice must be
authenticated.

@\@\GIMMEDEFS@\Client -> Server.  Return default system-wide subscriptions.

ZEPHYR_CTL@\HM@\BOOT@\HostManager -> Server.  Tell the server that
this host has just booted and all state associated with it should be
flushed.

@\@\FLUSH@\HostManager -> Server.  Tell the server to flush all state
associated with this host.

@\@\DETACH@\HostManager -> Server.  Tell the server that this
HostManager no longer considers it to be its owning server.

@\@\ATTACH@\HostManager -> Server.  Tell the server that this
HostManager now considers it to be its owning server.

HM_CTL@\SERVER@\SHUTDOWN@\Server -> HostManager.  Tell the HostManager
that the server is going down, and that it should find another server.
This packet optionally includes a suggested server in the client data
area for the HostManager to transfer to.  If included, the suggestion
will be the IP Address of the suggested server, in Internet Address dot
notation, in ASCII.

@\@\PING@\Server -> HostManager.  Ask the HostManager to acknowledge.
This assures that the HostManager (and thus the host) is still operating
after a client fails to acknowledge notices.

@\CLIENT@\FLUSH@\Client -> HostManager.  Tell the HostManager to flush
all host information by sending a FLUSH message to its server.

@\@\NEWSERV@\Client -> HostManager.  Tell the HostManager to abandon its
current server and choose a new server.

HM_STAT@\HMST_CLIENT@\GIMMESTATS@\Client -> HostManager.  Ask the
HostManager to return statistics about itself.

LOGIN@\<ZID>@\<EXPOSURE>@\Client -> Server.  Tell the server
that the  user named by <ZID> has logged in to the host listed in the
message field.  This notice must be authenticated.  The opcode contains
the exposure level, one of NONE, OPSTAFF, REALM-VISIBLE,
REALM-ANNOUNCED, NET-VISIBLE, or NET-ANNOUNCED.  The client data area
contains the following NUL-terminated ASCII strings, in order: official
hostname, login time, and display device.

@\@\USER_LOGOUT@\Client -> Server.  Tell the server that the specified
user has logged out.  The client data area contains the same fields as
specified above for USER_LOGIN.

@\@\USER_FLUSH@\Client -> Server.  Tell the server to flush all
location information for the user.

USER_LOCATE@\<ZID>@\LOCATE@\Client -> Server.  Ask the server to
return all visible locations of the user named by <ZID>.  This notice must
be authenticated.

WG_CTL@\USER@\REREAD@\Client -> WindowGram client.  Ask the WindowGram
client to re-read the description file (which specifies its action on
receipt of notices).

@\@\SHUTDOWN@\Client -> WindowGram client.  Ask the WindowGram client to
cancel its subscriptions and to ignore subsequently delivered notices.

@\@\STARTUP@\Client -> WindowGram client.  Ask the WindowGram client to
reinstate subscriptions canceled by a SHUTDOWN notice and to display
subsequently delivered notices.

ZEPHYR_ADMIN@\``''@\HELLO@\Server -> Other Server.  Inform the other server
that this server is operating normally.

@\@\IHEARDYOU@\Server -> Other Server.  Inform the other server
that this server received its HELLO notice.

@\@\GOODBYE@\Server -> Other Server.  Inform the other server
that this server is ceasing operation.

@\@\LOST_CLIENT@\Server -> Other Server.  Inform the other server that
this server cannot contact a client and the other server should attempt
to verify the failure of the client.  The client data area contains two
NUL-terminated strings: the Internet address of the client's host, in
Internet ASCII dot notation, and the port number of the client, in
ASCII.

@\@\KILL_CLIENT@\Server -> Other Server.  Inform the other server that
this server has verified the failure of a client, and that the other
server should remove the client from its database.  The client data area
contains information in the same format as noted above for LOST_CLIENT.

@\@\STATUS@\Client -> Server.  Ask the server to respond with various
statistics about its operation.

@\<VERSION>@\DUMP_AVAIL@\Server -> Other Server.  Inform the
other server that a brain-dump is available.  The instance is the
version number identifying the brain-dump protocol.  The client data
area contains two NUL-terminated strings: the Internet address of the
originating server, in ASCII dot notation, and the port number from
which the brain-dump is to be obtained, in ASCII.

@End(Center)