Skip to content
Go to file

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

**The Qabel Core Library**

This project provides a core library for all Qabel Clients implementing Qabel.

Introduction | Install | Getting Started | Usage | Contribution

Release License Build


For a comprehensive documentation of the whole Qabel Platform use as the main source of information. may provide additional technical information.

Qabel consists of multiple Projects:


Distributions of the Clients are provided by the official Qabel website at . Everything below this line describes the usage of the Qabel Core Library for development purposes.

To use the Qabel Core as a library with gradle, add the following to your build.gradle:

repositories {
    maven { url "" }
dependencies {
    compile 'com.github.Qabel.qabel-core:core:0.19.0'
    compile 'com.github.Qabel.qabel-core:box:0.19.0'
    compile 'com.github.Qabel.qabel-core:chat:0.19.0'


replace 0.16.1 with the latest release from

Getting started

For a reference build, the core provides a Vagrantfile that sets up all requirements and can do a full build. For a manual setup, take a look at the

Vagrant build: Install Vagrant from vagrantup and then build inside the box

vagrant up      # starts the vagrant vm (takes a while because all dependency need to be installed)
vagrant ssh     # enters the vm
cd /vagrant
./gradlew build


The Qabel-Core is developed in Java 7 and Kotlin. The Kotlin plugin is automatically loaded in the gradle build scripts and there are plugins for IntelliJ based IDEs, Eclipse, Vim and Emacs. It is recommended that new code is written in Kotlin instead of Java and that the Kotlin standard library is used instead of the Java standard library where applicable.

Currently, we do not provide a distribution of the Qabel Core Library via Maven Repositories. Thus, you have to include it via the artifact that you may find after the build at build/libs/qabel-core-x.y.z.jar and build/libs/qabel-box-x.y.z.jar. You also need to include the kotlin standard library in your project:

buildscript {
    ext.kotlin_version = '1.0.2'
dependencies {
    compile "org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version"

Don't forget to include the curve25519-linux-*.jar (JNI) and the according libcurve implementation for your system (build/binaries). Qabel does a lot of crypto that is written in C and called via JNI. When launching your java application, add the directory containing the jars and the C library wo javas library path via -Djava.library.path=....


To understand the concepts of Qabel, please read the documentations linked at Introduction.


For most actions, you need an Identity. It consists of a KeyPair, DropURLs and an Alias. You can create one with

DropURL url = new DropURL("");
Identity identity = new Identity("My New Identity", new ArrayList<DropURL>(), new QblECKeyPair());


and to communicate with other people, you need your Contact:

Contact contact = new Contact(identity.getAlias(), identity.getDropUrls(), identity.getEcPublicKey());

String serializedContact = ContactExportImport.exportContact(contact);
Files.write(Paths.get("myNewIdentity.qco"), serializedContact);

Sending drop messages

For wrapper that do this work for you, take a look at the client repositories. Otherwise sending a drop message is currently pretty complicated:

Identity sender = ...;
Contact receiver = ...;
DropURL dropURL = ...;  // select one dropURL from the receiver contact

// assemble the message
String jsonEncodedMessage = "{msg: \"this is a plaintext message for you\"}";
String messageType = "box_message";     // plaintext message ( explains these)
DropMessage message = new DropMessage(identity, jsonEncodedMessage, messageType);

// encrypt the message
BinaryDropMessageV0 binaryMessage = new BinaryDropMessageV0(message);
final byte[] messageByteArray = binaryMessage.assembleMessageFor(receiver, sender);
HTTPResult<?> dropResult = new DropHTTP().send(dropURL.getUri(), messageByteArray);
if (dropResult.getResponseCode() < 200 || dropResult.getResponseCode() >= 300) {
    // handle failure

The receiver can then receive the message with

for (DropURL url : identity.getDropUrls()) {
    long messagesSince = 0; // 0 means all messages, this should be increased to the last-modified from the server response
    HTTPResult<Collection<byte[]>> result = new DropHTTP().receiveMessages(url.getUri(), messagesSince);

    if (result.getResponseCode() == 0) {
        // handle failure...

    for (byte[] encryptedMessage : result.getData()) {
        byte binaryFormatVersion = encryptedMessage[0];
        if (binaryFormatVersion != 0) {
            continue;   // currently, we have spec version 0 so other messages won't be parseable

        try {
            AbstractBinaryDropMessage binMessage = new BinaryDropMessageV0(encryptedMessage);
            DropMessage dropMessage = binMessage.disassembleMessage(identity);  // decrypt with identities private key

            // TODO do something with the dropMessage (dropMessage.getPayload() contains '{msg: \"this is a plaintext message for you\"}')

        } catch (QablException e) {
            // failed to read ... maybe this message was not for us


The accounting server handles authentication and authorization for all actions related to the Box component of Qabel. The responsible helper class for these actions is the AccountingHTTP.



The block server is the storage backend for the Box component of Qabel. To be able to upload something, your request needs to be authenticated so that the accounting server can authorize your requests:

AccountingHTTP accounting = ...;

HttpRequest request = ...;  // prepare your block server request
// do the request, it is now authorized


For issues using one of the Clients, please use the integrated feedback features. For the Qabel Android Client, it is integrated at Settings -> write Feedback. For the Qabel Desktop Client, use the feedback button (feedback icon) inside the application.

For issues concerning the Qabel Core Library, use the Issue tracker of GitHub.

Please read the Contribution Guidelines ( carefully.