X-Mailer: ELM [version 2.3 PL11]
Newsgroups: bit.listserv.cw-email
Date:         Fri, 4 Sep 1992 17:37:33 CDT
              <CW-EMAIL@TECMTYVM.BITNET>
From:         David E Boyes <dboyes@IS.RICE.EDU>
Subject:      Re: MIME (E-mail and calendaring recommendations)
              92 5:23 pm

This message contains the last draft of the Chronos protocol
specification. Paul Lindner at UMN did a significant portion of
the work in coordinating the draft RFC, with assistance from a
number of people like me who want to see this happen.

David Boyes
dboyes@rice.edu

;; begin included file: chronos.spec

$Author: lindner $
$Revision: 1.13 $
$Date: 91/02/04 00:59:05 $

Distributed Scheduling Protocol Working Group	Paul Lindner
Proposed Internet Draft:			(lindner@boombox.micro.umn.edu)


                      The Chronos Protocol
	A protocol for appointment scheduling and time management.


Status of This Memo:

   In transit.

   Distribution of this memo is unlimited.


1. Introduction

   Let's face it, planning meetings and schedules is a pain.  Trying to
   find out when someone is available is tough if not impossible.  The
   Chronos protocol was developed to ease these problems.

1.1 Problems addressed.

   The first problem is that there are many calendar managers in the
   world.  Most are either a) geared to a U*IX or CMS environment, b)
   do not work well if at all in a networked environment, or c)
   proprietary.  The chronos protocol has been designed to address
   these problems by allowing multiple server, multiple clients to
   communicate in a standardized way.

   In it's simplest form a client using the chronos protocol will
   provide the following services to the user:

    - Inserting various appointments and reminders into the users
      schedule on the server.  The client should provide a simple
      method to specify recurring events.

    - Notifying the user at user-defined intervals and methods of
      upcoming appointments.  Some of the basic notification methods
      are "pop-up" windows, beeps, flashes, etc.

    - Display appointments and reminders in a coherent chronological
      fashion.  The client should provide daily, weekly, and monthly
      displays and also include the option of printing the same.

    - Provide a means of changing the access list for the user.

    - Inserting various appointments and reminders into other users
      schedules.  The client should notify the user when errors occur
      and allow the user to try again.  Also the client should use
      facilities provided by the server to find a group of free time
      common to many users.

    - The client should allow the user to peruse appointments and
      reminders posted from other people and to either add them to the
      schedule, or delete them.

    - The client should allow the user to group events into
      different calendars.  For instance the user could place all
      events related to schoolwork into a Calendar called "School".

    - Allow the user to edit already posted events.  For instance the
      user could change the methods of notification, or the status of
      the event.

    - Provide as much security as is possible.


   The server provides the following services:

    - Store the appointments and reminders of a large number of users.

    - Allow for the creation of "psuedo-users" such as conference
      rooms.

    - Communicate with other chronos servers in a secure, transparent
      manner.

    - Provide a method of mutual exclusion to ensure that two users
      can not interfere with each other's schedules simultaneously.

    - Implement security among different users.


1.2  Desirable Features

   The Chronos protocol includes many features that make client
   implementation easy, including:

	- Access control lists.
	- An extensible control message structure.
	- A date format that allows recurring events to be easily specified
	- Secure password transmission.


1.3   The Chronos Paradigm.

1.3.1 Many Clients, Many Servers.

   The chronos paradigm for single users is quite simple.  The User
   communicates with the chronos server using a chronos client(s).
   The client allows the user to do many things to their schedule,
   including adding and deleting events (HELO, EVENT, DELETE).

   ---------                        ----------
   | User  |----------------------> | Server |
   | Agent |  POST/EVENT/DELETE     |        |
   ---------                        ----------

   Of course this is greatly simplified.  If this is all the user
   wanted to do then they could just as easily have used something
   like SideKick etc.  Now let's have some fun, let's add the
   functionality for multiple users.  Now we have to worry about
   security.  Chronos implements security with access lists and
   security levels for user to user security.  Also a method of user
   authentication is now needed (HELO).  With the acknowledgement of
   multiple users we can also add the ability to find free time among
   a bunch of users (FREE) and we can make psuedo-users
   (NEWUSER/DELUSER).

   ---------                        ----------
   | User 1|----------------------> | Server |
   | Agent |  POST/EVENT/DELETE     |        |
   ---------                        ----------
       .                               ^
       .                               |
   ---------                           |
   | User n|----------------------------
   | Agent |  and GETA/PUTA/HELO/FREE/NEWUSER/DELUSER
   ---------

   This would be enough for most people, but not for us!  The above
   diagram is similar to the timesharing method of computing.
   Something that utilized a distributed system would be much better
   indeed.  There are a few stumbling blocks, including server-server
   authentication (HELO/CALLBACK).  Also, this is the reason why such
   things as Greenwich time are used.

   ---------                 ----------                     ------------
   | User 1|---------------> | Server | <=================> | Server 2 |
   | Agent | Local Requests  |        |   Remote Requests   |          |
   ---------                 ----------                     ------------


