This document is the reference guide for inWebo mAccess, the SDK product from inWebo Technologies. inWebo mAccess is an OTP generator library available in C, C# and Java. Any application implementing mAccess should be linked to an inWebo account that can be created online at http://www.inwebo.com. This library performs only internal computation on data in memory. The only system call is to get the time elapsed from 01/01/1970. Data types are simple:

  • int

  • string

The Booleans are coded as 'int' (0: false; !=0: true) Host: We will further call 'host', the application which is using this library.Functions may return errors. In each function's description we present the errors the function could return. There is an additional error (IW_ERR_OTHER) which could be returned by any function, but not in a normal behavior.

The Activation Code was formerly called "Secure Site ID" in some authentication tools or in the documentation.
Please note that a "Secure Site ID" refers to an activation code.

General Principles

Local storage

The host application must store locally the internal state of mAccess. This internal state is an ASCII string provides by the function IWStorageDataGet ().The implementation of this storage is system-dependent, and up to the developer to design.After each call to a library function, the host must call IWStorageDataChanged (), in order to find out if the internal state has changed. If this function returns a non-zero integer, the host must call IWStorageDataGet () and then update the local storage. When the host application starts, it must get the ASCII string stored locally and give it to the library using the function IWStorageDataSet ().

Synchronous or Asynchronous mode

Some mAccess library functions execute network calls, namely webservice calls, to query inWebo servers. And most mAccess webservice calls are divided in two steps, i.e. two functions, a start function and a finalize function.There are two different ways of implementing the webservice calls: synchronously or asynchronously. The code architecture of the host will vary according to the chosen mode.Note that on Windows Phone 8 and 8.1, all network calls MUST be asynchronous.Let's illustrate this with a dummy API action.

Synchronous mode

The host function myAction will execute the IWActionStart () function and will directly fetch the result of the webservice call. If the result of the IWActionStart() is successful it will then execute the IWActionFinalize ().

Function myAction (params) {

	Int result = IWActionStart (params)

	If (result == IW_ERR_OK) {

 		Int result = IWActionFinalize (otherParams);

  		%%//%%Handle final result here
	}
}
C#

Asynchronous mode

In this case the result of the webservice calls will be handled by callback functions which are passed to the start and finalize functions.

Function myActionStart (params) {

	IWActionStartAsync (params, myActionStartDone);

}

Function myActionStartDone (result) {

	If (result == IW_ERR_OK) {

		IWActionFinalizeAsync (params, myActionFinalizeDone);

	}

}

Function myActionFinalizeDone (result) {

	%%//%%Handle final result here

}
C#

Web services calls

mAccess uses platform dependent functions to call inWebo web services. These functions should be part of the host. mAccess code samples exposes such functions in each proposed language. You may use them as is or enhance them.

Synchronous mode

In this mode, the host code should contain only one function:

WebServiceCall: (string URL, int timeout) -> String
CODE

This function performs a GET request to a specific URL. The call is synchronous, and the timeout is given in milliseconds. The response is directly fetched inside the function. It consists of an XML document (as an ASCII string).

On success, the function will have to call IWSetWsBuffer () with the result (XML response). On failure, the function just returns.

Asynchronous mode

In this case the host code should contain two functions:The function executing the API webservice call:

WebServiceCall: (string URL, int timeout) -> Int
CODE

This function performs a GET request to a specific URL.The network call response is handled by a second function:

HandleWebServiceCallResult: (object result) -> Void
CODE

Depending on the platform implementing the mAccess library the way of declaring this handler function and the structure of the fetched result object may vary.The final API call result (which is normally a property or a field of the result object) is an XML Document (as an ASCII string).

On success the handler function will have to call IWSetWsBuffer () with the response. Then the function will have to execute the callback function (passed in argument of the mAccess API asynchronous function) with argument 0 (0 = success).

Typically:

IWSetWsBuffer (string response);

WSCallBack (0);
CODE

On failure:

  • The handler function will have to execute the callback function (passed in argument of the mAccess API asynchronous function) with argument 1 (1 = error).

WSCallBack (1);
CODE

Should I use online or offline OTP?

In order to generate an online OTP, mAccess will perform one or more webservice calls to inWebo servers. This mode is suitable for a connected application (online banking for instance), as the token will always be synchronized with inWebo Servers.For a non-connected application (VPN dialer, authenticator-type app), Offline OTP is recommended. In this case, an OTP will be generated without any network call. The drawback of this method is the possibility for the token to desynchronize.

Using mobile push notifications

If you plan to use mAccess within a mobile phone application, you may request your users to authenticate with their mobile phones via mobile push notifications. In this case, InWebo servers need to know the unique Device ID of the phone.Push notification mechanisms are different according to the platform the host is designed for: Microsoft, Apple, and Google, all have their own architecture and channels to send notifications. So the first prerequisite is to understand this mechanism platform per platform:

  • How do I get the unique user or device ID that is used within the notification mechanism of the platform to communicate with a given device

  • How do I handle notifications on the device, i.e. what is the format of the received notifications, how do I parse their content to extract variables, etc.

With regards to mAccess, your concerns are:

  • The unique identifier of the user or device that needs to be sent to inWebo servers via the IWPushRegistrationStart() function. It will allow inWebo to send push notifications to your App via the communication channels of the platform

  • The variables received inside the notifications that will be passed in argument in mAccess API push activation and authentication functions (activation code, transaction alias).

  • The notification platform used on the application site will depend on the DeviceOS you'll set via the IWSetDeviceOS() function and must match the mAccess push notification parameters you will set in the inWebo Admin console.

You will also have to fill in the "mAccess push notification parameters" section in the "Service Parameters" of your inWebo service: 

Firebase push notifications for iOS

Firebase push notifications are supported for iOS environment: you should set the deviceOS value to "firebase", using the IWSetDeviceOS function.

About notifications payload

In an application that integrates mAccess, the push notifications sent are from the "Message" class of Firebase. They contain payload data. Here are the push notifications payload details:

{
"CollapseKey":"",

"Data":{
    "serviceName":"",
    "deviceAlias":"",
    "action": "",
    "serviceid":"",
    "alias":""
},
"content_available": true

"From":"",
"MessageId":"",
"SenderId":"",
"SentTime":""
}
CODE
  • The CollapseKey is set in the inWebo administration console, in the service configuration.

  • The information sent by inWebo is in the "Data" object.

  • content_available is a boolean. When set to true, an inactive client app is awoken, and the data is sent through APNs as a silent notification and not through Firebase Cloud Messaging.

  • Firebase manages the following data: "From", "MessageId", "SenderId", "SentTime"

Find more information in the Firebase Reference documentation: https://firebase.google.com/docs/cloud-messaging/http-server-ref

Particular case: two applications

To have two applications on the same service, which receive push notifications, you should:

  1. Use the Firebase notifications → change the deviceOS value to "firebase", using IWSetDeviceOS in C.

  2. Set push notifications in the Admin Console > Service parameters tab > "mAccess push notification parameters" > Firebase → leave the parameters “Notification Collapse Key” and “Application Package Name” fields empty, so all applications will receive the notifications.

