Reference doc - mAccess library (iOS)

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 helium or 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

IW_DESYNCHRONIZED

27

device desynchronized

IW_ERR_OTHER

999

any other error

IW_PINMODE_NONE

0

no pin is required (leave “”)

IW_PINMODE_CURRENT

1

current pin is required

IW_PINMODE_NEW

2

a new pin is required

IW_PINMODE_BIO

8

a biokey is required

IW_PINMODE_CURRENT | IW_PINMODE_BIO

9

a pin OR biokey is required

int IWActivationStart(IW* iw,char* code)

Function description: starts the device activation process.

Parameters:

• code (char*) → activation code

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

int IWActivationFinalize(IW* iw,char* code,char* pin,char* name)

Function description: finalizes the device activation process

Parameters:

• code (char*) → activation code

• pin (char*) → the user’s pin code

• name (char*) → the name of the device that is about to be activated

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 ActivationStart

int IWResetStart(IW* iw,char* code)

Function description: starts the reset pin process

Parameters:

• code (char*)→ unlock 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_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)

 int IWResetFinalize(IW* iw,char* code,char* pin)

Function description: finalizes the reset pin process

Parameters:

• code (char*) → unlock code

• pin (char*) → the user’s pin code

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

int IWSynchronizeStart(IW* iw)

Function description: starts the synchronization process to synchronize information between the application and TrustBuilder server.

Returns: an error code

int IWSynchronizeFinalize(IW* iw,char* pin)

Function description: finalizes the synchronization process to synchronize information between the application and TrustBuilder server.

Parameters:

• pin (char*) → the user’s pin code

Returns: an error code

int IWPwdUpdateStart(IW* iw)

Function description: starts the pin update process

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 NewVersionAvailable)

int IWPwdUpdateFinalize(IW* iw,char* newpin,char* pin)

Function description: finalizes the pin update process

Parameters:

• newpin (char) → the user’s new pin code

• pin (char*) → the user’s current pin code that is about to be replaced by newpin

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

int IWUnsetBiokeysStart(IW* iw)

Function description: starts the process of resetting all biometric keys.

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)

int IWUnsetBiokeysFinalize(IW* iw, char* pin)

Function description: finalize the process of resetting all biometric keys.

Parameters:

• pin (char*) → the user’s pin code

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 UnsetBiokeysStart

int IWSetBiokeyStart(IW* iw)

Function description: starts the biometrics registration process

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)

int IWSetBiokeyFinalize(IW* iw, char* biokey, char* pin)

Function description: finalizes the biometrics registration process

Parameters:

• biokey(char*) → biometric key

• pin(char*) → the user’s pin code

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

int IWOnlineOtpStart(IW* iw,int i)

Function description: starts the “online OTP generation” process

Parameters:

• i (int) → the index of the service associated with the user.
  In most configurations, this value must be 0, as users are typically linked to a single service. Non-zero values were used for multi-service setups but are now deprecated. Use the ServiceNb method to check the number of enrolled services and ServiceName to retrieve their names.

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)

int IWOnlineOtpFinalize(IW* iw,int i,char* pin)

Function description: finalizes the “online OTP generation” process

Parameters:

• i (int) → the index of the service associated with the user.
  In most configurations, this value must be 0, as users are typically linked to a single service. Non-zero values were used for multi-service setups but are now deprecated. Use the ServiceNb method to check the number of enrolled services and ServiceName to retrieve their names.

• pin (char*) → the user’s pin code

Returns: IWOnlineOtpFinalizeExt(i, pin, 0)

char* IWOtpAnswerOtp(IW* iw)

Function description: retrieves a generated OTP after a process of online OTP generation (only if the IWOnlineOtpFinalize or IWOnlineOtpFinalizeExt call returns a response code “0”).

Returns: an OTP

int IWOnlineOtpFinalizeExt(IW* iw, int i, char* pin, int keytype)

Function description: finalizes the “online OTP generation” process with biometric keys

Parameters:

• i (int) → the index of the service associated with the user.
  In most configurations, this value must be 0, as users are typically linked to a single service. Non-zero values were used for multi-service setups but are now deprecated. Use the ServiceNb method to check the number of enrolled services and ServiceName to retrieve their names.

• pin (char*) → the user’s pin code

• keytype (int) → the keytype ( 0= pincode , 1= biometric key)

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

int IWOtpShouldSynchronize(IW* iw, int serviceid)

Function description: checks if a synchronization process is required, before starting the process of Offline OTP generation

Parameters:

• serviceid (int) → the TrustBuilder service identifier

Returns: an error code

• 0 : no synchronization required

• 1 : synchronization required

IWOtpModeQuery(IW* iw, int serviceid)

Function description: indicates whether the pin should be requested, after a otpShouldSynchronize call and before starting the process of Offline OTP generation.

