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

Update pages.

main
polistern 2021-11-16 17:44:09 +00:00
parent 2ccd6b3a72
commit 15193abb9b
11 changed files with 221 additions and 147 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docs/devs/bote/v5/cryptography.md
View File

@ -4,7 +4,7 @@
Supported encryption and signature algorithms:
* ALG=1: ElGamal-2048 / DSA-1024 / AES-256 / SHA-256 (same as the I2P router uses)
* ALG=1: ElGamal-2048 / DSA-1024 / AES-256 / SHA-256
* ALG=2: ECDH-256 / ECDSA-256 / AES-256 / SHA-256
* ALG=3: ECDH-521 / ECDSA-521 / AES-256 / SHA-512
* ALG=4: NTRUEncrypt-1087 / GMSS-512 / AES-256 / SHA-512

27
docs/devs/bote/v5/introduction.md
View File

@ -1,22 +1,11 @@
# 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.
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.
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 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.
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:
@ -69,9 +58,8 @@ Below is a diagram of how an email Packet is routed from a sender to a recipient
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:
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:
```
.--------.
@ -101,5 +89,4 @@ and recipient chose not to use relays, the diagram looks like this:
`-----------'
```
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)
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)).

6
docs/devs/bote/v5/kademlia.md
View File

@ -6,7 +6,11 @@ The Kademlia implementation used by I2P-Bote differs from standard Kademlia in s
* 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: Email Packets, Index Packets, and Contacts.
There are three types of data that is stored in the DHT:
* Email Packets
* Index Packets
* Contacts
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.

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

@ -1,16 +1,16 @@
# 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.
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
**E** denotes encrypted data.
For supported encryption and signature algorithms, see [7.1](cryptography.md)
```
Packet Type | Field | Data Type | Description

15
docs/tutorials/POP3.md
View File

@ -0,0 +1,15 @@
# POP3
To be able to receive email through POP3 you need to:
- Fill [pop3] section in configuration file:
```
[pop3]
enabled = true
address = 127.0.0.1
port = 110
```
- Restart the **pboted** to apply the settings
- After loading, you be able to connect to the specified POP3 port manually or with your mail client.

15
docs/tutorials/SMTP.md
View File

@ -0,0 +1,15 @@
# SMTP
To be able to send email through SMTP you need to:
- Fill [smtp] section in configuration file:
```
[smtp]
enabled = true
address = 127.0.0.1
port = 25
```
- Restart the **pboted** to apply the settings
- After loading, you be able to connect to the specified SMTP port manually or with your mail client.

8
docs/tutorials/addressbook.md
View File