API

This section describes the exhaustive list of primitives included in mAccess.

Error codes

IW_ERR_OK

0

no error

IW_ERR_NETWORK

1

network or server unreachable

IW_ERR_CODE

2

The Activation code is incorrect

IW_ERR_SN

3

one argument does not have the right syntax

IW_ERR_ACCESS

4

access refused

IW_ERR_VERSION

5

version error

IW_ERR_BLOCKED

7

account is blocked

IW_ERR_STATE

8

internal state not correct

IW_ERR_NODEVICE

9

device is disabled or unknown

IW_ERR_NOCA

10

User must activate inWebo helium or inWebo Desktop Token before achieving this operation

IW_ERR_NOSRV

11

No service is available

IW_ERR_PINREUSED

12

the new password equals the previous one

IW_ERR_SYNCHROFAILED

13

the operation succeeded but it required a post-synchronization which failed

IW_ERR_FORBIDDEN

14

forbidden operation (due to activated state/blocked state/upgradable state)

IW_ERR_PINREFUSED

15

the password is refused (bad format)

IW_ERR_TIMEOUT

16

timeout expired between xxxStart and xxxFinalize

IW_ERR_BIOKEY

26

device is locked due to biokey errors

ERR_DESYNCHRONIZED

27

device desynchronized

IW_ERR_OTHER

999

any other error

Pin mode code

IW_PINMODE_NONE

0

no password is required (leave “”)

IW_PINMODE_CURRENT

1

current password is required

IW_PINMODE_NEW

2

a new password is required

IW_PINMODE_BIO

8

a biokey is required

IW_PINMODE_CURRENT | IW_PINMODE_BIO

9

a password OR biokey is required

Initialization and configuration

IWInit: (Boolean ma, string SN, string Data, func webcall, object user) -> void
CODE

Boolean ma is unused and should be set to 0 or false.You application may provide 2 strings: One should be linked to the device (Serial Number) and the other one to the installation (timestamp of an install directory). These strings should not change over the lifetime of your application. If they do, the application will be locked.webcall is the function that makes webservices calls. It is provided in the SDK as an example that you can customize.user is an object that you can pass. It can be used in callbacks when using Async functions.(warning) Please note that SN and Data parameters should be sent as ASCII strings.

IWVersionGet: () -> string
CODE

The library provides its version number, as a string

IWHostVersionSet: (string) -> int
CODE

The host provides its version number, as a string. In order to be compliant with inWebo convention, it needs to be formatted as: AppName-Version. Example: myApp-1.3.0

IWWsTimeoutSet: (int timeout) -> int
CODE

The host defines the timeout value for the web service calls, in millisecond.Returns always true.

IWWsServerSet: (string server) -> int
CODE

The host defines the server value for the web service calls, such as “https://www.myinWebo.com:443”.Returns always true.

IWLangSet: (string) -> void
CODE

The host provides the language (“fr” or “en”). This may be changed at runtime.

IWMaccessSet: (string) -> void
CODE

The host provides the mAccess ID associated to its service.

Storage

IWStorageDataChanged: () -> int
CODE

The library indicates whether the stored data has changed. When true, the host should call IWStorageDataGet () and update the locally stored data.

IWStorageDataGet: () -> string
CODE

The library returns the data to be stored locally. This string contains everything mAccess requires (keys, service description …). The host should not try to process this string: it should only store it locally.

IWStorageDataSet: (string data) -> int
CODE

The host provides the stored data to the library. This should be done only once, at initialization.May return IW_ERR_SN.

Information

IWMajorVersionRequired: () -> int
CODE

Returns 1 if a major version update is available and therefore required. The host should stop working.

IWNewVersionAvailable: () -> string
CODE

The library indicates whether a new version of the host is available. If no new version is available, it returns empty string. If a new version is available, it returns the name of this new version.Use IWMajorVersionRequired () to know whether this new version is major or minor.

IWNewVersionURL: () -> string
CODE

When IWNewVersionAvailable returns a non-empty string, this function will return a URL to get the new version. Else it will return empty string.

ShouldAskForMinorUpdate: () -> int
CODE

Returns 1 if a minor version update should be proposed to the user. After this function returns 1 once, it will always return 0.

IWIsActivated: () -> int
CODE

The library indicates whether the application is activated.

IWMustUpgrade: () -> int
CODE

The library indicates whether the application must upgrade first (the local data is from an old version).

IWIsBlocked: () -> int
CODE

The library indicates whether the device is blocked. If yes, it has to regenerate first.

IWServiceNb: () -> int
CODE

The library indicates the number of services.A typical mAccess implementation will return 1 (your mAccess is linked to only one service).

IWServiceName: (int i) -> string
CODE

The library indicates the name of the ith service.A typical call of this function in a mAccess implementation will be IWServiceName (0) as there will be only one service whose index in the service list is 0.

IWServiceLogo: (int i) -> string
CODE

The library indicates the URL of the PNG logo of the ith service.A typical call of this function in a mAccess implementation will be IWServiceLogo (0) as there will be only one service whose index in the service list is 0.

IWServiceDisabled: (int i) -> int
CODE

The library indicates whether the service is disabled or not. When disabled, it may be displayed as grayed, and should not be accessible.A typical call of this function in a mAccess implementation will be IWServiceDisabled (0) as there will be only one service whose index in the service list is 0.

IWPinMode: () -> int
CODE

The library indicates whether the password is required for the current operation. For example, this may be called after IWActivationStart () to know if the user has to define his password, or type in his existing one.May return:

IW_PINMODE_NONE

0

no password is required (leave "")

IW_PINMODE_CURRENT

1

current password is required

IW_PINMODE_NEW

2

a new password is required

IW_PINMODE_BIO

8

a biokey is required

IW_PINMODE_CURRENT | IW_PINMODE_BIO

9

a password OR biokey is required

IWSynchroJustDone: () -> int
CODE

The library indicates whether a full synchronization just occurred. If yes, it means that the list of services may have changed, as well as the list of logos.
The host may need to refresh its display and reload the logos from the net.

Synchronous mode

IWCheckStatus: () -> int
CODE

This function returns the server-side status of your mAccess instance. Use it for instance to check whether the device has been unlocked by an administrator or another device.May return:

IW_ERR_OK

0

no error device is not blocked

IW_ERR_NETWORK

1

network or server unreachable

IW_ERR_VERSION

5

version error

IW_ERR_BLOCKED

7

device is blocked

IW_ERR_NODEVICE

9

device is disabled or unknown

IW_ERR_FORBIDDEN

14

forbidden operation (due to activated state/blocked state/upgradable state)

Asynchronous mode

IWCheckStatusAsync: (function callback) -> int
CODE

This function returns the server-side status of your mAccess instance. Use it for instance to check whether the device has been unlocked by an administrator or another device.

Activation

Synchronous mode

IWActivationStart: (string code) -> int
CODE