1.3.2  The Event Paradigm.


2. The Chronos Protocol Specification

2.1. Overview

   The Chronos server specified by this document uses a stream connection
   (such as TCP) and SMTP-like commands and responses.  It is designed to
   accept connections from clients, and to provide a simple interface to
   the information contained within the Chronos server.  Requests that
   reference users at non-local hosts will be dealt with by server-server
   communications.

   The specification for the chronos server is geared towards a TCP
   implementation.  However the server is stateless enough that it should
   be possible to implement a server using a datagram oriented protocol
   (such as UDP).  However the implementation is left for people
   who like to apply lit cigarettes to their selves.

   When used via Internet TCP, the contact port assigned for this service is
   TBD (To be determined).

   The data channel in all cases is assumed to be able to handle eight
   bit ASCII characters.  The server will not, except under specific
   circumstances, be able to operate over a 7-bit data channel.

2.3 Commands

   Commands consist of a command word, which in some cases may be followed
   by parameters.  Commands with parameters must seperate the parameters
   from each other and from the command by one or more space or tab
   characters.  Command lines must be complete with all required
   parameters, and may not contain more than one command.

   Commands and command parameters are not case sensitive.

   Each command line must be terminated by a CR-LF (Carriage Return -
   Line Feed) pair.

   Command Lines shall not exceed 512 characters in length, counting all
   characters including spaces, spearators, punctuation, and the
   trailing CR-LF.  This leaves 510 characters available for the command
   and it's parameters.  There is no provision for continuation of
   command lines.

2.4 Responses

   Responses are of two kinds, textual and status.

2.4.1 Text Responses

   Text is sent only after a numeric status response has been sent that
   indicates the text will follow.  Text is sent as a series of
   successive lines of textual matter, each terminated with a CR-LF pair.
   A single line containing only a period (.) is sent to indicate the
   end of the text (i.e., the server will send a CR-LF pair at the end
   of the last line of text, a period, and another CR-LF pair).

   If the text contained a period as the first character of the text
   line in the original, that first period is doubled.  Therefore, the
   client must examine the first character of each line received, and
   for those beginning with a period, determine either that this is the
   end of the text or whether to collapse the doubled period to a single
   one.

   The intention is that text messages will usually be displayed on the
   user's terminal whereas command/status responses will be interpreted
   by the client program before any possible display is done.

2.4.2 Status Responses

   These are status reports from the server and indicate the response to
   the last command received from the client.

   Status response lines begin with a 3 digit numeric code which is
   sufficient to distinguish all responses.  Some of these may herald
   the subsequent transmission of text.

   The first digit of the response broadly indicates the success,
   failure, or progress of the previous command.

      1xx - Informative message
      2xx - Command ok
      3xx - Command ok so far, send the rest of it.
      4xx - Command was correct, but couldn't be performed for
            some reason.
      5xx - Command unimplemented, or incorrect, or a serious
            program error occurred.

   The next digit in the code indicates the function response category.

      x0x - Connection, setup, and miscellaneous
      x1x - User Selection
      x2x - Event Selection
      x3x - Event Posting
      x4x - Event Deletion
      x5x - Global Access Setting
      x6x - Scheduling Commands
      x8x - Nonstandard (private implementation) extensions
      x9x - Debugging output

   The exact response codes that should be expected from each command
   are detailed in the description of that command.  In addition, below
   is listed a general set of response codes that may be received at any
   time.

   Certain status responses contain parameters such as numbers and
   names. The number and type of such parameters is fixed for each
   response code to simplify interpretation of the response.
   Parameters are separated from the numeric response code and from each
   other by a single space. All numeric parameters are decimal, and may
   have leading zeros. All string parameters begin after the separating
   space, and end before the following separating space or the CR-LF
   pair at the end of the line. (String parameters may not, therefore,
   contain spaces.) All text, if any, in the response which is not a
   parameter of the response must follow and be separated from the last
   parameter by a space.  Also, note that the text following a response
   number may vary in different implementations of the server. The
   3-digit numeric code should be used to determine what response was
   sent.

2.4.3.  General Responses

   The following is a list of general response codes that may be sent by
   the Chronos server.  These are not specific to any one command, but may
   be returned as the result of a connection, a failure, or some unusual
   condition.

   In general 1xx codes may be ignored or displayed as desired

	100 help text
	190-199 debug output

	400 service discontinued

	500 Command not recognized
	501 Command syntax error
	502 Access restriction or permission denied
	503 program fault - command not performed


2.5 Event Control Message Format

   When it is necessary for the client and server to exchange
   events, a Event Message is sent.  The Event Message is similar to
   a SMTP mail message; there is a header that contains information,
   which is followed by a text message.  Header lines may appear in
   any order.  Unrecognized lines in the header will be ignored by
   the server.  The unrecognized header lines will be preserved by
   the server.  Thus a client can put implementation specific
   information into the header without worrying that the server will
   destroy it.  It is reccommended that implementation specific
   headers begin with the letter X, to avoid conflicting with future
   versions of the protocol.


