NAV
java

Introduction

Welcome to the iDenKey developer's guide! This guide provides comprehensive information on integrating and utilizing our technology "iDenKey" for risk based authentication in your application. To get started, you'll need to request the license from us. To request the license, kindly email us at info@toppangravity.com. Once you receive the license key and complete the initial setup, you can begin using the services by following the provided guide.

We have language bindings in Java! You can view code examples in the dark area to the right. If you need any info, feel free to write us at info@toppangravity.com.

Server API

Server API request is by HTTP FORM POST to the following URIs:

HTML FORM POST example，it is to get server public key from the iDenKey Server

curl --location --request POST 'https://localhost:10000/GW/WSM' \
--header 'Content-Type: application/json' \
--header 'apiKey: API_Key' \
--data-raw '{
    "method": "svfGetPubKey",
    "channel": "TP"
    }’

 Return message is in JSON，example as below
{
 "returnCode": "0000",
 "returnMsg": ”Success”
}

- 0000:Normal
- Other:Depending on the method called

WSM vs WSI

Server APIs are categorized into

Authentication

Load License

The mobile app has to initialize and load the license to the SDK in order to use it.

-(NSDictionary*)mobfSetConfigWithLicName:(NSString*)licName

Parameter Data Type Description
licName NSString License filename
Response Note
rspCode NSString Response code
rspMsg NSString Response message

Registration

mobfRegister

private void mobfRegister(String rsaPubKey, String regReq, int replace,int verifyType, byte[] encUIData, com.idgate.idenkeyfidoplus.sdk.kit.FinishedListener finishedListener) {
        IDenKeyMgr.getInstance().mobfRegister(rsaPubKey, regReq, replace, verifyType, encUIData, finishedListener);
    }

Register Device

-(void)mobfRegisterWithRSAPubKey:(NSString*)rsaPubKey andRegReq:(NSString*)regReq andEncUIData:(NSData*)encUIData andFinishedBlock:(finishedBlock)finishedBlock

Parameter Data Type Description Data Source
rsaPubKey NSString Server public key iDenKey server
regReq NSString Registration request from server iDenKey server
encUIData NSData Encrypted bio hash data(auth type=1), SDK UI object return(auth type=2, 3) or nil(auth type=0) for authentication. SDK. Return from mobfEncryptUI or UI object callback
finishedBlock Block
Block Response Note
rspCode NSString Response code  
rspMsg NSString Response message  
encRegRes NSString Encrypted registration response Send back to server API: svfGetRegRequest

mobfRegSuccess

private void mobfRegSuccess(String encRegRes, int verifyType, byte[] encUI, com.idgate.idenkeyfidoplus.sdk.kit.FinishedListener finishedListener ) {
        //Intent q1 = new Intent(getActivity(), BiometricActivity.class);
        //startActivity(q1);
        System.out.println("in mobfRegSuccess encRegRes:"+encRegRes);
        System.out.println("in mobfRegSuccess verifyType:"+verifyType);
        System.out.println("in mobfRegSuccess encUI:"+bytesToHexStr(encUI));
        IDenKeyMgr.getInstance().mobfRegSuccess(encRegRes, verifyType, encUI, finishedListener);
    }

Inform SDK successful registration to finish the registration process

-(void)mobfRegSuccessWithEncRegResult:(NSString*)encRegResult andEncUIData:(NSData*)encUIData andFinishedBlock:(finishedBlock)finishedBlock
Parameter Data Type Description Data Source
regReqResult NSString Server registration result iDenKey Server
encUIData NSData Encrypted bio hash data(auth type=1), SDK UI object return(auth type=2, 3) or nil(auth type=0) for authentication. Depending on which auth type is used. SDK. Return from mobfEncryptUI or UI object callback
finishedBlock Block Callback  
Response Note
rspCode NSString Response code  
rspMsg NSString Response message  
idgateID NSString Device idgateID  
       