The library starts the activation process. It will perform at least one webservice call.Returns an error code:

  • IW_ERR_OK: no error

  • IW_ERR_NETWORK: network error

  • IW_ERR_FORBIDDEN: device is already activated

  • IW_ERR_SN: syntax error for “code”

  • IW_ERR_VERSION: version error, user must upgrade the device (see IWNewVersionAvailable above)

A call to IWPinMode () will indicate which kind of password is required (current or new or biokey)

IWActivationFinalize: (string code, string pin, string name) -> int
CODE

The library finalizes the activation process. It will perform at least one webservice call.Returns an error code:

  • IW_ERR_OK: no error

  • IW_ERR_NETWORK: network error

  • IW_ERR_FORBIDDEN: device is already activated

  • IW_ERR_SYNCHROFAILED: the device is activated but not synchronized. Should propose to resynchronize.

  • IW_ERR_PINREFUSED: syntax error for “pin”

  • IW_ERR_CODE: bad code.

  • IW_ERR_SN: syntax error for “code”

  • IW_ERR_TIMEOUT: timeout since IWActivationStart

Asynchronous mode

IWActivationStartAsync: (string code, function callback) -> int
CODE

The library starts the activation process. It will perform at least one webservice call.Returns an error code:

  • IW_ERR_OK: no error

  • IW_ERR_NETWORK: network error

  • IW_ERR_FORBIDDEN: device is already activated

  • IW_ERR_SN: syntax error for “code”

  • IW_ERR_VERSION: version error, user must upgrade the device (see IWNewVersionAvailable above)

A call to IWPinMode () will indicate which kind of password is required (current or new)

IWActivationFinalizeAsync: (string code, string pin, string name, function callback) -> int
CODE

The library finalizes the activation process. It will perform at least one webservice call.Returns an error code:

  • IW_ERR_OK: no error

  • IW_ERR_NETWORK: network error

  • IW_ERR_FORBIDDEN: device is already activated

  • IW_ERR_SYNCHROFAILED: the device is activated but not synchronized. Should propose to resynchronize.

  • IW_ERR_PINREFUSED: syntax error for “pin”

  • IW_ERR_CODE: bad code.

  • IW_ERR_SN: syntax error for “code”

  • IW_ERR_TIMEOUT: timeout since IWActivationStart

Set Biometric Key

If you choose to implement biometric factors in you mobile application, you will need to use the following functions in order to manipulate biometric keys.

Synchronous mode

SetBiokeyStart () -> int
CODE

Returns an error code:

  • IW_ERR_OK: no error

  • IW_ERR_NETWORK: network error

  • IW_ERR_FORBIDDEN: device is not activated or not blocked or to be upgraded

  • IW_ERR_NODEVICE: the device is unknown or has been permanently disabled

  • IW_ERR_VERSION: version error, user must upgrade the device (see IWNewVersionAvailable above)

A call to IWPinMode () will indicate which kind of password is required (current or none)

SetBiokeyFinalize (string biokey, string pin) -> int
CODE

The 'biokey' is a string generated by the application. The 'pin' code is the pincode of the user or an empty string for a service without pin. In the case of a service without pin, it is not possible to call this function repeatedly to change the Biokey.Returns an error code:

  • IW_ERR_OK: no error

  • IW_ERR_NETWORK: network error

  • IW_ERR_FORBIDDEN: device is not activated or blocked or to be upgraded

  • IW_ERR_ACCESS: wrong password.

  • IW_ERR_NODEVICE: the device is unknown or has been permanently disabled

  • IW_ERR_TIMEOUT: timeout since IWPwdUpdateStart

Asynchronous mode

SetBiokeyStartAsync (function callback) -> int
CODE

Returns an error code:

  • IW_ERR_OK: no error

  • IW_ERR_NETWORK: network error

  • IW_ERR_FORBIDDEN: device is not activated or not blocked or to be upgraded

  • IW_ERR_NODEVICE: the device is unknown or has been permanently disabled

  • IW_ERR_VERSION: version error, user must upgrade the device (see IWNewVersionAvailable above)

A call to IWPinMode () will indicate which kind of password is required (current or none)

SetBiokeyFinalizeAsync (string biokey, string pin, function callback) -> int
CODE

The 'biokey' is a string generated by the application. The 'pin' code is the pincode of the user or an empty string for a service without pin. In the case of a service without pin, it is not possible to call this function repeatedly to change the Biokey.Returns an error code:

  • IW_ERR_OK: no error

  • IW_ERR_NETWORK: network error

  • IW_ERR_FORBIDDEN: device is not activated or blocked or to be upgraded

  • IW_ERR_ACCESS: wrong password.

  • IW_ERR_NODEVICE: the device is unknown or has been permanently disabled

  • IW_ERR_TIMEOUT: timeout since IWPwdUpdateStartAsync

Unset biometric keys

Use the following functions in order to reset all biometric keys registered. The library performs all the biometric keys reset process.

In C or C#

Synchronous mode

IWUnsetBiokeysStart (IW* iw)
CODE

Returns an error code:

  • IW_ERR_OK: no error

  • IW_ERR_NETWORK: network error

  • IW_ERR_FORBIDDEN: device is not activated or not blocked or to be upgraded

  • IW_ERR_NODEVICE: the device is unknown or has been permanently disabled

  • IW_ERR_VERSION: version error, user must upgrade the device (see IWNewVersionAvailable above)

A call to IWPinMode () will indicate which kind of password is required (current or none)

IWUnsetBiokeysFinalize (IW* iw, char* pin)
CODE

The ‘iw’ is structure data type. The character array ’pin' is the pin code of the user.

Returns an error code:

  • IW_ERR_OK: no error

  • IW_ERR_NETWORK: network error

  • IW_ERR_FORBIDDEN: device is not activated or blocked or to be upgraded

  • IW_ERR_ACCESS: wrong password.

  • IW_ERR_NODEVICE: the device is unknown or has been permanently disabled

  • IW_ERR_TIMEOUT: timeout since IWPwdUpdateStart

Asynchronous mode

IWUnsetBiokeysStartAsync (IW* iw, IWCALLBACK callback, void* user)
CODE

Returns an error code:

  • IW_ERR_OK: no error

  • IW_ERR_NETWORK: network error

  • IW_ERR_FORBIDDEN: device is not activated or not blocked or to be upgraded

  • IW_ERR_NODEVICE: the device is unknown or has been permanently disabled

  • IW_ERR_VERSION: version error, user must upgrade the device (see IWNewVersionAvailable above)

A call to IWPinMode () will indicate which kind of password is required (current or none)

IWUnsetBiokeysFinalizeAsync (IW* iw, char* pin, IWCALLBACK callback, void* user)
CODE

The ‘iw’ is structure data type. The character array ’pin' is the pin code of the user.

Returns an error code:

  • IW_ERR_OK: no error

  • IW_ERR_NETWORK: network error

  • IW_ERR_FORBIDDEN: device is not activated or blocked or to be upgraded

  • IW_ERR_ACCESS: wrong password.

  • IW_ERR_NODEVICE: the device is unknown or has been permanently disabled

  • IW_ERR_TIMEOUT: timeout since IWPwdUpdateStartAsync

Connection

IWConnected: () -> int
CODE

