I2P-Bote Ver. 0.1
-----------------

1) Introduction

I2P-Bote is a serverless pseudonymous email exchange service for the I2P network.  Emails are stored
encrypted in a Kademlia DHT formed by all I2P-bote nodes.
There is a web interface that lets the user send/read email and change settings.
An SMTP/POP interface to use with an email client is planned for the future.

Email can be sent through a number of other nodes (relays) for increased anonymity, or directly to a set
of storage nodes for faster delivery. Receiving email through relays is not yet implemented.
All nodes are created equal. There are no "supernodes" or designated relay/storage nodes.
Everybody acts as a potential relay and storage node. At some point in the
future, the maximum amount of disk space used for relayed/stored email packets will be user-configurable.
Before an email is sent, it is broken up into packets 30 kb or smaller and encrypted with the recipient's
public key. The packets are then stored in the DHT.

Email packets are stored redundantly in a Kademlia DHT (distributed hash table).
Stored email packets and relay packets are kept for at least 100 days, during which the recipient can
download them. If a node runs out of email storage space, and there are no old packets that can be deleted,
the node refuses storage requests.

Below is a diagram of how an email packet is routed from a sender to a recipient:


                    .-------.         .-------.         .--------.
                    | Relay |  ---->  | Relay |  ---->  | Storer |  --------------------.
                _   `-------'         `-------'         `--------'                       `\
                /`                                                                         |
               /                                                                           |
 .--------.   /      .-------.        .-------.         .--------.                         |
 | Sender |  ----->  | Relay |  --->  | Relay |  ---->  | Storer |  -------------.         |
 `--------'   \      `-------'        `-------'         `--------'                `\       |
               \                                                                    |      |
               _\/                                                                  |      |
                    .-------.         .-------.         .--------.                  |      |
                    | Relay |  ---->  | Relay |  ---->  | Storer |  ------.         |      |
                    `-------'         `-------'         `--------'         `\       |      |
                                                                             |      |      |
                                                                             V      V      V

                                           .--------------- Kademlia DHT -------------------------.
                                           |                                .---------.           |
                                           |   .---------.                  | Storage |           |
                                           |   | Storage |     .---------.  |  Node   |           |
                                           |   |  Node   |     | Storage |  `---------'           |
                                           |   `---------'     |  Node   |                        |
                                           |                   `---------'            .---------. |
                                           |  .---------.   .---------.               | Storage | |
                                           |  | Storage |   | Storage |  .---------.  |  Node   | |
                                           |  |  Node   |   |  Node   |  | Storage |  `---------' |
                                           |  `---------'   `---------'  |  Node   |              |
                                           |                             `---------'              |
                                           `------------------------------------------------------'

                                                                             |      |      |
                     .-------.          .-------.         .---------.       _'      |      |
                     | Relay |  <-----  | Relay |  <----  | Fetcher |  <---'        |      |
                  /  `-------'          `-------'         `---------'               |      |
                 /                                                                  |      |
               \/_                                                                  |      |
 .-----------.         .-------.        .-------.         .---------.              _'      |
 | Recipient |  <----  | Relay |  <---  | Relay |  <----  | Fetcher |  <----------'        |
 `-----------'  _      `-------'        `-------'         `---------'                      |
               |\                                                                          |
                 \                                                                         |
                  \  .-------.          .-------.         .---------.                     _'
                     | Relay |  <-----  | Relay |  <----  | Fetcher |  <-----------------'
                     `-------'          `-------'         `---------'


The number of relays for sending or retrieving an email is user-configurable.

For higher performance (but reduced anonymity), it is possible to use no relays and no storers/fetchers,
i.e. sender and recipient talk to the storage nodes directly. If both sender and recipient chose not to use
relays, the diagram looks like this:

 .--------.
 | Sender |  ----------------------------.
 `--------'                               `\
                                            |
                                            V

               .--------------- Kademlia DHT -------------------------.
               |                                .---------.           |
               |   .---------.                  | Storage |           |
               |   | Storage |     .---------.  |  Node   |           |
               |   |  Node   |     | Storage |  `---------'           |
               |   `---------'     |  Node   |                        |
               |                   `---------'            .---------. |
               |  .---------.   .---------.               | Storage | |
               |  | Storage |   | Storage |  .---------.  |  Node   | |
               |  |  Node   |   |  Node   |  | Storage |  `---------' |
               |  `---------'   `---------'  |  Node   |              |
               |                             `---------'              |
               `------------------------------------------------------'

                                            |
                                            |
 .-----------.                             _'
 | Recipient |  <-------------------------'
 `-----------'


I2P-Bote uses base64 strings for addresses. They are called email destinations and can be between 86 and 512
characters long, depending on the type of encryption the user chooses.

The code is licensed under the GPL. The author can be reached via I2PMail at HungryHobo@mail.i2p,
or via I2P-Bote at:

hobo37SEJsEMfQHwcpVlvEgnrERGFz34GC1yjVyuRvl1QHnTi0UAoOtrLP~qkFY0oL59BBqj5sCep0RA8I5G8n

 - either in German or English.


2. Kademlia

The Kademlia implementation used by I2P-Bote differs from standard Kademlia in several ways:

 * Items can be deleted from the DHT
 * No caching of DHT items because they are only retrieved once and then deleted
 * I2P-Bote uses sibling lists (s-buckets) as suggested in the S/Kademlia paper

There are two types of data that is stored in the DHT: Email Packets and Index Packets. A third data type
will be added for the address directory when it is implemented.
Index packets contain the DHT keys of one or more email packets. The DHT key of an index packet is the
SHA-256 hash of the Email Destination the email packets are destined for.
To check for new email for a given Email Destination, I2P-Bote first queries the DHT for index packets for that
Email Destination, then queries the DHT for all email packet keys in the index packets. When a complete set of
email packets has been received, the email is reconstructed and placed in the inbox.

To delete an email packet, or an entry in an index packet, the delete request must contain the correct
verification code (the delete verification hash). The verification code is the SHA-256 hash of another block of
data called the delete authorization which is encrypted in the email packet. This means no third party can delete
the packet until the recipient has decrypted the packet and sent out a delete request containing the delete
authorization.
Note that once a delete request for a given email packet has been received by a node that is storing the
email packet, the node knows the delete authorization code and can propagate the delete request to other nodes
that don't know yet that the packet has been deleted.

To delete an index packet entry, a delete verification hash is required as well. It is the same hash as the one
for the email packet which the index packet entry points to.


3. Packet Types

As of release 0.2.5, the protocol version is 4. It is incompatible to earlier versions.
Version 4 clients will talk to higher versions. There will be at least one more protocol version at some point
in the future; this version will be backwards compatible to version 4.
All packets start with one byte for the packet type, followed by one byte for the packet version.
Strings in packets are UTF8 encoded.

3.1. Data Packets

  These are always sent wrapped in a Communication Packet (see 3.1).
  E denotes an encrypted field.
  Supported encryption and signature algorithms:
    ALG=1: ElGamal-2048 / DSA-1024 / AES-256 / SHA-256 (same as the I2P router uses)
    ALG=2: ECDH-256 / ECDSA-256 / AES-256 / SHA-256
    ALG=3: ECDH-521 / ECDSA-521 / AES-256 / SHA-256

   Packet Type        | Field | Data Type  | Description
  --------------------+-------+------------+------------------------------------------------------------------
   Email Packet,      |       |            | An email or email fragment, one recipient. Part of
   encrypted          |       |            | the packet is encrypted with the recipient's key.
                      | TYPE  | 1 byte     | Value = 'E'
                      | VER   | 1 byte     | Protocol version
                      | KEY   | 32 bytes   | DHT key of the packet, SHA-256 hash of LEN+DATA
                      | TIM   | 4 bytes    | The time the packet was stored on a storage node
                      | DV    | 32 bytes   | Delete verification hash, SHA-256 hash of DA
                      | ALG   | 1 byte     | Encryption algorithm used
                      | LEN   | 2 bytes    | Length of DA+DATA together
                      | DA    | 32 bytes E | Delete authorization key, randomly generated
                      | DATA  | byte[]   E | An Unencrypted Email Packet
  --------------------+-------+------------+------------------------------------------------------------------
   Email Packet,      |       |            | Storage format for the Incomplete Email Folder
   unencrypted        |       |            | 
                      | TYPE  | 1 byte     | Value = 'U'
                      | VER   | 1 byte     | Protocol version
                      | MSID  | 32 bytes   | Message ID in binary format
                      | DA    | 32 bytes   | Delete authorization key, randomly generated
                      | FRID  | 2 bytes    | Fragment Index of this packet (0..NFR-1)
                      | NFR   | 2 bytes    | Number of fragments in the email
                      | MLEN  | 2 bytes    | Length of the MSG field
                      | MSG   | byte[]     | email content (MLEN bytes)
  --------------------+-------+------------+------------------------------------------------------------------
   Index Packet       |       |            | Contains the DHT keys of one or more Email Packets, a
                      |       |            | Delete Verification Hash, and time stamp for each DHT key.
                      | TYPE  | 1 byte     | Value = 'I'
                      | VER   | 1 byte     | Protocol version
                      | DH    | 32 bytes   | SHA-256 hash of the recipient's email destination
                      | NP    | 4 bytes    | Number of entries in the packet
                      | KEY1  | 32 bytes   | DHT key of the first Email Packet
                      | DV1   | 32 bytes   | Delete verification hash for KEY1
                      |       |            | (SHA-256 hash of DA in the email packet)
                      | TIM1  | 4 bytes    | The time the key KEY1 was added
                      | KEY2  | 32 bytes   | DHT key of the second Email Packet
                      | DV2   | 32 bytes   | Delete verification hash for KEY2
                      |       |            | (SHA-256 hash of DA in the email packet)
                      | TIM2  | 4 bytes    | The time the key KEY2 was added
                      | ...   | ...        | ...
                      | KEYn  | 32 bytes   | DHT key of the n-th Email Packet
                      | DVn   | 32 bytes   | Delete verification hash for KEYn
                      |       |            | (SHA-256 hash of DA in the email packet)
                      | TIMn  | 4 bytes    | The time the key KEYn was added
  --------------------+-------+------------+------------------------------------------------------------------
   Deletion Info      |       |            | Contains information about deleted  DHT items, which can be
   Packet             |       |            | Email Packets or Index Packet entries.
                      | TYPE  | 1 byte     | Value = 'T'
                      | VER   | 1 byte     | Protocol version
                      | NP    | 4 bytes    | Number of entries in the packet
                      | KEY1  | 32 bytes   | First DHT key
                      | DA1   | 32 bytes   | Delete Authorization for KEY1
                      | TIM1  | 4 bytes    | The time the key KEY1 was added
                      | KEY2  | 32 bytes   | Second DHT key
                      | DA2   | 32 bytes   | Delete Authorization for KEY2
                      | TIM2  | 4 bytes    | The time the key KEY2 was added
                      | ...   | ...        | ...
                      | KEYn  | 32 bytes   | The n-th DHT key
                      | DAn   | 32 bytes   | Delete Authorization for KEYn
                      | TIMn  | 4 bytes    | The time the key KEYn was added
  --------------------+-------+------------+------------------------------------------------------------------
   Peer List          |       |            | Response to a Find Close Peers Request or a Peer List Request
                      | TYPE  | 1 byte     | Value = 'P'
                      | VER   | 1 byte     | Protocol version
                      | NUMP  | 2 bytes    | Number of peers in the list
                      | P1    | 384 bytes  | Destination key
                      | P2    | 384 bytes  | Destination key
                      | ...   | ...        | ...
                      | Pn    | 384 bytes  | Destination key
  --------------------+-------+------------+------------------------------------------------------------------
   Directory Entry    |       |            | A name/Email Destination mapping
                      | TYPE  | 1 byte     | Value = 'M'
                      | VER   | 1 byte     | Protocol version
                      | NLEN  | 2 bytes    | Length of the NAME field, max 50
                      | NAME  | byte[]     | Name in UTF8
                      | DLEN  | 2 bytes    | Length of the DEST field
                      | DEST  | byte[]     | Email destination, 8 bit encoded (not base64)
                      | PLEN  | 2 bytes    | Length of PIC, max 25,000
                      | PIC   | byte[]     | User picture in a browser-compatible format (JPG, PNG, GIF)
                      | TLEN  | 2 bytes    | Length of the TEXT field, max 2000
                      | TEXT  | byte[]     | User defined text in UTF8
  --------------------+-------+------------+------------------------------------------------------------------

3.2. Communication Packets

  Communication packets are used for sending data between two I2P-Bote nodes.
  They contain a data packet, see 3.1.
  All Communication Packets start with a four-byte prefix, followed by one byte for the packet type,
  one byte for the packet version, and a 32-byte Correlation ID.
  
   Packet Type        | Field | Data Type  | Description
  --------------------+-------+------------+------------------------------------------------------------------
   Relay Request      |       |            | A packet that tells the receiver to communicate with a peer,
                      |       |            | or peers, on behalf of the sender. It contains an I2P
                      |       |            | destination, a delay time, and a Communication Packet.
                      | PFX   | 4 bytes    | Packet prefix, must be 0x6D 0x30 0x52 0xE9
                      | TYPE  | 1 byte     | Value = 'R'
                      | VER   | 1 byte     | Protocol version
                      | CID   | 32 bytes   | Correlation ID, used for responses
                      | HLEN  | 2 bytes    | HashCash length
                      | HK    | byte[]     | HashCash token (HLEN bytes)
                      | DLY   | 4 bytes    | Delay in seconds before sending
                      | NEXT  | 384 bytes  | Destination to forward the packet to
                      | RET   | Ret. Chain | An empty or non-empty Return Chain
                      | DLEN  | 2 bytes    | Length of the DATA field in bytes
                      | DATA  | byte[]   E | Encrypted with the recipient's public key. Can contain another
                      |       |            | Relay Request, a Store Request, or a Deletion Query.
                      | PAD   | byte[]     | Optional padding
  --------------------+-------+------------+------------------------------------------------------------------
   Relay Return       |       |            | Contains a Return Chain and a payload. The final destination
   Request            |       |            | is unknown to the sender or any of the hops.
   (not implemented)  |       |            | Used for responding to a relayed data packet.
                      | PFX   | 4 bytes    | Packet prefix, must be 0x6D 0x30 0x52 0xE9
                      | TYPE  | 1 byte     | Value = 'K'
                      | VER   | 1 byte     | Protocol version
                      | CID   | 32 bytes   | Correlation ID, used for confirmation between two relay peers.
                      |       |            | A new correlation ID is set at every hop.
                      | RET   | Ret. Chain | A non-empty Return Chain
                      | DLEN  | 2 bytes    | Length of the DATA field in bytes
                      | DATA  | byte[]   E | The payload. AES256-encrypted at every hop in the return chain.
  --------------------+-------+------------+------------------------------------------------------------------
   Return Chain       |       |            | Not a packet itself, but part of a Relay (Return) Request
                      | RL1   | 2 bytes    | Length of RET1. Zero means an empty return chain, nothing follows.
                      | RET1  | RL1 bytes  | Hop 1 in the return chain. Contains a zero byte, followed by the
                      |       |            | hop's I2P destination and an AES key to encrypt the payload with.
                      | RL2   | 2 bytes   E| Length of RET2.
                      | RET2  | RL2 bytes E| Hop 2 in the return chain. Contains a zero byte, followed by the
                      |       |            | hop's I2P destination and an AES key to encrypt the payload with.
                      |       |            | This field is encrypted with the PK of hop 2.
                      | RL3   | 2 bytes   E| Length of RET3.
                      | RET3  | RL3 bytes E| Hop 3 in the return chain. Contains a zero byte, followed by the
                      |       |            | hop's I2P destination and an AES key to encrypt the payload with.
                      |       |            | This field is encrypted with the PKs of hops 3 and 2.
                      | ...   | ...        | ...
                      | RLn   | 2 bytes   E| Length of RETn.
                      | RETn  | RLn bytes E| Last hop in the return chain. Contains a zero byte, followed by the
                      |       |            | hop's I2P destination and an AES key to encrypt the payload with.
                      |       |            | This field is encrypted with the PKs of hops n...2.
                      | RLn+1 | 2 bytes   E| Length of RETn+1.
                      | RETn+1| RLn+1 byt E| Number of hops (>0) followed by all AES256 keys (one per hop)
                      | RLn+2 | 2 bytes    | Value=0 to indicate this is the end of the return chain
  --------------------+-------+------------+------------------------------------------------------------------
   Fetch Request      |       |            | Request to a chain end point to retrieve an Index Packet or
                      |       |            | Email Packet.
                      | PFX   | 4 bytes    | Packet prefix, must be 0x6D 0x30 0x52 0xE9
                      | TYPE  | 1 byte     | Value = 'F'
                      | VER   | 1 byte     | Protocol version
                      | CID   | 32 bytes   | Correlation ID, used for responses
                      | DTYP  | 1 byte     | Type of data to retrieve
                      | KEY   | 32 bytes   | DHT key to look up
                      | KPR   | 384 bytes  | Email keypair of recipient
                      | RLEN  | 2 bytes    | Length of the RET field
                      | RET   | byte[]     | Relay packet, contains the return chain (RLEN bytes)
  --------------------+-------+------------+------------------------------------------------------------------
   Response Packet    |       |            | Response to a Retrieve Request, Fetch Request,
                      |       |            | Find Close Peers Request, or a Peer List Request
                      | PFX   | 4 bytes    | Packet prefix, must be 0x6D 0x30 0x52 0xE9
                      | TYPE  | 1 byte     | Value = 'N'
                      | VER   | 1 byte     | Protocol version
                      | CID   | 32 bytes   | Correlation ID of the request packet
                      | STA   | 1 byte     | Status code:
                      |       |            |   0 = OK
                      |       |            |   1 = General error
                      |       |            |   2 = No data found
                      |       |            |   3 = Invalid packet
                      |       |            |   4 = Invalid HashCash
                      |       |            |   5 = Not enough HashCash provided
                      |       |            |   6 = No disk space left
                      | DLEN  | 2 bytes    | Length of the DATA field; can be 0 if no payload
                      | DATA  | byte[]     | A Data Packet
  --------------------+-------+------------+------------------------------------------------------------------
   Peer List Request  |       |            | A request for a list of
                      |       |            | high-reachability relay peers
                      | PFX   | 4 bytes    | Packet prefix, must be 0x6D 0x30 0x52 0xE9
                      | TYPE  | 1 byte     | Value = 'A'
                      | VER   | 1 byte     | Protocol version
                      | CID   | 32 bytes   | Correlation ID, used for responses
  --------------------+-------+------------+------------------------------------------------------------------

  DHT Communication Packets
  
   Packet Type        | Field | Data Type  | Description
  --------------------+-------+------------+------------------------------------------------------------------
   RetrieveRequest    |       |            | A request to a peer to return a data item for a given DHT key
                      |       |            | and data type
                      | PFX   | 4 bytes    | Packet prefix, must be 0x6D 0x30 0x52 0xE9
                      | TYPE  | 1 byte     | Value = 'Q'
                      | VER   | 1 byte     | Protocol version
                      | CID   | 32 bytes   | Correlation ID, used for responses
                      | DTYP  | 1 byte     | Type of data to retrieve:
                      |       |            |   'I' = Index Packet
                      |       |            |   'E' = Email Packet
                      |       |            |   'M' = Directory Entry
                      | KEY   | 32 bytes   | DHT key to look up
  --------------------+-------+------------+------------------------------------------------------------------
   Deletion Query     |       |            | A request to a peer to return a Deletion Info Packet for a given
   (Not implemented)  |       |            | DHT key and data type. No response is expected if the DHT item
                      |       |            | is not known to be deleted.
                      | PFX   | 4 bytes    | Packet prefix, must be 0x6D 0x30 0x52 0xE9
                      | TYPE  | 1 byte     | Value = 'L'
                      | VER   | 1 byte     | Protocol version
                      | CID   | 32 bytes   | Correlation ID, used for responses
                      | DTYP  | 1 byte     | Type of data to query for:
                      |       |            |   'I' = Index Packet
                      |       |            |   'E' = Email Packet
                      |       |            |   'M' = Directory Entry
                      | KEY   | 32 bytes   | DHT key to look up
  --------------------+-------+------------+------------------------------------------------------------------
   Store Request      |       |            | DHT Store Request
                      | PFX   | 4 bytes    | Packet prefix, must be 0x6D 0x30 0x52 0xE9
                      | TYPE  | 1 byte     | Value = 'S'
                      | VER   | 1 byte     | Protocol version
                      | CID   | 32 bytes   | Correlation ID, used for responses
                      | HLEN  | 2 bytes    | HashCash length
                      | HK    | byte[]     | HashCash token (HLEN bytes)
                      | DLEN  | 2 bytes    | Length of the DATA field
                      | DATA  | byte[]     | Data packet to store (DLEN bytes).
                      |       |            | Can be an Index Packet, Email Packet, or Email Destination.
  --------------------+-------+------------+------------------------------------------------------------------
   Email Packet       |       |            | Request to delete an Email Packet by DHT key
   Delete Request     |       |            |
                      | PFX   | 4 bytes    | Packet prefix, must be 0x6D 0x30 0x52 0xE9
                      | TYPE  | 1 byte     | Value = 'D'
                      | VER   | 1 byte     | Protocol version
                      | CID   | 32 bytes   | Correlation ID, used for responses
                      | KEY   | 32 bytes   | DHT key of the Email Packet to delete
                      | DA    | 32 bytes   | Delete Authorization (SHA-256 must equal DV in the email pkt)
  --------------------+-------+------------+------------------------------------------------------------------
   Index Packet       |       |            | Request to remove one or more entries (Email Packet keys) from
   Delete Request     |       |            | an Index Packet
                      | PFX   | 4 bytes    | Packet prefix, must be 0x6D 0x30 0x52 0xE9
                      | TYPE  | 1 byte     | Value = 'X'
                      | VER   | 1 byte     | Protocol version
                      | CID   | 32 bytes   | Correlation ID, used for responses
                      | DH    | 32 bytes   | The Email Destination hash of the Index Packet
                      | N     | 1 byte     | Number of entries in the packet
                      | DHT1  | 32 bytes   | First DHT key to remove
                      | DA1   | 32 bytes   | Delete Authorization (SHA-256 must equal DV in the email packet
                      |       |            | referenced by DHT1)
                      | DHT2  | 32 bytes   | Second DHT key to remove
                      | DA2   | 32 bytes   | Delete Authorization (SHA-256 must equal DV in the email packet
                      |       |            | referenced by DHT2)
                      | ...   | ...        | ...
                      | DHTn  | 32 bytes   | n-th DHT key to remove
                      | DAn   | 32 bytes   | Delete Authorization (SHA-256 must equal DV in the email packet
                      |       |            | referenced by DHTn)
  --------------------+-------+------------+------------------------------------------------------------------
   Find Close Peers   |       |            | Request for k peers close to a key
                      | PFX   | 4 bytes    | Packet prefix, must be 0x6D 0x30 0x52 0xE9
                      | TYPE  | 1 byte     | Value = 'C'
                      | VER   | 1 byte     | Protocol version
                      | CID   | 32 bytes   | Correlation ID, used for responses
                      | KEY   | 32 bytes   | DHT key
  --------------------+-------+------------+------------------------------------------------------------------


4. Protocols

4.1. Storing a DHT item via relays
  I2P nodes involved: A=Sender, R1...Rn=Relays, S1...Sm=Storage Nodes

  1) A onion-encrypts the Store Request with the public keys of all hops, resulting in a Relay Packet.
  2) A sends the Relay Packet to R1.
  3) R1 decrypts the packet, waits a random amount of time, and sends it to R2.
  4) R2 confirms delivery with R1.
  5) Repeat until packet arrives at Rn.
  6) Rn decrypts the Relay Packet into an Email Packet.
  7) Rn sends the packet to S1,...,Sm through a Kademlia STORE

4.2. Return Chains

In order to make it impossible for two non-adjacent nodes on the return chain to identify Relay
Return Request packets, the payload and the entire Return Chain are re-encrypted at every hop.
A new Correlation ID is generated at every hop.
Here is a simplified diagram of how a Relay Return Packet is sent from one hop to the next:

  (A) The packet is received. HOP1 through HOP3 contain encrypted data (encrypted with the public key
      for the receiving I2P node):
      
      +------------------- Relay Return Request --------------------------+
      |                                                                   |
      |                                .-----KEY1-----.                   |
      |                .---KEY1---.   |  .---KEY2---.  |                  |
      |     .-KEY1-.  |  .-KEY2-.  |  | |  .-KEY3-.  | |  .---------.     |
      |     | HOP1 |  |  | HOP2 |  |  | |  | HOP2 |  | |  | PAYLOAD |     |
      |     `------’  |  `------’  |  | |  `------’  | |  `---------’     |
      |                `----------’   |  `----------’  |                  |
      |                                `--------------’                   |
      |                                                                   |
      +-------------------------------------------------------------------+
      
      KEYx denotes a layer of encryption.

  (B) The receiving node decrypts HOP1, HOP2, and HOP3. HOP1 is now in plain text. It contains the
      destination of the next hop and an AES key.
  
      +------------------- Relay Return Request --------------------------+
      |                                                                   |
      |                                .-----KEY2-----.                   |
      |                .---KEY2---.   |  .---KEY3---.  |                  |
      |     .------.  |  .------.  |  | |  .------.  | |  .---------.     |
      |     | HOP1 |  |  | HOP2 |  |  | |  | HOP2 |  | |  | PAYLOAD |     |
      |     `------’  |  `------’  |  | |  `------’  | |  `---------’     |
      |                `----------’   |  `----------’  |                  |
      |                                `--------------’                   |
      |                                                                   |
      +-------------------------------------------------------------------+

  (C) HOP1 is replaced with random data and moved to the end of the chain. The payload is encrypted with
      the AES key from HOP1:
  
      +------------------- Relay Return Request --------------------------+
      |                                                                   |
      |                      .-----KEY2-----.                             |
      |      .---KEY2---.   |  .---KEY3---.  |                            |
      |     |  .------.  |  | |  .------.  | |  .------.  .---AES---.     |
      |     |  | HOP2 |  |  | |  | HOP2 |  | |  | HOP1 |  | PAYLOAD |     |
      |     |  `------’  |  | |  `------’  | |  `------’  `---------’     |
      |      `----------’   |  `----------’  |                            |
      |                      `--------------’                             |
      |                                                                   |
      +-------------------------------------------------------------------+

  (D) The packet is sent to the next node in the chain.