2.5.1 General Data Formats

   The following data formats are used throughout the specification in
   various places.

      time ::= <YYYYMMDDhhmmss>

   The time format is the same as that given by the ISO3307 standard.
   Remember it's in Greenwhich Mean Time.  Let me say that a little louder,
   it's in GREENWHICH MEAN TIME!  Thus the client will need to check
   with the operating system to find it's time zone.  In addition,
   the chronos server gives the relative GMT timezone in it's banner.
   This is useful, especially when your client connects up with a
   server in another time zone, or you're scheduling events that will
   occur in another time-zone using the client in the current
   time-zone.  See section 3.1 to see how the initial connection is
   handled.

      length ::= <positive number of minutes>

   Length is the length of the particular event.  Length may be set to
   Zero if the event is informational only.  Examples of this include
   holidays and reminders to pay the rent.

      user ::= <username> | <username>@<fully qualified domain name>

      text string ::= <A bunch of characters terminated by a CR-LF combo.>


      revision ::= positive integer number
      Event_ID ::= <time><name><unique>@<host>-revision
      Event-ID: <Event_ID>


2.5.2 The Time: header

   The Time header line is composed in the following manner:

        interval ::= <integer number of days greater than 0>
        recurs ::= <D | W | B | M | Y | <interval>>
        weekday ::= <MO|TU|WE|TH|FR|SA|SU> |','<weekday> | <<1-5|L><weekday>>

        Time: <time> <length> [<recurs>] [<weekday>]

   The <time> field specifies the time of the event.  In the case of a
   recurring event, the <time> field specifies the time of the first
   valid recurring event.

   The recurs format uses a single letter or a number to abbreviate
   the six different types of reccurring behavior.  D for daily
   recurrence, W for weekly recurrence, B for biweekly (every 2nd
   week) recurrence, M for monthly recurrence, and Y for yearly
   recurrence.  Interval is the number of days between the recurring
   events.  The Interval specification does replicate the functions of
   'D' (1), 'W'(7), and 'B' (14), however the added functionality
   outweighs the replication. 'M' should be interpreted as recurring
   an event on a *specific* day of the month, i.e. every Day #n of the
   month,  The same goes for 'Y', it's defined to recur on the nth day
   of the year.

   In the weekday field the optional number before the last weekday
   is used to specify the particular numbered weekday of the month.
   Thus 1TU would be interpreted as the 1st tuesday of the month.

   Examples:
      MO
      1MO,2TU
      1MO2TU
      MO,TU,WE,TH,FR

   The weekday and recurs field are used to specify recurring events.
   The first form of weekday is a listing of the days of the week
   with (i.e. MO,TU,WE,TH,FR).  An entry such as this combined with
   recurs == w can be used to specify an event such as lunch
   or a class that occurs on multiple days in a month.  The second
   form of Weekday: is when a number in the range of 1-5 precedes
   the weeday.  This, when combined with a recurs == m can be
   used to specify events that occur on the nth weekday of the
   month (e.g. 1st Tuesday of the month).

   Note that it is possible to specify a different recurs field
   that does not mesh with the weekday field.  Any messages
   that contain a Weekday header with just days of the week
   should have the Recurs == weekly or recurs == biweekly
   header too.  Likewise events that have a weekday field
   with days of the week preceded by a number
   should have the recurs field set to "monthly".


2.5.3  The Type: Header Line.

      event_type ::= <U | C | P>
      status ::= <PENDING | APPROVED | CANCELLED | OLD>
      Calendar_name ::= <textstring>

      Type: <event_type> <status> [<Calendar_Name>]

   The event type allows the client to specify the security level of a
   message.  U is Unrestricted, which means that anyone who has a proper
   level of access can see the event (see the GETA and PUTA commands).
   C is Confidential, only people at level 5 or 6 security can see the
   contents of this event.  P is personal, only the owner of the event can
   see the contents of this event.

   The status field is used to describe the current state of the event message.
   Events posted by other users are automatically set to the PENDING state
   when posted.  User Agents should not display PENDING events in the schedule.
   The UA should instead query the user if they want to accept the event, or
   delete it. Use of the APPROVE command moves an event from the PENDING or
   CANCELLED state to the APPROVED state.  A User Agent may also use the
   CANCEL command to move an event to the CANCELLED state.  Events in the
   CANCELLED and PENDING state are effectively ignored by the server when
   doing calculations for such commands as FREE.

   The Calendar_name allows the user to organize events within their own
   calendar.  For instance a user could seperate their events into different
   categories such as "Classes", "Meetings", and "Work".  The client should
   make a reasonable effort to sort the events into the user-specified
   categories.


2.5.4  The Location: and Summary: Header Lines

       Location: <text string>
       Summary: <text string>

    The Location and Summary lines provide information about the
    event.  The summary should contain a brief synopsis of the the
    event.  The location specifies the meeting place of the event.
    These fields are informational only.


2.5.5  The From: Header Line

       From: <user> "<Real Name>"

   The From: field is something that the server supplies when sending
   messages to the client.  The server will ignore the From: lines when
   it receives an event via the POST command.  The server will insert
   the name of the currently authenticated user into the From: field.
   When the event is later retrieved, the From: information will be present.

   The server should provide the Real Name in quotes after the
   username if it is available.  If the real user name isn't
   available, then the server should just put two quote marks, with
   nothing in between.