The library indicates whether the mAccess is connected or not, and how long it will be. The return value is the number of seconds. 0 means “not connected”.“Not connected” means that the password will be required for any operation.

IWServiceConnected: (int service) -> int
CODE

The library indicates whether the mAccess is connected or not for a specific service, and how long it will be. The return value is the number of seconds. 0 means “not connected”. “Not connected” means that the password will be required for any operation.

Synchronous mode

IWDisconnect: () -> int
CODE

The library disconnects from the server. It will perform at least one webservice call.Returns an error code:

  • IW_ERR_OK: no error

  • IW_ERR_NETWORK: network error

Asynchronous mode

IWDisconnectAsync: (function callback) -> int
CODE

The library disconnects from the server. It will perform at least one webservice call.Returns an error code:

  • IW_ERR_OK: no error

  • IW_ERR_NETWORK: network error

Offline OTP

IWDisplayTime: () -> int
CODE

The library indicates the time the OTP should be displayed to the user.

IWOtpShouldSynchronize: (int service) -> int
CODE

The library indicates if synchronization should be proposed to the user, BEFORE it tries to generate an OTP (i.e. before calling IWOtpModeQuery ()). This would signify that more than 3 generations are performed in less than 2 minutes for the same service.

IWOtpModeQuery: (int service) -> int
CODE

The library indicates whether the password should be requested. The “service” argument is the index of the service.

IWOtpGenerate: (string pin) -> string
CODE

The library generates the OTP for the specific service. The “pin” argument should be empty if no password was requested (see IWOtpModeQuery ()).

IWOtpResult: (int used) -> void
CODE

The host indicates whether the OTP was used by the user.

  • RESULT_USEDOK=0; // OTP used

  • RESULT_USEDCANCEL=1; // OTP not used

Online OTP

Synchronous mode

IWOnlineOtpStart: (int service_index) -> int
CODE

The library starts the “online OTP generation” process. It will perform at least one webservice call.
Returns an error code:

  • IW_ERR_OK: no error

  • IW_ERR_NETWORK: network error

  • IW_ERR_FORBIDDEN: device is not activated or blocked or to be upgraded

  • IW_ERR_NODEVICE: the device is unknown or has been permanently disabled

  • IW_ERR_VERSION: version error, user must upgrade the device (see IWNewVersionAvailable above)

A call to IWPinMode () will indicate which kind of password is required (current or none or biokey).

IWOnlineOtpFinalize: (int service, string pin) -> int

OR when using biometric keys:
CODE
IWOnlineOtpFinalizeExt: (int service, string pin, int keytype) -> int
CODE

Possible values for 'keytype' are:

  • 0 : pincode entered

  • 1 : biokey used

The library finalizes the “online OTP generation” process. It will perform at least one webservice call.
Returns an error code:

  • IW_ERR_OK: no error

  • IW_ERR_NETWORK: network error

  • IW_ERR_FORBIDDEN: device is not activated or blocked or to be upgraded

  • IW_ERR_ACCESS: wrong password.

  • IW_ERR_SYNCHROFAILED: the last step of the synchronization failed. Should propose to resynchronize.

  • IW_ERR_NODEVICE: the device is unknown or has been permanently disabled

  • IW_ERR_TIMEOUT: timeout since IWOnlineOtpStart

On success, the host will get the OTP by calling IWOtpAnswersGet () and IWOtpAnswerOtp ().

Asynchronous mode

IWOnlineOtpStartAsync: (int service, function callback) -> int
CODE

The library starts the “online OTP generation” process. It will perform at least one webservice call.
Returns an error code:

  • IW_ERR_OK: no error

  • IW_ERR_NETWORK: network error

  • IW_ERR_FORBIDDEN: device is not activated or blocked or to be upgraded

  • IW_ERR_NODEVICE: the device is unknown or has been permanently disabled

  • IW_ERR_VERSION: version error, user must upgrade the device (see IWNewVersionAvailable above)

A call to IWPinMode () will indicate which kind of password is required (current or none or biokey).

IWOnlineOtpFinalizeAsync: (int service, string pin, function callback) -> int

OR when using biometric keys:
CODE
IWOnlineOtpFinalizeExtAsync: (int service_index, string pin, int keytype, function callback) -> int
CODE

Possible values for 'keytype' are:

  • 0 : pincode entered

  • 1 : biokey used

The library finalizes the “online OTP generation” process. It will perform at least one webservice call. Returns an error code:

  • IW_ERR_OK: no error

  • IW_ERR_NETWORK: network error

  • IW_ERR_FORBIDDEN: device is not activated or blocked or to be upgraded

  • IW_ERR_ACCESS: wrong password.

  • IW_ERR_SYNCHROFAILED: the last step of the synchronization failed. Should propose to resynchronize.

  • IW_ERR_NODEVICE: the device is unknown or has been permanently disabled

  • IW_ERR_TIMEOUT: timeout since IWOnlineOtpStartAsync

On success, the host will get the OTP by calling IWOtpAnswersGet () and IWOtpAnswerOtp ().

IWOtpAnswersGet: () -> int
CODE

After a successful call to IWOnlineOtpFinalize () or IWOnlineOtpFinalizeAsync (), the library returns a mask of available data:MSK_OTP (1) OTP; use IWOtpAnswerOtp () to retrieve the OTP.

IWOtpAnswerOtp: () -> string
CODE

After a successful call to IWOnlineOtpFinalize ()IWOnlineOtpFinalizeExt ()IWOnlineOtpFinalizeAsync () or IWOnlineOtpFinalizeAsyncExt (), the library provides the OTP.

Offline Seal

Before using sealing feature, be sure that the “Transaction sealing” option is set to “Yes” (admin console > service parameters tab).

IWSealShouldSynchronize: (int service) -> int
CODE

The library indicates if synchronization should be proposed to the user, BEFORE it tries to generate a Seal (i.e. before calling IWSealModeQuery ()). This would signify that more than 3 generations are performed in less than 2 minutes for the same service.

IWSealModeQuery: (int service) -> int
CODE

This function initializes the Offline Seal Process. It will always return 1.

IWSealGenerate: (string pin, string data) -> string
CODE

The library generates the Seal for the specific service.

IWOtpResult: (int used) -> void
CODE

The host indicates whether the Seal was used by the user.

  • RESULT_USEDOK=0; // Seal used

  • RESULT_USEDCANCEL=1; // Seal not used

IWDisplayTime: () -> int
CODE

The library indicates the time the OTP should be displayed to the user.

Online Seal

Before using sealing feature, be sure that the “Transaction sealing” option is set to “Yes” (admin console > service parameters tab).

Synchronous mode

IWOnlineSealStart: (int service) -> int
CODE

The library starts the “online seal generation” process. It will perform at least one webservice call.
Returns an error code:

  • IW_ERR_OK: no error

  • IW_ERR_NETWORK: network error

  • IW_ERR_FORBIDDEN: device is not activated or blocked or to be upgraded

  • IW_ERR_NODEVICE: the device is unknown or has been permanently disabled

  • IW_ERR_VERSION: version error, user must upgrade the device (see IWNewVersionAvailable above)

