Green Sky
8eb4892b49
6d634674a9 cleanup: Remove old type-ordered event getters. d1d48d1dfc feat: add ngc events 994ffecc6b refactor: Make event dispatch ordered by receive time. 812f931d5f fix: Make sure there's enough space for CONSUME1 in fuzzers. 50f1b30fa9 test: Add fuzz tests to the coverage run. df76f5cf47 chore: Move from gcov to llvm source-based coverage. 072e3beb3f fix: issues with packet broadcast error reporting 6b6718e4d2 cleanup: Make group packet entry creation less error-prone 5b9c420ce1 refactor: packet broadcast functions now return errors af4cb31028 refactor: Use `operator==` for equality tests of `Node_format`. 9592d590cf refactor(test): Slightly nicer C++ interface to tox Random. c66e10fb7a refactor: Minor refactoring of get_close_nodes functions. ebc9643862 fix: don't pass garbage data buffer to packet send functions 32b68cffca cleanup: Some more test cleanups, removing overly smart code. 0426624dcb refactor: Assign malloc return to a local variable first. afc38f2458 test: Add more unit tests for `add_to_list`. 05ce5c1ab9 test: Add "infer" CI check to github, remove from circle. REVERT: 8f0d505f9a feat: add ngc events REVERT: 9b8216e70c refactor: Make event dispatch ordered by receive time. git-subtree-dir: external/toxcore/c-toxcore git-subtree-split: 6d634674a929edb0ab70689dcbcb195b3547be13 |
||
---|---|---|
.circleci | ||
.clusterfuzzlite | ||
.devcontainer | ||
.github | ||
auto_tests | ||
build | ||
cmake | ||
docs | ||
m4 | ||
other | ||
super_donators | ||
testing | ||
third_party | ||
toxav | ||
toxcore | ||
toxencryptsave | ||
.cirrus.yml | ||
.clang-format | ||
.clang-tidy | ||
.dockerignore | ||
.editorconfig | ||
.gitignore | ||
.gitmodules | ||
.hadolint.yaml | ||
.restyled.yaml | ||
autogen.sh | ||
azure-pipelines.yml | ||
BUILD.bazel | ||
CHANGELOG.md | ||
CMakeLists.txt | ||
CMakePresets.json | ||
codecov.yml | ||
conanfile.py | ||
configure.ac | ||
DONATORS | ||
INSTALL.md | ||
libtoxav.pc.in | ||
libtoxcore.pc.in | ||
LICENSE | ||
Makefile.am | ||
netlify.toml | ||
README.md | ||
so.version | ||
sonar-project.properties | ||
tox.spec.in | ||
vcpkg.json |
Website | Wiki | Blog | FAQ | Binaries/Downloads | Clients | Compiling
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 libsodium (based on NaCl) for its encryption and authentication.
IMPORTANT!
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 libsodium provides reliable encryption, but the security model has not yet been fully specified. See issue 210 for a discussion on developing a threat model. See other issues for known weaknesses (e.g. issue 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.
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 installed, run:
mkdir _build && cd _build
cmake ..
make
sudo make install
If you have libvpx and 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.
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 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.
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
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".
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.
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 for more information.
Other resources
- Another echo bot
- minitox (A minimal tox client)