Go to file
Green Sky cae0ab9c5c Squashed 'external/toxcore/c-toxcore/' changes from 03e9fbf3703..55752a2e2ef
55752a2e2ef fix(toxav): pass video bit rate as kbit Previously we unintentionally made it Mbit.
7e573280a75 docs(toxav): fix docs of toxav.h - fix units to be more readable - use width before height consistently - video -> audio typo
5f88a084e8c fix: friend_connections leak on allocation failure clean up when it only contains connections in the NONE state
6d27a1ae178 fix: wrong comment for closelist
ce4f29e8036 cleanup: Fix all `-Wsign-compare` warnings.
4d4251c397f chore: lower cirrus ci timeout drastically
40676284507 fix: events leak that can occur if allocation fails rare in practice, found by fuzzing
9610ac31c5f fix: Return an error instead of crashing on nullptr args in NGC.
a57c2c8f956 refactor: Make ToxAV independent of toxcore internals.
5752fc29f86 refactor: Make tox-bootstrapd use bool instead of int
df675786eb2 chore: Add release-drafter github action.
03fd7a69dcf chore: Use toktok's cmp instead of upstream.
350c0ba1205 cleanup: Sort apk/apt install commands in Dockerfiles.
8c1bda502cb chore(deps): bump golang.org/x/net
ddb9d3210da chore: Upgrade to FreeBSD 14.1 in cirrus build.
e9076f45bd3 chore(cmake): set options changes as cache and with force

