polistern
/
pboted_docs
mirror of https://github.com/polistern/pboted_docs
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Reformation of Bote protocol section.

main
polistern 2021-11-18 09:38:15 +00:00
parent 5f51fbf816
commit c8f5eb71ac
Signed by: polistern
GPG Key ID: E131651B5A988EAC
37 changed files with 427 additions and 381 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
.readthedocs.yaml
View File

@ -6,9 +6,9 @@ build:
python: "3.9"
mkdocs:
configuration: mkdocs.yml
configuration: docs/mkdocs.yml
fail_on_warning: false
python:
install:
- requirements: requirements.txt
- requirements: docs/requirements.txt

40
docs/devs/bote/v5/files.md
View File

@ -1,40 +0,0 @@
# 6. Files
## 6.1. Identities file
Stores all email identities the local user has created. The file uses the Java Properties format, and can be read into / written out from a Java Properties object.
The following property keys are currently stored and recognized:
* identity#.publicName - The public name of the identity, included in emails.
* identity#.key - Base64 of the identity keys.
* identity#.salt - Salt used to generate a fingerprint.
* identity#.description - Description of the identity, only displayed locally.
* identity#.picture - Base64 of byte[] containing picture data
* identity#.text - Text associated with the identity.
* identity#.published - Has the identity been published to the public addressbook?
(# is an integer index)
The base64 key contains two public keys (encryption+signing) and two private keys.
The identities file can optionally contain the property key "default", with its value set to an Email Destination (i.e. two public keys).
If the Email Destination matches one of the identities, that identity is used as the default.
ToDo: Looks specific to Java app, remove from protocol description
## 6.2. Included .jar files and third-party source code
```
bcprov-jdk15on-152.jar The BouncyCastle library and SecurityProvider.
mailapi-1.5.4.jar Part of JavaMail 1.5.4
lzma-9.20.jar An LZMA implementation from http://www.7-zip.org/sdk.html
ntruenc-1.2.jar An NTRU implementation from http://sf.net/projects/ntru/
(only the NTRUEncrypt part, not NTRUSign)
flexi-gmss-1.7p1.jar A stripped down and patched version of the FlexiProvider
sources (http://www.flexiprovider.de/), containing only the
classes needed for GMSS.
The patch consists of a modified de.flexiprovider.core.CoreRegistry
and de.flexiprovider.api.Registry and its purpose is to
reduce dependencies on classes not related to GMSS.
scrypt-1.4.0.jar An scrypt implementation from https://github.com/wg/scrypt/
```

297
docs/devs/bote/v5/packet_types.md
View File

@ -1,297 +0,0 @@
# 3. Packet Types
As of release 0.7.0, the protocol version is 5. It is incompatible to earlier versions.
Version 5 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 5.
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.2).
**E** denotes encrypted data.
For supported encryption and signature algorithms, see [7.1](cryptography.md)
```
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 | ID number of the encryption algorithm used
| LEN | 2 bytes | Length of DATA
| DATA | byte[] E | Data for decryption and Unencrypted Email Packet
| | | ToDo: add info about alg-specific prefixes
--------------------+-------+------------+--------------------------------------------------------
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
Packet | | | can be 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 = 'L'
| VER | 1 byte | Protocol version
| NUMP | 2 bytes | Number of peers in the list
| IDN1 | 384 bytes | Standart I2P identity
| TYPE1 | 1 byte | Certificate type
| LEN1 | 2 byte | Length of extra bytes DATA1 field
| DATA1 | byte[] | Extra bytes
| IDN2 | 384 bytes | Standart I2P identity
| TYPE2 | 1 byte | Certificate type
| LEN2 | 2 byte | Length of extra bytes DATA2 field
| DATA2 | byte[] | Extra bytes
| ... | ... | ...
| IDNn | 384 bytes | Standart I2P identity
| TYPEn | 1 byte | Certificate type
| LENn | 2 byte | Length of extra bytes DATAn field
| DATAn | byte[] | Extra bytes
--------------------+-------+------------+--------------------------------------------------------
Directory Entry | | | A name/Email Destination mapping
(Contact.java) | TYPE | 1 byte | Value = 'C'
| VER | 1 byte | Protocol version
| KEY | 32 bytes | DHT key (SHA-256 hash of the UTF8-encoded name in
| | | lower case)
| DLEN | 2 bytes | Length of the DEST field
| DEST | byte[] | Email destination, 8 bit encoded (not base64)
| SALT | 4 bytes | A value such that scrypt(KEY|DEST|SALT) ends with
| | | a zero byte
| PLEN | 2 bytes | Length of PIC, max 7500
| PIC | byte[] | User picture in a browser-compatible format
| | | (JPG, PNG, GIF)
| COMP | 1 byte | Compression type_ for TEXT
| 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
Request | | | destination is unknown to the sender or any of the
(not implemented) | | | hops. 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)
(not implemented) | | | 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 endpoint to retrieve an Index
(not implemented) | | | Packet or Email Packet.
| PFX | 4 bytes | Packet prefix, must be 0x6D 0x30 0x52 0xE9
| TYPE | 1 byte | Value = ''
| 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
--------------------+-------+------------+--------------------------------------------------------
Retrieve Request | | | 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
| | | 'C' = 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 Email Packet DHT key. If the Email Packet
| | | is not known to be deleted, no response is expected
| | | back.
| PFX | 4 bytes | Packet prefix, must be 0x6D 0x30 0x52 0xE9
| TYPE | 1 byte | Value = 'Y'
| VER | 1 byte | Protocol version
| CID | 32 bytes | Correlation ID, used for responses
| 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
Delete Request | | | keys) from 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 = 'F'
| VER | 1 byte | Protocol version
| CID | 32 bytes | Correlation ID, used for responses
| KEY | 32 bytes | DHT key
--------------------+-------+------------+--------------------------------------------------------
```