4.3. Retrieving DHT items via relays (not implemented yet)
  I2P nodes involved:
    A=Address Owner
    F=Fetcher
    O1...On=Outbound Relays
    I1...In=Inbound Relays,
    S1...Sm=Storage Nodes

  1) A builds a Relay Request containing a Retrieve Request and sends it to F via O1, O2, ..., On
     as described in 4.1
  2) F queries the DHT for the DHT item
  3) F encrypts the DHT data with the public key for hop 1 of the return chain
  4) F moves the (RL1,RET1) block of the return chain to the end (behind RETn+1)
  5) F sends the results of steps 3) and 4) to I1
  6) I1 decrypts all (RLx,RETx) blocks of the return chain and finds I2 and the AES key in the first block
  7) I1 replaces (RL1,RET1) with random data that is encrypted with the PK for I2
  8) I1 moves the (RL1,RET1) block of the return chain to the end (behind RETn+1)
  9) I1 encrypts the payload with the AES key
  10) I1 sends the results of steps 7) and 8) to I2
  11) Repeat from 6) for I2, I3, ..., until the data reaches A (when the first byte of RET1 is non-zero)
  12) A decrypts the (RL1,RET1) block which contains all AES keys
  13) A decrypts the payload with the AES keys, starting from the last hop's key
  14) The decrypted data contains the DHT data packet