Parameters:

• serviceid (int) → the TrustBuilder service identifier

Returns: an error code

• 0 → No PIN required

• 1 → the Pin is required

char* IWOtpGenerateMa(IW* iw, char* pin)

Function description: retrieves a generated OTP after a process of offline OTP generation (only if the IWOnlineOtpFinalize or IWOnlineOtpFinalizeExt call returns a response code “0”).

Parameters:

• pin (char*) → the user’s pin code

Returns: an OTP

int IWDisplayTime(IW* iw)

Function description: displays the remaining time before the OTP expiration (in seconds)

Returns: Otp.displayTime()

void IWSetDeviceOS(IW* iw, char *deviceos)

Function description: defines the device operating system.

Parameters:

• deviceOS (char*) → the device’s OS

int IWPushRegistrationStart(IW* iw)

Function description: starts the push registration process to allow TrustBuilder to send push notifications to your application.

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

int IWPushRegistrationFinalize(IW* iw, char *push_id)

Function description: finalizes the push registration process to allow TrustBuilder to send push notifications to your application.

Parameters:

• push_id (char*) → the push id of the device used for notification push service

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

int IWCheckPush(IW* iw)

Function description: Checks if a push notification is available on TrustBuilder server for the active instance of mAccess, and retrieves it. Typically this function can be called when starting the application.

Returns: an error code

• 0 → a push is available

• 999 → no pending push available or mobile push service may not be activated

char* IWPushAlias(IW* iw)

Function description: Gets the push session id, or alias, related to the retrieved push (if a IWCheckPush call returns a 0)

Returns: pushAlias (char*)

public String PushAction()

Function description: gets the push action type of the push notification (authenticate or activate)

Returns: pushAction (char*)

char* IWPushContext(IW* iw)

Function description: gets the push notification context information if there is one (authentication only)

Returns: pushContext (char*)

int IWOnlineSealStart(IW* iw, int i)

Function description: starts the “online seal generation” process

Parameters:

• i (int) → the index of the service associated with the user.
  In most configurations, this value must be 0, as users are typically linked to a single service. Non-zero values were used for multi-service setups but are now deprecated. Use the ServiceNb method to check the number of enrolled services and ServiceName to retrieve their names.

Returns: an error code

int IWOnlineSealFinalize(IW* iw, int i, char* pin, char *sealdata)

Function description: finalizes the “online seal generation” process

Parameters:

• i (int) → the index of the service associated with the user.
  In most configurations, this value must be 0, as users are typically linked to a single service. Non-zero values were used for multi-service setups but are now deprecated. Use the ServiceNb method to check the number of enrolled services and ServiceName to retrieve their names.

• pin (char*) → the user’s pin code

• sealdata (char*) → the data to seal (it is highly recommended to hash the data)

Returns: IWOnlineSealFinalizeExt(i, pin, 0, sealdata)

int IWOnlineSealFinalizeExt(IW* iw, int i, char* pin, int keytype, char *sealdata)

Function description: finalizes the “online seal generation” process with biometric keys

Parameters:

• i (int) → the index of the service associated with the user.
  In most configurations, this value must be 0, as users are typically linked to a single service. Non-zero values were used for multi-service setups but are now deprecated. Use the ServiceNb method to check the number of enrolled services and ServiceName to retrieve their names.

• pin (char*) → the user’s pin code

• keytype (long) → the keytype ( 0= pincode , 1= biometric key)

• sealdata (char*) → the data to seal (it is highly recommended to hash the data)

Returns: an error code

char* IWSealAnswerOtp(IW* iw)

Function description: retrieves a generated OTP after a process of seal generation (only if the IWOnlineSealFinalize or IWOnlineSealFinalizeExt call returns a response code “0”).

Returns: an OTP

int IWSealShouldSynchronize(IW* iw,int serviceid)

Function description: indicates if synchronization should be proposed to the user, BEFORE offline sealing. (i.e. before calling IWSealModeQuery ()). This would signify that more than 3 generations are performed in less than 2 minutes for the same service.

Parameters:

• serviceid (int) → the service identifier

Returns: IWOtpShouldSynchronize(serviceid)

• 0 → no synchronization required

• 1 → synchronization required

int IWSealModeQuery(IW* iw,int serviceid)

Function description: initializes the Offline Seal process indicating whether the pin should be requested

Parameters:

• serviceid (int) → the service identifier

Returns: always returns 1 → pin is required

char* IWSealGenerate(IW* iw,char* pin, char *sealdata)

Function description: generates the seal

Parameters:

• pin (char*) → the user’s pin code

• sealdata (char*) → the data to seal (it is highly recommended to hash the data)

Returns: the generated seal

char* IWVersionGet(IW* iw)