2.5.6  The Notify: Header Line

       Notify: (<command> <length> [options]) [ (<command> <length>)...]

   The Notify: header line tells the client when to remind the user of
   an upcoming event.  The client will notify the user of the event
   before the time (time - length).  This function can be
   provided by an auxilliary program like "biff" or it can be built
   directly into the user agent.

   The interpretation of the [command] is up to the client.  Naturally
   different clients will have different methods of notification.  However
   for the sake of sanity across implementations the following guidelines
   should be observed:

   For Beeping the terminal:
        Use "Beep <length> <n> <m>" where n is the number of times to
	beep, and <m> is the length in seconds between beeps.

   For Flashing the Terminal/screen:
        Use "Flash <length> <n>" where n is the number times to flash
	the terminal/screen.

   For Displaying a message on the users terminal/screen:
        Use "Display <length> <message>"  Where message is what will
	be presented to the user.  (The client may opt to display
	other information as well, such as details of the event
	itself.)

   For Sending a mail message:
        Use "Mail <length> <user>"  Sends mail to user specified.


   Here is an example of the

   Notify: (Display 15 Alert!) (Mail 120 lindner@coral.micro.umn.edu)

   By definition the Notify time of 0 means that the server should notify
   user as close as possible to the actual event.  If the client does
   not supply a Notify: line, or submits an empty notify line then the
   then the notification client should ignore the event for
   notifications.


2.5.7 The Expires: Header Line

      Expires: <time>

   The Expires: header, combined with the Time: header can be used
   to specify when a given recurring event is valid.  "Time:" is
   set to the first date the event occurs, the Expires: header denotes
   the last day of the recurring event.  A good example is a
   class at a University.  The recurring event will be only active
   between first day of classes and the last day of classes.


2.5.8 The Event-ID: Header Line

      revision ::= positive integer number
      Event_ID ::= <time><name><unique>@<host>-revision
      Event-ID: <Event_ID>

   The Event-ID: header line contains a unique identifier specified by
   the Event_ID data format (original eh?).



2.5.9 The Depends: Header Line

   Eventually there will be event dependencies in here.


2.5.10 Summary of Header Lines.

   Header Lines required for every Event Message.

      Time: <time> <length> [<recurs>] [<weekday>]
      Type: <event_type> <status> [<Calendar_Name>]
      Location: <text string>
      Summary: <text string>

   Optional Header Lines.

      Depends: <Event-ID>
      Notify: <length>
      Expires: <time>

   Header Lines supplied by the server.

      From: <user> "[Real User Name]"
      Event-ID: <Event_ID>


