This is the ceema library, which provides a C++ implementation of the Threema communication protocol (and, in the future, a C interface to it). The aim is to provide a somewhat simple interface to hook the Threema protocol in client applications such as multi-protocol IM clients.
If you are looking for a ready-to-use desktop application, consider openMittsu.
Since this is CMake based, building the library consists of the following steps
git submodule init git submodule sync git submodule update --init --recursive mkdir build && cd build cmake ../ make
This library requires the following dependencies to be installed (both headers and libraries):
src you will find:
client: Structures for dealing with clients/contact. The primary class is
Client, and a utility class
encoding: Some utilities for massaging data (hashing, padding, ...)
logging: What it says on the tin
protocol: Main protocol handling. Goes from packets, to messages, to payloads
socket: Low-level network interface
types: Type definitions used throughout the library
The protocol is fairly straightforward. First, a client-server handshake is performed to set-up the encryption (using sodium/NaCl). This is handled by the Session class. Next, the client and server will communicate in (encrypted) packets as follows:
- A (2 byte) length prefix is sent, followed by an encrypted packet
- A packet consists of a (4 byte) type prefix, followed by an optional payload.
There are roughtly 4 types of packets:
- Session status packets, indicating start (after any pending messages have been sent), or end (server generally ends the session when the client connects using the same credentials form another source). Normally sent by the server only. The end packet contains a UTF-8 encoded string payload
- Keep-alive/ping packets, containing an arbitrary payload that must be in the reply. Can be sent both by the server and the client
- Messages (see below), identified by a random ID
- Acknowledgements, sent by both the server and the client in response to receiving a message, containing the sender and ID of the message being acknowledged. Without an acknowledgement, the server will keep retrying to deliver the message.
- Messages contain both a sender and recipient, some arbitrary message ID,
a timestamp (seconds since epoch), the ID or nickname of the sender and some
payload. They are prefixed by a (1 byte) type identifier, which determines
the type of payload. The payload is encrypted using the keys of the sender and
recipient, after adding padding according to PKCS#7. The following types of
messages are known:
- Client message:
- Text: Payload is a UTF-8 encoded string.
- Location: Payload is UTF-8 encoded string with coordinates: Two lines, separated by LF, first in decimal, then minutes
- User status message, either typing, or typing stopped
- Client message-status message, can be received, seen, agree/disagree
- Group message:
- Client message:
The Threema client allows for backup of the private key and client ID using a backup string. Its is a base32 encoded string consisting of a salt and the encrypted data. The salt and password generate a hash which can be used to decrypt the data, which will yield the client ID, private key, and 2 bytes of the SHA-256 hash of both which can be used to validate the decryption.