@ -4,7 +4,7 @@ This feature allows you to use short names when forming letters by third-party a
## Usage
First you need to fill in file addressbook.txt in pboted data directory (usually it is /var/lib/pboted).
First you need to fill in file `addressbook.txt` in pboted data directory (usually it is `/var/lib/pboted`).
For example:
```
@ -24,8 +24,8 @@ root@localhost;root;7uI3bOBph5pUAgVT5MWxg8lFPYvT2O6LpPVUHL-Sqdl24noEIMPvV9CEwrSW
!!! warning "Warning"
Do not edit this file while pboted is running as it will be overwritten.
Do not edit addressbook.txt file while pboted is running as it will be overwritten.
When you're done filling out the addressbook.txt file, start the **pboted**.
When you're done filling out the `addressbook.txt` file, start the **pboted**.
Now you able to use aliases in your TO field in application.
Now you able to use aliases in your TO field in application.

172
docs/user-guide/configuration.md
View File

@ -1,127 +1,69 @@
# Configuration
## The pboted needs I2P router
## Available options
- Install and run i2pd
- Enable SAM API in i2pd. Edit in i2pd.conf:
Run `pboted --help` to show builtin help message (default value of option will be shown in braces).
### General options
| Option | Description |
|------------|------------------------------------|
| conf | Config file (default: ~/.pboted/pboted.conf or /etc/pboted/pboted.conf). This parameter will be silently ignored if the specified config file does not exist. |
| pidfile | Where to write pidfile (default: pboted.pid) |
| daemon | pboted will go to background after start |
| service | pboted will use system folders like '/var/lib/pboted' |
| log | Logs destination: stdout, file, syslog (stdout if not set or invalid) (if daemon, stdout/unspecified are replaced by file in some cases) |
| logfile | Path to logfile (default - autodetect) |
| loglevel | Log messages above this level (debug, info, warn, error, none; default - info) |
| logclftime | Write full CLF-formatted date and time to log (default: write only time) |
| host | pboted external IP for incoming connections |
| port | UDP port to listen for incoming connections |
!!! note "Note"
`datadir` and `service` options are only used as arguments for pboted, these options have no effect when set in `pboted.conf`.
### SAM
| Option | Description |
|-------------|--------------------------------------|
| sam.name | If SAM is enabled. true by default |
| sam.address | I2P SAM address (default: 127.0.0.1) |
| sam.tcp | I2P SAM TCP port (default: 7656) |
| sam.udp | I2P SAM UDP port (default: 7655) |
|
### Bootstrap
| Option | Description |
|-------------------|------------------------------------|
| bootstrap.address | These are the nodes with high uptime and the most information about peers in the network. To get started, you need at least one node that supports protocol version 4 or higher. Each line should be a I2P destination key in Base64 format. |
You can specify this parameter multiple times with different addresses.
For example:
```
[sam]
enabled = true
[bootstrap]
address = <first address>
address = <second address>
...
address = <N-th address>
```
- Restart i2pd
- Local TCP port 7656 and UDP port 7655 should be available
## User service configuration
- Copy example config from `contrib/pboted.conf` to `~/.pboted/pboted.conf`:
```
cp contrib/pboted.conf ~/.pboted/pboted.conf`
```
- Edit the config to suit your needs. The file is well documented, comments will help you.
- Now you can run application:
```
./pboted --conf ~/.pboted/pboted.conf
```
## Unix daemon configuration [recommended]
- Create `/etc/pboted` directory:
```
sudo mkdir /etc/pboted
```
- Copy example config from `contrib/pboted.conf` to `~/.pboted/pboted.conf`:
```
sudo cp contrib/pboted.conf /etc/pboted/pboted.conf`
```
- Edit the config to suit your needs. The file is well documented, comments will help you.
- Create user, data and logs directories:
```
sudo useradd pboted -r -s /usr/sbin/nologin
sudo mkdir /var/lib/pboted
sudo chown -R pboted: /var/lib/pboted
sudo mkdir /var/log/pboted
sudo chown -R pboted: /var/log/pboted
```
- Copy example systemd service from `contrib/pboted.service` to `/lib/systemd/system/pboted.service`:
```
sudo cp contrib/pboted.service /lib/systemd/system/pboted.service`
```
- Reload daemons configuration and start unit:
```
sudo systemctl daemon-reload
sudo systemctl start pboted.service
```
- Now you can see in log files that all works. Also, you can see the status of the SAM session in the I2P Router console.
# Usage
You may need the utilities from the `utils` directory to work with **pboted**.
In the future, their list will grow.
There are plans to transfer all means for interaction into a separate CLI utility.
You can only continue to use your Java I2P-Bote identities if:
- your address is created using the ECDH-256/ECDSA-256/AES-256/SHA-256 algorithm (others are not supported yet)
- identities file is not encrypted (encrypted files are not supported yet)
## Sending email
### SMTP
To be able to send email through SMTP you need to:
- Fill [smtp] section in configuration file:
```
[smtp]
enabled = true
address = 127.0.0.1
port = 25
```
- Restart the **pboted** to apply the settings
- After loading, you be able to connect to the specified SMTP port manually or with your mail client
### Via `outbox` directory
- Prepare plain test message
- Format it with `message_formatter`
- Put result file to `outbox` directory in pboted working directory
- pboted will automatically check `outbox` and send email
- After sending email file will be moved to `sent` directory
## Receiving email
After starting with a generated identity the application will begin its normal job of searching for mail.
If mail for identity are found, they will be placed in the `inbox` directory.
| Option | Description |
|--------------|------------------------------------------|
| smtp.enabled | Allow connect via SMTP (default: true). |
| smtp.address | SMTP listen address (default: 127.0.0.1) |
| smtp.port | SMTP listen TCP port (default: 25) |
### POP3
To be able to receive email through POP3 you need to:
- Fill [pop3] section in configuration file:
```
[pop3]
enabled = true
address = 127.0.0.1
port = 110
```
- Restart the **pboted** to apply the settings
- After loading, you be able to connect to the specified POP3 port manually or with your mail client.
| Option | Description |
|--------------|------------------------------------------|
| pop3.enabled | Allow connect via POP3 (default: true). |
| pop3.address | POP3 listen address (default: 127.0.0.1) |
| pop3.port | POP3 listen port (default: 110) |

