irungentoo/toxcore — pull request #1029 by ittner (2014-08-25 00:36:25+00:00)
Title: Add support for user avatars in the core protocol

Folks,

I started studying the Tox protocol a few days ago and, as a learning aid,
decided to implement the support for user avatars, a feature apparently
missing (and, although the STS describes a solution, no client seems to
implement it for now). Issue #729 also suggested another approach, but I
think publishing them in the DHT can add too much load to the network -- to
say nothing of the privacy implications.

So, this branch adds a protocol and the APIs to straightforwardly support
user avatars in client applications. The protocol is designed to transfer
avatars in background, between friends only, and minimize network load by
providing a lightweight avatar notification for local cache validation.
Strict safeguards are imposed to avoid damage from non-cooperative or
malicious users and to limit network usage.

My design criteria were:

- Avatars are handled as private information, ie., only exchanged over
Tox encrypted channels among previously authenticated friends;

- The library treats all images as blobs and does not interpret or
understands image formats, only ensures that the avatar data sent by
an user is correctly received by the other. The client application is
responsible for validating, decoding, resizing, and presenting the
image to the user.

- There is a strict limit of 16 KiB to the avatar raw data size -- this
seems suitable for practical use as, for example, the raw data of an
uncompressed 64 x 64 pixels 24 bpp RGB bitmap is 12288 bytes long; the
data limit provides enough space for larger bitmaps if the usual
compressed formats are used;

**Notice:** As designed, this limit can be changed in the future without
breaking the protocol compatibility, but clients using the original
limit will reject larger avatars;

- The protocol MUST provide means to allow caching and avoid unnecessary
data transfers;

- Avatars are transfered between clients in a background operation;

- Avatars are served in a "best effort" basis, without breaking clients
who do not support them;

- The protocol MUST resist to malicious users;

- The protocol MUST work with both UDP and TCP networks.

By design, this protocol:

- Provides a simpler and cleaner interfaces for client applications;

- Hides protocol complexities from the client;

- Avoids code duplication and ad-hoc protocols in the clients;

- Avoids incompatibility between client implementations;

- Allows important optimizations such as lightweight notification of
removed and updated avatars;

- Plays well with cache schemes;

- Makes avatar transfer an essentially background operation.

An high level description of the protocol is:

- **Avatar Information Notifications** are events which may be sent by
an user to another anytime, but are usually sent after one of them
connects to the network, changes his avatar, or in reply to an **avatar
information request**. They are delivered by a very lightweight message
but with information enough to allow an user to validate or discard an
avatar from the local cache and decide if is interesting to request the
avatar data from the peer.

This events contains two data fields: (1) the image format and (2) the
cryptographic hash of the actual image data. Image format may be NONE
(for users who have no avatar or removed their avatars), JPEG, PNG, or
GIF. The cryptographic hash is compared with the hash of the currently
cached avatar (if any) and check if it stills up to date.

- **Avatar Information Requests** are very lightweight messages sent by an
user asking for an **avatar information notification**. They may be sent
as part of the login process or when the client thinks the currently
cached avatar is outdated. The receiver may or may not answer to this
request. This message contains no data fields.

- An **Avatar Data Request** is sent by an user asking another for his
complete avatar data. It is sent only when the requesting user decides
the avatar do not exists in the local cache or is outdated. The receiver
may or may not answer to this request. This message contains no data
fields.

- An **Avatar Data Notification** is an event signaling the client that
the complete avatar image data of another user is available. The actual
data transfer is implemented using several data and control messages,
but the details are hidden from the client applications. This event can
only arrive in reply to an **avatar data request**.

This event contains three data fields: (1) the image format, (2) the
cryptographic hash of the image data, and (3) the raw image data. If the
image format is NONE (i.e. no avatar) the hash is zeroed and the image
data is empty. The raw image data is locally validated and ensured to
match the hash (the event is **not** triggered otherwise).

The complete documentation is available in docs/Avatars.md and sample
code is available in testing/test_avatars.c.

I hope I understood the Tox inner workings correctly and that this code is,
in some way, useful for the project!

Thanks,