svfGetRegRequest

OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json; charset=UTF-8");
RequestBody body = RequestBody.create(mediaType, "{\"channel\":\"your_channel_value_here\"}");

Request request = new Request.Builder()
        .url("your_iden_key_url_here/svfGetRegRequest")
        .post(body)
        .addHeader("Content-Type", "application/json; charset=UTF-8")
        .addHeader("apiKey", "API_Key")
        .build();

Response response = client.newCall(request).execute();
System.out.println(response.body().string());

Request for device registration

POST https://{{ServerURL}}/svfGetRegRequest

Parameter Data Type Description Data Source
method String ”svfGetRegRequest” Client
channel String(30) For business application to specify a business channel Client
Return
returnCode String Return code
returnMsg String Return message
regReq String { "regReqInner": "[{\"header\":{\"upv\":{\"major\":1,\"minor\":0},\"op\":\"Reg\",\"appID\":\"http://localhost:8080/fidouaf/v1/public/uaf/facets\",\"serverData\":\"c295dFFLYUMteDBMZ1lpcllFMHNYb mE1eXctNGVqZTlNSnk1U0twMm8yMC5NVFkyTnpVMU1EZ3pOekU1TncuZFhObGNrNWhiV1V3TWcuU2tSS2FFcEVSWGRLUlhoc1dURmtjR0pHY0ZSWldFcFBWRzF6TVdKNlNYVlJWbG95V2xo Vg\"},\"challenge\":\"JDJhJDEwJExlY1dpbFpTYXJOTms1bzIuQVZ2ZXU\",\"username\":\"userName02\",\"policy\":{\"accepted\":[[{\"aaid\":[\"5431#3280\"]}],[{\"aaid\":[\"FFFF#test1\"]}] ,[{\"aaid\":[\"FFFF#test2\"]}]]}}]", "idgateID": "1000000001"}
serverPubKey String Server’s public key

svfSendRegResponse

OkHttpClient client = new OkHttpClient();

String json = "{\"deviceInfo\":{\"deviceIP\":\"deviceIP\",\"deviceOs\":\"os 5\",\"appVer\":\"1.0.0\",\"deviceLabel\":\"APPLE\",\"deviceModel\":\"Google Pixel 4a (5G)\",\"deviceName\":\"iPhone4\",\"userID\":\"userID2\",\"deviceOsVer\":\"13.2\"},\"method\":\"svfSendRegResponse\",\"channel\":\"TP\",\"transactionID\":\"0f65f10b-525f-48eb-a7ba-f668c342bc07\",\"encRegRes\":\"eyJrZX... jEifQ==\"}";

MediaType mediaType = MediaType.parse("application/json; charset=UTF-8");
RequestBody body = RequestBody.create(mediaType, json);

Request request = new Request.Builder()
        .url("your_iden_key_url_here")
        .post(body)
        .addHeader("Content-Type", "application/json; charset=UTF-8")
        .addHeader("apiKey", "API_Key")
        .build();

Response response = client.newCall(request).execute();
System.out.println(response.body().string());

Confirmation for device registration

POST https://{{ServerURL}}/svfSendRegResponse

Parameter Data Type Description Data Source
method String ” svfSendRegResponse” Client
channel String(30) For business application to specify a business channel Client
transactionID String(64) Transaction Id for auditing purpose Client
encRegRes JSON String Encrypted registration response from SDK SDK, returned from mobfRegister
deviceInfo JSON String Device info to record, to be provisioned by the mobile app
{
"deviceLabel":"xxx", //Manufacturer
"deviceModel":"xxx", //Model
"deviceOS":"xxx", //Device OS "deviceName":"xxx", //Device friendly name "userID":"xxx", //
"deviceOsVer":" ",// Device OS
"appVer":" "// App version
}		 Client
Return
returnCode String Return code
returnMsg String Return message
encRegResult String Encrypted registration result returned by iDenKey Server