0
docs/about/contributing.md → docs/docs/about/contributing.md
View File

0
docs/about/donations.md → docs/docs/about/donations.md
View File

0
docs/about/license.md → docs/docs/about/license.md
View File

0
docs/about/thanks.md → docs/docs/about/thanks.md
View File

0
docs/devs/bote/v4/algorithms_used_by_nodes_locally.md → docs/docs/devs/bote/v4/algorithms_used_by_nodes_locally.md
View File

0
docs/devs/bote/v4/cryptography.md → docs/docs/devs/bote/v4/cryptography.md
View File

0
docs/devs/bote/v4/files.md → docs/docs/devs/bote/v4/files.md
View File

0
docs/devs/bote/v4/glossary_of_terms.md → docs/docs/devs/bote/v4/glossary_of_terms.md
View File

0
docs/devs/bote/v4/introduction.md → docs/docs/devs/bote/v4/introduction.md
View File

0
docs/devs/bote/v4/kademlia.md → docs/docs/devs/bote/v4/kademlia.md
View File

0
docs/devs/bote/v4/packet_types.md → docs/docs/devs/bote/v4/packet_types.md
View File

0
docs/devs/bote/v4/protocols.md → docs/docs/devs/bote/v4/protocols.md
View File

8
docs/devs/bote/v5/algorithms_used_by_nodes_locally.md → docs/docs/devs/bote/v5/algorithms_used_by_nodes_locally.md
View File

@ -1,4 +1,4 @@
# 5. Algorithms Used By Nodes Locally
# 5. Algorithms Used By Nodes Locally (DRAFT)
## 5.1. Retrieving Email via relays
@ -10,11 +10,7 @@ See also http://forum.i2p/viewtopic.php?p=19927#19927 ff.
- 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)
(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)

32
docs/devs/bote/v5/cryptography.md → docs/docs/devs/bote/v5/cryptography.md
View File

