From 8e4c6dd2db3e9c83171ccadbc8e324d69ef61a62 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Roman=20Smr=C5=BE?= Date: Sat, 10 Feb 2024 22:52:48 +0100 Subject: Add README file --- README.md | 121 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ erebos.cabal | 4 ++ 2 files changed, 125 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..22d6c82 --- /dev/null +++ b/README.md @@ -0,0 +1,121 @@ +Erebos +====== + +The erebos binary provides simple CLI interface to the decentralized Erebos +messaging service. Local identity is created on the first run. + +Erebos identity is based on locally stored cryptographic keys, all +communication is end-to-end encrypted. Multiple devices can be attached to the +same identity, after which they function interchangeably, without any one being +in any way "primary"; messages and other state data are then synchronized +automatically whenever the devices are able to connect with one another. + +Usage +----- + +On the first run, local identity will be created for this device based on +interactive prompts for: + +`Name:` name of the user/owner, which will be shared among all devices +belonging to the same user; keep empty when initializing device that is going +to be attached to already existing identity on other device. + +`Device:` name describing current device, can be empty. + +After the initial setup, the erebos tool presents interactive prompt for +messages and commands. All commands start with the slash (`/`) character, +followed by command name and parameters (if any) separated by spaces. When a +peer or contact is selected, message to send him can be entered directly on the +command prompt. + +### Messaging + +`/peers` +List peers with direct network connection. Peers are discovered automatically +on local network or can be manually added. + +`/contacts` +List known contacts (see below). + +`/` +Select contact or peer `` based on previous `/contacts` or `/peers` +output list. + +`` +Send `` to selected contact. + +`/history` +Show message history for selected contact or peer. + +### Add contacts + +To ensure the identity of the contact and prevent man-in-the-middle attack, +generated verification code needs to be confirmed on both devices to add +contacts to contact list (similar to bluetooth device pairing). Before adding +new contact, list peers using `/peers` command and select one with `/`. + +`/contacts` +List already added contacts. + +`/contact-add` +Add selected peer as contact. Six-digit verification code will be computed +based on peer keys, which will be displayed on both devices and needs to be +checked that both numbers are same. After that it needs to be confirmed using +`/contact-accept` to finish the process. + +`/contact-accept` +Confirm that displayed verification codes are same on both devices and add the +selected peer as contact. The side, which did not initiate the contact adding +process, needs to select the corresponding peer with `/` command first. + +`/contact-reject` +Reject contact request or verification code of selected peer. + +### Attach other devices + +Multiple devices can be attached to single identity to be used by the same +user. After the attachment process completes the roles of the devices are +equivalent, both can send and receive messages independently and those +messages, along with any other sate data, are synchronized automatically +whenever the devices can connect to each other. + +The attachment process and underlying protocol is very similar to the contact +adding described above, so also generates verification code based on peer keys +that needs to be checked and confirmed on both devices to avoid potential +man-in-the-middle attack. + +Before attaching device, list peers using `/peers` command and select the +target device with `/`. + +`/attach` +Attach current device to the selected peer. After the process completes the +owner of the selected peer will become owner of this device as well. Six-digit +verification code will be displayed on both devices and the user needs to check +that both are the same before confirmation using the `/attach-accept` command. + +`/attach-accept` +Confirm that displayed verification codes are same on both devices and complete +the attachment process (or wait for the confirmation on the peer device). The +side, which did not initiate the attachment process, needs to select the +corresponding peer with `/` command first. + +`/attach-reject` +Reject device attachment request or verification code of selected peer. + +### Other + +`/peer-add []` +Manually add network peer with given hostname or IP address. + +`/update-identity` +Interactively update current identity information + + +Storage +------- + +Data are by default stored within `.erebos` subdirectory of the current working +directory. This can be overriden by `EREBOS_DIR` environment variable. + +Private keys are currently stored in plaintext under the `keys` subdirectory of +the erebos directory. diff --git a/erebos.cabal b/erebos.cabal index 93051b5..8cd2143 100644 --- a/erebos.cabal +++ b/erebos.cabal @@ -14,6 +14,8 @@ Description: one being in any way "primary"; messages and other state data are then synchronized automatically whenever the devices are able to connect with one another. + . + See README for usage of the CLI tool. License: BSD-3-Clause License-File: LICENSE Homepage: http://erebosprotocol.net @@ -22,6 +24,8 @@ Maintainer: roman.smrz@seznam.cz Category: Network Stability: experimental Build-type: Simple +Extra-Doc-Files: + README.md Extra-Source-Files: src/Erebos/ICE/pjproject.h -- cgit v1.2.3