4.4. Deleting an Email Packet

  Every time a recipient receives an email packet directly from one or more storage nodes, it asks the
  storage node(s) to delete the packet.
  If the email packet is received through one or more relays, the recipient issues a delete request to
  a (possibly different) relay endpoint, which entails an additional findClosestNodes lookup because the
  endpoint has to find out which nodes are storing the packet.
  
  The recipient also sends a delete request for index packet, asking the storage nodes to delete the DHT
  key of the email packet. Each index packet node then removes the DHT key from the stored index packet,
  and adds the DHT key to a list of deleted DHT keys it maintains for each index packet (plus the
  delete verification hash).
  The purpose of this is so a node that is about to replicate an email packet can find out if it missed
  an earlier delete request for that packet, in which case the node "replicates" the delete request rather
  than the packet itself.
  This helps reduce storage space by removing old Email Packets from nodes that weren't online at the time
  the delete request was sent initially.
  
4.5 Deleting an Index Packet Entry

  Similar to deleting an email packet.

4.6. Replication

See comments at the beginning of src/i2p/bote/network/kademlia/ReplicateThread.java


5. Algorithms Used By Nodes Locally

5.1. Retrieving Email via relays

   see also http://forum.i2p/viewtopic.php?p=19927#19927 ff.
   
   1) Randomly choose a set of n relay nodes,  R1...Rn (outgoing chain for request)
   2) Randomly choose a set of m relay nodes, S1...Sm. (return chain / inbound mail chain)
        - with Sm being the node closest to the receiver
          and S1 the chain node closest to fetcher
   3) Generate m+1 random 32-byte arrays (for XORing the return packets), X1...Xm+1
      (This is done so the outgoing chain's endpoint or inbound first hop need
      not know all inbound hops in order to perform hop-to-hop encryption. Each
      hop will decrypt one 32-byte random array and encrypt the packet with it,
      so it looks different at each hop without one node at the beginning
      knowing all hops)
   4) With Sm's public key, encrypt the local destination key and Xm+1
   5) With Sm-1's public key, encrypt Sm's destination key, Xm, and the data from step 4)
   6) With Sm-2's public key, encrypt Sm-1's destination key, Xm-1, and the data from step 5)
   7) Repeat until the entire return chain, S1...Sm, has been onion-encrypted, and also include a
      delay for each hop.
   8) Add S1's destination key and X1 to the data from step 7)
   9) Add the data (which is a Relay Packet) to a Retrieve Request packet.
  10) Encrypt the resulting packet, using the public keys of relays Rn (Fetcher), Rn-1, ..., R1,
      and add the destination key of the next relay each time. Also included is a delay for each relay.
  11) Set a random Correlation ID on the packet at each layer
  12) Add the packet to the relay packet folder.
  13) When a reply packet is received, decrypt it first with the local node's private
      decryption key, then with all the random keys X1...Xm+1.