2.5.11  Examples of Event Messages.

   This is an example of a non-recurring, one-shot event.  This event is
   a personal event, thus only the owner will be able to see it.  It is
   also part of the User defined calendar "Party Schedule".

     From: lindner
     Time: 19901030210000 240
     Location: Dans House.
     Type: P A Party Schedule
     Summary: Dans Halloween Party

     Great Halloween Party at Dans!
     .

   This next event is an example of a yearly recurring event.  It's an
   unrestricted event, thus anyone who has access to the users' calendar
   (see the "PUTA" command) will be able to see this event.
   A reminder will be sent to this user 24 hours before the event.

     From: lindner
     Time: 19910401130000 90 y
     Location: Stub n' Herbs
     Type: U A
     Summary: Birthday Party
     Notify: (24 Display)

     Paul Lindner's birthday, also April fools day.
     .


   This is an example of a simple weekly recurring meeting.  Anyone
   can see this event.


     From: yen
     Time: 19910107160000 30 W
     Summary: Weekly MWNC staff meeting
     Location: 125 Shepherd Labs
     Type: U A Meetings

     Just about the only time all of MWNC is under one roof,
     Discussion of stuff.
     .

   This is an example of lunch.  This event is confidential, only people
   at the "PARTNER" security level can see this level.  (See GETA and PUTA
   for a description of security levels.)  This event is in the user defined
   schedule "Other Stuff".

     From: lindner
     Time: 19910107120000 60 W MO,TU,WE,TH,FR
     Location: A restaurant
     Type: C A Other Stuff
     Summary: Lunch

     I'll be at one of the many fine eating establishments stuffing
     my face.
     .

   This example is kind of nit picking, but what the heck, it works!
   It also gives an example of a PENDING event.  Thus the owner has
   yet to accept this event.

     From: toothfairy@mother.goose.org
     Time: 19910101080000 5 d
     Location: My Bathroom
     Type: U P
     Summary: Teeth

     Good dental hygiene is most useful for healthy teeth and
     gums.
     .


   The following is an example of a bi-weekly meeting.

     From: hobbie@mailbox.mail.umn.edu
     Time: 19910108140000 30 B
     Type: U A Meetings
     Location: Russ Hobbies Office
     Summary: IT Computing Committee meeting

     This Russ Hobbie shouldn't be confused with the other Mr.
     Hobby of the ietf!
     .


   Here's where some of the recurring event stuff gets a little hairy.
   This one is a meeting on the 1st wednesday of the month.  This event
   is also in the CANCELLED state, it can later be re-APPROVEd, if the
   user wishes.  This is what could happen if you let anyone post to
   your schedule :)

     From: weasel@amazing.discoveries.com
     Time: 19910102203000 120 M 1WE
     Type: U C Trash
     Location: The Swank Sheraton Hotel on the fabulous Bloomington Strip!
     Summary: We want you to buy our stuff!

     Yes, be the first on your block to join us in our
     special buying club.  You bring us all your money,
     and we'll supply you with a lifetime supply of
     Didi 7 Car cleaner!  What a deal! Bring a friend!!
     .


   September 24 is the first day of classes, December 1st is the
   last day of classes.  Thus I could enter this event into
   my schedule ahead of time.  Neat huh?

     From: lindner
     Time: 19900924140000 75 W MO,WE
     Type: U A Classes
     Location: MechEng 212
     Summary: Software Engineering Class 5180
     Expires: 19901201235900

     Probably THE most boring class I've ever taken.  Prof Tsai is
     as interesting as a sack of wet lentil beans.
     .


   Here's another example of an event on specified weekdays of a month.
   Also notice that this is just a reminder, not a real event.

     From: lindner
     Time: 19910103080000 0 M 1TH,3TH
     Type: U A Mundane Stuff
     Location: My Curb
     Summary: Put out those recyclables

     Cans, glass, and what not.  What goes around comes around.
     .


   Here's an example of the Depends: keyword.  In this case we have
   the first event with an event ID of 12365.

     From: doc@medical.mods.com
     Time: 19910110090000 360
     Type: C A Surgery
     Location: West Medical Hospital
     Summary: Sex Change Operation.

     Our snippers are ready for you Mr. Lindner.
     .


   The next event uses the Depends: keyword to show a dependency.

     From: dmj@boombox.micro.umn.edu
     Time: 19910111210000 360
     Type: C A Dates
     Location: The town
     Summary: A date with Dave "Big Stud" Johnson
     Depends: 12365

     I'll go out with you if you go through with the surgery hehehehehe.
     .

   If Event #12365 had been deleted then the other event would also be deleted.
   Similarly if Event #12365 had been cancelled, then the subsequent event
   would also be marked as cancelled.


2.6 Security.

   Most of the security aspects of a chronos server will end up here
   eventually.


3. Command and Response Details

   On the following pages are descriptions of each command recognized by
   the Chronos server and the responses which will be returned by those
   commands.

   Each command is shown in upper case for clarity, although case is
   ignored in the interpretation of commands by the Chronos server.  Any
   parameters are shown in lower case.  A parameter shown in [square
   brackets] is optional.

   Every command described in this section must be implemented by all
   Chronos servers.

   There is no prohibition against additional commands being added;
   however, it is recommended that any such unspecified command begin
   with the letter "X" to avoid conflict with later revisions of this
   specification.

   Implementors are reminded that such additional commands may not
   redefine specified status response codes.  Using additional
   unspecified responses for standard commands is also prohibited.


3.1  Connecting to the Server.

   Upon connection, the server will respond with a one line response
   fitting this template:

      timezone ::= <timezone relative to GMT>
      200 <hostname> SECURITY <n> CODE <16-digit HEX num> TZ <timezone>

   "n" in this case is the maximum SECURITY level that the server
   supports.  Security level 1 is defined to be minimal security.
   No encryption is done.  At security level 2 passwords are encrypted
   using the eight digit HEX number after CODE.   Security Level three
   is undefined as of yet, though we anticipate that complete encoding
   using the value of CODE could be used.

   "hostname" is the fully qualified domain name of the chronos server
   as given in RFC nnn.

   A client may also receive the 201 response when connecting to the server.
   In this case the server is not accepting connections from the calling
   host.  The client should immediately issue a QUIT command and notify
   the user that his host is unacceptable to the chronos server.

   Examples:

      200 boombox.micro.umn.edu SECURITY 2 CODE 546798A0987454D6 TZ -4
      201 Sorry, connections from your host are not allowed.


3.2  The HELO command.

      HELO S <hostname> <username> <Callback Code>
      HELO C <username> <password> <Security Level> [<hostname>]

   The HELO command should be the first thing the client does upon
   connecting to the chronos server.  There are two forms of the
   HELO command, one for clients and one for servers.

   The HELO for clients takes three parameters.  The username is the
   name of a user on the local chronos server (i.e. none of this
   foo@bar.com business).  The security level is a number that defines
   the level of security of the connection.  Here are the current
   security levels:

        1: No encoding.  All text is passed as is.
        2: Passwords are encrypted using the "CODE" given in the
           banner message.
        3: All transactions except the initial HELO
           are encoded using the "CODE".

   The client must not issue a security level above that specified
   by the "SECURITY" level given in the banner message.

   The encoding method used is TBD.

   The HELO for servers is covered more heavily in the CALLBACK
   command section.  Following the S, the connecting server transmits
   it's fully qualified domain name, followed by the username that
   wishs to connect from the local server to the remote server.
   After that the server transmits a Callback code, that will be used
   by the CALLBACK command.  After the HELO is negotiated the
   remote server will transmit a response 211.  The link will then
   be closed.  The remote server will then reconnect to the
   local server and use the CALLBACK command to verify the connection.


   Responses:

     210 Client login accepted.
     211 Server login accepted, See you in a second.
     410 You blew it! wrong password.
     411 I don't do that security level, try again.

   Examples:

     HELO C fred fredpw 1
     HELO C fred Gq78fjdl 2
     HELO C fred Gq78fjdl 3


