Merge pull request #35 from VirgilSecurity/dev-before-group-chats

Dev before group chats

Author: BuddahLD

README.md

@@ -3,7 +3,7 @@
 [![Build Status](https://travis-ci.com/VirgilSecurity/virgil-e3kit-kotlin.svg?branch=master)](https://travis-ci.com/VirgilSecurity/virgil-e3kit-kotlin)
 [![GitHub license](https://img.shields.io/badge/license-BSD%203--Clause-blue.svg)](https://github.com/VirgilSecurity/virgil/blob/master/LICENSE)
 
-[Introduction](#introduction) | [SDK Features](#sdk-features) | [Install E3Kit SDK](#install-e3kit-sdk) | [Usage](#usage) | [Samples](#samples) | [License](#license) | [Support](#support)
+[Introduction](#introduction) | [SDK Features](#sdk-features) | [Installation](#installation) | [Usage Examples](#usage-examples) | [Samples](#samples) | [License](#license) | [Docs](#docs) | [Support](#support)
 
 ## Introduction
 
@@ -15,40 +15,27 @@ Virgil E3kit allows you to setup user encryption with multidevice support in jus
 - group chats
 - manage users' Public Keys
 
-## Install E3Kit SDK
+## Installation
 
 You can install E3Kit SDK using [Gradle](https://gradle.org/). Please, choose package that suits best for your needs:
 
 | Package | Description |
 |----------|---------|
 | [`E3Kit`](./ethree-kotlin) | Standard package for Java/Kotlin with methods responses in `callbacks` |
-| [`E3Kit Coroutines`](./ethree-kotlin-coroutines) | [Coroutines](https://github.com/Kotlin/kotlinx.coroutines) package with methods responses in [`Deferred`](https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-deferred/) |
 
-## Samples
-
-You can find the code samples for Java and Kotlin (for Kotlin-Coroutines module as well) here:
-
-| Sample type | 
-|----------| 
-| [`Android Java`](./samples/android-java) | 
-| [`Android Kotlin`](./samples/android-kotlin) | 
-| [`Android Kotlin Coroutines`](./samples/android-kotlin-coroutines) | 
-| [`Android Java Firebase`](./samples/android-java-firebase-function) | 
-| [`Android Kotlin Firebase`](./samples/android-kotlin-firebase-function) | 
 
-You can run any of them on an emulator to check out the example of how to initialize the SDK, register users and encrypt messages using the E3Kit.
+## Usage Examples
 
-## Usage
+#### Initialize e3kit
 
-#### Register User
-Use the following lines of code to authenticate a user.
+In order to interact with the Virgil Cloud, the Virgil e3kit SDK must be provided with a callback that it will call to fetch the Virgil JWT from your backend for the current user.
 
 ```kotlin
-var eThree: EThree? = null
+lateinit var eThree: EThree
 
 // Listener for E3Kit initialization
 val initializeListener =
-    object : EThree.OnResultListener<EThree> {
+    object : OnResultListener<EThree> {
         override fun onSuccess(result: EThree) {
             // Init done!
             eThree = result
@@ -60,91 +47,156 @@ val initializeListener =
     }
 
 // initialize E3Kit
-EThree.initialize(context, virgilTokenCallback, initializeListener)
+EThree.initialize(context, virgilTokenCallback).addCallback(initializeListener)
 ```
 
-#### Encrypt & decrypt
+#### Register user
 
-Virgil E3Kit lets you use a user's Private key and his or her Public Keys to sign, then encrypt text.
+Use the following lines of code to register a user:
 
 ```kotlin
-var eThree: EThree? = null
-var encryptedData: ByteArray? = null
-var encryptedText: String? = null           
-
-// Listener for keys lookup Two
-val lookupKeysListenerTwo =
-    object : EThree.OnResultListener<Map<String, PublicKey>> {
-        override fun onSuccess(result: Map<String, PublicKey>) {
-            // Decrypt data using senders public key (In this example it's E3Kit current user)
-            val decryptedData = eThree.decrypt(encryptedData!!, result[identityInToken])
-            
-            // Decrypt data using senders public key (In this example it's E3Kit current user)
-            val decryptedText = eThree.decrypt(encryptedText!!, result[identityInToken])
+// TODO: Initialize e3kit
+
+val registerListener =
+    object : OnCompleteListener {
+        override fun onSuccess() {
+            // User private key loaded, ready for end-to-end encrypt!
         }
 
         override fun onError(throwable: Throwable) {
             // Error handling
         }
     }
 
-// Listener for keys lookup
+eThree.register().addCallback(registerListener)
+```
+This function generates PrivateKey/PublicKey keypair, saves PrivateKey locally on device and publishes PublicKey to Virgil Cards Service.
+
+#### Sign and encrypt data/text
+
+This method signs the data/text with the sender's private key and encrypts the message for recipients' public key(s).
+
+```kotlin
+// TODO: Initialize e3kit, Register e3kit user          
+
 val lookupKeysListener =
-    object : EThree.OnResultListener<Map<String, PublicKey>> {
-        override fun onSuccess(result: Map<String, PublicKey>) {
-            val text = "I was a text, but become a byte array"
+    object : OnResultListener<LookupResult> {
+        override fun onSuccess(result: LookupResult) {
+            val text = "I was text but become byte array"
             val data = text.toByteArray()
 
             // Encrypt data using user public keys
-            encryptedData = eThree.encrypt(data, result.values.toList())
+            val encryptedData = eThree.encrypt(data, result)
 
             // Encrypt message using user public keys
-            encryptedText = eThree.encrypt(text, result.values.toList())
-            
-            // E3Kit using identity that specified in Jwt provided with *virgilTokenCallback*
-            eThree!!.lookupPublicKeys(listOf(identityInToken), lookupKeysListenerTwo)
+            val encryptedText = eThree.encrypt(text, result)
         }
 
         override fun onError(throwable: Throwable) {
             // Error handling
         }
     }
 
-// Listener for register
-val registerListener =
-    object : EThree.OnCompleteListener {
-        override fun onSuccess() {
-            // User private key loaded!
-            // Now we need public keys and we ready for end-to-end encrypt.
-            eThree!!.lookupPublicKeys(listOf("AliceUUID", "BobUUID"), lookupKeysListener)
+// Lookup destination user public keys
+eThree.lookupPublicKeys(listOf("userUID1", "userUID2", "userUID3")).addCallback(lookupKeysListener)
+```
+
+#### Decrypt data/text and verify signature
+
+This method decrypts the data using the recipient's private key and verifies authenticity of the decrypted data with sender's public key.
+
+```kotlin
+// TODO: Initialize e3kit, Register e3kit user 
+
+val lookupKeysListener =
+    object : OnResultListener<LookupResult> {
+        override fun onSuccess(result: LookupResult) {
+            // Decrypt data and verify if it was really written by Bob
+            val decryptedData = eThree.decrypt(encryptedData, result["bobUID"])
+
+            // Decrypt text and verify if it was really written by Bob
+            val decryptedText = eThree.decrypt(encryptedText, result["bobUID"])
         }
 
         override fun onError(throwable: Throwable) {
             // Error handling
         }
     }
 
-// Listener for E3Kit initialization
-val initializeListener =
-    object : EThree.OnResultListener<EThree> {
-        override fun onSuccess(result: EThree) {
-            // Init done!
-            eThree = result
-            eThree!!.register(registerListener)
-        }
+// Lookup chat room member key
+eThree.lookupPublicKeys("bobUID").addCallback(lookupKeysListener)
+```
 
-        override fun onError(throwable: Throwable) {
-            // Error handling
+#### Encrypt & decrypt large files
+
+If the data that needs to be encrypted is too large for your RAM to encrypt all at once, use the following snippets to encrypt and decrypt streams.
+> Stream encryption doesn’t sign the data. This is why stream decryption doesn’t require VirgilPublicKey for verification unlike the general data decryption.
+
+Encryption:
+```kotlin
+// TODO: initialize and register user (see EThree.initialize and EThree#register)
+
+// Listener for keys lookup
+val lookupKeysListener =
+        object : OnResultListener<LookupResult> {
+            override fun onSuccess(result: LookupResult) {
+                val assetManager = context.assets
+
+                assetManager.open("some_file.txt").use { inputStream ->
+                    ByteArrayOutputStream().use { outputStream ->
+                        // Encrypt input stream using user public keys and writes output to the output stream
+                        eThree.encrypt(inputStream, outputStream, result)
+                    }
+                }
+            }
+
+            override fun onError(throwable: Throwable) {
+                // Error handling
+            }
         }
-    }
 
-// initialize E3Kit
-EThree.initialize(context, virgilTokenCallback, initializeListener)
+// Lookup destination user public keys
+eThree.lookupPublicKeys(listOf("userUID1", "userUID2", "userUID3")).addCallback(lookupKeysListener)
+```
+
+Decryption:
+```kotlin
+// TODO: init SDK and register users - see EThree.initialize and EThree#register
+ByteArrayOutputStream().use { outputStream ->
+    // Decrypt encrypted input stream and writes output to the output stream
+    eThree.decrypt(encryptedStream, outputStream)
+}
 ```
 
+## Samples
+
+You can find the code samples for Java and Kotlin here:
+
+| Sample type | 
+|----------| 
+| [`Android Java`](./samples/android-java) | 
+| [`Android Kotlin`](./samples/android-kotlin) | 
+| [`Android Java Firebase`](./samples/android-java-firebase-function) | 
+| [`Android Kotlin Firebase`](./samples/android-kotlin-firebase-function) | 
+| [`Android Kotlin Back4App`](./samples/android-kotlin-back4app) | 
+| [`Android Kotlin Nexmo`](./samples/android-kotlin-nexmo) | 
+
+You can run any of them on an emulator to check out the example of how to initialize the SDK, register users and encrypt messages using the E3Kit.
+
 ## License
 
-This library is released under the [3-clause BSD License](LICENSE).
+This library is released under the [3-clause BSD License](LICENSE.md).
+
+## Docs
+Virgil Security has a powerful set of APIs, and the documentation below can get you started today.
+
+* E3kit integrations with:
+  * [Custom platform][_any_platform]
+  * [Firebase][_firebase]
+  * [Twilio][_twilio]
+  * [Nexmo][_nexmo]
+  * [Pubnub][_pubnub]
+* [Reference API][_reference_api]
 
 ## Support
 Our developer support team is here to help you. Find out more information on our [Help Center](https://help.virgilsecurity.com/).
@@ -153,16 +205,9 @@ You can find us on [Twitter](https://twitter.com/VirgilSecurity) or send us emai
 
 Also, get extra help from our support team on [Slack](https://virgilsecurity.com/join-community).
 
-[_cards_service]: https://developer.virgilsecurity.com/docs/api-reference/card-service/v5
-[_use_card]: https://developer.virgilsecurity.com/docs/swift/how-to/public-key-management/v5/use-card-for-crypto-operation
-[_get_card]: https://developer.virgilsecurity.com/docs/swift/how-to/public-key-management/v5/get-card
-[_search_card]: https://developer.virgilsecurity.com/docs/swift/how-to/public-key-management/v5/search-card
-[_create_card]: https://developer.virgilsecurity.com/docs/swift/how-to/public-key-management/v5/create-card
-[_own_crypto]: https://developer.virgilsecurity.com/docs/swift/how-to/setup/v5/setup-own-crypto-library
-[_key_storage]: https://developer.virgilsecurity.com/docs/swift/how-to/setup/v5/setup-key-storage
-[_card_verifier]: https://developer.virgilsecurity.com/docs/swift/how-to/setup/v5/setup-card-verifier
-[_card_manager]: https://developer.virgilsecurity.com/docs/swift/how-to/setup/v5/setup-card-manager
-[_setup_authentication]: https://developer.virgilsecurity.com/docs/swift/how-to/setup/v5/setup-authentication
+[_any_platform]: https://developer.virgilsecurity.com/docs/use-cases/v5/encrypted-communication
+[_twilio]: https://developer.virgilsecurity.com/docs/use-cases/v5/encrypted-communication-for-twilio
+[_nexmo]: https://developer.virgilsecurity.com/docs/use-cases/v5/encrypted-communication-for-nexmo
+[_firebase]: https://developer.virgilsecurity.com/docs/use-cases/v5/encrypted-communication-for-firebase
+[_pubnub]: https://developer.virgilsecurity.com/docs/use-cases/v5/smart-door-lock
 [_reference_api]: https://developer.virgilsecurity.com/docs/api-reference
-[_configure_sdk]: https://developer.virgilsecurity.com/docs/how-to#sdk-configuration
-[_more_examples]: https://developer.virgilsecurity.com/docs/how-to#public-key-management