DESIGN

Dissent consists of several relatively independent components,
corresponding to subdirectories in the 'src' directory:

- Transports -- network communication layers such as Tcp, Ssl, Udp
- Connections -- represents an established link using a transport and gives an
  addressing scheme independent of the underlying transport
- Overlay -- organizes and specifies which nodes should connect with other
  nodes
- Crypto -- provides wrappers around external crypto libraries as well as
  extensions to many useful cryptographic techniques
- Identity -- an extension from the addressing of Connections to provide a more
  robust identity also supports various forms of authenication of this identity
- Tunnel -- provides a Socks5 compliant client and server stubs
- Anonymity -- anonymous group communication protocols
- Session -- establishes the set of participants for communicating in ensuing rounds

==============================================================================
Roadmap

I.    Overview
II.   Overlay protocol
III.  Round bootstrapping -- Server Setup
IV.   Round bootstrapping -- Client Setup
V.    Anonymity protocols
VI.   Technical notes
VII.  Terms
VIII. Message descriptions

==============================================================================
I.    Overview
==============================================================================

The following protocol provides the run-time group formation for running a
Dissent round. It assumes that one or more administrators have formed a group
configuration containing a list of public keys, one for each member in the
group and one for each server within the group.  Under anytrust assumptions,
the protocol ensures that each server and client have third-party verifiable
authenticated with the group and produces a unique RoundId that prevents replay
attacks, cross-round attacks, and sybil attacks.  The protocol is broken down
into 3 parts: the overlay protocol, server setup, and client setup.

The overlay protocol defines the means by which clients and servers form
overlay level connections intended to verify that the two parties are
connecting with the right group.  There are no intended security properties.

The server setup begins with a pre-specified server initiating a round
bootstrapping event embedded with causal information to prevent DoS attacks.
Servers then verify each others identity and agree upon a one time RoundId with
each server contributing to its randomness.  Servers also exchange information
necessary for executing a protocol run including an ephemeral signing key and
other optional information. All this information will be unique for each round
assuming anytrust.

At any point, clients may queue for an upcoming round. Once servers have
completed their bootstrapping protocol, they allow clients to register.  During
registration, clients learn the anytrust RoundId as well as the server round
information. Clients submit their own round information including an ephemeral
public key and optional information for the round. At the conclusion of the
client registration phase, servers agree upon the set of registered clients.

==============================================================================
II.   Overlay protocol
==============================================================================

Before beginning a Dissent round, a group configuration must be established, by
a set of server administrators, for example. A Dissent configuration consists
of a list of servers or super peers, mechanisms to connect to the servers
(transport type [TCP,SSL], transport address [IP:Port]), a set of public keys
named by a "Connection"-level address or PeerId (used for authentication), and
the protocol used for anonymous communication. The hash of this configuration
will serve as a group identifier, so that participants can ensure they have the
proper configuration.

To form an overlay, which may consist of one or more rounds, Servers, first,
establish connections to every other server, creating an all-to-all server
topology. Servers begin by first establishing a transport-level connection
followed by an overlay-level connection.  The owner of the incoming connection
transmits an Inquire message and the outgoing connection owner responds with an
Inquired; these messages establish the overlay Id of each peer.

I -> O Inquire (PeerId_I | TransportAddress_O |
                GroupId | DissentVersion)
O -> I Inquired (PeerId_O)

PeerId generation remains an open issue; however, with pre-exchanged keys, the
PeerId must be the name of the key as it is distributed. Certificates should
have the PeerId within the common name. 

==============================================================================
III.  Round bootstrapping -- Server Setup
==============================================================================

Upon establishing connections or completing a round, Dissent begins
resynchronization. The first server listed in the configuration file has the
unique role of proposing the start of a round via an Init message to all
servers.

A -> B Init ([PeerId_A | I Nonce | Timestamp | GroupId]_[Signature_A])