3.3  The CALLBACK command.

     CALLBACK <sixteen digit hexadecimal code>

   The CALLBACK command is used for server to server communication.
   It is used after a server HELO command.
   Here is the sequence of commands between server 1 (S1) and server 2
   (S2).

   	S1: [Open connection with S2]
	S1: HELO S s1.foo.bar.com gumby 0145679B017E6F11
	S2: 2nn - Okay, closing connection.
	[Connection is broken]
	S2: [Open connection with S1]
	S2: CALLBACK 0145679B017E6F11
	S1: 2nn - Okay, I'm the client now, logged in with user gumby.
	S1: POST
        etc,etc,etc....

   Using this scheme two servers can communicate in a secure fashion.

3.4  The LIST command

      LIST

   The LIST command retrieves a list of people who use the Chronos
   server.  It sends one line at time with the username followed by
   the "real" name of the User.  Any text following is defined to be
   the actual name of the person.  The server should not acknowledge
   the existance of users that have set their schedules to be
   "Restricted" to the current authenticated user.  (i.e. if Zeke is
   at "Restricted" access level in relation to "John", then when Zeke
   does a LIST command, John will not be in the list of users.)

   The LIST command does not necessarily get a listing of all the users who
   use the service.  Due to factors beyond the servers control some users
   may inadvertently remove themselves from the service.  (through accidental
   file deletion, or plain stupidity)  However it is a good place to start
   for client programs, which can present a list of users to the client,
   or can convert account names into something a little more palatable when
   reading event messages.

   The client should be prepared for a VERY long list.  When in doubt
   assume for the worst.

   Responses:
     202 Okee Dokee, user list follows

   Examples:

     LIST
     202 Okee Dokee, user list follows
     lindner Paul "Rock n Roll" Lindner
     mpm Mark "Markie" McCahil
     hairy Monkey S. Hines
     newton Cal Q. Lus
     .


3.5 The EVENTS command.

   EVENTS <username> [[Time] [length]]

   The EVENTS command retrieves the Event IDs associated with the
   current user.  The Event IDs are sent one per line in random order.
   The text is terminated by a single line containing only a period.

   If the optional time and length are given, then the server will
   only list events within the range of [Time, Time + Length].
   "Time" is a number in julian seconds since Jan 1 0:00 1970.  "Length"
   is given in number of minutes.

   Responses:
     204 Okay, Event IDs follow

   Examples:
     EVENTS goober
     204 Okay, Event IDs follow.
     98goober@foo.bar
     102goober
     109goober
     240goober
     .

     EVENTS 19910101090000 120
     204 Okay, Event IDs follow.
     102
     109

3.6 The EVENT command.

   EVENT <username> <Event_ID>

   The EVENT command retrieves the Event Message associated with an
   "Event_ID" on "username"'s schedule.  The recipients of the message
   are transmitted first, followed by a CR-LF.  Then the header of
   the event message is transmitted, followed by a CR-LF.  Finally the
   description of the event is transmitted.  The transmission is
   terminated by single line with a dot.

   It is possible for another user to delete an event between the
   time the EVENTS command and the EVENT <num> command is given.  In
   this case the server will return code "423 No Such Event."  The
   client should at this point do another EVENTS command to
   get the current valid Event IDs.

   Responses:
     203 Okay, Recipients and Event message follows:
     422 That user does not exist!
     423 No such event.

   Examples:

     EVENT lindner 98lindner@stupid.org
     203 Okay, Event message follows:
     lindner
     mpm
     sec

     From: yen
     Time: 19910107160000 30 W
     Summary: Weekly MWNC staff meeting
     Location: 125 Shepherd Labs
     Type: U A Meetings

     Just about the only time all of MWNC is under one roof,
     Catch me there if you can.
     .

     EVENT ziggy 1025ziggy
     423 No such event.