69
docs/user-guide/run.md
View File

@ -0,0 +1,69 @@
# Running
## The pboted needs I2P router
- Install and run i2pd
- Enable SAM API in i2pd. Edit in `i2pd.conf`:
```
[sam]
enabled = true
```
- Restart i2pd
- Local TCP port 7656 and UDP port 7655 should be available
## Recommended way to run pboted built from source
- Create `/etc/pboted` directory:
```
sudo mkdir /etc/pboted
```
- Copy example config from `contrib/pboted.conf` to `~/.pboted/pboted.conf`:
```
sudo cp contrib/pboted.conf /etc/pboted/pboted.conf`
```
- Edit the config to suit your needs. The file is well documented, comments will help you.
- Create user, data and logs directories:
```
sudo useradd pboted -r -s /usr/sbin/nologin
sudo mkdir /var/lib/pboted
sudo chown -R pboted: /var/lib/pboted
sudo mkdir /var/log/pboted
sudo chown -R pboted: /var/log/pboted
```
- Copy example systemd service from `contrib/pboted.service` to `/lib/systemd/system/pboted.service`:
```
sudo cp contrib/pboted.service /lib/systemd/system/pboted.service`
```
- Reload daemons configuration and start unit:
```
sudo systemctl daemon-reload
sudo systemctl start pboted.service
```
- Now you can see in log files that all works. Also, you can see the status of the SAM session in the I2P Router console.
## User service configuration
- Copy example config from `contrib/pboted.conf` to `~/.pboted/pboted.conf`:
```
cp contrib/pboted.conf ~/.pboted/pboted.conf`
```
- Edit the config to suit your needs. The file is well documented, comments will help you.
- Now you can run application:
```
./pboted --conf ~/.pboted/pboted.conf
```

41
docs/user-guide/usage.md 100644
View File

@ -0,0 +1,41 @@
# Usage
You may need the utilities from the `utils` directory to work with **pboted**.
In the future, their list will grow.
There are plans to transfer all means for interaction into a separate CLI utility.
You can only continue to use your Java I2P-Bote identities if:
- your address is created using the ECDH-256/ECDSA-256/AES-256/SHA-256 algorithm (others are not supported yet)
- identities file is not encrypted (encrypted files are not supported yet)
## Sending email
### SMTP
To be able to send email through SMTP you need to:
- Fill `[smtp]` section in configuration file with [parameters](configuration.md)
- Restart the **pboted** to apply the settings
- After loading, you be able to connect to the specified SMTP port manually or with your mail client
### Via `outbox` directory
- Prepare plain test message
- Format it with `message_formatter`
- Put result file to `outbox` directory in pboted working directory
- pboted will automatically check `outbox` and send email
- After sending email file will be moved to `sent` directory
## Receiving email
After starting with a generated identity the application will begin its normal job of searching for mail.
If mail for identity are found, they will be placed in the `inbox` directory.
### POP3
To be able to receive email through POP3 you need to:
- Fill [pop3] section in configuration file with [parameters](configuration.md)
- Restart the **pboted** to apply the settings
- After loading, you be able to connect to the specified POP3 port manually or with your mail client.

1
mkdocs.yml
View File

@ -11,6 +11,7 @@ nav:
- Installing: user-guide/install.md
- Running: user-guide/run.md
- Configuring: user-guide/configuration.md
- Usage: user-guide/usage.md
- FAQ: user-guide/FAQ.md
- Tutorials:
- AddressBook: tutorials/addressbook.md