6. Files

6.1. Identities file

  Stores all email identities the local user has created. One line per entry.
  Format:
    <base64 key><tab><public name>[<tab><description>][<tab><email address>]


7. Glossary of Terms

Email Destination
  As the name implies, an Email Destination is an identifier by which somebody can be reached via I2P-Bote.
  An Email Destination is a Base64 string containing a public encryption key and a signature verification key.
  Example of a 512-character Email Destination (ElGamal-2048/DSA-2048):
  
  uQtdwFHqbWHGyxZN8wChjWbCcgWrKuoBRNoziEpE8XDt8koHdJiskYXeUyq7JmpG
  In8WKXY5LNue~62IXeZ-ppUYDdqi5V~9BZrcbpvgb5tjuu3ZRtHq9Vn6T9hOO1fa
  FYZbK-FqHRiKm~lewFjSmfbBf1e6Fb~FLwQqUBTMtKYrRdO1d3xVIm2XXK83k1Da
  -nufGASLaHJfsEkwMMDngg8uqRQmoj0THJb6vRfXzRw4qR5a0nj6dodeBfl2NgL9
  HfOLInwrD67haJqjFJ8r~vVyOxRDJYFE8~f9b7k3N0YeyUK4RJSoiPXtTBLQ2RFQ
  gOaKg4CuKHE0KCigBRU-Fhhc4weUzyU-g~rbTc2SWPlfvZ6n0voSvhvkZI9V52X3
  SptDXk3fAEcwnC7lZzza6RNHurSMDMyOTmppAVz6BD8PB4o4RuWq7MQcnF9znElp
  HX3Q10QdV3omVZJDNPxo-Wf~CpEd88C9ga4pS~QGIHSWtMPLFazeGeSHCnPzIRYD

  Example of a 86-character Email Destination (ECC-256):
  1Lcvly8no5of6juJKxqy-xA-MStM2c2XKorepH1oqs5yKBkg9-ZcG4G4kZY1E~2672cMA806l9EicQLmlehB1m