For Seal Generation, PIN Mode is always set to 1 (current). This means that the user will have to type his PIN to generate a seal.

IWOnlineSealFinalize: (int service, string pin, string data) -> int
CODE

OR when using biometric keys:

IWOnlineSealFinalizeExt(int service, string pin, int keytype, string sealdata) -> int
CODE

Possible values for 'keytype' are:
0 : pincode entered
1 : biokey used

The library finalizes the “online seal generation” process. It will perform at least one webservice call. Returns an error code:

  • IW_ERR_OK: no error

  • IW_ERR_NETWORK: network error

  • IW_ERR_FORBIDDEN: device is not activated or blocked or to be upgraded

  • IW_ERR_ACCESS: wrong password.

  • IW_ERR_SYNCHROFAILED: the last step of the synchronization failed. Should propose to resynchronize.

  • IW_ERR_NODEVICE: the device is unknown or has been permanently disabled

  • IW_ERR_TIMEOUT: timeout since IWOnlineSealStart

On success, the host will get the Seal by calling IWSealAnswersGet () and IWSealAnswerOtp ().

Asynchronous mode

IWOnlineSealStartAsync: (int service, function callback) -> int
CODE

The library starts the “online seal generation” process. It will perform at least one webservice call.
Returns an error code:

  • IW_ERR_OK: no error

  • IW_ERR_NETWORK: network error

  • IW_ERR_FORBIDDEN: device is not activated or blocked or to be upgraded

  • IW_ERR_NODEVICE: the device is unknown or has been permanently disabled

  • IW_ERR_VERSION: version error, user must upgrade the device (see IWNewVersionAvailable above)

For Seal Generation, PIN Mode is always set to 1 (current). This means that the user will have to type his PIN to generate a seal.

IWOnlineSealFinalizeAsync: (int service, string pin, string data, function callback) -> int
CODE

OR when using biometric keys:

IWOnlineSealFinalizeExtAsync(int service, string pin, int keytype, string sealdata, function callback) -> int
CODE

Possible values for 'keytype' are:
0 : pincode entered
1 : biokey used

The library finalizes the “online seal generation” process. It will perform at least one webservice call. Returns an error code:
CODE
  • IW_ERR_OK: no error

  • IW_ERR_NETWORK: network error

  • IW_ERR_FORBIDDEN: device is not activated or blocked or to be upgraded

  • IW_ERR_ACCESS: wrong password.

  • IW_ERR_SYNCHROFAILED: the last step of the synchronization failed. Should propose to resynchronize.

  • IW_ERR_NODEVICE: the device is unknown or has been permanently disabled

  • IW_ERR_TIMEOUT: timeout since IWOnlineSealStartAsync

On success, the host will get the Seal by calling IWSealAnswersGet () and IWSealAnswerOtp ().

IWSealAnswersGet: () -> int
CODE

After a successful call to IWOnlineSealFinalize () or IWOnlineSealFinalizeAsync (), the library returns a mask of available data:MSK_SEAL (2) seal; use IWSealAnswerOtp () to retrieve the seal.

IWSealAnswerOtp: () -> string
CODE

After a successful call to IWOnlineSealFinalize () or IWOnlineSealFinalizeAsync (), the library provides the Seal.

Reset (Unlock)

Synchronous mode

IWResetStart: (string code) -> int
CODE

The library starts the reset process. It will perform at least one webservice call.Returns an error code:

  • IW_ERR_OK: no error

  • IW_ERR_NETWORK: network error

  • IW_ERR_FORBIDDEN: device is not activated or not blocked or to be upgraded

  • IW_ERR_CODE: bad code.

  • IW_ERR_SN: syntax error for “code”

  • IW_ERR_NODEVICE: the device is unknown or has been permanently disabled

  • IW_ERR_VERSION: version error, user must upgrade the device (see IWNewVersionAvailable above)

A call to IWPinMode will indicate which kind of password is required (current or new).

IWResetFinalize: (string code, string pin) -> int
CODE

The library finalizes the reset process. It will perform at least one webservice call.Returns an error code:

  • IW_ERR_OK: no error

  • IW_ERR_NETWORK: network error

  • IW_ERR_FORBIDDEN: device is not activated or blocked or to be upgraded

  • IW_ERR_ACCESS: wrong password.

  • IW_ERR_SYNCHROFAILED: the last step of the synchronization failed. Should propose to resynchronize.

  • IW_ERR_SN: syntax error for “code”

  • IW_ERR_PINREFUSED: syntax error for “password”

  • IW_ERR_NODEVICE: the device is unknown or has been permanently disabled

  • IW_ERR_TIMEOUT: timeout since IWResetStart

Asynchronous mode

IWResetStartAsync: (string code, function callback) -> int
CODE

The library starts the reset process. It will perform at least one webservice call.Returns an error code:

  • IW_ERR_OK: no error

  • IW_ERR_NETWORK: network error

  • IW_ERR_FORBIDDEN: device is not activated or not blocked or to be upgraded

  • IW_ERR_CODE: bad code.

  • IW_ERR_SN: syntax error for “code”

  • IW_ERR_NODEVICE: the device is unknown or has been permanently disabled

  • IW_ERR_VERSION: version error, user must upgrade the device (see IWNewVersionAvailable above)

A call to IWPinMode () will indicate which kind of password is required (current or new).

IWResetFinalizeAsync: (string code, string pin, function callback) -> int
CODE

The library finalizes the reset process. It will perform at least one webservice call.Returns an error code:

  • IW_ERR_OK: no error

  • IW_ERR_NETWORK: network error

  • IW_ERR_FORBIDDEN: device is not activated or blocked or to be upgraded

  • IW_ERR_ACCESS: wrong password.

  • IW_ERR_SYNCHROFAILED: the last step of the synchronization failed. Should propose to resynchronize.

  • IW_ERR_SN: syntax error for “code”

  • IW_ERR_PINREFUSED: syntax error for “password”

  • IW_ERR_NODEVICE: the device is unknown or has been permanently disabled

  • IW_ERR_TIMEOUT: timeout since IWResetStartAsync

Request Activation code

This function allows the user to get an Activation code from inWebo. This 9-digit code will be used to activate a new inWebo token (typically a new inWebo Helium browser token).

Synchronous mode

IWActivationcodeRequestStart: () -> int
CODE

The library starts the “request Activation code” process. It will perform at least one webservice call.Returns an error code:

  • IW_ERR_OK: no error

  • IW_ERR_NETWORK: network error

  • IW_ERR_FORBIDDEN: device is not activated or blocked or to be upgraded

  • IW_ERR_NODEVICE: the device is unknown or has been permanently disabled

  • IW_ERR_VERSION: version error, user must upgrade the device (see IWNewVersionAvailable above)

A call to IWPinMode () will indicate which kind of password is required (current or none).

IWActivationcodeRequestFinalize: (string pin) -> int
CODE