This message will then be embedded in the servers next exchange to address
synchronization issues.  A server can determine if a message is past, current,
or if they have yet to receive an Init.  Previous messages have an earlier
timestamp, current messages match the Init they have received from the
proposer, and yet to receive have future timestamps but have valid signatures.
The proposer may chose any timestamp he choses, such that an evaluation can be
made using integer comparisons, and that he maintains a consistent timestamp
across the lifetime of the group.

The Timestamp mitigates DoS attacks in which either a malicious server or
external entity might replay an old proposer Init message to confuse other
servers into enlisting in a round other than the latest.  However, the
Timestamp is not essential to ensuring the critical security invariant that
each round eventually acquires a fresh RoundId: even if a proposer maliciously
reuses an old I Nonce and/or Timestamp, the randomness in the Enlist messages
from other servers (below) guarantee RoundId freshness.

After receiving the Init messages, servers begin exchanging Enlist messages
with each other.  Enlist messages authenticate servers and contain ephemeral
keys used for signing messages in the rounds and optional data for use in an
upcoming protocol round. The Init message received earlier is included in case
an Enlist message arrives before the Init is is based upon does. A server can
use the embedded Init instead of waiting on the proposer's Init or having to
maintain state for out of order messages.

A -> B Enlist ([PeerId_A | Init Message | EphemeralPublicKey_A |
                Optional_A]_[Signature_A])

Once a server has received an Enlist from all other servers, they begin the
round identifier generation process. Currently, Servers currently employ the
following process: RoundId = SHA1([Enlist]) ordered by the Id of the servers.
Thus the ephemeral key in the Enlist message serves as a guarantee that under
the anytrust model the RoundId has some randomness.

A -> B Agree ([PeerId_A | RoundId | EphemeralPublicKey_A |
               Optional_A]_[Signature_A])

==============================================================================
IV.   Round bootstrapping -- Client Setup
==============================================================================

At the conclusion of this process, servers allow clients to register.  Prior to
registering, clients must connect to a server using the same process as servers
connect to each other, Inquire and Inquired messages. First establishing a
transport-level connection, followed by an overlay-level connection.

During registration, clients first transmit a Queue message to enter the
registration queue. Queue messages contain a client temporary nonce as a means
to authenticate the upstream servers to prevent replay attacks.

C -> S Queue (Nonce_C)

When the servers have completed the round identifier generation, they respond
to these messages with a Queued message containing the accumulated Agree
messages exchanged by the servers.  

S -> C Queued ([AgreeMessages | Nonce_C]_[Signature_S])

Clients then respond with a Register message containing a third-party
verifiable authentication context, a signature using private key cryptography,
against the RoundId, an ephemeral key to be used during the protocol, and any
additional information necessary for the upcoming protocol. At this point,
clients should prepare their round to receive messages but not process them.

C -> S Register ([PeerId_C | RoundId | EphemeralPublicKey_C |
                  Optional_C]_[Signature_C])

Upon beginning the registration process, each server accepts registration
messages for 5 minutes from their own prospective. After this registration
window, each server transmits their list of client registration messages to
every other server, using the List message.

A -> B List ([ListOfRegister_A]_[Signature_A])

Upon receiving the List from all servers, a server constructs a complete list
consisting of all clients, eliminating duplicate identities, and then hashes
the resulting list.  Servers then sign the resulting list and share among each
other their signatures via the VerifyList.  Clients authenticating with
multiple servers and using different entries for each server are removed.
Since this process is deterministic, servers need not share the list. Prior to
sending the VerifyList, servers should prepare to receive protocol round
messages.

A -> B VerifyList (Signature_A(ListOfRegister))

Upon receiving all signatures, servers can begin the round and simultaneously
transmit a Start message to clients initiating the beginning of the protocol
round.  A client registering with multiple servers remains connected to the
server with the lowest Id specified in the configuration.

S -> C Start (ListOfRegister | VerifyListSignatures)