3.7 The POST command.

   POST

   The POST command is used to add a new event to one or more schedules.
   It is followed by a list of the recipients and the event message.

   After the post command is received, the server will respond with
   code 330.  The client will then specify the recipients of the
   message, one per line, terminating with a dot.

   At this point the server will respond in one of two ways. The server
   will respond with code "331 Send event message" if the user
   has the proper security access to post to all the specified recipients
   and all the other chronos servers for users on remote machines are
   running.  Otherwise the server will respond with code "430 Access
   denied, or remote server unavailable", and it will then output the
   offending names, one per line.  It will end the transmission with a
   single period on a line


   Examples:

     Here's what happens when the chronos server cannot contact the
     chronos server running on north.pole.org.  [Yes Virgini,a santa doesn't
     run a chronos server :->]

     POST
     330 Okay, send over the recipients names
     lindner
     audit@irs.gov
     santa@north.pole.org
     mpm
     .
     430 Access denied, or remote server unavailable.
     santa@north.pole.org
     .


   If posting is permitted the event should be presented as specified in
   section 2.5.  After the event message has been completely sent from
   the client to the server, a further response code will be returned to
   indicate success or failure of the posting attempt.

   If the posting is successful the Event ID of the posted Event is
   returned in the success response.  If the posted event overlaps any
   current events, then the response 231 will be sent to notify the client
   that there is an overlap.

   If an event is posted to another persons schedule, then the event
   will automatically be put in the PENDING state.

   Responses:
     230 Event posted successfully.
     231 <Event_ID> Overlaps other events, Event Posted.
     330 - Okay, send over the recipients names
     331 - Okay send the Event Message, end with <CR-LF>.<CR-LF>
     430 Permission denied
     431 Event not posted successfully.

   Examples:
     POST
     330 - Okay, send over the recipients names
     ziggy
     audit@irs.gov
     zippy
     .
     331 - Okay send the Event Message, end with <CR-LF>.<CR-LF>
     Time: 19900825800000 180
     Type: U Concerts
     Summary: Danzig Concert
     Location: First Avenue
     Notify: Yes

     An Awesome spectacle of heavy metal music.
     .
     230 Event posted successfully.
     19910101090000ziggy@foo.bar.com-0
     19910101090000audit@irs.gov-0
     19910101090000zippy@foo.bar.com-0
     .

3.8  The REPOST command.

       REPOST <Event_ID>

     The REPOST command's main purpose in life is to change or add
     header lines to an already posted event.  Specifically this command
     is most useful for changing an event from PENDING to APPROVED, or
     for changing the Notify: header line.   There are some fields you
     cannot change although:

        From:, Event-ID:

     The only real reason this command is really needed is because of
     the fact that we may soon do event dependencies.  Thus
     preservation of Event-ID's becomes very very important.

     Responses:

     Examples:



3.9  The DELETE command.

       DELETE <username> EventNum

    The DELETE command deletes events of the currently selected user.
    It deletes the event specified by "EventNum".

    The 441 response is returned if the authenticated user doesn't
    have the proper security level.  The 440 response is for when the
    given event does not exist.

    Responses:
      240 Event Successfully deleted.
      440 Deletion Failed, no such event.
      441 Deletion Failed, permission denied.

    Examples:
      DELETE gruber@foo.bar.org 6956gruber@foo.bar.org
      240 Event Successfully deleted.


3.10  The GETA and PUTA commands.

       GETA [username]
       PUTA <username|*> <security-level>

    The GETA and PUTA commands are used to control how other users see your
    calendar.  The server stores an access list for each user.  The GETA and
    PUTA commands operate on the access list of the currently authenticated
    user.

    The PUTA command takes two arguments. A username, which can either be a
    normal name of a user on the current chronos server, (e.g. "paul") or a
    username followed by an @ sign and a fully qualified domain name.
    (e.g. "paul@turtle.micro.umn.edu").  The second argument is the security
    level given to the user.  The security level is a number in the range of
    one to five.  The following table describes each level.

         1 -- Restricted: "user" cannot access any information.
         2 -- Limited Browse: "user" can access all fields of the event
                except the Summary: line, Location: line, and Message Body.
         3 -- Browse: "user" can see all the fields of all events, except
                those marked as *confidential* or *personal*.
         4 -- Post Mode: "user" can post to your schedule.
         5 -- Post and Delete Mode: "user" can post to your schedule and
                delete existing events.
         6 -- Partner level:  "user" can see and change *confidential*
                events.
         7 -- Owner mode: Should only be given to the actual owner of
                the calendar.  Access to everything.

    The PUTA command returns response 251 if it successfully changes
    the access list.  It returns response 450 if it cannot make the
    change.

    If the first argument is an asterisk (*), then the following access
    level will be the default access level for all users not defined in
    the access-list.

    The GETA command retrieves the current access list if no parameter is
    given.  It returns a listing of usernames and security-levels, one
    per line, terminated by a single line with a period.

    GETA returns response 250 before it transmits the access list.

    GETA will also accept an optional parameter.  This parameter is a
    username as defined by PUTA above.  GETA will return

      252 <n> level for that user.

    Where <n> is one of the security levels given in the previous paragraph.
    GETA will return 451 if the <user> isn't defined.  If an asterisk (*)
    is given as the username then the Global access-level is retrieved.

    Responses:
      250 Access List follows.
      251 Successfully set the access list.
      252 <n> access level for that user.
      450 Sorry can't set the accesslist.
      451 User access level not defined

    Examples:

     To allow mpm to view confidential events.
      PUTA mpm 6
      251 Successfully set the access list.

     Set irs to Restricted level
      PUTA irs@audit.gov 1
      251 Successfully set the access list.

     Set the global access level
      PUTA * 2
      251 Successfully set the access list.

     Get the accesslist
      GETA
      250 Access List follows.
      * 2
      irs@audit.gov 1
      mpm 6
      .

     Get mpm's entry in my accesslist
      GETA mpm
      252 3 access level for that user.