The library finalizes the “request Activation code” process. It will perform at least one webservice call.Returns an error code:

  • IW_ERR_OK: no error

  • IW_ERR_NETWORK: network error

  • IW_ERR_FORBIDDEN: device is not activated or blocked or to be upgraded

  • IW_ERR_ACCESS: wrong password.

  • IW_ERR_SYNCHROFAILED: the last step of the synchronization failed. Should propose to resynchronize.

  • IW_ERR_NODEVICE: the device is unknown or has been permanently disabled

  • IW_ERR_TIMEOUT: timeout since IWActivationcodeRequestStart

On success, the host will retrieve the Activation code by calling IWCode ().

Asynchronous mode

IWActivationcodeRequestStartAsync: (function callback) -> int
CODE

The library starts the “request Activation code” process. It will perform at least one webservice call.Returns an error code:

  • IW_ERR_OK: no error

  • IW_ERR_NETWORK: network error

  • IW_ERR_FORBIDDEN: device is not activated or blocked or to be upgraded

  • IW_ERR_NODEVICE: the device is unknown or has been permanently disabled

  • IW_ERR_VERSION: version error, user must upgrade the device (see IWNewVersionAvailable above)

A call to IWPinMode () will indicate which kind of password is required (current or none).

IWActivationcodeRequestFinalizeAsync: (string pin, function callback) -> int
CODE

The library finalizes the “request Activation code” process. It will perform at least one webservice call.Returns an error code:

  • IW_ERR_OK: no error

  • IW_ERR_NETWORK: network error

  • IW_ERR_FORBIDDEN: device is not activated or blocked or to be upgraded

  • IW_ERR_ACCESS: wrong password.

  • IW_ERR_SYNCHROFAILED: the last step of the synchronization failed. Should propose to resynchronize.

  • IW_ERR_NODEVICE: the device is unknown or has been permanently disabled

  • IW_ERR_TIMEOUT: timeout since IWActivationcodeRequestStartAsync

On success, the host will retrieve the Activation code by calling IWCode ().

Update password

Synchronous mode

IWPwdUpdateStart: () -> int
CODE

The library starts the password update process. It will perform at least one webservice call.Returns an error code:

  • IW_ERR_OK: no error

  • IW_ERR_NETWORK: network error

  • IW_ERR_FORBIDDEN: device is not activated or not blocked or to be upgraded

  • IW_ERR_NODEVICE: the device is unknown or has been permanently disabled

  • IW_ERR_VERSION: version error, user must upgrade the device (see IWNewVersionAvailable above)

A call to IWPinMode () will indicate which kind of password is required (current or none).

IWPwdUpdateFinalize: (string newPin, string pin) -> int
CODE

The library finalizes the password update process. It will perform at least one webservice call.Returns an error code:

  • IW_ERR_OK: no error

  • IW_ERR_NETWORK: network error

  • IW_ERR_FORBIDDEN: device is not activated or blocked or to be upgraded

  • IW_ERR_ACCESS: wrong password.

  • IW_ERR_SYNCHROFAILED: the last step of the synchronization failed. Should propose to resynchronize.

  • IW_ERR_PINREFUSED: syntax error for “password”

  • IW_ERR_PINREUSED: new password equals previous password

  • IW_ERR_NODEVICE: the device is unknown or has been permanently disabled

  • IW_ERR_TIMEOUT: timeout since IWPwdUpdateStart

Asynchronous mode

IWPwdUpdateStartAsync: (function callback) -> int
CODE

The library starts the password update process. It will perform at least one webservice call.Returns an error code:

  • IW_ERR_OK: no error

  • IW_ERR_NETWORK: network error

  • IW_ERR_FORBIDDEN: device is not activated or not blocked or to be upgraded

  • IW_ERR_NODEVICE: the device is unknown or has been permanently disabled

  • IW_ERR_VERSION: version error, user must upgrade the device (see IWNewVersionAvailable above)

A call to IWPinMode () will indicate which kind of password is required (current or none).

IWPwdUpdateFinalizeAsync: (string newPin, string pin, function callback) -> int
CODE

The library finalizes the password update process. It will perform at least one webservice call.Returns an error code:

  • IW_ERR_OK: no error

  • IW_ERR_NETWORK: network error

  • IW_ERR_FORBIDDEN: device is not activated or blocked or to be upgraded

  • IW_ERR_ACCESS: wrong password.

  • IW_ERR_SYNCHROFAILED: the last step of the synchronization failed. Should propose to resynchronize.

  • IW_ERR_PINREFUSED: syntax error for “password”

  • IW_ERR_PINREUSED: new password equals previous password

  • IW_ERR_NODEVICE: the device is unknown or has been permanently disabled

  • IW_ERR_TIMEOUT: timeout since IWPwdUpdateStartAsync

Upgrade

The upgrade process is required when the device detects that the local data is from a previous version of the library (it is not the update of the host; it is AFTER an update of the host).

Synchronous mode

IWUpgradeStart: () -> int
CODE

The library starts the upgrade process. It will perform at least one webservice call.Returns an error code:

  • IW_ERR_OK: no error

  • IW_ERR_NETWORK: network error

  • IW_ERR_FORBIDDEN: device is not to be upgraded

  • IW_ERR_NODEVICE: the device is unknown or has been permanently disabled

  • IW_ERR_VERSION: version error, user must upgrade the device (see IWNewVersionAvailable above)

A call to IWPinMode () will indicate which kind of password is required (current or none).

IWUpgradeFinalize: (string pin, string oldSerial) -> int
CODE

The library finalizes the upgrade process. It will perform at least one webservice call. It requires the old serial number, as it was computed before.Returns an error code:

  • IW_ERR_OK: no error

  • IW_ERR_NETWORK: network error

  • IW_ERR_FORBIDDEN: device is not to be upgraded

  • IW_ERR_ACCESS: wrong password.

  • IW_ERR_SYNCHROFAILED: the last step of the synchronization failed. Should propose to resynchronize.

  • IW_ERR_NODEVICE: the device is unknown or has been permanently disabled

  • IW_ERR_TIMEOUT: timeout since IWUpgradeStart

Asynchronous mode

IWUpgradeStartAsync: (function callback) -> int
CODE

The library starts the upgrade process. It will perform at least one webservice call.Returns an error code:

  • IW_ERR_OK: no error

  • IW_ERR_NETWORK: network error

  • IW_ERR_FORBIDDEN: device is not to be upgraded

  • IW_ERR_NODEVICE: the device is unknown or has been permanently disabled

  • IW_ERR_VERSION: version error, user must upgrade the device (see IWNewVersionAvailable above)

A call to IWPinMode () will indicate which kind of password is required (current or none).

IWUpgradeFinalizeAsync: (string pin, string oldSerial, function callback) -> int
CODE

The library finalizes the upgrade process. It will perform at least one webservice call. It requires the old serial number, as it was computed before.Returns an error code:

  • IW_ERR_OK: no error

  • IW_ERR_NETWORK: network error

  • IW_ERR_FORBIDDEN: device is not to be upgraded

  • IW_ERR_ACCESS: wrong password.

  • IW_ERR_SYNCHROFAILED: the last step of the synchronization failed. Should propose to resynchronize.

  • IW_ERR_NODEVICE: the device is unknown or has been permanently disabled

  • IW_ERR_TIMEOUT: timeout since IWUpgradeStartAsync