@ -1,7 +1,9 @@
# 7. Cryptography
# 7. Cryptography (DRAFT)
## 7.1. Asymmetric encryption and signing
ToDo: Looks specific to Java app, remove from protocol description
Supported encryption and signature algorithms:
* ALG=1: ElGamal-2048 / DSA-1024 / AES-256 / SHA-256
@ -9,32 +11,32 @@ Supported encryption and signature algorithms:
* ALG=3: ECDH-521 / ECDSA-521 / AES-256 / SHA-512
* ALG=4: NTRUEncrypt-1087 / GMSS-512 / AES-256 / SHA-512
ToDo: Looks specific to Java app, remove from protocol description
## 7.2. Password Encryption
ToDo: Looks specific to Java app, remove from protocol description
The identities file, the address book, and all email files are encrypted with AES-256.
To generate the AES key from the password, scrypt (http://www.tarsnap.com/scrypt.html) is used.
The file format is:
```
Field | #bytes | Description
-------+--------+------------------------------------------------------------------
SOF | 4 | Start of file, contains the characters "IBef"
VER | 1 | Format version, must be 1
N | 4 | scrypt CPU cost parameter
r | 4 | scrypt memory cost parameter
p | 4 | scrypt parallelization parameter
SALT | 32 | Salt for scrypt
IV | 32 | IV for AES
DATA | | The encrypted data
```
|Field | #bytes | Description |
|------|--------|-----------------------------------------------|
|SOF | 4 | Start of file, contains the characters "IBef" |
|VER | 1 | Format version, must be 1 |
|N | 4 | scrypt CPU cost parameter |
|r | 4 | scrypt memory cost parameter |
|p | 4 | scrypt parallelization parameter |
|SALT | 32 | Salt for scrypt |
|IV | 32 | IV for AES |
|DATA | | The encrypted data |
Parameters N through SALT are cached in a file named derivparams so all encrypted files can use the same key derivation parameters.
This makes decryption much faster because the key only needs to be derived once per session.
## 7.3. Fingerprints For Directory Entries
ToDo: Looks specific to Java app, remove from protocol description
TODO
H = scrypt(name, dest, zuf.wert); die letzten 8 Binärstellen von H müssen 0 sein
13*7+22+18 = 131

35
docs/docs/devs/bote/v5/files.md 100644
View File

@ -0,0 +1,35 @@
# 6. Files (DRAFT)
## 6.1. Identities file
Stores all email identities the local user has created.
The file uses the Java Properties format, and can be read into / written out from a Java Properties object.
The following property keys are currently stored and recognized (N is an integer index):
| Field | Description |
|----------------------|------------------------------------------------------------|
|identityN.publicName | The public name of the identity, included in emails. |
|identityN.key | Base64 of the identity keys. |
|identityN.salt | Salt used to generate a fingerprint. |
|identityN.description | Description of the identity, only displayed locally. |
|identityN.picture | Base64 of byte[] containing picture data |
|identityN.text | Text associated with the identity. |
|identityN.published | Has the identity been published to the public addressbook? |
The base64 key contains two public keys (encryption+signing) and two private keys.
The identities file can optionally contain the property key "default", with its value set to an Email Destination (i.e. two public keys).
If the Email Destination matches one of the identities, that identity is used as the default.
## 6.2. Included .jar files and third-party source code
ToDo: Looks specific to Java app, remove from protocol description
- bcprov-jdk15on-152.jar The BouncyCastle library and SecurityProvider.
- mailapi-1.5.4.jar Part of JavaMail 1.5.4
- lzma-9.20.jar An LZMA implementation from http://www.7-zip.org/sdk.html
- ntruenc-1.2.jar An NTRU implementation from http://sf.net/projects/ntru/ (only the NTRUEncrypt part, not NTRUSign)
- flexi-gmss-1.7p1.jar A stripped down and patched version of the FlexiProvider sources (http://www.flexiprovider.de/), containing only the classes needed for GMSS. The patch consists of a modified de.flexiprovider.core.CoreRegistry and de.flexiprovider.api.Registry and its purpose is to reduce dependencies on classes not related to GMSS.
- scrypt-1.4.0.jar An scrypt implementation from https://github.com/wg/scrypt/

11
docs/devs/bote/v5/glossary_of_terms.md → docs/docs/devs/bote/v5/glossary_of_terms.md
View File

@ -1,6 +1,6 @@
# 9. Glossary of Terms
# 8. Glossary of Terms (DRAFT)
## Email Destination
## 8.1 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.
@ -23,12 +23,13 @@ Example of a 86-character Email Destination (ECC-256):
1Lcvly8no5of6juJKxqy-xA-MStM2c2XKorepH1oqs5yKBkg9-ZcG4G4kZY1E~2672cMA806l9EicQLmlehB1m
```
## Email Address
## 8.2 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.
## Email Identity
## 8.3 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:
@ -40,7 +41,7 @@ Technically speaking, an Email Identity consists of four things:
An email identity is not required for sending emails (in that case only "Anonymous" can be selected in the "sender" field).
## I2P destination
## 8.4 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.

4
docs/devs/bote/v5/introduction.md → docs/docs/devs/bote/v5/introduction.md
View File

@ -1,4 +1,4 @@
# 1. Introduction
# 1. Introduction (DRAFT)
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 SMTP/POP3 interface that lets the user send/read email.
@ -89,4 +89,4 @@ If both sender and recipient chose not to use relays, the diagram looks like thi
`-----------'
```
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 (see [7.1](cryptography.md)).
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 (see [7.1 Cryptography](cryptography.md)).

8
docs/devs/bote/v5/kademlia.md → docs/docs/devs/bote/v5/kademlia.md
View File

@ -1,10 +1,10 @@
# 2. Kademlia
# 2. Kademlia (DRAFT)
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
* 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 three types of data that is stored in the DHT:

334
docs/docs/devs/bote/v5/packet_types.md 100644
View File

@ -0,0 +1,334 @@
# 3. Packet Types
Version 5 is incompatible to earlier versions.
Version 5 clients will talk to higher versions.
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.2).
**E** denotes encrypted data.
For supported encryption and signature algorithms, see [7.1 Cryptography](cryptography.md)
### 3.1.1 Email Packet (encrypted)
An email or email fragment, one recipient. Part of the Packet is encrypted with the recipient's key.
| Field | Data Type | Description |
|-------|------------|----------------------------------------------------|
| 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 | ID number of the encryption algorithm used |
| LEN | 2 bytes | Length of DATA |
| DATA | byte[] E | Data for decryption and Unencrypted Email Packet |
ToDo: add info about alg-specific prefixes
### 3.1.2 Email Packet (unencrypted)
Storage format for the Incomplete Email Folder
| Field | Data Type | Description |
|-------|------------|-----------------------------------------------|
| 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) |
### 3.1.3 Index Packet
Contains the DHT keys of one or more Email Packets, a Delete Verification Hash, and time stamp for each DHT key.
| Field | Data Type | Description |
|-------|------------|----------------------------------------------------------------------------|
| 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 |
### 3.1.4 Deletion Info Packet
Contains information about deleted DHT items, which can be Email Packets or Index Packet entries.
| Field | Data Type | Description |
|-------|------------|---------------------------------|
| 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 |
### 3.1.5 Peer List
Response to a Find Close Peers Request or a Peer List Request
| Field | Data Type | Description |
|-------|------------|-----------------------------------|
| TYPE | 1 byte | Value = 'L' |
| VER | 1 byte | Protocol version |
| NUMP | 2 bytes | Number of peers in the list |
| IDN1 | 384 bytes | Standart I2P identity |
| TYPE1 | 1 byte | Certificate type |
| LEN1 | 2 byte | Length of extra bytes DATA1 field |
| DATA1 | byte[] | Extra bytes |
| IDN2 | 384 bytes | Standart I2P identity |
| TYPE2 | 1 byte | Certificate type |
| LEN2 | 2 byte | Length of extra bytes DATA2 field |
| DATA2 | byte[] | Extra bytes |
| ... | ... | ... |
| IDNn | 384 bytes | Standart I2P identity |
| TYPEn | 1 byte | Certificate type |
| LENn | 2 byte | Length of extra bytes DATAn field |
| DATAn | byte[] | Extra bytes |
### 3.1.6 Directory Entry (Contact)
A name/Email Destination mapping
| Field | Data Type | Description |
|-------|------------|---------------------------------------------------------------|
| TYPE | 1 byte | Value = 'C' |
| VER | 1 byte | Protocol version |
| KEY | 32 bytes | DHT key (SHA-256 hash of the UTF8-encoded name in lower case) |
| DLEN | 2 bytes | Length of the DEST field |
| DEST | byte[] | Email destination, 8 bit encoded (not base64) |
| SALT | 4 bytes | A value such that scrypt(KEY|DEST|SALT) ends with a zero byte |
| PLEN | 2 bytes | Length of PIC, max 7500 |
| PIC | byte[] | User picture in a browser-compatible format (JPG, PNG, GIF) |
| COMP | 1 byte | Compression type_ for TEXT |
| 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.
### 3.2.1 Relay Request (not implemented)
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.
| Field | Data Type | Description |
|-------|------------|--------------------------------------------|
| 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 |
### 3.2.2 Relay Return Request (not implemented)
Contains a Return Chain and a payload_. The final destination is unknown to the sender or any of the hops. Used for responding to a relayed data Packet.
| Field | Data Type | Description |
|-------|------------|--------------------------------------------------------|
| 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. |
### 3.2.3 Return Chain (not implemented)
Not a Packet itself, but part of a Relay (Return) Request
| Field | Data Type | Description |
|-------|------------|--------------------------------------------------------------------|
| 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 |
### 3.2.4 Fetch Request (not implemented)
Request to a chain endpoint to retrieve an Index Packet or Email Packet.
| Field | Data Type | Description |
|-------|------------|------------------------------------------------------|
| PFX | 4 bytes | Packet prefix, must be 0x6D 0x30 0x52 0xE9 |
| TYPE | 1 byte | Value = '' |
| 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) |
### 3.2.5 Response Packet
Response to a Retrieve Request, Fetch Request, Find Close Peers Request, or a Peer List Request.
| Field | Data Type | Description |
|-------|------------|--------------------------------------------------|
| 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 (see below) |
| DLEN | 2 bytes | Length of the DATA field; can be 0 if no payload |
| DATA | byte[] | A Data Packet |
Status codes:
|Value | Description |
|------|------------------------------|
|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 |
### 3.2.6 Peer List Request
A request for a list of high-reachability relay peers.
| Field | Data Type | Description |
|-------|------------|--------------------------------------------|
| 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 |
## 3.3 DHT Communication Packets
### 3.3.1 Retrieve Request
A request to a peer to return a data item for a given DHT key and data type.
| Field | Data Type | Description |
|-------|------------|--------------------------------------------|
| 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 (see below) |
| KEY | 32 bytes | DHT key to look up |
Type of data to retrieve:
| Value | Type of data |
|-------|-----------------|
| 'I' | Index Packet |
| 'E' | Email Packet |
| 'C' | Directory Entry |
### 3.3.2 Deletion Query
A request to a peer to return a Deletion Info Packet for a given Email Packet DHT key. If the Email Packet is not known to be deleted, no response is expected back.
| Field | Data Type | Description |
|-------|------------|--------------------------------------------|
| PFX | 4 bytes | Packet prefix, must be 0x6D 0x30 0x52 0xE9 |
| TYPE | 1 byte | Value = 'Y' |
| VER | 1 byte | Protocol version |
| CID | 32 bytes | Correlation ID, used for responses |
| KEY | 32 bytes | DHT key to look up |
### 3.3.3 Store Request
DHT Store Request.
| Field | Data Type | Description |
|-------|------------|--------------------------------------------|
| 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. |
### 3.3.4 Email Packet Delete Request
Request to delete an Email Packet by DHT key
| Field | Data Type | Description |
|-------|------------|------------------------------------------------------------------|
| 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 packet) |
### 3.3.5 Index Packet Delete Request
Request to remove one or more entries (Email Packet keys) from an Index Packet.
| Field | Data Type | Description |
|-------|------------|-------------------------------------------------------------------------------------|
| 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) |
### 3.3.6 Find Close Peers
Request for k peers close to a key.
| Field | Data Type | Description |
|-------|------------|--------------------------------------------|
| 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 |
| KEY | 32 bytes | DHT key |

21
docs/devs/bote/v5/protocols.md → docs/docs/devs/bote/v5/protocols.md
View File

@ -1,4 +1,4 @@
# 4. Protocols
# 4. Protocols (DRAFT)
## 4.1. Storing a DHT item via relays
@ -15,10 +15,13 @@ I2P nodes involved: A=Sender, R1...Rn=Relays, S1...Sm=Storage Nodes
## 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.
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):
### (A)
The Packet is received. HOP1 through HOP3 contain encrypted data (encrypted with the public key for the receiving I2P node):
```
@ -37,7 +40,9 @@ Here is a simplified diagram of how a Relay Return Packet is sent from one hop t
KEYx denotes a layer of encryption.
```
### (B) The receiving node decrypts HOP1, HOP2, and HOP3. HOP1 is now in plain text. It contains thedestination of the next hop and an AES key.
### (B)
The receiving node decrypts HOP1, HOP2, and HOP3. HOP1 is now in plain text. It contains thedestination of the next hop and an AES key.
```
+------------------- Relay Return Request --------------------------+
@ -52,7 +57,9 @@ Here is a simplified diagram of how a Relay Return Packet is sent from one hop t
| |
+-------------------------------------------------------------------+
```
### (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:
### (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 --------------------------+
@ -68,7 +75,9 @@ Here is a simplified diagram of how a Relay Return Packet is sent from one hop t
+-------------------------------------------------------------------+
```
### (D) The Packet is sent to the next node in the chain.
### (D)
The Packet is sent to the next node in the chain.
## 4.3. Retrieving DHT items via relays (not implemented yet)

6
docs/devs/bote/v5/version5.md → docs/docs/devs/bote/v5/version5.md
View File

@ -1,7 +1,7 @@
# Protocol version 5
# Protocol version 5 (DRAFT)
At the moment, PeerList packets of 5th version have been implemented to support current types of I2P destination.
PeerList packets of 4th version are supported, older Java nodes respond but do not send requests due to protocol restrictions at DSA I2P destinations.
You can see the implementation details in [this](./packet_types.md) page.
You can see the implementation details in this section.
Proposals for improving the 5th version of the protocol are accepted for consideration.
Proposals for improving the 5th version of the protocol are accepted for consideration.

0
docs/devs/building/requirements.md → docs/docs/devs/building/requirements.md
View File

0
docs/devs/building/unix.md → docs/docs/devs/building/unix.md
View File

0
docs/index.md → docs/docs/index.md
View File

0
docs/tutorials/POP3.md → docs/docs/tutorials/POP3.md
View File

0
docs/tutorials/SMTP.md → docs/docs/tutorials/SMTP.md
View File

0
docs/tutorials/addressbook.md → docs/docs/tutorials/addressbook.md
View File

0
docs/user-guide/FAQ.md → docs/docs/user-guide/FAQ.md
View File

0
docs/user-guide/configuration.md → docs/docs/user-guide/configuration.md
View File

0
docs/user-guide/install.md → docs/docs/user-guide/install.md
View File

0
docs/user-guide/run.md → docs/docs/user-guide/run.md
View File

0
docs/user-guide/usage.md → docs/docs/user-guide/usage.md
View File

7
mkdocs.yml → docs/mkdocs.yml
View File

@ -4,6 +4,7 @@ site_description: pboted documentation
site_author: polistern
repo_url: https://github.com/polistern/pboted_docs
repo_name: polistern/pboted_docs
nav:
- Home: index.md
@ -47,19 +48,23 @@ nav:
- Contributing: about/contributing.md
- Donations: about/donations.md
copyright: <a href="https://creativecommons.org/licenses/by-sa/4.0/">CC-BY-SA 4.0</a>, Maintained by polistern
copyright: <a href="https://creativecommons.org/licenses/by-sa/4.0/">CC-BY-SA 4.0</a>, Maintained by <a href="https://github.com/polistern">polistern</a>
markdown_extensions:
- admonition
- pymdownx.details
- pymdownx.superfences
plugins:
- git-revision-date
theme:
name: 'material'
palette:
scheme: slate
primary: green
icon:
repo: fontawesome/brands/github
admonition:
note: octicons/tag-16
abstract: octicons/checklist-16

1
requirements.txt → docs/requirements.txt
View File

@ -1,5 +1,6 @@
pymdown-extensions==9.1
mkdocs==1.2.3
mkdocs-git-revision-date-plugin==0.3.1
mkdocs-material==7.3.6
mkdocs-material-extensions==1.0.3
mkdocs-windmill-dark==0.2.0