Set authType

Auth Type

authType is the user authentication method that can be triggered in the mobile app with SDK.

authType can be:
The authType to enable or disable
eAuthType_OneClick: Quick login (0)
eAuthType_Biometrics: App own UI or device biometrics (1)
eAuthType_Pattern: SDK UI Pattern (2)
eAuthType_PIN: SDK UI PIN (3)

Verify Type

iDenKey Fido SDK support multiple key pairs for authentication for different business purposes.

verify Type can be:
eVerifyType_All – All verify types
eVerifyType_OfflineOTP – offlineotp(0)
eVerifyType_Login - login(1)
eVerifyType_Transaction – transaction signing(2)

mobfGetIdgateID


 private String mobfGetIdgateIDs() {
        Bundle temp = IDenKeyMgr.getInstance().mobfGetIdgateIDs();
        return bundleToJSON(temp);
    }

To get idgate Id

-(NSDictionary*)mobfGetIdgateID

Parameter Data Type Description Data Source
- - -  
NSDictionary Response Note
rspCode NSString Response code  
rspMsg NSString Response message  
idgateID NSString idgate Id  

mobfSetAuthType

private void mobfSetAuthType(String rsaPubKey, String serverTime, int authType,boolean isEnabled,int verifyType,byte[] encUI, com.idgate.idenkeyfidoplus.sdk.kit.FinishedListener finishedListener) {
        IDenKeyMgr.getInstance().mobfSetAuthType(rsaPubKey, serverTime, authType, isEnabled,verifyType, encUI, finishedListener);
    }

To set auth type to the SDK

-(void)mobfSetAuthTypeWithRSAPubKey:(NSString*)rsaPubKey andServerTime: (NSString*)serverTime andAuthType:(eAuthType)authType andIsEnabled: (BOOL)isEnabled andVerifyType:(eVerifyType)verifyType andEncUIData:(NSData* _Nullable)encUIData andFinishedBlock:(finishedBlock)finishedBlock

Parameter Data Type Description Data Source
rsaPubKey NSString Server’s Public Key iDenKey Server
serverTime NSString svfGetPubKeyNTime returned from Server iDenKey Server
authType eAuthType The authType to enable or disable Client
isEnabled BOOL YES: Enabled NO: Disabled Client
verifyType eVerifyType To specify particular key pair to use eVerifyType_Login - login(1) eVerifyType_Transaction – transaction signing(2) Client
encUIData NSData Encrypted bio hash data(auth type=1), SDK UI object return(auth type=2, 3) or nil(auth type=0) for authentication. Depending on which auth type is used SDK. Return from mobfEncryptUI or UI object callback
finishedBlock Block  Callback                                                                                                                                                                         
Block Response Note
rspCode NSString Response code  
rspMsg NSString Response message  
encSettingData NSString Encrypted setting data To be used in Server API: svfSetAuthType

This API is to set and toggle the auth type to the SDK.

For the case of auth Type = 1, it is either to use the local biometric authentication or the mobile app to handle it on its own UI. The SDK will not updated the stored bio hash, the API: mobfUpdateBioHash should be called subsequently to do so to update the bio hash in the SDK.

mobfEncryptUI

 private void mobfEncryptUI(String uiHash, int authType, com.idgate.idenkeyfidoplus.sdk.kit.FinishedListener finishedListener ) {
        IDenKeyMgr.getInstance().mobfEncryptUI(uiHash,authType,finishedListener);
    }

To generate encUIData for App using its own UI

-(void)mobfEncryptUI:(NSString*)uiHash andAuthType:(eAuthType)authType andFinishedBlock:(finishedBlock)finishedBlock

Parameter Data Type Description Data Source
uiHash NSString The authentication hash generated by the App for this authType Client
authType eAuthType eAuthType_Biometrics: App own UI or device biometrics (1) SDK. Return from mobfEncryptUI or UI object callback
finishedBlock Block  Callback                                                                                                                           
Block Response Note
rspCode NSString Response code  
rspMsg NSString Response message  
encUIData NSData Encrypted hash data for authentication  

