(Re-)opening the API discussion.

[George Danezis <gd@theory.lcs.mit.edu>]

Dear All,

We have now a volunteer that would like to implement something that uses 
the MixMinion protocols and it made me thinking that it would be helpful 
is a standard API was provided to clients to perform 99% of the functions 
they might need (for the 1% hacking will always be needed).

Zooko had started this discussion a bit earlier:
http://archives.seul.org/mixminion/dev/Mar-2002/msg00043.html

At the time we did not have yet a clear idea about what SURB's would look 
like or how they would be encoded. We were also thinking of implementing 
fragmentation at the minion layer that has since faded away (I would argue 
that it should be implemented above it, as TCP is above IP).

In the Nym-spec document I propose the following API to be presented to 
clients, and I would greatly appreciate comments:

(An API for mixminion clients)

PROCEDURE: Create SURB
Input: -
Output: ID of the generated SURB. 
	SURB data.

The above procedure generates a SURB that is addressed to the local
machine given the local configuration.

PROCEDURE: Send Anonymous
Input: Address as specified in the ``Routing information'' section of
	the mixminion spec.
       OR 
       SURB provided by another user.
       Message to be encoded and sent.
Output: -

The above procedure sends a sender anonymous (and recipient anonymous
if a SURB is provided) message.

PROCEDURE: Send
Input: SURB provided by another user.
       Message to be encoded and sent.
Output: -

The ``Send'' procedure sends a normal (non-anonymous) message to an
anonymous address.

PROCEDURE: Receive Anonymous 
Input: -
Output: ID, the id of the SURB used to encode this message.
	Message, the message received (decoded)

The ID can be zero (0) if the message received did not use a SURB, and
therefore is not anonymous. It is important to make sure that
information that is to remain anonymous is not sent back as a reply.

It is important to note that in order to create the new procedures
from the ones provided in the mixminion specification a lot of
internal state is required in the client. Hopefully this state should
be preconfigured in the ``anonymous communication stack'' and then
hidden from the layer above that should only need the operations above
to use the anonymity layer. In particular additional information
required includes:
- Lists of mixes, with reliability statistics or another strategy to
choose routes with.
- Secret keys under which the TAG field is encrypted or public/private
key pairs to decode normal mixminion headers.
- A strategy to compute the route lengths.
- A knowledge of the local host parameters, and preferred modes of
delivery (IP or SMTP).

Notes: 
* SURBS are included in the messages when needed and encoded using 
the standard binary or ASCII encoding.
* It is important for clients to be able to tell which SURB was used to 
route back a message otherwise it could be tricky to implement multiple 
pseudonyms above this stack. Likewise it is important to establish if the 
message was routed without any SURB (no anonymity for recipient)

Yours,

George