A protocol round constitutes one or more anonymous exchanges.  The protocol
round continues for at least 1 exchange or 60 minutes, whichever is longer. At
which point, each server broadcasts a Stop message with the reason "Protocol
run complete" and immediate set to false.  At any point, if a server
disconnects from any other server, that server immediately broadcasts a Stop
message with reason "Server disconnected x from y" and immediate set to true.

S -> C Stop ([RoundId, Immediate, Reason]_[Signature_A])

Upon receiving a stop message, the round terminates immediately if immediate is
set to true or upon conclusion of the current round if not. At which point, the
entire process repeats from the first server transmitting an Init message and
clients' Queue.

==============================================================================
V.    Anonymity protocols
==============================================================================
Protocol -- Neff Shuffle:

TODO

==============================================================================
Protocol -- Client/Server Bulk:

TODO

==============================================================================
Protocol -- Verifiable DC-nets:

TODO


==============================================================================
VI.   Technical notes
==============================================================================

- Dissent does not directly provide peer-level authentication, that is left to
  the transport. For anonymous authentication, that means that clients will not
  be required to authenticate. If peers perform authentication, the identity
  should be matched against what is provided at the overlay level.
- Start and Started merely provide for synchronization on messages that may be
  transmitted by the round.
- Start may optionally contain group-wide information, if the Anonymity protocol
  requires it. In particular, this might be the Accumulated List of Queued and
  matching signatures from the Listed messages.
- If server has received a Stop message before stopping, it does not need to
  broadcast a Stop message.
- Dissent assumes that messages between two parties are delivered in order.
- The Timestamp in the Init message prevents an adversary from partitioning the
  online server set when the proposer is actively attempting to Init a new
  round
- If a Timestamp has been replayed, the proposer is offline, and there exists
  at least one honest online server, then the round will terminate at the
  RoundId message exchange because there would be no proper proposer
  signature on the RoundId
- If the proposer is the only honest server and a Timestamp has been replayed,
  servers would only be able to replay previous state up until the Start
  message. Honest clients will detect at this point that their registration
  information is either absent, incorrect, or improperly signed.

==============================================================================
VII.  Terms
==============================================================================

Group - a well-defined set of entities that may participate in one or more
  anonymous communication rounds

Round - an instance of a protocol execution, where some subset of the entities
  participate in anonymous communication

Exchange - some rounds support multiple transmissions from participants,
  each transmission and resulting cleartext constitutes an exchange

==============================================================================
VIII. Message formats
==============================================================================

A message either is a request, response, or notification. A request and
notification are RPC. A request expects a response in return.  Dissent stores
these messages as QVariantLists into QByteArrays using QDataStream. All incoming
messages also contain a path to the remote sender, so that a receiver can easily
determine the source of a message.

A request and notification use the following format: [Type, Id, Method, Data]
The fields are defined as follows:
- Type - QString - the type of message, 'n' - notification,  'r' - response,
    'p' - response
- Id - int - unique identifier for a request, that is included within the response
    so that it can be routed to the correct requestor
- Method - QString - the remote procedure
- Data - QVariant - data for the RPC

A response uses the following format: [Type, Id, Success, Data / Error]
- Type - QString - the type of message, 'n' - notification,  'r' - response,
    'p' - response
- Id - int - unique identifier for a request, that is included within the response
    so that it can be routed to the correct requestor
- Method - bool - whether or not the request was successfully handled
- Data - QVariant - response data for the procedure call
- Error - int - error code, see ErrorTypes (need doxygen link)

The following are messages defined within Dissent. Initiating messages place
their name into the Request (or Notification) Method field. Responses are
implied, therefore their name is not included within the Response. The
following reprsent the Data portion of a message stored as a QVariant.
Messages will be converted into QByteArrays via QDataStream, signed if
necessary, signed messages will be stored as two QByteArrays stored in series
via QDataStream. PeerIds are only included for messages that do not clearly
indicate ownership, single source messages. In messages that contain a
signature from all servers, the order of signatures is implicitly defined by
the order in which the servers are listed within the configuration file.