3.11  The FREE command

      FREE <Time> <Length>

   The free command finds blocks of time in which the specified users
   have nothing scheduled during the time period specified by
   <Time> and <Length>.  The user schedules to be searched are sent
   one-per-line, ending with a dot on a single line after the 360
   response code is retrieved. The free blocks of time are transmitted
   as a textual response with one Time and Length per line.  The response is
   terminated by a period on a line by itself.

   It is the clients responsibility to present the user with only
   "sane" blocks of time.  For instance if two users have events
   that almost abut, the server may return a block of time as
   small as one minute.   This does very little for the user.
   Caveat Cliente!

   Responses:
     260 Open Blocks of time follow:
     360 Send UserNames, one per line:
     460 No Open Blocks of time.

   Examples
     FREE 199104010900 360
     360 Okay, send usernames, one per line:
     lindner
     phk
     hobbie@mailbox.mail.umn.edu
     dfsjol@vx.acs.umn.edu
     yen
     dunn@cs.umn.edu
     .
     260 Open Blocks of time follow
     199104010900 30
     199104011000 45
     .

     FREE 65835000 36000
     360 Okay, send usernames, one per line:
     zog
     zig
     newt@bigtoad.com
     .
     460 No Open Blocks of time.


3.12 The NEWUSER and DELUSER commands.

      password ::= <text_string>

      NEWUSER <user> <password> <Real Name>
      DELUSER <user>

   The NEWUSER and DELUSER commands are used to add and remove
   "psuedo-users" respectively.  The NEWUSER creates a user with the
   given username and the given password.  The DELUSER deletes the
   specified "psuedo-user".  It has no effect on normal users.

   Both of these commands should be restricted to a special chronos
   administrative user.  Specifically we recommend the server provide
   a chronos-admin user specifically for pseudo-user management.
   However implementors are free to choose their names, "root" in U*IX
   parlance or perhaps "Administrator" for Macintosh users.

   Responses:

     2nn User operation successfully.
     4nn User operation failed.
     4nn User operation failed - Permission denied.

   Examples:

     ADDUSER 113Shep mumbles Shepherd Labs Conference Room
     2nn Okay, user created

     DELUSER lindner
     4nn User operation failed - Permission denied


3.13 The HELP command

      HELP

   Provides a short summary of commands that are understood by the
   implementation of the server.  The help text will be presented as a
   textual response, terminated by a single period on a line by itself.
   However people who wish to connect to a chronos server with telnet
   will quickly find that HELP isn't very helpful at all.

   Responses:
     100 help text follows:


3.14 The QUIT command

      QUIT

   The server process acknowledges the QUIT command and then closes the
   connection to the client.  This is the preferred method for a client
   to indicate that it has finished all its transactions with the Chronos
   server.

   If a client simply disconnects (or the connection times out, or some
   other fault occurs), the server should gracefully cease its attempts
   to service the client.

   Responses:
     205 Party on dude!  Excellent!


APPENDIX A:  Summary of Commands

  DELETE
  EVENT
  EVENTS
  FREE
  GETA
  FREE
  HELP
  PASS
  POST
  PUTA
  QUIT
  USER


APPENDIX B: Summary of Response Codes.

     100 help text follows:
     200 Server ready
     202 Okee Dokee, user list follows
     203 Okay, Event message follows:
     204 Okay, Event IDs follow.
     205 Party on dude!  Excellent!
     210 User ok, Event posting allowed.
     211 User ok, Event posting not allowed.
     212 User login accepted.
     220 Use EVENT to retrieve.
     230 <Event ID> Event posted successfully.
     240 Event Successfully deleted.
     250 <accesslist>
     251 Successfully set the access list.
     330 - Okay send the Event Message, end with <CR-LF>.<CR-LF>
     410 No such user.
     411 You blew it! wrong password.
     422 No user specified, use USER command.
     423 No such event.
     430 Permission denied.
     431 Event not posted successfully.
     432 No user specified, use USER command.
     440 Deletion Failed.
     441 Deletion Failed, permission denied.
     450 Sorry can't set the accesslist.


4.  Progress of connections.

4.1 Client-server connection.

4.2 Server-server connection.



5. Sample Conversations





Special Thanks go to:

   Big Ten for their fabulous submarine sandwiches.
   Motorhead and Metallica for giving my ears something to do.
   Richard Stallman for EMACS and especially Indented-Text-Fill!

Author's Address:

   Paul Lindner
   Microcomputer, Workstation, Networks Center
   University of Minnesota
   134 Shepherd Labs
   100 Union Street SE
   Minneapolis MN, 55455

   Phone: (612)-626-1627
   Fax:
   E-Mail: lindner@boombox.micro.umn.edu
Comments: Gated by NETNEWS@AUVM.AMERICAN.EDU