Encryption as a Service SDK for Cordova

The IDENTOS SDK allows you to secure application data and enables applications to encrypt, decrypt and share access to data across multiple devices and users. IDENTOS provides simple interfaces to register a device to your application, authenticate your users, and access the data protected by our encryption key management system.

Main functions of the SDK:

Register a Device
An application must register the user and device before the IDENTOS service can be initialized. When the device is registered, it is associated to the application and user and is subsequently governed by the key management policies set by the administrator.

Authenticate & Authorize
IDENTOS provides the ability to enforce a PIN entry upon application launch to ensure the user is authenticated. This PIN helps to secure the user's private key which is used to protect data and digitally sign requests for keys. The PIN can be set to 0 to disable PIN Required as a feature, however this is not recommended. 

Control access to data
Encrypt and decrypt any given piece of data, grant users access to the encryption keys, and maintain compliance by logging every request for data and keys.

Getting Started

Download the SDK

Contact us to request the SDK

Install the Framework

From your app directory, run

cordova plugin add path/to/cordova-plugin-identos/
This will allow you to access the IDENTOS interfaces.

Initialize the SDK

You can find your appId and clientKey on your app’s admin page.

/** 
initialize

Start using the Identos client

@params appId Your applications id
@params clientKey Your mobile client identifier

@return int 0=success, -50=unregistered, -1=failure 
*/
initialize: function(appId, clientKey, version, successCallback, errorCallback) ;

Registering the Users Device

The first step in the implementation of IDENTOS encryption services is to register the user’s device. This provides the first factor of authentication (what the user has). Only once a device has a registered identity with the IDENTOS trusted server can authentication take place. You can optionally require a user PIN, which is the second factor of authentication. Read more about user PIN below.

The process of registration is comprised of two main parts. The first part is completed by the code in the client application (registering the device) and the output of that is an identifier called a ‘device package’ that can be used in the second step to complete the registration.

Once the client has generated a device package, the package is passed to the server, which in turn completes the registration by verifying the user and passing the package back to the IDENTOS SDK using the Post user/register API.

Back End

POST user/register
https://sandbox.identos.com/api/v0/user/register

Purpose

Register a new user with the trusted server. Usernames must be unique in your application. If a username already exists, an additional device is added to that username.

Request

devicePackage: function (pin, successCallback, errorCallback);

Response

HTTP 200

{ "userid"  : "1234" }

Curl Example

#! /bin/bash

curl -X POST \
-H "Content-Type: application/json" \
-d '{
"appid": "appid",
"serverkey": "servicekey",
"username": "username-uniqueidentifier",
"device-package": "eyJkZXZpY2VfaWQiOiAidUs1QlhYUHpFK250SkUvcDFKM0VMY3JIU1V4MyIsICJleHAiOiAiQVFBQiIsICJtb2QiOiAiNjZmdk10d2lCKzZDM1RWVGVmWEovdDB4NU81K3hIYkJ0ZVBZQ2pxYkQ3WmdHdEY2NlBuZXhjMkdmV05Pcms4RDNsK2xOMzVjUHNZOE02dEN0WG5HU256S0loUEJ1NjZSWTZoV1Z0Y2FhUmdPbHIyNGdPQjA0MnRobmhnZjY3SHpRSllnZjE0SlRjcFFuc1VBazh4bjZHQmJ4Q2V1RTZ0S05oRlZSWmpETFE4VXY3V0taOXFlNmRTNm1IZURkMjZiemJqUXVkeEIwMDBJTGJqMkF5U3hwNFdqbk81c1JmTURxNkluZ0ZYMkRINGI5QUJuUTlONGJPQ0Y4UUNibnl0ZWwwYXhvcEhmL0RKbWJHd3U1N0kvV2t4N0YyZ3hxUlA0Z25XU0R5cWl3QXkwZEQ2NXp0QVJVWnNqNkViQjRsTi9xK2I4QmpHK3MxWTdxQjlIR09ZLzZRPT0ifQ=="  
}' \
https://sandbox.identos.com/api/v0/user/register

One Time Password

Coming soon!

Authenticating the User

Authentication allows access to IDENTOS functions such as encryption, decryption, and granting access to private keys. Authentication will not succeed unless a device has been registered.

User PIN

An optional feature, requiring the user to enter a PIN provides the second authentication factor (what the user knows) which helps protect the device’s private key at rest. You should request the PIN just in time to use it, and not keep it around longer than necessary.

Depending on the configuration of your app, a user supplied PIN may be required during steps such as registering a user device, authentication, or data encryption functions.

Example

/** 
authenticate

@params pin The users pin

@returns int 0=success, -1=failure
*/
authenticate: function(pin, successCallback, errorCallback);

Encryption Functions

Encryption functions include encryption of data, the decryption of data, and granting user access. These functions only succeed after the application has been successfully authenticated.

Interface

/**
encrypt

@param data(Base64) Base64 encoded string of the data
@param identifier (optional) Identifier to encrypt with

@return Array[Base64, String] encrypted_data & the identifier used
*/
encrypt: function (data, identifier, successCallback, errorCallback);

/**
decrypt

@param data(Base64) encoded string of the ciphertext

@return Array[Base64, String] encoded plaintext & the identifier used
*/
decrypt: function (data, successCallback, errorCallback);

/**
grantAccess

@param identifier Identifier being modifierd
@param user_ids :Array(String) Array of ids to add to read/grant list

@return void
*/
grantAccess: function (identifier, userids, successCallback, errorCallback) ;

Errors

IDENTOS uses response codes to indicate sucess or failure of a request

Response Codes

Success = 0,
Failed = -1,
InvalidState = -2,
InvalidParameter = -29,
DeviceUnregistered = -50,
InvalidPin = -101,
WrongPin = -102,
NoInternetAccess = -200