mobfUpdateBioHash

To update bio hash to the SDK for the case of auth type = 1

-(void)mobfUpdateBioHashWithVerifyType:(eVerifyType)verifyType andEncUIData: (NSData* _Nullable)encUIData andFinishedBlock:(finishedBlock)finishedBlock

Parameter Data Type Description Data Source
verifyType eVerifyType To specify particular key pair to use eVerifyType_Login - login(1) eVerifyType_Transaction – transaction signing(2) Client
encUIData NSData Encrypted bio hash data(auth type=1), SDK UI object return(auth type=2, 3) or nil(auth type=0) for authentication. Depending on which auth type is used. SDK. Return from mobfEncryptUI or UI object callback
finishedBlock Block  Callback                                                                                                                           
Block Response Note
rspCode NSString Response code  
rspMsg NSString Response message  

svfGetPubKeyNTime

OkHttpClient client = new OkHttpClient();

        String json = "{\"method\":\"svfGetPubKeyNTime\",\"channel\":\"TP\"}";

        MediaType mediaType = MediaType.parse("application/json; charset=UTF-8");
        RequestBody body = RequestBody.create(mediaType, json);

        Request request = new Request.Builder()
                .url("your_iden_key_url_here")
                .post(body)
                .addHeader("Content-Type", "application/json; charset=UTF-8")
                .addHeader("apiKey", "API_Key")
                .build();

        Response response = client.newCall(request).execute();
        System.out.println(response.body().string());

To get server’s RSA public key

POST https://{{ServerURL}}/svfGetPubKeyNTime

Parameter Data Type Description Data Source
method String ”svfGetPubKeyNTime Client
channel String(30) For business application to specify a business channel Client
Return
String Return code  
String Return message  
String Server’s public key  
String Server’s time in millisecond ‘s  

svfSetAuthType

OkHttpClient client = new OkHttpClient();

String json = "{\"method\":\"svfSetAuthType\",\"channel\":\"TP\",\"idgateID\":\"1000010455\",\"encSettingData\":\"eyJrZ...YifQ==\"}";

MediaType mediaType = MediaType.parse("application/json; charset=UTF-8");
RequestBody body = RequestBody.create(mediaType, json);

Request request = new Request.Builder()
        .url("your_iden_key_url_here")
        .post(body)
        .addHeader("Content-Type", "application/json; charset=UTF-8")
        .addHeader("apiKey", "API_Key")
        .build();

Response response = client.newCall(request).execute();
System.out.println(response.body().string());

To enable/disable auth type

POST https://{{ServerURL}}/svfSetAuthType

Parameter Data Type Description Data Source
method String ” svfSetAuthType” Client
channel String(30) For business application to specify a business channel Client
idgateID String(38) idgate Id Client
encSettingData String Encrypted setting data returned by SDK SDK
Return
returnCode String Return code
returnMsg String Return message

Authentication

mobfAuthentication

 private void mobfAuthentication(String rsaPubKey, String authReq, int verifyType, byte[] encUI, String txnID, com.idgate.idenkeyfidoplus.sdk.kit.FinishedListener finishedListener) {
        System.out.println("encUI "+bytesToHexStr(encUI));
        System.out.println("verifyType="+verifyType);
        IDenKeyMgr.getInstance().mobfAuthentication(rsaPubKey, authReq, verifyType, encUI, txnID, finishedListener);
    }

To generate a signature for authentication

-(void)mobfAuthenticationWithRSAPubKey:(NSString*)rsaPubKey andEncAuthReq:(NSString*)encAuthReq andEncUIData:(NSData* _Nullable)encUIData andBankTxnID:(NSString*)bankTxnID andFinishedBlock:(finishedBlock)finishedBlock