git-subtree-dir: external/toxcore/c-toxcore
git-subtree-split: 55752a2e2ef894bfa6d7a2a21a0278e3f2bede7d
2024-11-09 13:44:30 +01:00
.circleci Squashed 'external/toxcore/c-toxcore/' changes from da438763d5b..671b1f92332 2024-09-19 13:45:12 +02:00
.clusterfuzzlite Squashed 'external/toxcore/c-toxcore/' changes from 6d634674a9..73d9b845a3 2024-01-14 21:51:01 +01:00
.devcontainer Squashed 'external/toxcore/c-toxcore/' changes from 67badf694..82460b212 2023-10-10 19:37:39 +02:00
.github Squashed 'external/toxcore/c-toxcore/' changes from 03e9fbf3703..55752a2e2ef 2024-11-09 13:44:30 +01:00
auto_tests Squashed 'external/toxcore/c-toxcore/' changes from 03e9fbf3703..55752a2e2ef 2024-11-09 13:44:30 +01:00
build Squashed 'external/toxcore/c-toxcore/' content from commit 67badf69 2023-07-25 11:53:09 +02:00
cmake Squashed 'external/toxcore/c-toxcore/' changes from e2c01e457b..b03b571272 2024-03-07 23:12:55 +01:00
docs Squashed 'external/toxcore/c-toxcore/' changes from e2c01e457b..b03b571272 2024-03-07 23:12:55 +01:00
m4 Squashed 'external/toxcore/c-toxcore/' content from commit 67badf69 2023-07-25 11:53:09 +02:00
other Squashed 'external/toxcore/c-toxcore/' changes from 03e9fbf3703..55752a2e2ef 2024-11-09 13:44:30 +01:00
super_donators Squashed 'external/toxcore/c-toxcore/' changes from d4b06edc2a..adbd5b32d8 2023-12-15 15:21:40 +01:00
testing Squashed 'external/toxcore/c-toxcore/' changes from 03e9fbf3703..55752a2e2ef 2024-11-09 13:44:30 +01:00
third_party Squashed 'external/toxcore/c-toxcore/' changes from 03e9fbf3703..55752a2e2ef 2024-11-09 13:44:30 +01:00
toxav Squashed 'external/toxcore/c-toxcore/' changes from 03e9fbf3703..55752a2e2ef 2024-11-09 13:44:30 +01:00
toxcore Squashed 'external/toxcore/c-toxcore/' changes from 03e9fbf3703..55752a2e2ef 2024-11-09 13:44:30 +01:00
toxencryptsave Squashed 'external/toxcore/c-toxcore/' changes from 03e9fbf3703..55752a2e2ef 2024-11-09 13:44:30 +01:00
.cirrus.yml Squashed 'external/toxcore/c-toxcore/' changes from 03e9fbf3703..55752a2e2ef 2024-11-09 13:44:30 +01:00
.clang-format Squashed 'external/toxcore/c-toxcore/' content from commit 67badf69 2023-07-25 11:53:09 +02:00
.clang-tidy Squashed 'external/toxcore/c-toxcore/' changes from e2c01e457b..b03b571272 2024-03-07 23:12:55 +01:00
.dockerignore Squashed 'external/toxcore/c-toxcore/' changes from d4b06edc2a..adbd5b32d8 2023-12-15 15:21:40 +01:00
.editorconfig Squashed 'external/toxcore/c-toxcore/' content from commit 67badf69 2023-07-25 11:53:09 +02:00
.gitignore Squashed 'external/toxcore/c-toxcore/' changes from 73d9b845a3..e2c01e457b 2024-01-15 23:32:23 +01:00
.gitmodules Squashed 'external/toxcore/c-toxcore/' changes from 03e9fbf3703..55752a2e2ef 2024-11-09 13:44:30 +01:00
.hadolint.yaml Squashed 'external/toxcore/c-toxcore/' content from commit 67badf69 2023-07-25 11:53:09 +02:00
.restyled.yaml Squashed 'external/toxcore/c-toxcore/' changes from e2c01e457b..b03b571272 2024-03-07 23:12:55 +01:00
autogen.sh Squashed 'external/toxcore/c-toxcore/' content from commit 67badf69 2023-07-25 11:53:09 +02:00
azure-pipelines.yml Squashed 'external/toxcore/c-toxcore/' changes from d4b06edc2a..adbd5b32d8 2023-12-15 15:21:40 +01:00
BUILD.bazel Squashed 'external/toxcore/c-toxcore/' changes from f1df709b87..8f0d505f9a 2024-01-09 16:39:05 +01:00
CHANGELOG.md Squashed 'external/toxcore/c-toxcore/' changes from 3e05824b80..da438763d5 2024-03-28 16:13:51 +01:00
CMakeLists.txt Squashed 'external/toxcore/c-toxcore/' changes from 03e9fbf3703..55752a2e2ef 2024-11-09 13:44:30 +01:00
CMakePresets.json Squashed 'external/toxcore/c-toxcore/' changes from f1df709b87..8f0d505f9a 2024-01-09 16:39:05 +01:00
codecov.yml Squashed 'external/toxcore/c-toxcore/' changes from 67badf694..82460b212 2023-10-10 19:37:39 +02:00
conanfile.py Squashed 'external/toxcore/c-toxcore/' changes from 67badf694..82460b212 2023-10-10 19:37:39 +02:00
configure.ac Squashed 'external/toxcore/c-toxcore/' changes from 3e05824b80..da438763d5 2024-03-28 16:13:51 +01:00
DONATORS Squashed 'external/toxcore/c-toxcore/' content from commit 67badf69 2023-07-25 11:53:09 +02:00
INSTALL.md Squashed 'external/toxcore/c-toxcore/' changes from 3e05824b80..da438763d5 2024-03-28 16:13:51 +01:00
libtoxav.pc.in Squashed 'external/toxcore/c-toxcore/' content from commit 67badf69 2023-07-25 11:53:09 +02:00
libtoxcore.pc.in Squashed 'external/toxcore/c-toxcore/' changes from e29e185c03..f1df709b87 2023-12-27 12:37:22 +01:00
LICENSE Squashed 'external/toxcore/c-toxcore/' changes from f1df709b87..8f0d505f9a 2024-01-09 16:39:05 +01:00
Makefile.am Squashed 'external/toxcore/c-toxcore/' content from commit 67badf69 2023-07-25 11:53:09 +02:00
netlify.toml Squashed 'external/toxcore/c-toxcore/' content from commit 67badf69 2023-07-25 11:53:09 +02:00
README.md Squashed 'external/toxcore/c-toxcore/' changes from e2c01e457b..b03b571272 2024-03-07 23:12:55 +01:00
so.version Squashed 'external/toxcore/c-toxcore/' changes from 3e05824b80..da438763d5 2024-03-28 16:13:51 +01:00
sonar-project.properties Squashed 'external/toxcore/c-toxcore/' changes from 8f0d505f9a..6d634674a9 2024-01-12 21:30:48 +01:00
tox.spec.in Squashed 'external/toxcore/c-toxcore/' content from commit 67badf69 2023-07-25 11:53:09 +02:00
vcpkg.json Squashed 'external/toxcore/c-toxcore/' changes from f1df709b87..8f0d505f9a 2024-01-09 16:39:05 +01:00

Project Tox

Current Coverage: coverage

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!

Danger: Experimental

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:

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

SAST Tools

This project uses various tools supporting Static Application Security Testing:

  • clang-tidy: A clang-based C++ "linter" tool.
  • Coverity: A cloud-based static analyzer service for Java, C/C++, C#, JavaScript, Ruby, or Python that is free for open source projects.
  • cppcheck: A static analyzer for C/C++ code.
  • cpplint: Static code checker for C++
  • goblint: A static analyzer for multi-threaded C programs, specializing in finding concurrency bugs.
  • infer: A static analyzer for Java, C, C++, and Objective-C.
  • PVS-Studio: A static analyzer for C, C++, C#, and Java code.
  • tokstyle: A style checker for TokTok C projects.