Function description: gets the mAccess library version

Returns: the library version number IWLIBVERSION()

void IWHostVersionSet(IW* iw,char* version)

Function description: provides the host/application version number.

Parameters:

• version (char*) → the host/application version number. In order to be compliant with TrustBuilder convention, it needs to be formatted as: AppName-Version. Example: myApp-1.3.0

void IWWsTimeoutSet(IW* iw,int t)

Function description: defines the timeout value for the web service calls, in millisecond.

Parameters:

• t (int) → the timeout value

void IWWsServerSet(IW* iw,char* server)

Function description: defines the server value for the web service calls

Parameters:

• server (char*) → the server for webservice calls - “https://www.myinWebo.com”

void IWSetLang(IW* iw,char* lang)

Function description: defines the application language.

Parameters:

• 1(char*) → English

• 2(char*) → French

void IWMaccessSet(IW* iw,char* macid)

Function description: provides the mAccess ID associated to its service

Parameters:

• macid (char*) → the mAccess identifier associated to the service (see the integration guide to know more about the mAccess ID)

int IWStorageDataChanged(IW* iw)

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

Returns:

• 0 → the stored data hasn’t changed

• 1 → the stored data has changed

 char* IWStorageDataGet(IW* iw)

Function description: gets the data to be stored locally. This string contains the internal state of mAccess (keys, service description …). The host should not try to process this string: it should only store it locally.

Returns: The data to be stored (ASCII string)

int IWStorageDataSet(IW* iw,char *src)

Function description: provides the stored data to the library. This should be done only once, at initialization.

Parameters:

• src (char*) → the location of the stored data

Returns: an error code

• IW_ERR_OK → no error

• IW_ERR_SN → syntax error

 int IWPinMode(IW* iw)

Function description: indicates the pin mode that should be used for the current process

Returns: pinmode

• 0 → PINMODE_NONE

• 1 → PINMODE_CURRENT

• 2 → PINMODE_NEW

• 8 → PINMODE_BIO

• 9 → PINMODE_CURRENT | PINMODE_BIO

To know more, refer to “Pin Mode codes” table.

int IWMajorVersionRequired(IW* iw)

Function description: indicates whether a major version update of the mAccess library is required.

Returns:

• 0 → no major version update is required

• 1 → a major version update is available and therefore required

char* IWNewVersionAvailable(IW* iw)

Function description: indicates whether a new version of the host/application is available

Returns:

• 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.

char* IWNewVersionURL(IW* iw)

Function description: gets the URL new version

Returns:

• If no new version is available, it returns empty string.

• If a new version is available, it returns the URL to get the new version

int IWShouldAskForMinorUpdate(IW* iw)

Function description: indicates whether a minor version update should be proposed to the user.

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

int IWIsActivated(IW* iw)

Function description: indicates whether the application integrating mAccess library is activated, whether the account is activated with mAccess or not.

Returns:

• 0 → the application is not activated

• 1 → the application is activated

int IWMustUpgrade(IW* iw)

Function description: indicates whether the application must upgrade first (the local data is from an old version).

Returns:

• 0 → the application is up to date

• 1 → the application must upgrade

int IWIsBlocked(IW* iw)

Function description: indicates whether the device is blocked. If yes, it has to be unlocked.

Returns:

• 0 → the device is not blocked

• 1 → the device is blocked

int IWServiceNb(IW* iw)

Function description: indicates the number of services

Returns: “1” which means that the application is linked to one service.

char* IWServiceName(IW* iw,int i)

Function description: indicates the name of the TrustBuilder service linked to the application

Parameters:

• i (int) → the index of the service associated with the user.
  In most configurations, this value must be 0, as users are typically linked to a single service. Non-zero values were used for multi-service setups but are now deprecated. Use the ServiceNb method to check the number of enrolled services and ServiceName to retrieve their names.

Returns: the service name

char* IWServiceLogo(IW* iw,int i)

Function description: indicates the URL of the service PNG logo.

Parameters:

• i (int) → the index of the service associated with the user.
  In most configurations, this value must be 0, as users are typically linked to a single service. Non-zero values were used for multi-service setups but are now deprecated. Use the ServiceNb method to check the number of enrolled services and ServiceName to retrieve their names.

Returns: URL of the service logo

int IWServiceDisabled(IW* iw,int i)

Function description: indicates whether the service is disabled or not.

Parameters:

• i (int) → the index of the service associated with the user.
  In most configurations, this value must be 0, as users are typically linked to a single service. Non-zero values were used for multi-service setups but are now deprecated. Use the ServiceNb method to check the number of enrolled services and ServiceName to retrieve their names.

Returns:

• 0 → the service is not disabled

• 1 → the service is disabled. When disabled, it may be displayed as grayed, and should not be accessible