Parameter Data Type Description Data Source
rsaPubKey NSString Server’s Public Key iDenKey Server
encAuthReq NSString svfGetAuthRequest returned from Server iDenKey Server
encUIData NSData Encrypted UI Data returned by SDK nil for auth type=0 SDK
bankTxnID NSString Transaction Id for auditing Client
finishedBlock Block Callback
Block Response Note
rspCode NSString Response code  
rspMsg NSString Response message  
encVerifyTxnData NSString Encrypted signature for authentication  

svfGetAuthRequest

OkHttpClient client = new OkHttpClient();

String json = "{\"title\":\"Transaction authentication\",\"idgateID\":\"1000010275\",\"authType\":\"1\",\"txnData\":\"{\\\"TxnDetail\\\":[{\\\"item1\\\":\\\"Transaction Id\\\",\\\"item2\\\":\\\"Transaction time\\\",\\\"item3\\\":\\\"Transaction amount\\\",\\\"value1\\\":\\\"Transfer\\\",\\\"value2\\\":\\\"2020/10/15\\\",\\\"value3\\\":\\\"10,000\\\"}],\\\"Timestamp\\\":\\\"1579195645621\\\"}\",\"keyType\":\"0\",\"method\":\"svfGetAuthRequest\",\"channel\":\"TP\"}";

MediaType mediaType = MediaType.parse("application/json; charset=UTF-8");
RequestBody body = RequestBody.create(mediaType, json);

Request request = new Request.Builder()
        .url("your_iden_key_url_here")
        .post(body)
        .addHeader("Content-Type", "application/json; charset=UTF-8")
        .addHeader("apiKey", "API_Key")
        .build();

Response response = client.newCall(request).execute();
System.out.println(response.body().string());

To generate authentication request

POST https://{{ServerURL}}/svfGetAuthRequest

Parameter Data Type Description Data Source
method String ” svfGetAuthRequest” Client
channel String(30) For business application to specify a business channel Client
idgateID String(38) idgate Id Client
authType String(4) Auth type Client
keyType String(1) Key pair to use (0 / 1 / 2) Client
title String(100) Transaction title to show Client
txnData String Transaction details to show Client
Return
returnCode String Return code
returnMsg String Return message
encAuthReq String Encrypted authentication request for SDK to sign
encTxnData String Encrypted transaction details for SDK to decrypt for user’s confirmation and authorization
serverPubKey String Server’s public key
txnID String (24) Transaction Id for auditing

svfSendAuthResponse

OkHttpClient client = new OkHttpClient();

String json = "{\"bankTxnID\":\"6C68306E-B6C2-43C6-9A13-FB677F93554E\",\"method\":\"svfSendAuthResponse\",\"channel\":\"TP\",\"idgateID\":\"1000010427\",\"encVerifyTxnData\":\"eyJrZXk...3In0=\"}";

MediaType mediaType = MediaType.parse("application/json; charset=UTF-8");
RequestBody body = RequestBody.create(mediaType, json);

Request request = new Request.Builder()
        .url("your_iden_key_url_here")
        .post(body)
        .addHeader("Content-Type", "application/json; charset=UTF-8")
        .addHeader("apiKey", "API_Key")
        .build();

Response response = client.newCall(request).execute();
System.out.println(response.body().string());

To verify transaction signature

POST https://{{ServerURL}}/svfSendAuthResponse

