Skip to content

Latest commit

 

History

History
197 lines (151 loc) · 8.45 KB

README.md

File metadata and controls

197 lines (151 loc) · 8.45 KB
Raw

**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

Introduction

For a comprehensive documentation of the whole Qabel Platform use https://qabel.de as the main source of information. https://qabel.github.io/docs/ may provide additional technical information.

Qabel consists of multiple Projects:

Install

Distributions of the Clients are provided by the official Qabel website at https://qabel.de/de/download . 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 "https://jitpack.io" }
}
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 https://jitpack.io/#Qabel/qabel-core

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 INSTALL.md.

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

Usage

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=....

Entities

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

Identity

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("https://drop.qabel.de/123456789012345678901234567890123456789012c");
Identity identity = new Identity("My New Identity", new ArrayList<DropURL>(), new QblECKeyPair());
identity.addDrop(url);

Contact

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 (https://qabel.github.io 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
        }
    }
}

Account

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.

// TODO

Block

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 = ...;
accounting.login();

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

Contribution

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 (CONTRIBUTING.md) carefully.