----------------------------------------------------------------------
              Elvin Ticker Group Subscription Format
----------------------------------------------------------------------


  Purpose of This Document
----------------------------------------------------------------------

  This document provides a brief description of the proposed format
  for exchanging ticker group subscriptions between tickertape
  messaging clients.

  The format is designed to allow interchange of group subscriptions
  amongst clients, either via ticker attachments or other textual
  means such as clipboard copy and paste. The format encodes not only
  instructions for subscribing to the content, but also any associated
  security attributes.


  Overview
----------------------------------------------------------------------

  A ticker group subscription is described by a "group" XML
  element. Three sub-types of group are defined: "chat", "news" and
  "custom". The first two correspond to the two major ticker message
  formats: inter-person chat (ticker v1.0/v3.0) and news (NNTP or web
  news) respectively.

  The "custom" type can select from news and/or chat channels and is
  specified via an Elvin subscription expression. The subscription
  will be appended with an expression (using "&&") that ensures
  selection of valid chat or news messages (from the client's point of
  view), so the subscription may be thought of as a sub-selection from
  all news and/or chat messages.


  MIME type
----------------------------------------------------------------------

  The MIME type for ticker groups is:

    application/x-elvin-tickergroup


  Examples
----------------------------------------------------------------------

  A "chat" format group named "Babble"

  <group version="1.0" name="Babble" type="chat" />

  --

  A "news" format group named "CNN"

  <group version="1.0" name="CNN" type="news" />

  --

  A "chat" format group called "Private Chat" with security attributes

  <group version="1.0" name="Private Chat" type="chat"
         defaultSecure="true" allowInsecure="false">
    <keys>
      <key version="1.0" name="Private Chat" access="shared">
        65445e420820795b54700d6158772f0650401854
      </key>
    </keys>
  </group>

  --

  A custom group

  <group version="1.0" name="foobar" type="custom">
    contains (Message, "foobar") ||
    equals (From, "frodo")
  </group>


  Details
----------------------------------------------------------------------

  A group element has three required attributes:

    version: The group format version. Currently must be "1.0".
    name:    The group's channel name.
    type:    One of "chat", "news" or "custom".


  Custom group subscription:

    For "custom" groups, an Elvin subscription expression must be
    included in the body of the group element (it is an error for this
    to be empty). The client will append this expression with an
    expression that selects what the client considers to be valid chat
    or news messages, so this subscription only needs to contain
    additional constraints on the notifications.

      eg: contains (Message, "foobar").


  Optional security attributes:

    defaultSecure: Boolean ("true" or "false"). If true, the client
                   should default to sending securely.

    allowInsecure: Boolean ("true" or "false"). Whether to allow
                   send/receipt of insecure messages. If false, the
                   client should never accept or display a message
                   that wasn't received securely.


  Security keys:

    A group may have an optional "keys" element containing one or more
    XML "key" elements. These specify security keys to be associated
    with the group and used to restrict receivership of messages.

    While there is already an agreed specification for exchanging
    Elvin security keys, this format is not amenable to nesting within
    XML. However, the XML key format proposed here is a straighforward
    translation of existing format into XML representation.

    For example, a key in the current format might look like:

      Version: 1.0
      Name: Shhhh
      Access: Private
      Key: 65445e420820795b54700d6158772f0650401854

    The XML representation of this is:

      <key version="1.0" name="Shhhh" access="private">
        65445e420820795b54700d6158772f0650401854
      </key>

    An example group using this key:

      <group version="1.0" name="test"
             allowInsecure="false" defaultSecure="true" type="chat">
        <keys>
          <key version="1.0" name="Shhhh" access="private">
            65445e420820795b54700d6158772f0650401854
          </key>
        </keys>
      </group>


  Notes
----------------------------------------------------------------------

  * Extended attributes. Clients should attach any client-specific
    extended information they wish to add using the "x-" naming
    scheme commonly used in other formats of this type.

    For example:

      <group version="1.0" name="CNN" type="news" x-icon="news.gif" />

  * Embedded key security. This format allows private keys to be
    embedded in group subscriptions, which is something that the user
    may not realise. Clients should take steps to warn the user before
    sending a group with embedded private keys across an insecure
    channel.

  * Character encoding. If the character encoding differs from the
    assumed default of UTF-8, it should be specified using an XML
    header plus an explicit encoding, eg:

     <?xml version="1.0" encoding="ISO-8859-1"?>

  * User interface terminology. It is suggested that clients sending
    ticker group subscriptions encoded in this way present the action
    to the user as "Send an invitation to the group". Importing the
    attachment would be likewise termed "Accepting the invitation".


  Author
----------------------------------------------------------------------

  This document was written by Matthew Phillips
  <matthew.phillips@dsto.defence.gov.au>.

  Last modified on 24 Sep 2004.