Add contributing file, update license, readme and releasing file

Author: lgrahl

CONTRIBUTING.md

@@ -0,0 +1,24 @@
+# Contributors Guideline
+
+Thanks a lot for any contribution!
+
+To keep code quality high and maintenance work low, please adhere to the
+following guidelines when creating a pull request:
+
+## Style Guide
+
+Try to write clean code and to adhere to the already used coding style.
+
+Lines should be kept below 120 characters.
+
+## Tests
+
+If possible, new code should be covered by automated tests.
+
+## Commit messages
+
+Use meaningful commit messages: Please follow the advice in [this
+blogpost](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html).
+First line of your commit message should be a very short summary (ideally 50
+characters or less) in the imperative mood. After the first line of the commit
+message, add a blank line and then a more detailed explanation (when relevant).

LICENSE-MIT

@@ -1,4 +1,4 @@
-Copyright (c) 2016-2017 Threema GmbH
+Copyright (c) 2016-2019 Threema GmbH
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -1,27 +1,22 @@
 # SaltyRTC WebRTC Task for Java
 
-[![Java Version](https://img.shields.io/badge/java-8%2B-orange.svg)](https://github.com/saltyrtc/saltyrtc-client-java)
-[![License](https://img.shields.io/badge/license-MIT%20%2F%20Apache%202.0-blue.svg)](https://github.com/saltyrtc/saltyrtc-client-java)
+[![Build status](https://circleci.com/gh/saltyrtc/saltyrtc-task-webrtc-java.svg?style=shield&circle-token=:circle-token)](https://circleci.com/gh/saltyrtc/saltyrtc-task-webrtc-java)
+[![Java Version](https://img.shields.io/badge/java-8%2B-orange.svg)](https://github.com/saltyrtc/saltyrtc-task-webrtc-java)
+[![License](https://img.shields.io/badge/license-MIT%20%2F%20Apache%202.0-blue.svg)](https://github.com/saltyrtc/saltyrtc-task-webrtc-java)
 [![Chat on Gitter](https://badges.gitter.im/saltyrtc/Lobby.svg)](https://gitter.im/saltyrtc/Lobby)
 
 This is a [SaltyRTC](https://github.com/saltyrtc/saltyrtc-meta) [WebRTC
 task](https://github.com/saltyrtc/saltyrtc-meta/blob/master/Task-WebRTC.md)
 implementation for Java 8+.
 
-For now, as long as `RTCPeerConnection` only works on Android, this library
-will not work outside of projects.
-
-The development is still ongoing, the current version is only at alpha-level
-and should not be used for production yet.
-
 For an application example, please see our [demo
 application](https://github.com/saltyrtc/saltyrtc-demo).
 
 
 ## Installing
 
 The package is available [on
-Bintray](https://bintray.com/saltyrtc/maven/saltyrtc-client/).
+Bintray](https://bintray.com/saltyrtc/maven/saltyrtc-task-webrtc).
 
 Gradle:
 
@@ -43,70 +38,171 @@ Maven:
 
 ## Usage
 
-Instantiate the task.
+To create the task instance, you need to use the `WebRTCTaskBuilder` instance
+which can be used to configure the task before creating it.
+
+The below configuration represents the default values chosen by the builder as
+if you had not configured the builder and just called `.build()` directly.
 
 ```java
-final WebRTCTask task = new WebRTCTask();
+final WebRTCTask task = new WebRTCTaskBuilder()
+    .withVersion(WebRTCTaskVersion.V1)
+    .withHandover(true)
+    .withMaxChunkLength(262144)
+    .build();
 ```
 
-Then, register a message handler:
+To send offers, answers and candidates, use the following task methods:
+
+* `task.sendOffer(offer: @NonNull Offer): void`
+* `task.sendAnswer(answer: @NonNull Answer): void`
+* `task.sendCandidates(candidate: @NonNull Candidate[]): void`
+
+You can register an event handler in the following way:
 
 ```java
 task.setMessageHandler(new MessageHandler() {
     @Override
-    public void onOffer(SessionDescription sd) {
+    public void onOffer(@NonNull Offer offer) {
         // Handle offer
     }
 
     @Override
-    public void onAnswer(SessionDescription sd) {
+    public void onAnswer(@NonNull Answer answer) {
         // Handle answer
     }
 
     @Override
-    public void onCandidates(List<IceCandidate> candidates) {
-        for (IceCandidate candidate : candidates) {
-            peerConnection.addIceCandidate(candidate);
-        }
+    public void onCandidates(@NonNull Candidate[] candidates) {
+        // Handle candidates
     }
 });
 ```
 
-Finally, pass the task instance to the `SaltyRTCBuilder` through the
-`.usingTasks(...)` method.
+### Data Channel Crypto Context
+
+The task provides another security layer for data channels which can be
+leveraged by usage of a `DataChannelCryptoContext` instance. To retrieve such
+an instance, call:
+
+```java
+final DataChannelCryptoContext context = task.createCryptoContext(dataChannel.id);
+```
+
+You can encrypt messages on the sending end in the following way:
+
+```java
+final Box box = context.encrypt(yourData);
+dataChannel.send(ByteBuffer.wrap(box.toBytes()));
+```
+
+On the receiving end, decrypt the message by the use of the crypto context:
+
+```java
+final Box box = new Box(message);
+final byte[] yourData = context.decrypt(
+    box, DataChannelCryptoContext.NONCE_LENGTH);
+```
 
-Once the signaling channel is open, create offer/answer/candidates as usual and
-send them through the signaling channel using the corresponding methods:
+Note, that you should not use a crypto context for a data channel that is being
+used for handover. The task will take care of encryption and decryption itself.
 
-- `task.sendOffer(offer)`
-- `task.sendAnswer(answer)`
-- `task.sendCandidates(candidates)`
+### Handover
+
+Before initiating the handover, the application needs to fetch the
+`SignalingTransportLink` instance which contains the necessary information to
+create a data channel.
+
+```java
+final SignalingTransportLink link = task.getTransportLink();
+
+final DataChannel.Init parameters = new DataChannel.Init();
+parameters.id = link.getId();
+parameters.negotiated = true;
+parameters.ordered = true;
+parameters.protocol = link.getProtocol();
+
+final DataChannel dataChannel = peerConnection.createDataChannel(
+    link.getLabel(), parameters);
+```
+
+Note that the data channel used for handover **must** be created with the
+label and parameters as shown in the above code snippet.
+
+Now that you have created the channel, you need to implement the
+`ISignalingTransportHandler` interface. Below is a minimal handler that forwards
+the necessary events and messages to the created data channel.
+
+```java
+final ISignalingTransportHandler handler = new ISignalingTransportHandler() {
+    @Override
+    public long getMaxMessageSize() {
+        return peerConnection.sctp().getMaxMessageSize();
+    }
+
+    @Override
+    public void close() {
+        dataChannel.close();
+    }
+
+    @Override
+    public void send(@NonNull final ByteBuffer message) {
+        // Note: Always send binary
+        dataChannel.send(new DataChannel.Buffer(message, true));
+    }
+};
+```
 
-As soon as the data channel is open, request a handover of the signaling channel:
+Furthermore, you have to bind all necessary events in order to connect the data
+channel to the `SignalingTransportLink`.
 
 ```java
-dc.registerObserver(new DataChannel.Observer() {
-    // ...
+dataChannel.registerObserver(new DataChannel.Observer() {
+    // [...]
 
     @Override
     public void onStateChange() {
-        if (dc.state() == DataChannel.State.OPEN) {
-            task.handover();
+        switch (dataChannel.state()) {
+            case OPEN:
+                task.handover(handler);
+                break;
+            case CLOSING:
+                link.closing();
+                break;
+            case CLOSED:
+                link.closed();
+                break;
         }
     }
+
+    @Override
+    public void onMessage(@NonNull final DataChannel.Buffer buffer) {
+        if (!buffer.binary) {
+            // Note: This should be handled as a protocol error
+            task.close(CloseCode.PROTOCOL_ERROR);
+        } else {
+            link.receive(buffer.data);
+        }
+    }
+    
+    // [...]
 });
 ```
 
-To know when the handover is done, subscribe to the SaltyRTC `handover` event.
+The above setup will forward the `CLOSING`/`CLOSED` state and all messages to
+the task by the use of the `SignalingTransportLink`. On `OPEN`, the handover
+will be initiated.
 
+To be signalled once the handover is finished, you need to register the
+`handover` event on the SaltyRTC client instance.
 
-## Logging
+### Logging
 
 The library uses the slf4j logging API. Configure a logger (e.g. slf4j-simple)
 to see the log output.
 
 
-## Testing
+## Manual Testing
 
 To try a development version of the library, you can build a local version to
 the maven repository at `/tmp/maven`:
@@ -121,7 +217,76 @@ Include it in your project like this:
     }
 
 
-## Hashes
+## Coding Guidelines
+
+Unfortunately we cannot use all Java 8 features, in order to be compatible with
+Android API <24. Please avoid using the following APIs:
+
+- `java.lang.annotation.Repeatable`
+- `AnnotatedElement.getAnnotationsByType(Class)`
+- `java.util.stream`
+- `java.lang.FunctionalInterface`
+- `java.lang.reflect.Method.isDefault()`
+- `java.util.function`
+
+The CI tests contains a script to ensure that these APIs aren't being called.
+You can also run it manually:
+
+    bash .circleci/check_android_support.sh
+
+
+## Automated Testing
+
+### 1. Preparing the Server
+
+First, clone the `saltyrtc-server-python` repository.
+
+    git clone https://github.com/saltyrtc/saltyrtc-server-python
+    cd saltyrtc-server-python
+
+Then create a test certificate for localhost, valid for 5 years.
+
+    openssl req -new -newkey rsa:1024 -nodes -sha256 \
+        -out saltyrtc.csr -keyout saltyrtc.key \
+        -subj '/C=CH/O=SaltyRTC/CN=localhost/'
+    openssl x509 -req -days 1825 \
+        -in saltyrtc.csr \
+        -signkey saltyrtc.key -out saltyrtc.crt
+
+Create a Java keystore containing this certificate.
+
+    keytool -import -trustcacerts -alias root \
+        -file saltyrtc.crt -keystore saltyrtc.jks \
+        -storetype JKS -storepass saltyrtc -noprompt
+
+Create a Python virtualenv with dependencies:
+
+    python3 -m virtualenv venv
+    venv/bin/pip install .[logging]
+
+Finally, start the server with the following test permanent key:
+
+    export SALTYRTC_SERVER_PERMANENT_KEY=0919b266ce1855419e4066fc076b39855e728768e3afa773105edd2e37037c20 # Public: 09a59a5fa6b45cb07638a3a6e347ce563a948b756fd22f9527465f7c79c2a864
+    venv/bin/saltyrtc-server -v 5 serve -p 8765 \
+        -sc saltyrtc.crt -sk saltyrtc.key \
+        -k $SALTYRTC_SERVER_PERMANENT_KEY
+
+### 2. Running Tests
+
+Make sure that the certificate keystore from the server is copied or symlinked
+to this repository:
+
+    ln -s path/to/saltyrtc-server-python/saltyrtc.jks
+
+With the server started in the background and the `saltyrtc.jks` file in the
+current directory, run the tests:
+
+    ./gradlew test
+
+
+## Security
+
+### Release Checksums
 
 These are the SHA256 hashes for the published releases of this project:
 
@@ -152,6 +317,22 @@ You can use tools like [gradle
 witness](https://github.com/WhisperSystems/gradle-witness) to make sure that
 your application always gets the correct version of this library.
 
+### Responsible Disclosure / Reporting Security Issues
+
+Please report security issues directly to one or both of the following contacts:
+
+- Danilo Bargen
+    - Email: [email protected]
+    - Threema: EBEP4UCA
+    - GPG: [EA456E8BAF0109429583EED83578F667F2F3A5FA][keybase-dbrgn]
+- Lennart Grahl
+    - Email: [email protected]
+    - Threema: MSFVEW6C
+    - GPG: [3FDB14868A2B36D638F3C495F98FBED10482ABA6][keybase-lgrahl]
+
+[keybase-dbrgn]: https://keybase.io/dbrgn
+[keybase-lgrahl]: https://keybase.io/lgrahl
+
 
 ## License
 

RELEASING.md

@@ -14,11 +14,11 @@ Update version numbers:
 Build:
 
     rm -r build
-    ./gradlew build
+    ./gradlew build publish
 
 Add hash to README.md:
 
-    sha256sum build/outputs/aar/saltyrtc-task-webrtc-release.aar
+    sha256sum build/libs/saltyrtc-task-webrtc.jar
 
 Add and commit:
 
@@ -32,4 +32,3 @@ Tag and push:
 
     git tag -s -u ${GPG_KEY} v${VERSION} -m "Version ${VERSION}"
     git push && git push --tags
-