Encryption as a Service SDK for iOS

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. Drag the IdentosSDK.framework into your project

2. Drag the openssl.framework into your project

3. Drag the fidouaf.framework into your project

4. Link Frameworks: LocalAuthentication and UserNotifications
   • Go to the Project->TARGETS->Build Phases->Link Binary With Libraries.Go to the Project->TARGETS->Build Phases->Link Binary With Libraries.
   • Press the plus in the lower left of the list.
   • Add LocalAuthentication.framework.

Initialization

/**
 Initialize the SDK 

 @param config  The app config to use

 @see +initialize:completion:
 */
+(void)initialize:(IdentosConfiguration*)config;

/**
 Initialize the SDK w completion

 @param config      The app config to use
 @param completion  Completion block
 */
+(void)initialize:(IdentosConfiguration*)config completion:(IDInitializeCompletion)completion;

Completion

/**
 Adds a completion block to the initialize call

 If more than one block is submitted, they will be called in order upon completion
 If initialization has already completed, the block will be called immediatly (before method returns)
 */
+(void)onInitialize:(IDInitializeCompletion)completion;

Status

/**
 Has the SDK completed initialization
 */
+(BOOL)hasInitialized;

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

 

Device Registration 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
 */
+(NSString*)deviceRegistrationToken;

 

Unregister

 

/** Removed device information from storage
 to continue using the sdk, this device will require registration
 */
+(void)unregisterDevice;   

 [IdentosRegistration unregisterDevice];

In the Server Application

See API Documentation for details

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.

Interface

/**
 On biometric enabled devices (touchID/faceID) a passphrase may not be required.
 If this returns authenticationRequiresPassphrase == NO, you may pass pin == nil and Identos will prompt for native biometric
 */
+(BOOL)authenticationRequiresPassphrase;


/**
 Authenticates the user of the SDK
 
 @param userPin The PIN used during device registration
 @param queue   The queue to run the compeltion block on, if nil, defaults to main queue
 @param completion  Authentication completion block
 */
+(void)authenticateWithPin:(NSString*)userPin
             completionQueue:(dispatch_queue_t)queue
                  completion:(void(^)(IdentosClient *client, NSError *error))completion;

Example


    [Identos authenticateWithPin:pin completionQueue:nil completion:^(IdentosClient *client, NSError *error) {
       

        if (error != nil) {
            // there was an error

        }{
        else {

        }
        
    }];

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

@interface IDReturn : NSObject
@property (nonatomic, strong) NSData * data;
@property (nonatomic, strong) NSString * identifier;
@property (nonatomic, strong) NSError * error;


@end

@interface IdentosClient : NSObject


/**
 *  The Identos Client Instance
 *
 *  @return nil, unless in an Authenticated State
 */
+(instancetype)sharedClient;


#pragma mark - Crypto
/**
 Encrypts some data with a key retrieved from the trusted server
 
 @param data                The data to encrypt
 @param resourceIdentifer   The optional resouce identifier associated with the data. Use this when locally encrypting data (or derived data) from a previous networkRequest or decrypt method call
 @param completion          Decryption return block
 
 @see decrypt:password:completion:
 @see networkRequest:body:identifier:completion:
 */
-(IDReturn*)encrypt:(NSData*)data
        identifier:(NSString*)resourceIdentifer;

/**
 Decrypts some data that was previously encrypted by the sdk
 
 @param e_data              The data to decrypt
 @param completion          Decryption return block
 */
-(IDReturn*)decrypt:(NSData*)e_data;


/**
 Sign arbitrary data with this users private key

 @param data The data to sign

 @return Signed data package
*/
-(NSData*)sign:(NSData*)data;

/**
 Verify a signature created by the SDK sign function

 @param signature Signature to verify
 @param data Data signature was made on

 @return Signature matches data and was made by a registered identos user
*/
-(BOOL)verify:(NSData*)signature onData:(NSData*)data;

#pragma mark access control
/**
 Grants access to a resourceIdentifier from a group of users
 Will fail if the authenticated users doesn't have access to the specified resource
 
 @param toData      The encrypted data to give access to
 @param userIds     The users ids to grant access to
 
 @todo: add success/failure indication
 */
-(BOOL)grantAccess:(NSData*)toData forUserIds:(NSArray*)userIds;


/**
 Grants access to a resourceIdentifier from a group of users
 Will fail if the authenticated users doesn't have access to the specified resource
 
 @param resourceIdentfier   The identifier to give access to
 @param userIds     The users ids to grant access to
 
 @todo: add success/failure indication
 */
-(BOOL)grantAccessToResource:(NSString*)resouceIdentifier forUserIds:(NSArray*)userIds;

Derived Credential Functions

Derived Credential functionality includes generation of a new elliptic curve (EC) keypair, exporting the public key, signing data, and revoking an existing keypair. These functions only succeed after the application has been successfully authenticated, with the exception of the SecureEnclave type on iOS, which leverage's device hardware to protect the private key.

Types

enum
{
    IdentosDerivedCredentialTypeEC = 0,
    IdentosDerivedCredentialTypeSECURE_ENCLAVE, // ios only
    IdentosDerivedCredentialTypeCOUNT,
};
typedef int IdentosDerivedCredentialType;

Interface

/**
 Create a new DC with the given type
 
 @param type
 
 @return handle for the DC, or nil if failed
 */
+(NSString*)createDerivedCredential:(IdentosDerivedCredentialType)type;

/**
 Revoke (delete) a DC
 
 @param handle
 
 @return YES if deleted
 */
+(BOOL)revokeDerivedCredential:(NSString*)handle;

/**
 Get the PEM representation of a DC
 
 @param handle
 
 @return PEM string or nil
 */
+(NSString*)publicKeyForDerivedCredential:(NSString*)handle;

/**
 Sign some data with a DC
 
 @param handle DC to use
 @param data Data to sign
 
 @return signed data or nil
 */
+(NSData*)signWithDerivedCredential:(NSString*)handle toSign:(NSData*)data;

Federated Identity

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

Interface

/**
    Register the device push token with IDENTOS Server

    @param token
    @param type
*/
+(void)registerPushToken:(NSString*)token type:(IdentosPushTokenType)type;

/**
 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
 @param prompt  Optional, prompt to present for touchID
 @param queue   The queue to run the compeltion block on, if nil, defaults to main queue
 @param completion  Authentication completion block
 */
+(void)authenticateExternalApp:(NSString *)pin
                        joinOTP:(NSString*)joinOTP
                        prompt:(NSString*)prompt
               completionQueue:(dispatch_queue_t)queue
                    completion:(void(^)(IdentosClient *client, NSError *error))completion;

Errors

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

Response Codes

/**
 List of potential error codes
 */
enum {
    /**
     *  The submitted PIN was invalid (didn't meet length/format requirments)
     */
    IdentosErrorInvalidPin  = -101,
    
    /**
     *  The submitted PIN was valid, but incorrect
     */
    IdentosErrorWrongPin    = -102,
    
    /**
     *  A required request timed out, please try again
     */
    IdentosRequestTimedOut  = -1001,
    
    /**
     *  The method failed because the device was unregistered
     */
    IdentosDeviceUnregistered = -50,
    
    /**
     *  Device validation failed, and the application policy indicates a ERROR policy level
     */
    IdentosDeviceComprimised = -103,
    
    /**
     *  This method requires an internet connection
     */
    IdentosNoInternetAccess = -200,
    
    
    IdentosFailedSelectKey       = 201,
    IdentosFailedAES             = 202,
    IdentosFailedRSA             = 203,
    IdentosFailedBadInputData    = 204,
};
typedef int IdentosError;