Reference doc - mAccess library (iOS)

This is a reference documentation of the TrustBuilder MFA mAccess library (iOS). It lists error codes and functions integrated in the library.

Download mAccess library

The last version of TrustBuilder MFA mAccess library is available on the Resources Downloads page.

The mAccess library for iOS is a static C library. To integrate it in Swift, go over the implementation guide and the sample application to know how to integrate the TrustBuilder MFA SDK to your iOS application.

Error codes

Code	Value	Description
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

Pin Mode codes

Code	Value	Description
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

Functions

The following functions are declared is the header file iw.h.

Activation

IWActivationStart

CODE

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

IWActivationFinalize

CODE

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

Unlock - Reset PIN

IWResetStart

CODE

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)

IWResetFinalize

CODE

 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

Synchronization

IWSynchronizeStart

CODE

int IWSynchronizeStart(IW* iw)

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

Returns: an error code

IWSynchronizeFinalize

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

PIN update

IWPwdUpdateStart

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)

IWPwdUpdateFinalize

CODE

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

Reset all Biometric keys

IWUnsetBiokeysStart

CODE

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)

IWUnsetBiokeysFinalize

CODE

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

Register Biometric key

IWSetBiokeyStart

CODE

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)

IWSetBiokeyFinalize

CODE

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

Online OTP

IWOnlineOtpStart

CODE

int IWOnlineOtpStart(IW* iw,int i)

Function description: starts the “online OTP generation” process

Parameters:

i (int) → the service index in the table of available services. For a standard configuration with one service, the service index is 0.

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)

IWOnlineOtpFinalize

CODE

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

Function description: finalizes the “online OTP generation” process

Parameters:

i(int) → the service index in the table of available services. For a standard configuration with one service, the service index is 0.
pin (char*) → the user’s pin code

Returns: IWOnlineOtpFinalizeExt(i, pin, 0)

IWOtpAnswerOtp

CODE

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

IWOnlineOtpFinalizeExt

CODE

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 service index in the table of available services. For a standard configuration with one service, the service index is 0.
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

Offline OTP

IWOtpShouldSynchronize

CODE

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

CODE

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

IWOtpGenerateMa

CODE

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

IWDisplayTime

CODE

int IWDisplayTime(IW* iw)

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

Returns: Otp.displayTime()

Push Notifications

IWSetDeviceOS

CODE

void IWSetDeviceOS(IW* iw, char *deviceos)

Function description: defines the device operating system.

Parameters:

deviceOS (char*) → the device’s OS

To use Firebase notification service you must change the device OS to "firebase" using IWSetDeviceOS("firebase").

IWPushRegistrationStart

CODE

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

IWPushRegistrationFinalize

CODE

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

IWCheckPush

CODE

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

IWPushAlias

CODE

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

IWPushAction

CODE

public String PushAction()

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

Returns: pushAction (char*)

IWPushContext

CODE

char* IWPushContext(IW* iw)

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

Returns: pushContext (char*)

Sealing

IWOnlineSealStart

CODE

int IWOnlineSealStart(IW* iw, int i)

Function description: starts the “online seal generation” process

Parameters:

i (int) → the service index in the table of available services. For a standard configuration with one service, the service index is 0.

Returns: an error code

IWOnlineSealFinalize

CODE

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

Function description: finalizes the “online seal generation” process

Parameters:

i(int) → the service index in the table of available services. For a standard configuration with one service, the service index is 0.
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)

IWOnlineSealFinalizeExt

CODE

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 service index in the table of available services. For a standard configuration with one service, the service index is 0.
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

IWSealAnswerOtp

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

IWSealShouldSynchronize

CODE

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

IWSealModeQuery

CODE

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

IWSealGenerate

CODE

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

Configuration

IWVersionGet

CODE

char* IWVersionGet(IW* iw)

Function description: gets the mAccess library version

Returns: the library version number IWLIBVERSION()

IWHostVersionSet

CODE

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

IWWsTimeoutSet

CODE

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

IWWsServerSet

CODE

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”

IWLangSet