Email Address
  Email Addresses in I2P-Bote are shortcuts for Email Destinations.
  Email Address <--> Email Destination mappings are stored in two places: the local address book and the
  distributed address directory (the latter not being implemented yet).

Email Identity
  An Email Identity is an Email Destination plus a name you want to be known as when you use that identity.
  Technically speaking, an Email Identity consists of four things:
   * An Email Destination (i.e. two public keys)
   * The two private keys for the Email Destination
   * A public name which is shown to other people in emails
   * A description which is not shown to anybody but you.
     It helps you remember which Email Identity you use for which purpose.
  An email identity is not required for sending emails (in that case only "Anonymous" can be selected in the
  "sender" field).

I2P destination
  The address of a I2P-Bote node on the I2P network. There is normally no need to know it.
  I2P destinations and Email Destinations look similar, but are completely independent of each other.


8. To Do / Ideas

  * If multiple Delete Verification Hashes and multiple encrypted AES session keys could be put into an
    email packet, it wouldn't be necessary to store one email packet per recipient
  * Keep email identities in a keystore (JKS)
  * Deletion of emails after they have been sent: Sender knows the
    delVerificationHashes of the packets and can delete the packets from the DHT.
  * Once SMTP/POP3 is supported, allow a @host to be appended to email
    destinations so email clients that insist on it, like Thunderbird, don't complain.
  * Expire DHT items sooner (currently, expiration time = 100 days) and require
    that senders resend emails before they expire, until the email has been picked up
  * For each email in the "sent" folder, keep a list of email package keys
    and periodically check to see if they have been deleted from the DHT.
    When they are all deleted, show "email delivered" in the sent folder.
  * ignore store requests for existing packets so malicious index nodes cannot replace email packets on other index nodes
  * instead of republishing after T seconds, pick a random time from the interval [T-a, T+a];
    the probability should be low at T-a and then increase
  * Cache email dest - closest node mappings for faster Kademlia lookups
  * Externally synchronize ArrayLists?
  * identities: "publish to distributed address book" button, asks for an email address
  * b32 email destinations in the distributed address book? could also be useful for getting around the address size limit in POP/SMTP
  * <jsp:useBean> instead of zero-param JSP functions
  * button to delete all packets with an invalid protocol version
  * auto-refresh network.jsp
  * show remaining time for the 3-min delay at startup
  * Automatically create a different sender address for each recipient
  * test relays and storage nodes periodically, ban nodes that break the contract
  * optionally pad all packets to a system-wide fixed size
  * Always use the same amount of bandwidth, testing nodes or sending dummy messages if necessary.
  * Always keep incoming bandwidth the same as outgoing bandwidth (can this be done?)
  * Pad packets before encrypting to prevent tagging attacks (only relay packets?)
  * delivery confirmation to sender
  * Turnkey outproxy feature?
  * select different set of hops for each packet
  * make minimum reachability configurable (currently 80%)
  * mention that min/max delay = earliest/latest send time (explain that there is no guarantee for the send time being between min and max, it can be after max)
  * On first run, offer to create a new email identity
  * Folder structure on disk should reflect folders in app. All email folders visible to the user have the same root directory: [app dir]/folders.
  * ask user for confirmation before deleting an email identity
  * use a key store for email identities so they are not locally readable?
  * prioritize packets in I2PSendQueue? Should PeerListRequests get higher priority than relay packets etc.?
