mirror of
https://github.com/simplex-chat/simplex-chat.git
synced 2025-06-28 12:19:54 +00:00
edit readme, add images and table of contents (#52)
* Edited text, added images and table of contents * readme corrections * change win command to forward slashes * readme corrections Co-authored-by: Evgeny Poberezkin <2769109+epoberezkin@users.noreply.github.com> Co-authored-by: Efim Poberezkin <8711996+efim-poberezkin@users.noreply.github.com>
This commit is contained in:
Mark Aleksander Hil
GitHub
parent
822c9bbd3a
commit
701e120e9a
4 changed files with 129 additions and 53 deletions
135
README.md
135
README.md
|
|
@ -1,56 +1,70 @@
|
|||
<img align="right" src="images/logo.svg" alt="SimpleX logo" height="90">
|
||||
|
||||
# SimpleX chat
|
||||
|
||||
## Federated, private, secure, decentralized
|
||||
|
||||
[](https://github.com/simplex-chat/simplex-chat/actions?query=workflow%3Abuild)
|
||||
[](https://github.com/simplex-chat/simplex-chat/releases)
|
||||
|
||||
## Federated chat - private, secure, decentralized
|
||||
SimpleX chat prototype is a thin terminal UI on top of [SimpleXMQ](https://github.com/simplex-chat/simplexmq) message broker that uses [SMP protocol](https://github.com/simplex-chat/simplexmq/blob/master/protocol/simplex-messaging.md) and [SMP agent protocol](https://github.com/simplex-chat/simplexmq/blob/master/protocol/agent-protocol.md).
|
||||
|
||||
See [simplex.chat](https://simplex.chat) website for chat demo and the explanations of the system and how SMP protocol works.
|
||||
|
||||
SimpleX chat prototype is a "thin" terminal UI on top of [SimpleXMQ](https://github.com/simplex-chat/simplexmq) message broker, that uses [SMP protocol](https://github.com/simplex-chat/simplexmq/tree/master/protocol) and SMP agent protocol.
|
||||
## Table of contents
|
||||
|
||||
- [Features](#features)
|
||||
- [Installation](#installation)
|
||||
- [Download chat client](#download-chat-client)
|
||||
- [Build from source](#build-from-source)
|
||||
- [Using Docker](#using-docker)
|
||||
- [Using Haskell stack](#using-haskell-stack)
|
||||
- [Usage](#usage)
|
||||
- [Running the chat client](#running-the-chat-client)
|
||||
- [How to use SimpleX chat](#how-to-use-simplex-chat)
|
||||
- [Access chat history](#access-chat-history)
|
||||
- [Roadmap](#roadmap)
|
||||
- [Disclaimer](#disclaimer)
|
||||
- [License](#license)
|
||||
|
||||
## Features
|
||||
|
||||
These features are implemented:
|
||||
- 1-to-1 chat with multiple people in the same terminal window.
|
||||
- auto-populated recipient name - just type your messages to reply to the sender.
|
||||
- default server is available to use - `smp1.simplex.im:5223` - you can deploy your own server (`smp-server` executable in [simplexmq](https://github.com/simplex-chat/simplexmq) repo).
|
||||
- no global identity or any names visible to the server(s) - for the full privacy of your contacts and conversations.
|
||||
- E2E encryption, with RSA public key that has to be passed out-of-band (see below).
|
||||
- message signing and verification with automatically generated RSA keys.
|
||||
- message integrity validation (via including the digests of the previous messages).
|
||||
- authentication of each command/message by SMP servers with automatically generated RSA key pairs.
|
||||
- Auto-populated recipient name - just type your messages to reply to the sender once the connection is established.
|
||||
- Demo SMP server available at `smp1.simplex.im:5223` - you can deploy your own server (`smp-server` executable in [simplexmq](https://github.com/simplex-chat/simplexmq) repo).
|
||||
- No global identity or any names visible to the server(s), ensuring full privacy of your contacts and conversations.
|
||||
- E2E encryption, with RSA public key that has to be passed out-of-band (see [How to use SimpleX chat](#how-to-use-simplex-chat)).
|
||||
- Message signing and verification with automatically generated RSA keys.
|
||||
- Message integrity validation (via including the digests of the previous messages).
|
||||
- Authentication of each command/message by SMP servers with automatically generated RSA key pairs.
|
||||
- TCP transport encryption using SMP transport protocol.
|
||||
|
||||
RSA keys are not used as identity, they are randomly generated for each contact. 2048 bit keys are used, it can be changed to 4096-bit in code via [rsaKeySize setting](https://github.com/simplex-chat/simplex-chat/blob/master/apps/dog-food/Main.hs).
|
||||
|
||||
The chat client is stable, but it is quite new and unaudited, so you probably should NOT use it yet for high security communications - unless you know what you are doing.
|
||||
## Installation
|
||||
|
||||
## SimpleX chat roadmap for 2021-22
|
||||
### Download chat client
|
||||
|
||||
1. Switch to application level chat protocol. This will allow to separate physical server connection management from logical chat contacts, and to support all common chat functions.
|
||||
2. SMP queue redundancy and rotation in SMP agent protocol.
|
||||
3. Symmetric groups support in SMP agent protocol, as a foundation for chat groups.
|
||||
4. Delivery confirmation in SMP agent protocol.
|
||||
5. Multi-agent/device data synchronisation - to use chat on multiple devices.
|
||||
6. Synchronous streams support in SMP and SMP agent protocols, to support file transfer.
|
||||
7. Terminal chat UI and mobile apps.
|
||||
8. Scripts for simple SMP server deployment to hosting providers: Linode, Digital Ocean and Heroku.
|
||||
9. Public broadcast channels.
|
||||
10. Optional public contact/group addresses using DNS to establish connections, but not using it to send and receive messages - in this way you will keep all your contacts and groups even if you lose the control of the domain.
|
||||
Download the chat binary for your system from the [latest stable release](https://github.com/simplex-chat/simplex-chat/releases) and make it executable as shown below.
|
||||
|
||||
## Installing the chat client
|
||||
#### Linux and MacOS
|
||||
|
||||
You can:
|
||||
- download the executable file built on Github CI
|
||||
- build it from source
|
||||
```sh
|
||||
chmod +x <binary>
|
||||
mv <binary> ~/.local/bin/dog-food
|
||||
```
|
||||
|
||||
### Downloading the executable chat client
|
||||
(or any other preferred location on PATH).
|
||||
|
||||
You can download the executable binary file for your platform from the [latest stable release](https://github.com/simplex-chat/simplex-chat/releases) and make it executable:
|
||||
On MacOS you also need to [allow Gatekeeper to run it](https://support.apple.com/en-us/HT202491).
|
||||
|
||||
- Linux and MacOS: `chmod +x <binary>; mv <binary> ~/.local/bin/dog-food` (or any other preferred location on PATH). On MacOS you need to [allow Gatekeeper to run it](https://support.apple.com/en-us/HT202491).
|
||||
- Windows: `move <binary> %APPDATA%\local\bin\dog-food.exe`.
|
||||
#### Windows
|
||||
|
||||
### Building from source
|
||||
```sh
|
||||
move <binary> %APPDATA%/local/bin/dog-food.exe
|
||||
```
|
||||
|
||||
### Build from source
|
||||
|
||||
#### Using Docker
|
||||
|
||||
|
|
@ -60,7 +74,6 @@ On Linux, you can build the chat executable using [docker build with custom outp
|
|||
$ git clone git@github.com:simplex-chat/simplex-chat.git
|
||||
$ cd simplex-chat
|
||||
$ DOCKER_BUILDKIT=1 docker build --output ~/.local/bin .
|
||||
$ dog-food
|
||||
```
|
||||
|
||||
> **Please note:** If you encounter ``version `GLIBC_2.28' not found`` error, rebuild it with `haskell:8.8.4-stretch` base image (change it in your local [Dockerfile](Dockerfile)).
|
||||
|
|
@ -79,14 +92,17 @@ and build the project:
|
|||
$ git clone git@github.com:simplex-chat/simplex-chat.git
|
||||
$ cd simplex-chat
|
||||
$ stack install
|
||||
$ dog-food
|
||||
```
|
||||
|
||||
## Running the chat client
|
||||
## Usage
|
||||
|
||||
Run `dog-food` (as in "eating your own dog food"), or the downloaded file (if you did not move it to bin folder), to start the chat client.
|
||||
### Running the chat client
|
||||
|
||||
By default, app data directory is created in the home directory (`~/.simplex`, or `%APPDATA%/simplex` on Windows), and SQLite database file `smp-chat.db` is initialized in it. The default SMP server is `smp1.simplex.im:5223#pLdiGvm0jD1CMblnov6Edd/391OrYsShw+RgdfR0ChA=` (base-64 encoded string after server port is the transport key digest) - it is pre-configured in the app.
|
||||
To start the chat client, run `dog-food` (as in [eating your own dog food](https://en.wikipedia.org/wiki/Eating_your_own_dog_food)) from the terminal.
|
||||
|
||||
By default, app data directory is created in the home directory (`~/.simplex`, or `%APPDATA%/simplex` on Windows), and SQLite database file `smp-chat.db` is initialized in it.
|
||||
|
||||
The default SMP server is `smp1.simplex.im#pLdiGvm0jD1CMblnov6Edd/391OrYsShw+RgdfR0ChA=` (base-64 encoded string after server host is the transport key digest) - it is pre-configured in the app.
|
||||
|
||||
To specify a different file path for the chat database use `-d` command line option:
|
||||
|
||||
|
|
@ -94,7 +110,7 @@ To specify a different file path for the chat database use `-d` command line opt
|
|||
$ dog-food -d my-chat.db
|
||||
```
|
||||
|
||||
If you deployed your own SMP server you can set client to use it via `-s` option:
|
||||
If you deployed your own SMP server(s) you can configure client via `-s` option:
|
||||
|
||||
```shell
|
||||
$ dog-food -s smp.example.com:5223#KXNE1m2E1m0lm92WGKet9CL6+lO742Vy5G6nsrkvgs8=
|
||||
|
|
@ -102,29 +118,25 @@ $ dog-food -s smp.example.com:5223#KXNE1m2E1m0lm92WGKet9CL6+lO742Vy5G6nsrkvgs8=
|
|||
|
||||
The base-64 encoded string in server address is the digest of RSA transport handshake key that the server will generate on the first run and output its digest.
|
||||
|
||||
You can still talk to people using default or any other server, it only affects the location of the message queue when you initiate the connection (and the reply queue can be on another server, as set by the other party's client).
|
||||
You can still talk to people using default or any other server - it only affects the location of the message queue when you initiate the connection (and the reply queue can be on another server, as set by the other party's client).
|
||||
|
||||
Run `dog-food --help` to see all available options.
|
||||
|
||||
## Using chat client
|
||||
### How to use SimpleX chat
|
||||
|
||||
Once chat client is started, use `/add <name1>` to create a new connection and generate an invitation to send to your contact via any other communication channel (`<name1>` - is any name you want to use for that contact).
|
||||
This diagram shows how to connect and message a contact:
|
||||
|
||||
Invitation has format `smp::<server>::<queue_id>::<rsa_public_key_for_this_queue_only>` - this needs to be shared with another party, via any other channel. This invitation can only be used once - even if this is intercepted, the attacker would not be able to use it to send you the messages via this queue once your contact confirms that the connection is established.
|
||||
<div align="center">
|
||||
<img align="center" src="images/how-to-use-simplex.svg">
|
||||
</div>
|
||||
|
||||
The party that received the invitation should use `/connect <name2> <invitation>` to accept the connection (`<name2>` is any name that the accepting party wants to use for you).
|
||||
Once you have started the chat, use `/add <name1>` to create a new connection and generate an invitation (`<name1>` is any name you want to use for that contact). The add command will output an invitation. Send this invitation to your contact via any other channel.
|
||||
|
||||
For example, if Alice and Bob want to chat, with Alice initiating, Alice would use [in her chat client]:
|
||||
The invitation has the format `smp::<server>::<queue_id>::<rsa_public_key_for_this_queue_only>`. The invitation can only be used once and even if this is intercepted, the attacker would not be able to use it to send you the messages via this queue once your contact confirms that the connection is established.
|
||||
|
||||
```
|
||||
/add bob
|
||||
```
|
||||
The contact who received the invitation should use `/connect <name2> <invitation>` to accept the connection (`<name2>` is any name that the accepting contact wants to use for you).
|
||||
|
||||
And then send the generated invitation to Bob out-of-band. Bob then would use [in his chat client]:
|
||||
|
||||
```
|
||||
/connect alice <alice's invitation>
|
||||
```
|
||||
Once the contact has used the `/connect` command, a connection is established and both parties are notified.
|
||||
|
||||
They would then use `@<name> <message>` commands to send messages. One may also press Space or just start typing a message to send a message to the contact that was the last.
|
||||
|
||||
|
|
@ -132,9 +144,9 @@ If your contact is disconnected, restart the chat client - it may happen if you
|
|||
|
||||
Use `/help` in chat to see the list of available commands.
|
||||
|
||||
## Accessing chat history
|
||||
### Access chat history
|
||||
|
||||
SimpleX chat stores all your contacts and conversations in the local database file, making it private and portable by design, fully owned and controlled by you.
|
||||
SimpleX chat stores all your contacts and conversations in a local database file, making it private and portable by design, fully owned and controlled by you.
|
||||
|
||||
You can search your chat history via SQLite database file:
|
||||
|
||||
|
|
@ -153,6 +165,23 @@ order by internal_id desc;
|
|||
|
||||
> **Please note:** SQLite foreign key constraints are disabled by default, and must be **[enabled separately for each database connection](https://sqlite.org/foreignkeys.html#fk_enable)**. The latter can be achieved by running `PRAGMA foreign_keys = ON;` command on an open database connection. By running data altering queries without enabling foreign keys prior to that, you may risk putting your database in an inconsistent state.
|
||||
|
||||
## Roadmap
|
||||
|
||||
1. Switch to application level chat protocol. This will allow to separate physical server connection management from logical chat contacts, and to support all common chat functions.
|
||||
2. SMP queue redundancy and rotation in SMP agent protocol.
|
||||
3. Symmetric groups support in SMP agent protocol, as a foundation for chat groups.
|
||||
4. Delivery confirmation in SMP agent protocol.
|
||||
5. Multi-agent/device data synchronisation - to use chat on multiple devices.
|
||||
6. Synchronous streams support in SMP and SMP agent protocols, to support file transfer.
|
||||
7. Terminal chat UI and mobile apps.
|
||||
8. Scripts for simple SMP server deployment to hosting providers: Linode, Digital Ocean and Heroku.
|
||||
9. Public broadcast channels.
|
||||
10. Optional public contact/group addresses using DNS to establish connections, but not using it to send and receive messages - in this way you will keep all your contacts and groups even if you lose the control of the domain.
|
||||
|
||||
## Disclaimer
|
||||
|
||||
System and protocol security have not been audited yet. As such, it is not advised to use SimpleX chat for high security communications.
|
||||
|
||||
## License
|
||||
|
||||
[AGPL v3](./LICENSE)
|
||||
|
|
|
|||
32
images/how-to-use-simplex.svg
Normal file
32
images/how-to-use-simplex.svg
Normal file
File diff suppressed because one or more lines are too long
|
After Width: | Height: | Size: 376 KiB |
12
images/logo.svg
Normal file
12
images/logo.svg
Normal file
|
|
@ -0,0 +1,12 @@
|
|||
<svg width="815" height="233" viewBox="0 0 815 233" fill="none" xmlns="http://www.w3.org/2000/svg">
|
||||
<g clip-path="url(#clip0)">
|
||||
<path fill-rule="evenodd" clip-rule="evenodd" d="M40.5683 66.9141C43.9954 66.9141 47.376 67.2323 50.7104 67.8687C54.0448 68.5051 57.2403 69.3234 60.2968 70.3235C63.3533 71.3236 66.2014 72.4601 68.8411 73.7329C71.4809 75.0058 73.9122 76.2786 76.1351 77.5515L66.132 96.0987L65.9952 95.9474C65.6001 95.5596 64.6732 94.9282 63.2144 94.0531C61.5472 93.053 59.4632 92.0074 56.9624 90.9164C54.4616 89.8254 51.7293 88.8708 48.7654 88.0525C45.8015 87.2342 42.8376 86.8251 39.8737 86.8251C31.723 86.8251 27.6476 89.5072 27.6476 94.8713C27.6476 96.5079 28.0876 97.8716 28.9675 98.9627C29.8474 100.054 31.1441 101.031 32.8576 101.895C34.5711 102.758 36.7245 103.554 39.318 104.281C41.9114 105.009 44.9216 105.827 48.3486 106.736C53.0723 108.009 57.3329 109.395 61.1304 110.896C64.9279 112.396 68.1465 114.26 70.7862 116.487C73.4259 118.715 75.4636 121.419 76.8993 124.602C78.3349 127.784 79.0527 131.602 79.0527 136.057C79.0527 141.512 78.0107 146.126 75.9267 149.899C73.8427 153.673 71.0872 156.718 67.6602 159.037C64.2332 161.355 60.2968 163.037 55.8509 164.083C51.4051 165.128 46.8203 165.651 42.0966 165.651C38.4844 165.651 34.7795 165.378 30.982 164.833C27.1845 164.287 23.4796 163.492 19.8674 162.446C16.2551 161.401 12.7587 160.15 9.37796 158.696C5.99726 157.241 2.87128 155.559 0 153.65L10.0032 134.148L10.1812 134.338C10.6877 134.825 11.8324 135.625 13.6154 136.739C15.6531 138.012 18.177 139.285 21.1872 140.558C24.1974 141.83 27.555 142.967 31.2599 143.967C34.9647 144.967 38.7159 145.467 42.5134 145.467C50.5715 145.467 54.6006 143.058 54.6006 138.239C54.6006 136.421 53.9985 134.921 52.7944 133.739C51.5903 132.557 49.9231 131.489 47.7928 130.534C45.6625 129.579 43.1386 128.693 40.221 127.875C37.3034 127.056 34.1311 126.147 30.7041 125.147C26.1657 123.783 22.2292 122.306 18.8948 120.715C15.5605 119.124 12.805 117.283 10.6284 115.192C8.45174 113.1 6.83086 110.691 5.76571 107.964C4.70056 105.236 4.16798 102.054 4.16798 98.4171C4.16798 93.3257 5.14051 88.8253 7.08557 84.9158C9.03063 81.0063 11.6703 77.7106 15.0047 75.0285C18.3391 72.3464 22.2061 70.3235 26.6056 68.9597C31.0051 67.5959 35.6594 66.9141 40.5683 66.9141ZM131.47 67.7323V164.56H108.685V67.7323H131.47ZM191.39 67.7323L216.954 118.328L242.657 67.7323H267.248V164.56H244.463V106.6L223.067 148.74H210.841L189.445 106.6V164.56H166.66V67.7323H191.39ZM419.925 67.7323V144.922H467.718V164.56H397.14V67.7323H419.925ZM560.072 67.7323V87.3706H514.78V106.191H553.681V124.329H514.78V144.922H561.323V164.56H491.995V67.7323H560.072ZM341.818 67.7323L343.378 67.7677C347.5 67.9563 351.31 68.8991 354.809 70.5962C358.745 72.5055 362.126 75.0058 364.951 78.097C367.776 81.1882 369.999 84.6885 371.62 88.598C373.24 92.5075 374.051 96.4624 374.051 100.463C374.051 104.736 373.287 108.827 371.758 112.737C370.23 116.646 368.1 120.147 365.368 123.238C362.635 126.329 359.324 128.784 355.434 130.602C351.976 132.218 348.189 133.116 344.072 133.296L342.513 133.33H322.507V164.56H299.722V67.7323H341.818ZM340.29 87.3706H322.507V113.828H341.124C343.81 113.828 346.125 112.691 348.07 110.418C350.016 108.145 350.988 104.827 350.988 100.463C350.988 98.1898 350.687 96.2351 350.085 94.5986C349.483 92.9621 348.672 91.5983 347.654 90.5073C346.635 89.4163 345.477 88.6207 344.18 88.1207C342.884 87.6206 341.587 87.3706 340.29 87.3706Z" fill="#062D56"/>
|
||||
<path fill-rule="evenodd" clip-rule="evenodd" d="M642.628 136.08L680.309 173.782L699.513 154.567L699.506 154.561L737.917 116.134L700.236 78.4367L700.243 78.4334L681.404 59.5826L642.993 98.014L642.99 98.0104L681.401 59.5829L643.725 21.881L662.929 2.6652L700.605 40.3673L739.016 1.93511L757.855 20.7859L719.443 59.2176L757.121 96.918L795.533 58.4875L814.373 77.3382L775.959 115.768L813.643 153.471L794.439 172.687L756.756 134.984L718.348 173.415L756.031 211.119L736.827 230.335L699.144 192.63L660.74 231.065L641.901 212.214L680.306 173.78L642.625 136.083L642.628 136.08Z" fill="#07B4B9"/>
|
||||
<path fill-rule="evenodd" clip-rule="evenodd" d="M604.77 59.7651L642.446 97.4664L680.856 59.035L699.696 77.8858L661.285 116.317L698.966 154.019L679.762 173.235L642.081 135.532L603.675 173.965L584.836 155.114L623.243 116.682L585.566 78.9809L604.77 59.7651Z" fill="#062D56"/>
|
||||
</g>
|
||||
<defs>
|
||||
<clipPath id="clip0">
|
||||
<rect width="815" height="233" fill="white"/>
|
||||
</clipPath>
|
||||
</defs>
|
||||
</svg>
|
||||
|
After Width: | Height: | Size: 4.3 KiB |
3
images/strapline.svg
Normal file
3
images/strapline.svg
Normal file
File diff suppressed because one or more lines are too long
|
After Width: | Height: | Size: 23 KiB |
Loading…
Add table
Add a link
Reference in a new issue