Push registration

Synchronous mode

IWPushRegistrationStart: () -> int
CODE

The library starts the push registration process. It will perform at least one webservice call.Returns an error code:

  • IW_ERR_OK: no error

  • IW_ERR_NETWORK: network error

  • IW_ERR_FORBIDDEN: device is not activated or blocked or to be upgraded

  • IW_ERR_NODEVICE: the device is unknown or has been permanently disabled

IWPushRegistrationFinalize: (string pushId) -> int
CODE

The library finalizes the push registration process. It will perform at least one webservice call.Returns an error code:

  • IW_ERR_OK: no error

  • IW_ERR_NETWORK: network error

  • IW_ERR_FORBIDDEN: device is not activated or blocked or to be upgraded

  • IW_ERR_NODEVICE: the device is unknown or has been permanently disabled

  • IW_ERR_TIMEOUT: timeout since IWPushRegistrationStart

Asynchronous mode

IWPushRegistrationStartAsync: (function callback) -> int
CODE

The library starts the push registration process. It will perform at least one webservice call.Returns an error code:

  • IW_ERR_OK: no error

  • IW_ERR_NETWORK: network error

  • IW_ERR_FORBIDDEN: device is not activated or blocked or to be upgraded

  • IW_ERR_NODEVICE: the device is unknown or has been permanently disabled

IWPushRegistrationFinalizeAsync: (string pushId, function callback) -> int
CODE

The library finalizes the push registration process. It will perform at least one webservice call.Returns an error code:

  • IW_ERR_OK: no error

  • IW_ERR_NETWORK: network error

  • IW_ERR_FORBIDDEN: device is not activated or blocked or to be upgraded

  • IW_ERR_NODEVICE: the device is unknown or has been permanently disabled

  • IW_ERR_TIMEOUT: timeout since IWPushRegistrationStartAsync


Important note: To use firebase notification service you must change the device OS to "firebase" using IWSetDeviceOS("firebase") → voidIf your mobile is on a filtered network (wifi by example), please ensure the following ports are opened to be able to register for push notifications and also to receive them:

  • Android (Google):  outbound TCP ports 5228 to 5230.

  • iOS (Apple): outbound TCP port 5223 

Get Pending Push

IWCheckPush: () -> int
CODE

Check if a push notification is available on inWebo server for the active instance of mAccess. Typically this function can be called when starting the mAccess application. In case of a push notification not received, this function will retrieve this pending authentication request.

IWPushAlias: () -> String
CODE

Get the push session id, or alias, related to the retrieved push

IWPushAction: () -> String
CODE

Get the push action (“activate” or “authenticate”) related to the retrieved push

IWPushContext: () -> String
CODE

Authentication only. Get the push context information related to the retrieved push. To be used if a context has been sent during the pushAuthenticate APIcall.

Push Activate

This function should be used when a user tries to activate helium on his PC, using a Push notification to his mobile app as a security check. The Push notification sent by InWebo servers contains an “alias” that must be passed as a parameter.

Synchronous mode

IWPushActivateCaStart: (string alias) -> int
CODE

The library starts the push activation process. It will perform at least one webservice call.Returns an error code:

  • IW_ERR_OK: no error

  • IW_ERR_NETWORK: network error

  • IW_ERR_FORBIDDEN: device is not activated or blocked or to be upgraded

  • IW_ERR_NODEVICE: the device is unknown or has been permanently disabled

IWPushActivateCaFinalize: (string alias, string pin, int confirm) -> int
CODE

The library finalizes the push registration process. It will perform at least one webservice call. Confirm is an integer telling whether the activation via push notification is refused (0) or accepted (1). Returns an error code:

  • IW_ERR_OK: no error

  • IW_ERR_NETWORK: network error

  • IW_ERR_FORBIDDEN: device is not activated or blocked or to be upgraded

  • IW_ERR_NODEVICE: the device is unknown or has been permanently disabled

  • IW_ERR_TIMEOUT: timeout since IWPushActivateCaStart

Asynchronous mode

IWPushActivateCaStartAsync: (string alias, function callback) -> int
CODE

The library starts the push activation process. It will perform at least one webservice call. Returns an error code:

  • IW_ERR_OK: no error

  • IW_ERR_NETWORK: network error

  • IW_ERR_FORBIDDEN: device is not activated or blocked or to be upgraded

  • IW_ERR_NODEVICE: the device is unknown or has been permanently disabled

IWPushActivateCaFinalizeAsync: (string alias, string pin, int confirm, function callback) -> int
CODE

The library finalizes the push activation process. It will perform at least one webservice call. Confirm is an integer telling whether the activation via push notification is refused (0) or accepted (1). Returns an error code:

  • IW_ERR_OK: no error

  • IW_ERR_NETWORK: network error

  • IW_ERR_FORBIDDEN: device is not activated or blocked or to be upgraded

  • IW_ERR_NODEVICE: the device is unknown or has been permanently disabled

  • IW_ERR_TIMEOUT: timeout since IWPushActivateCaStartAsync

Push OTP

Synchronous mode

IWPushOTPStart: (string alias) -> int
CODE

The library starts the push OTP process. It will perform at least one webservice call. Returns an error code:

  • IW_ERR_OK: no error

  • IW_ERR_NETWORK: network error

  • IW_ERR_FORBIDDEN: device is not activated or blocked or to be upgraded

  • IW_ERR_NODEVICE: the device is unknown or has been permanently disabled

A call to IWPinMode () will indicate which kind of password is required (current or none or biokey).

IWPushOTPFinalize: (string alias, string pin, int confirm) -> int
CODE

OR

IWPushOTPFinalizeExt(string alias, string pin, int confirm, int keytype) -> int
CODE

'IWPushOTPFinalizeExt' is a new extended version of 'IWPushOTPFinalize' that must be used if you implement biometric factors in your application. In both cases, the library finalizes the push connection process. It will perform at least one webservice call. Possible values for 'keytype' are: (0) : pincode entered or (1) : biokey used. Confirm is an integer telling whether the activation via push notification is refused (0) or accepted (1). Returns an error code:

  • IW_ERR_OK: no error

  • IW_ERR_NETWORK: network error

  • IW_ERR_FORBIDDEN: device is not activated or blocked or to be upgraded

  • IW_ERR_NODEVICE: the device is unknown or has been permanently disabled

  • IW_ERR_TIMEOUT: timeout since IWPushOTPStart

Asynchronous mode

IWPushOTPStartAsync: (string alias, function callback) -> int
CODE

The library starts the push OTP process. It will perform at least one webservice call. Returns an error code:

  • IW_ERR_OK: no error

  • IW_ERR_NETWORK: network error

  • IW_ERR_FORBIDDEN: device is not activated or blocked or to be upgraded

  • IW_ERR_NODEVICE: the device is unknown or has been permanently disabled

A call to IWPinMode () will indicate which kind of password is required (current or none or biokey).