Inquire - PeerId_I | TransportAddress_O | GroupId |
         Dissent Version
- PeerId_I - Connections:Id as QByteArray - Inbound overlay Id
- TransportAddress_O - Transports::Address as a QString - Outbound Transport
  Address
- DissentVersion - int - Running version of Dissent, the receiver can close
  the connection if it does not match his own version

Inquired - PeerId_O
- PeerId_O - Outbound overlay Id (Connection::Id as a QByteArray)

Init - [PeerId_A | I Nonce | Timestamp | GroupId]_[Signature]
- PeerId - Connections::Id as QByteArray - Local Peer's overlay Id
- I Nonce - QByteArray - Used in the Enlist message to ensure causality
  of Enlist messages
- Timestamp - 64-bit integer - Time since the "Epoch"
- GroupId - QByteArray - The hash of the group information

Enlist - [PeerId_A | I Nonce | EphemeralPublicKey_A | Optional_A]_[Signature_A]
- PeerId_A - Connections::Id as QByteArray - Local Peer's overlay Id
- I Nonce - QByteArray - The nonce included in the Init message
- EphemeralPublicKey_A - QByteArray of DSA key - The ephemeral key to
  be used in operations during protocol exchanges
- Optional_A - QVariant - Additional data necessary for the protocol round
- Signature_A - QByteArray - Signature on [PeerId_A | EphemeralPublicKey_A |
  Optional_A], should use the servers well known public key that matches
  the PeerId

Agree - [PeerId_A | RoundId_A | EphemeralPublicKey_A | Optional_A]_[Signature_A]
- PeerId_A - Connections::Id as QByteArray - Local Peer's overlay Id
- RoundId_A - QByteArray - A nonce to use in the upcoming protocol round
- EphemeralPublicKey_A - QByteArray of DSA key - The ephemeral key to
  be used in operations during protocol exchanges
- Optional_A - QVariant - Additional data necessary for the protocol round
- Signature_A - QByteArray - Signature on [PeerId | Ephemeral Public Key |
  Optional], should use the servers well known public key that matches
  the PeerId

Queue - Nonce_C
- Nonce_C - QByteArray - An short-lived Nonce to prevent man in the
  middle attacks between the client and the upstream server

Queued - [AgreeMessages | Nonce_C]_[Signature]
- AgreeMessages - All of the server Agree messages
- Nonce_C - The client nonce specified in the Queue message
- Signature - QByteArray - Signature on [Agree Messages | Nonce_C],
  should use the servers well known public key that matches the PeerId

Register - [PeerId_C | RoundId | EphemeralPublicKey_C |
  Optional_C]_[Signature]
- PeerId_C - Connections::Id as QByteArray - Local Peer's overlay Id
- RoundId_C - QByteArray - A identifier to use in the upcoming protocol round
- EphemeralPublicKey_C - QByteArray of DSA key - The ephemeral key to
  be used in operations during protocol exchanges
- Optional_C - QVariant - Additional data necessary for the protocol round
- Signature_C - QByteArray - Depends on the authentication type, could be a
  DSA signature from a pre-exchanged key, an LRS signature from an agreed
  upon group of public keys, the format of the signature is depends on the
  group configuration.

List - [ListOfRegister_A]_[Signature_A]
- ListOfRegister_A - QVariantList - List of all the Register messages received
- Signature_A - QByteArray - Signature on QByteArray format of the List of
  Register

VerifyList - Signature on Complete List of Register
- Signature_A - QByteArray - Signature on the hashed accumulated List of Register

Start - Complete List of Register | VerifyListSignatures
- ListOfRegister - QVariantList - List of all the Register messages
- VerifyListSignatures - QVariantList - Set of all signatures for the
  accumulated list

Stop - [RoundId | Immediate | Reason]_[Signature_A]
- RoundId - QByteArray - The round identifier
- Immediate - bool - Should stop now or after the current exchange has
  completed
- Reason - QString - The reason for stopping
- Signature_A - The well known public key of the sender of this message