diff --git a/docs/devs/bote/v5/cryptography.md b/docs/devs/bote/v5/cryptography.md index 31a3b8a..2f2e2bb 100644 --- a/docs/devs/bote/v5/cryptography.md +++ b/docs/devs/bote/v5/cryptography.md @@ -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 diff --git a/docs/devs/bote/v5/introduction.md b/docs/devs/bote/v5/introduction.md index 8fc548b..a91a1f7 100644 --- a/docs/devs/bote/v5/introduction.md +++ b/docs/devs/bote/v5/introduction.md @@ -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)). diff --git a/docs/devs/bote/v5/kademlia.md b/docs/devs/bote/v5/kademlia.md index 1dd43ce..048d9dc 100644 --- a/docs/devs/bote/v5/kademlia.md +++ b/docs/devs/bote/v5/kademlia.md @@ -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. diff --git a/docs/devs/bote/v5/packet_types.md b/docs/devs/bote/v5/packet_types.md index 067760f..c002d8e 100644 --- a/docs/devs/bote/v5/packet_types.md +++ b/docs/devs/bote/v5/packet_types.md @@ -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 diff --git a/docs/tutorials/POP3.md b/docs/tutorials/POP3.md index e69de29..babfcff 100644 --- a/docs/tutorials/POP3.md +++ b/docs/tutorials/POP3.md @@ -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. diff --git a/docs/tutorials/SMTP.md b/docs/tutorials/SMTP.md index e69de29..d08b633 100644 --- a/docs/tutorials/SMTP.md +++ b/docs/tutorials/SMTP.md @@ -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. diff --git a/docs/tutorials/addressbook.md b/docs/tutorials/addressbook.md index 27a2d56..82bfe8c 100644 --- a/docs/tutorials/addressbook.md +++ b/docs/tutorials/addressbook.md @@ -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. diff --git a/docs/user-guide/configuration.md b/docs/user-guide/configuration.md index 26b0cf0..c0b5962 100644 --- a/docs/user-guide/configuration.md +++ b/docs/user-guide/configuration.md @@ -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 = +address = +... +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) | diff --git a/docs/user-guide/run.md b/docs/user-guide/run.md index e69de29..50ad1e2 100644 --- a/docs/user-guide/run.md +++ b/docs/user-guide/run.md @@ -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 +``` diff --git a/docs/user-guide/usage.md b/docs/user-guide/usage.md new file mode 100644 index 0000000..cb21d95 --- /dev/null +++ b/docs/user-guide/usage.md @@ -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. diff --git a/mkdocs.yml b/mkdocs.yml index e5aaadb..058f569 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -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