IWPushOTPFinalizeAsync: (string alias, string pin, int confirm, function callback) -> int
CODE

OR

IWPushOTPFinalizeExtAsync(string alias, string pin, int confirm, int keytype, function callback) -> int
CODE

'IWPushOTPFinalizeExtAsync' is a new extended version of 'IWPushOTPFinalizeAsync' that must be used if you implement biometric factors in your application. In both cases, theThe library finalizes the push connection process. It will perform at least one webservice call. Possible values for 'keytype' are: (0) : pincode entered or (1) : biokey used. Confirm is an integer telling whether the activation via push notification is refused (0) or accepted (1). Returns an error code:

  • IW_ERR_OK: no error

  • IW_ERR_NETWORK: network error

  • IW_ERR_FORBIDDEN: device is not activated or blocked or to be upgraded

  • IW_ERR_NODEVICE: the device is unknown or has been permanently disabled

  • IW_ERR_TIMEOUT: timeout since IWPushOTPStartAsync

Implementation

You will find below implementation guidelines to help you understand how to chain mAccess API functions to run the library. These guidelines are valid for both synchronous and asynchronous modes.

Startup

At host startup, you need to:A) Initialize the library

  • call IWInit ()

  • call IWHostVersionSet ()

  • call IWWsServerSet ()

  • call IWWsTimeoutSet ()

  • call IWMaccessSet () and provide mAccess ID, that can be found in inWebo Admin Console

  • Read the ASCII string stored locally, and pass it to the function IWStorageDataSet ().

  • Determine whether mAccess is activated or not by calling IWIsActivated (). If this function returns “1”, mAccess is activated.

  • If mAccess is not activated, go to step B).

  • Determine whether mAccess is blocked or not by calling IWIsBlocked ().

    • If this function returns “1”, mAccess is blocked. Go to section “Reset”.

    • If mAccess is activated and not blocked, startup procedure is over and completed successfully

B) Activation

  • Prompt the user for an Activation code

  • Once entered, call the function IWActivationStart () with this code as a parameter

  • Then, call IWPinMode () in order to find out if the user has to define a new password, or enter his existing password for verification.

    • New password: request it twice and make sure they are identical

    • Existing password: request only once

  • Then, call IWActivationFinalize ()

Push registration

After a successful activation, you can proceed to push registration:

  • Retrieve the device unique ID

  • Register the App calling IWPushRegistrationStart ()

Push registration should be performed only once. Yet you may want to check at application start-up if the unique parameter identifying the device and the user has been updated. In case this unique ID has changed you can safely call IWPushRegistrationStart () again.

Synchronization

In order to perform a synchronization:

  • First call IWSynchronizeStart ()

  • Then call IWPinMode () to know if a password is required

  • Then, prompt for the password

  • Finally, call IWSynchronizeFinalize ()

Generate an offline OTP

mAccess has been designed to support more than one service. This means that mAccess will be able to generate different OTPs for different sites or applications. This will be useful for multi-purposes host applications. In this example, we will assume that mAccess has only one service (i=0).A) Check if synchronization is requiredWhen the user requests an OTP, you first need to call IWOtpShouldSynchronize (0) in order to know if a synchronization should be proposed to the user prior to generate the OTPIf IWOtpShouldSynchronize returns 1, you should display a page such as “Your application seems desynchronized. Do you want to force synchronization?”If the user chooses “no”, go to step B)If the user chooses “yes” implement a synchronization at this stage (see later in the doc)B) Prompt the user for his mAccess passwordC) Display the OTP returned by the function IWOtpGenerate (PIN).The OTP will be valid for n seconds, where n is the result of IWDisplayTime ()If the host application knows whether the OTP was submitted or not, additional step will be useful to prevent desynchronization:

  • If the OTP was not submitted, call IWOtpResult (RESULT_USED_CANCEL)

  • If the OTP was submitted, or the information is not available, call IWOtpResult (RESULT_USED_OK)

The same logic can be used to implement offline sealing.

Generate an online OTP

When the user requests an OTP:

  • Call IWOnlineOtpStart (0)

  • Then call IWPinMode () to know if the password should be requested

  • Prompt for the password if needed

  • Call IWOnlineOtpFinalize (0,password) with the password as parameter

  • Call IWOtpAnswerOtp () to get the OTP

The same logic can be used to implement online sealing.

Activate other tokens with push notifications

This feature can be used to activate inWebo browser tokens (inWebo Helium) via mobile push notifications. Prerequisites:

  • inWebo push registration (see guideline above)

  • Implement the code to handle push notification in the host application. When receiving a notification parse the content to verify if it is an activation notification or a connection notification

If an activation notification is received:

  • Get the transaction ID alias from the notification content

  • Call IWPushActivateCaStart (alias)

  • Then call IWPinMode () to know if the password should be requested

  • Then prompt for the password

  • Then propose two buttons allowing the user to accept or refuse the activation

  • If activation is refused call IWPushActivateCaFinalize(alias, pin, 0)

  • If activation is accepted call IWPushActivateCaFinalize(alias, pin, 1)

  • Pin should be set to an empty string if IWPinMode() returns IW_PINMODE_NONE

Connect user to your applications with push notifications

This feature can be used to connect a user via push notifications sent either by your platform (using inWebo API on your server) or via inWebo browser tokens (inWebo Helium). Prerequisites:

  • inWebo push registration (see guideline above)

  • Implement the code to handle push notification in the host application. When receiving a notification parse the content to verify if it is an activation notification or a connection notification

If a connection notification is received:

  • Get the transaction ID alias from the notification content

  • Call IWPushOTPStart (alias)

  • Then call IWPinMode () to know if the password should be requested

  • Then prompt for the password and / or propose two buttons allowing the user to accept or refuse the connection

  • If connection is refused call IWPushOTPFinalize(alias, pin, 0)

  • If connection is accepted call IWPushOTPFinalize(alias, pin, 1)

  • Pin should be set to an empty string if IWPinMode() returns IW_PINMODE_NONE

Get an Activation code to activate another inWebo token

This feature is optional. It allows a user to activate an inWebo Helium token in a browser.

  • Call IWActivationcodeRequestStart ()

  • Then call IWPinMode () to know if a password is required

  • Then prompt for the password

  • Call IWActivationcodeRequestFinalize (Password) and then IWCode () to get and display the Activation code

Password change

  • Call IWPwdUpdateStart ()

  • Prompt for the current Password

  • Prompt twice for the new password

  • Call IWPwdUpdateFinalize (NEWPIN, PIN)

  • Parse the return code

Reset

If mAccess is blocked (IWIsBlocked ()), you need to:

  • Display a “Reset” page prompting for a “reset code”

  • call IWResetStart (code), and then IWPinMode () to know whether to prompt for a new password or the existing password

  • call IWResetFinalize (Password)

Password change with all biometric keys reset

  • Call IWPwdUpdateStart ()

  • Prompt for the current Password

  • Prompt twice for the new password

  • Call IWPwdUpdateFinalize ()

  • Parse the return code

  • Call IWUnsetBiokeysStart ()

  • Call IWUnsetBiokeysFinalize ()