Skip to content
This repository has been archived by the owner on Jun 19, 2018. It is now read-only.

Latest commit

 

History

History
158 lines (130 loc) · 7.29 KB

README.md

File metadata and controls

158 lines (130 loc) · 7.29 KB
Raw

Notice: This project is discontinued and no longer maintained nor supported by Tresorit. This repository only exists for archival purposes.

ZeroKit SDK for Android

ZeroKit is a simple, breach-proof user authentication and end-to-end encryption library.

The ZeroKit SDK for Android is currently under development and is accessible as a preview. We continuously improve the SDK and fix bugs.

You can sign up for ZeroKit here.

Content

Requirements

Android SDK: The Zerokit SDK library is compatible from API 21 (Android 5.0 - Lollipop).

Download

Add the dependency to build.gradle

dependencies {
    compile 'com.tresorit.zerokit:zerokit:4.1.2'
}

Usage

Initializing ZeroKit

To initialize the SDK you will need your API URL: In AndroidManifest.xml, add the following element as a child of the <application> element, by inserting it just before the closing </application> tag: AndroidManifest.xml

<meta-data
     android:name="com.tresorit.zerokitsdk.API_ROOT"
     android:value="YOUR API ROOT HERE (eg. https://{tenantid}.api.tresorit.io)"/>

Permissions

The following permissions are defined in the Zerokit SDK manifest, and are automatically merged into your app's manifest at build time. You don't need to add them explicitly to your manifest:

Proguard

If you are using ProGuard you might need to add the following option:

-dontwarn com.tresorit.zerokit.**

Using ZeroKit SDK

The API provides 2 possible ways to use the Zerokit SDK:

Asynchron

Zerokit.getInstance().encrypt(tresorId, "apple").execute(
    cipherText -> Log.d("Zerokit", String.format("Encrypted text: %s", cipherText)),
    error -> Log.d("Zerokit", String.format("Encrypting failed: %s", error.getMessage())));

Synchron

Response<String, ResponseZerokitError> response = Zerokit.getInstance().encrypt(tresorId, "apple").execute();
if (response.isError()) Log.d("Zerokit", String.format("Encrypting failed: %s", response.getError().getMessage()));
else Log.d("Zerokit", String.format("Encrypted text: %s", response.getResult()));

Password handling

A core concept of ZeroKit is that your application should not access and pass around the users' passwords. All password handling should be done by ZeroKit. For this we provide a PasswordEditText UI component that you should present to users to enter their passwords. If you are implementing data-binding solutions in your application and you do not want to use view ids, you can utilize PasswordHandler to achieve the same result.

With this solution you can ensure that the password will not be stored in String in Java side.

Some tips and examples for using PasswordEditText and/or PasswordHandler:

View

<com.tresorit.zerokit.PasswordEditText
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    ...
Zerokit.getInstance().login(userId, passwordEditText).subscribe(responseLogin -> {...});

Data Binding

<com.tresorit.zerokit.PasswordEditText
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    app:passwordExporter="@{viewmodel.passwordExporter}"
    ...
Zerokit.getInstance().login(userId, passwordExporter).subscribe(responseLogin -> {...});

It is also possible to securely compare two PasswordEditText and/or PasswordHandler without access of the concrete content in it. It can be useful when for example password confirmation is required:

passwordExporter.isContentEqual(passwordExporterConfirm)
passwordEditText.isContentEqual(passwordEditTextConfirm)

Identity Provider

ZeroKit comes with OpenID Connect provider implementation that you can use in your app. Use the getIdentityTokens(String clientId) method of a ZeroKit object to get authorization code and identity token for the current ZeroKit user. A user must be logged in when calling this method. The ZeroKit Open ID client used in mobile apps should have the following settings:

  • Redirect URL should have the following format: https://{Client ID}.{Tenant ID}.api.tresorit.io/
  • Flow should be set to Hybrid
  • You can optionally turn on Requires proof key (DHCE)

You can add new clients and edit settings on the management portal.

Administrative API

Most of the cryptographic operations (including invites and sharing) must be done client side by the SDK library. To provide control over these operations, and to prevent possible abuse by tampering the client, we introduced the admin API. All client initiated changes which has a permanent effect on the server has to be approved through the Admin API (typically by the server backend of the integrated app). For more information see the ZeroKit documentation.

Example Application

An example application is included with ZeroKit to demonstrate its usage. It demonstrates the following features:

  • Registration
  • Login and logout
  • Tresor creation
  • Tresor sharing
  • Encryption
  • Decryption

Configuring the Example

In the app/src/main/zerokit.properties set the values of apiroot, clientid, appbackend and objectserver. If this file does not exist, let’s create one with the same name.

apiroot=your base url (e.g. https://{tenantid}.api.tresorit.io)
clientid=client id for your openid
appbackend= url of the sample application backend (e.g. http://10.0.2.2:3000)
  • apiroot: This is your ZeroKit Service URL. You can find this URL on the management portal.
  • clientid: This is the client ID for your OpenID Connect client that you wish to use with your mobile app. You can find this value on the basic configuration page of your tenant at here
  • appbackend: This is the address of the sample application backend.

Now you are ready to Build and Run the example in Android Studio.

Registering Test Users

Register test users following the 'test-user-{XYZ}' username format. These users will be automatically validated by the sample backend so you can log in right after registration.

Used 3rd party libraries in the Example Application
  • Dagger 2: Dependency injector for Android
  • EventBus: A publish/subscribe event bus
  • Retrofit: Type-safe HTTP client for Android and Java

Changelog

See the CHANGELOG.md file.

Contact us

Do you have any questions? Contact us ([email protected])

License

See the LICENSE.txt file.