Auditorium messages

Auditorium messages are S-expressions which wrap data along with information about the sender and data type that are sent on the network.

Table of Contents Typographic conventions Data Structures Message Pointer Host Pointer Certificates and Signatures Messages Discover Discover Reply Join Join Reply Announce

Typographic conventions

• <> identifies a data structure defined here.
• [] names a specific type of string.
• {} names a specific type of s-expression (which is either a string or list)

Data Structures

The following data structures can be found inside auditorium messages.

Message Pointer

A message pointer, denoted <ptr>, is a reference to a particular message.

  (ptr [node-id] [sequence-number] [hash])

• node-id: This machine serial number uniquely identifies the machine which sent the message.
• sequence-number: This message number is an index into the sequence of messages sent by the sending machine.
• hash: This is the SHA-1 hash of the message in its complete s-expression format as it was placed on the wire.

Host Pointer

A host pointer, denoted <host>, is a reference to a particular host on the network.

  (host [node-id] [ip] [port])

• node-id: This machine serial number uniquely identifies the machine which sent the message.
• ip: This is the IP address of the referenced host in dotted-decimal format
• port: This is the port that the host is listening for incoming connections on. It is an integer formatted as a string.

Certificates and Signatures

Currently, a certificate is (cert [x.509]).

A certificate, denoted <cert>, is a signed key.

  (cert <signature>)

A key, denoted <key>, is:

  (key [id] [annotation] [mod] [exp])

A signature, denoted <signature> is:

  (signature [id] [sigdata] {payload})

Therefore, a certificate signed by the CA looks like:

  (cert (signature ca [sig-data] (key votebox-5 booth [mod] [exp])))

And a self-signed certificate looks like:

  (cert (signature votebox-5 [sig-data] (key votebox-5 booth [mod] [exp])))

Messages

All auditorium messages are formatted as follows:

    ([name] <host> [sequence-number] {datum})

• name: This string is one of:
  • discover
  • discover-reply
  • join
  • join-reply
  • announce
• host: This is a reference to the sender of the message.
• sequence-number: This is a unique identifier (across only messages from this sender) for the message.
• datum: This is the content of the message, which is different for each message.

Below, we describe the format of the datum for each message.

Discover

This message is broadcast by a host who seeks information about other auditorium hosts nearby. Discover's datum is a host pointer to the host that the responding host should send its discover-reply to.

    <host>

Discover Reply

This message is sent as a reply to a host who broadcast a discover message. The datum consists of all known hosts.

    (<host> <host> ... <host>)

Join

This message is sent by a host who wants to start a link with another host. The datum contains nothing.

    <nothing>

Join Reply

This message is sent in reply to a Join message in the event that the joiner is considered acceptable by the receiver of a Join message. In the event that the joiner is not considered acceptable, the socket is simply closed by the receiver of the Join message. The datum contains a list of message pointers. These point to messages that have been seen on the network but not yet referenced by a message.

    (<ptr> <ptr> ... <ptr>)

Announce

This message is the "backbone" of auditorium. All messages (shown here as the "payload") that intend to be logged and entangled are sent as announcement messages. If we assume auditorium uses an integrity layer wrapping a temporal layer, the messages are constructed as follows:

    (signed-message <cert> <signature>))))

• cert: This is the certificate of the party that is signing the payload.
• signature: The payload for a signed message is, of course, a signed message.

Because we've assumed that the signature will wrap the output of a temporal layer, the signature portion will look like this:

    (signature [signer] [sigdata] (succeeds (#listof:<ptr>) {payload}))

So, a complete announcement message might look like this:

 (announce
    (host votebox-5 1.2.3.4 5555)
    1
    (signed-message
        (cert
            (signature ca [sig-data] (key votebox-5 booth [mod] [exponent])))
        (signature
            votebox-5
            [sigdata]
            (succeeds
                ((ptr votebox-6 1 [SHA-1 hash]) (ptr votebox-5 0 [SHA-1 hash]))
                Hello World!))))

---