Encryption as a Service

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

1.  Create a jniLibs directory in your project folder (make the path src/main/jniLibs)
2.  Move the identos folders containing the .so files into the jniLibs directory.
3.  Create a libs directory in your project folder if it doesn't already exist (make the path ./libs)

compile fileTree(dir: 'src/main/jniLibs', include: ['*.jar'])M
This will allow you to access the IDENTOS interfaces.
4.  Under the dependencies section of your build.gradle file add this line
 compile fileTree(dir: 'libs', include: ['*.jar'])

This will allow you to access the IDENTOS interfaces

1.  Add the follow static call in your android project so that the identos libraries are loaded before making any identos sdk calls

 static {
     System.loadLibrary("identos");
 }

Initialize the SDK

You will need your app's clientKey and appId. They can be found through the trusted server's portal under your app's admin page.

/**
Initialize the Identos SDK

This is always the first call you make to the SDK

@param appId - Your app id, provided by Identos

@param clientKey - Your client key, provided by Identos

@param version - Your app version, allows different security policies based on version

@param path – app directory, this is where identos generated files are kept
@return int

*/

// Application identifier, provided by Identos
private static String IdentosAppId = "appId";
// Client Key, provided by Identos
private static String IdentosClientKey = "appKey";
//Version Number
private static String IdentosVersionNumber = "1.0.0";
//path
private static string path = context.getFilesDir().getAbsolutePath();

int initializeStatus = (int)Identos.instance.initialize(IdentosAppId, IdentosClientKey, IdentosVersionNumber, false, path);

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.

In the Client Application

Register Device Token

/**
 Creates a string that a backend application can use to register this device with the IDENTOS Server

 This token is available after the very first authentication, and after online initialize on subsequent runs

 @return Registration token to pass to backend
 */
Identos.instance.registration_token();

Unregister

/**
 Removed device information from storage
 to continue using the sdk, this device will require registration
 */
Identos.instance.unregisterDevice()

In the Server Application

See API Documentation for details

Authentication

Authentication is done after an initialization call to authenticate with the trusted server. If your device is unregistered, it will both authenticate the device and create a temporary user, returning a registration_token. The application's server can transfer this device to a real user to complete registration using the user/register endpoint with this registration_token.

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

/*

End Session

** Resets to before the initialization */ Identos.instance.closeSession();

Identos Client

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

Encrypt data with a key retrieved from the trusted server.

/**
                Encrypt a byte[]
                @param bytes Data to encrypt
                @param identifier Optional key identifier
                @return identos_return_data
            */
            identos_return_data ret = Identos.instance.encrypt(bytes, identifier);

Decrypt

Decrypt data previously encrypted by the sdk.

/**
decrypt 

@param data(Base64) encoded string of the ciphertext 

@return Array[Base64, String] encoded plaintext & the identifier used
*/
byte[] unencodedResult = Base64Decode(ret.getData64());
String decryptedAsHex = ByteArrayToString(unencodedResult);
/**
    Convert byte array to String
    @param a byte array
    @return formatted String
*/
public static String ByteArrayToString(byte[] a)
{
   StringBuilder sb = new StringBuilder(a.length * 2);
   for(byte b: a)
      sb.append(String.format("%02x", b & 0xff));
   return sb.toString();

}

/**
    Decode the Base64 encoded data
    @param String encoded data
    @return byte[] decoded data
*/
public static byte[] Base64Decode(String base64EncodedData)
{
    return Identos.Base64Decode(base64EncodedData);
}

Grant

Grant a user access to an en/decryption key.

/**

    @param identifier
    @param uid
    @return int
*/
int status = Identos.instance.grant(identifier, uid);

Sign

Sign arbitrary data with this users private key

/**
* @param data, data message to be signed
* @return identos_return_data       
*/
identos_return_data signresult = Identos.instance.sign(data);

Verify

Verify a message signed by the Identos SDK.

/**
* @param signature64, signature for signed message
* @param data, signed message
* @return int, verification status
*/
int verifyStatus =  Identos.instance.verify(signature64, data);

Federated Identity (Auth)

Register Push

This registers a push token (firebase, apns, etc) with the Identos Server.

/**
    Register the device push token with IDENTOS Server

    @param token
    @param type
*/

Identos.instance.registerPushToken(pushToken, type);

Join External Application's Session

This allows a device to perform a federated login with an external application using a join Otp.

/**
 Authenticates the user to an external application

 @note will also authenticate locally if required

 @param userPin The PIN used during device registration
 @param joinOTP The AUTH session joinOTP
 */
Identos.instance.authenticate(userPin, joinOtp);

Get Auth Token

After each successful authentication with a join opt, an auth opt token is available. This can be displayed to the user for manually completing an external login. This is neccessary only if the application does not use the callback functionality with the trusted server.

/**
 @return auth token to be manually entered to backend app
 */
 Identos.instance.auth_otp()

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