Parameter Data Type Description Data Source
method String ”svfSendAuthResponse” Client
channel String(30) For business application to specify a business channel Client
idgateID String(38) idgate Id Client
bankTxnID String(24) Transaction Id for auditing Client
encVerifyTxnData String Encrypted signature for authentication SDK
Return
String Return code  
String Return message  
String(24) Transaction Id for auditing  
String Current error count：”1”  
String Authentication result {  

De-Registration

mobfDeregister

To de-register device. It generates the response for server and removes data from SDK. Once it is called, it can not be undone.

-(void)mobfDeregisterWithRSAPubKey:(NSString*)rsaPubKey andServerTime:(NSString*)serverTime andFinishedBlock:(finishedBlock)finishedBlock

Parameter Data Type Description Data Source
rsaPubKey NSString Server’s Public Key iDekKey Server
serverTime NSString Server’s Time iDekKey Server
finishedBlock Block Callback  
Block Response Note
rspCode NSString Response code  
rspMsg NSString Response message  
encDeregData NSString Encrypted de-registration data to be sent back to  

mobfDeregSuccess

 private void mobfDeregSuccess(int verifyType, com.idgate.idenkeyfidoplus.sdk.kit.FinishedListener finishedListener) {
        System.out.println("inside function");
        IDenKeyMgr.getInstance().mobfDeregSuccess(verifyType,finishedListener);
    }

To de-register device on the mobile side. It removes data from SDK. Once it is called, it can not be undone.

-(void)mobfDeregSuccessWithVerifyType:(eVerifyType)verifyType andFinishedBlock:(finishedBlock)finishedBlock

Parameter Data Type Description Data Source
verifyType eVerifyType To specify the verify type to de-register eVerifyType_All – All verify types eVerifyType_OfflineOTP – offlineotp(0) eVerifyType_Login - login(1) Client
finishedBlock Callback
Block Response Note
rspCode NSString Response code  
rspMsg NSString Response message  

svfSendDeregResponse

OkHttpClient client = new OkHttpClient();

String json = "{\"method\":\"svfSendDeregResponse\",\"channel\":\"TP\",\"idgateID\":\"1000010455\",\"encDeregData\":\"eyJrZ...YifQ==\"}";

MediaType mediaType = MediaType.parse("application/json; charset=UTF-8");
RequestBody body = RequestBody.create(mediaType, json);

Request request = new Request.Builder()
        .url("your_iden_key_url_here")
        .post(body)
        .addHeader("Content-Type", "application/json; charset=UTF-8")
        .addHeader("apiKey", "API_Key")
        .build();

Response response = client.newCall(request).execute();
System.out.println(response.body().string());

To de-register device from server

POST https://{{ServerURL}}/svfSendDeregResponse

Parameter Data Type Description Data Source
method String ”svfSendDeregResponse” Client
channel String(30) For business application to specify a business channel Client
idgateID String(38) idgate Id Client
encDeregData String Encrypted de-registration data from SDK SDK
Return
returnCode String Return code
returnMsg String Return message

- WSI APIs -

Lock Device

svLockDevice

To lock device

Parameter Data Type Description Data Source
method String ”svLockDevice” Client
channel String(30) For business application to specify a business channel Client
idgateID String(38) idgate Id Client
Return
memberStatus String Device status
returnCode String Return code
returnMsg String Return message

Unlock Device

svUnLockDevice

To unlock device

Parameter Data Type Description Data Source
method String ”svUnLockDevice” Client
channel String(30) For business application to specify a business channel Client
idgateID String(38) idgate Id Client
Return
memberStatus String Device status
returnCode String Return code
returnMsg String Return message

Get Device Status

svGetDeviceStatus

To get device status

Parameter Data Type Description Data Source
method String ”svUnLockDevice” Client
channel String(30) For business application to specify a business channel Client
idgateID String(38) idgate Id Client
Return
failCount String Consecutive error count
memberStatus String Device status
type String Enabled auth type
deviceLabel String Device label
deviceModel String Device model
deviceOS String Device OS
returnCode String Return code
returnMsg String Return message

Force Device De-registration

svDeRegister

To de-register device from server

Parameter Data Type Description Data Source
method String svDeRegister Client
channel String(30) For business application to specify a business channel Client
idgateID String(38) idgate Id Client
Return
memberStatus String Device status
returnCode String Return code
returnMsg String Return message

Device Status

java