CODE

void IWSetLang(IW* iw,char* lang)

Function description: defines the application language.

Parameters:

1(char*) → English
2(char*) → French

IWMaccessSet

CODE

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)

Storage

IWStorageDataChanged

CODE

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

IWStorageDataGet

CODE

 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)

IWStorageDataSet

CODE

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

Information

IWPinMode

CODE

 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.

IWMajorVersionRequired

CODE

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

IWNewVersionAvailable

CODE

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.

IWNewVersionURL

CODE

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

IWShouldAskForMinorUpdate

CODE

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.

IWIsActivated

CODE

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

IWMustUpgrade

CODE

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

IWIsBlocked

CODE

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

IWServiceNb

CODE

int IWServiceNb(IW* iw)

Function description: indicates the number of services

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

IWServiceName

CODE

char* IWServiceName(IW* iw,int i)

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

Parameters:

i (int) → the service index in the table of available services. For a standard configuration with one service, the service index is 0.

Returns: the service name

IWServiceLogo

CODE

char* IWServiceLogo(IW* iw,int i)

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

Parameters:

i (int) → the service index in the table of available services. For a standard configuration with one service, the service index is 0.

Returns: URL of the service logo

IWServiceDisabled

CODE

int IWServiceDisabled(IW* iw,int i)

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

Parameters:

i (int) → the service index in the table of available services. For a standard configuration with one service, the service index is 0.

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

Asynchronous functions

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

See asynchronous functions

int IWActivationStartAsync(IW* iw,char* code, IWCALLBACK callback, void *user)
int IWActivationFinalizeAsync(IW* iw,char* code,char* pin,char* name, IWCALLBACK callback, void *user)
int IWResetStartAsync(IW* iw,char* code, IWCALLBACK callback, void *user)
int IWResetFinalizeAsync(IW* iw,char* code,char* pin, IWCALLBACK callback, void *user)
int IWUpgradeStartAsync(IW* iw, IWCALLBACK callback, void *user)
int IWUpgradeFinalizeAsync(IW* iw,char* pin,char* oldserial, IWCALLBACK callback, void *user)
int IWPwdUpdateStartAsync(IW* iw, IWCALLBACK callback, void *user)
int IWPwdUpdateFinalizeAsync(IW* iw,char* newpin,char* pin, IWCALLBACK callback, void *user)
int IWSynchronizeStartAsync(IW* iw, IWCALLBACK callback, void *user)
int IWSynchronizeFinalizeAsync(IW* iw,char* pin, IWCALLBACK callback, void *user)
int IWOnlineOtpStartAsync(IW* iw,int i, IWCALLBACK callback, void *user)
int IWOnlineOtpFinalizeAsync(IW* iw,int i,char* pin, IWCALLBACK callback, void *user)
int IWOnlineOtpFinalizeExtAsync(IW* iw, int i, char* pin, int keytype, IWCALLBACK callback, void *user)
int IWOnlineSealStartAsync(IW* iw, int i, IWCALLBACK callback, void *user)
int IWOnlineSealFinalizeAsync(IW* iw, int i, char* pin, char *sealdata, IWCALLBACK callback, void *user)
int IWOnlineSealFinalizeExtAsync(IW* iw, int i, char* pin, int keytype, char *sealdata, IWCALLBACK callback, void *user)
int IWSetBiokeyStartAsync(IW* iw, IWCALLBACK callback, void *user)
int IWSetBiokeyFinalizeAsync(IW* iw, char* biokey, char* pin, IWCALLBACK callback, void *user)
int IWUnsetBiokeysStartAsync(IW* iw, IWCALLBACK callback, void* user)
int IWUnsetBiokeysFinalizeAsync(IW* iw, char* pin, IWCALLBACK callback, void* user)
int IWPushRegistrationStartAsync(IW* iw, IWCALLBACK callback, void *user)
int IWPushRegistrationFinalizeAsync(IW* iw, char *push_id, IWCALLBACK callback, void *user)
int IWCheckPushAsync(IW* iw, IWCALLBACK callback, void *user)