tomato/README.md

174 lines
6.9 KiB
Markdown
Raw Normal View History

# ![Project Tox](https://raw.github.com/TokTok/c-toxcore/master/other/tox.png "Project Tox")
**Current Coverage:** [![coverage](https://codecov.io/gh/TokTok/c-toxcore/branch/master/graph/badge.svg?token=BRfCKo02De)](https://codecov.io/gh/TokTok/c-toxcore)
[**Website**](https://tox.chat) **|** [**Wiki**](https://wiki.tox.chat/) **|** [**Blog**](https://blog.tox.chat/) **|** [**FAQ**](https://wiki.tox.chat/doku.php?id=users:faq) **|** [**Binaries/Downloads**](https://tox.chat/download.html) **|** [**Clients**](https://wiki.tox.chat/doku.php?id=clients) **|** [**Compiling**](/INSTALL.md)
## What is Tox
Tox is a peer to peer (serverless) instant messenger aimed at making security
and privacy easy to obtain for regular users. It uses
[NaCl](https://nacl.cr.yp.to/) for its encryption and authentication.
## IMPORTANT!
### ![Danger: Experimental](other/tox-warning.png)
This is an **experimental** cryptographic network library. It has not been
formally audited by an independent third party that specializes in
cryptography or cryptanalysis. **Use this library at your own risk.**
The underlying crypto library [NaCl](https://nacl.cr.yp.to/install.html)
provides reliable encryption, but the security model has not yet been fully
specified. See [issue 210](https://github.com/TokTok/c-toxcore/issues/210) for
a discussion on developing a threat model. See other issues for known
weaknesses (e.g. [issue 426](https://github.com/TokTok/c-toxcore/issues/426)
describes what can happen if your secret key is stolen).
## Toxcore Development Roadmap
The roadmap and changelog are generated from GitHub issues. You may view them
on the website, where they are updated at least once every 24 hours:
- Changelog: https://toktok.ltd/changelog/c-toxcore
- Roadmap: https://toktok.ltd/roadmap/c-toxcore
## Installing toxcore
Detailed installation instructions can be found in [INSTALL.md](INSTALL.md).
Squashed 'external/toxcore/c-toxcore/' changes from d4b06edc2a..adbd5b32d8 adbd5b32d8 feat: add ngc events 15ee46d431 add simple test for max sized lossy custom group packet 01e7950c67 increase lossy custom packet size in ngc to the toxcore common max of 1373 9b3c1089f1 Make group saving/loading more forgiving with data errors 55a76003b0 Replace memset(int32_t*, -1, _) with a for-loop 66453439ac fix: also Install header for private/experimental API functions with autotools 3983369103 fix: Enable debug flag for ubsan. 4d1db21102 Update tox-boostrapd hash e700c31b70 Fix memory leak in group connection 2994441d9c Fix memory leak in save-generator d0400df13d Fix memory leak in tox-bootstrapd 7a6d50ebe3 Install header for private/experimental API functions d89677fb5f Remove defunct IRC channel from README.md 26d41fc604 Replace DEFAULT_TCP_RELAY_PORTS_COUNT with a compile-time calculation 63fb2941ca Clarify disabling of static assert checks 65b3375b98 refactor: Use Bin_Pack for packing Node_format. 84ba154f6a group connection queries now return our own connection type a4df2862ed Replace tabs with spaces 1b6dee7594 Update tox-bootstrapd's base Docker images a030cdee5c Fix Docker tox-bootstrapd hash update failing when using BuildKit 7cfe35dff2 cleanup: Remove explicit layering_check feature. d390947245 chore: Upgrade sonar-scan jvm to java 17. d1e850c56c fix: Add missing `htons` call when adding configured TCP relay. 814090f2b8 chore: Cancel old PR builds on docker and sonar-scan workflows. 83efb17367 perf: Add a KVM FreeBSD build on cirrus ci. a927183233 test: Add a test for encrypting 100MB of data. 28f39049f6 chore: Retry freebsd tests 2 times. 47e77d1bb0 chore: Use C99 on MSVC instead of C11. 7155f7f60e test: Add an s390x build (on alpine) for CI. 6c35cef63f chore: Add a compcert docker run script. 41e6ea865e cleanup: Use tcc docker image for CI. e726b197b0 refactor: Store time in Mono_Time in milliseconds. REVERT: d4b06edc2a feat: add ngc events git-subtree-dir: external/toxcore/c-toxcore git-subtree-split: adbd5b32d85d9c13800f5ece17c0a9dce99faacd
2023-12-15 15:21:40 +01:00
Be advised that due to the addition of `cmp` as a submodule, you now also need to initialize the git submodules required by toxcore. This can be done by cloning the repo with the following command: `git clone --recurse-submodules https://github.com/Toktok/c-toxcore` or by running `git submodule update --init` in the root directory of the repo.
In a nutshell, if you have [libsodium](https://github.com/jedisct1/libsodium)
installed, run:
```sh
mkdir _build && cd _build
cmake ..
make
sudo make install
```
If you have [libvpx](https://github.com/webmproject/libvpx) and
[opus](https://github.com/xiph/opus) installed, the above will also build the
A/V library for multimedia chats.
## Using toxcore
The simplest "hello world" example could be an echo bot. Here we will walk
through the implementation of a simple bot.
### Creating the tox instance
All toxcore API functions work with error parameters. They are enums with one
`OK` value and several error codes that describe the different situations in
which the function might fail.
```c
TOX_ERR_NEW err_new;
Tox *tox = tox_new(NULL, &err_new);
if (err_new != TOX_ERR_NEW_OK) {
fprintf(stderr, "tox_new failed with error code %d\n", err_new);
exit(1);
}
```
Here, we simply exit the program, but in a real client you will probably want
to do some error handling and proper error reporting to the user. The `NULL`
argument given to the first parameter of `tox_new` is the `Tox_Options`. It
contains various write-once network settings and allows you to load a
previously serialised instance. See [toxcore/tox.h](tox.h) for details.
### Setting up callbacks
Toxcore works with callbacks that you can register to listen for certain
events. Examples of such events are "friend request received" or "friend sent
a message". Search the API for `tox_callback_*` to find all of them.
Here, we will set up callbacks for receiving friend requests and receiving
messages. We will always accept any friend request (because we're a bot), and
when we receive a message, we send it back to the sender.
```c
tox_callback_friend_request(tox, handle_friend_request);
tox_callback_friend_message(tox, handle_friend_message);
```
These two function calls set up the callbacks. Now we also need to implement
these "handle" functions.
### Handle friend requests
```c
static void handle_friend_request(
Tox *tox, const uint8_t *public_key, const uint8_t *message, size_t length,
void *user_data) {
// Accept the friend request:
TOX_ERR_FRIEND_ADD err_friend_add;
tox_friend_add_norequest(tox, public_key, &err_friend_add);
if (err_friend_add != TOX_ERR_FRIEND_ADD_OK) {
fprintf(stderr, "unable to add friend: %d\n", err_friend_add);
}
}
```
The `tox_friend_add_norequest` function adds the friend without sending them a
friend request. Since we already got a friend request, this is the right thing
to do. If you wanted to send a friend request yourself, you would use
`tox_friend_add`, which has an extra parameter for the message.
### Handle messages
Now, when the friend sends us a message, we want to respond to them by sending
them the same message back. This will be our "echo".
```c
static void handle_friend_message(
Tox *tox, uint32_t friend_number, TOX_MESSAGE_TYPE type,
const uint8_t *message, size_t length,
void *user_data) {
TOX_ERR_FRIEND_SEND_MESSAGE err_send;
tox_friend_send_message(tox, friend_number, type, message, length,
&err_send);
if (err_send != TOX_ERR_FRIEND_SEND_MESSAGE_OK) {
fprintf(stderr, "unable to send message back to friend %d: %d\n",
friend_number, err_send);
}
}
```
That's it for the setup. Now we want to actually run the bot.
### Main event loop
Toxcore works with a main event loop function `tox_iterate` that you need to
call at a certain frequency dictated by `tox_iteration_interval`. This is a
polling function that receives new network messages and processes them.
```c
while (true) {
usleep(1000 * tox_iteration_interval(tox));
tox_iterate(tox, NULL);
}
```
That's it! Now you have a working echo bot. The only problem is that since Tox
works with public keys, and you can't really guess your bot's public key, you
can't add it as a friend in your client. For this, we need to call another API
function: `tox_self_get_address(tox, address)`. This will fill the 38 byte
friend address into the `address` buffer. You can then display that binary
string as hex and input it into your client. Writing a `bin2hex` function is
left as exercise for the reader.
We glossed over a lot of details, such as the user data which we passed to
`tox_iterate` (passing `NULL`), bootstrapping into an actual network (this bot
will work in the LAN, but not on an internet server) and the fact that we now
have no clean way of stopping the bot (`while (true)`). If you want to write a
real bot, you will probably want to read up on all the API functions. Consult
the API documentation in [toxcore/tox.h](toxcore/tox.h) for more information.
### Other resources
- [Another echo bot](https://wiki.tox.chat/developers/client_examples/echo_bot)
- [minitox](https://github.com/hqwrong/minitox) (A minimal tox client)