Re: (Re-)opening the API discussion.

[Nick Mathewson <nickm@alum.mit.edu>]

Summary: I implemented most of what George described here, and in the
process, found a couple of proposed tweaks.  I do some handwaving in the
middle in reference to a large message I'm about to send out later in
the night that will talk about (and propose solutions for!) most of our
lingering end-to-end issues.

Folks-- if you agree with this, I'll try this weekend to solidify the
code that implements it.

On Tue, 2002-09-10 at 10:22, George Danezis wrote:
> 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).

Hm.  I agree in principal, but I think that we shouldn't go calling this
an "API": those are usually language specific.  Instead, this is really
a list of required primitive interfaces that every client implementation
must provide in order to be usefully embeddable.

 [...]
> 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).

This is a separate discussion, but I think you are probably right.

> 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)

I've tried to code this up, so I can vouch for its realism.

> 
> 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.

Not every SURB has a sensible ID.  Stateless SURBs, for instance, have
no state.   Also, you'll need to know what "Address" the SURB should
target.   Finally, you'll need a range of dates during which the SURB
will be valid. I propose instead:

   PROCEDUE: Create 'Stateful' SURB
      Input: Address
             List of valid dates
     Output: ID of generated SURB,  
             Binary representation of generated SURB

  PRODECURE: Create 'Stateless' SURB
      Input: Address
             password or long-term secret
             List of valid dates
     Output: Binary representation of generated SURB.

(See the end of this mail for more info on addresses.)

> 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.


This is good.  It should have a way to do end-to-end payload encryption,
though:

    PROCEDURE: Send Anonymous
        Input: One of * an address, and optionally a public key
                      * a SURB.
               Message to be sent.
       Output: -
 
Also, we should have a way to generate a message and delay inserting it
into the system.  [One of the experienced crypto folk wanted this; I
forget quite why.]

    PROCEDURE: Encode Anonymous
        Input: <Same as 'send anonymous'> 
               Date (or dates) when this message must be valid
       Output: Encoded message to be sent
               Routing info for first hop
 
    PROCEDURE: Send MMTP
        Input: <Same as output of Encode Anonymous>
       Output: -

> 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.

This is fine.  I'd rename it to something else, though: nonanonymity is
risky enough that it shouldn't pass unmentioned.  "Send Open"?  "Send
Identifiable?"

Analogous to above, I'd also add an 'encode' companion for this
procedure.

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

I think we can do even better than this; see my next message.  We can
probably get by with a simple "Recieve"!
 
On addresses: 'Addresses' are a little more complicated than we thought,
especially when you consider encrypted forward messages, and MBOX-style
delivery where recipients run their own non-public nodes.

See my next message for more information.

-- 
Nick