Reference doc - mAccess library (Java)

ERR_OK

0

no error

ERR_NETWORK

1

network or server unreachable

ERR_CODE

2

The Activation code is incorrect

ERR_SN

3

one argument does not have the right syntax

ERR_ACCESS

4

access refused

ERR_VERSION

5

version error

ERR_BLOCKED

7

account is blocked

ERR_STATE

8

internal state not correct

ERR_NODEVICE

9

device is disabled or unknown

ERR_NOCA

10

User must activate helium or Desktop Token before achieving this operation

ERR_NOSRV

11

No service is available

ERR_PINREUSED

12

the new password equals the previous one

ERR_SYNCHROFAILED

13

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

ERR_FORBIDDEN

14

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

ERR_PINREFUSED

15

the password is refused (bad format)

ERR_TIMEOUT

16

timeout expired between xxxStart and xxxFinalize

ERR_BIOKEY

26

device is locked due to biokey errors

DESYNCHRONIZED

27

device desynchronized

ERR_OTHER

999

any other error

PINMODE_NONE

0

no pin is required (leave “”)

PINMODE_CURRENT

1

current pin is required

PINMODE_NEW

2

a new pin is required

PINMODE_BIO

8

a biokey is required

PINMODE_CURRENT | PINMODE_BIO

9

a pin OR biokey is required

public long ActivationStart(String code)

Method description: starts the device activation process.

Parameters:

• code (string) → activation code

Returns: an error code:

• ERR_OK: no error

• ERR_NETWORK: network error

• ERR_FORBIDDEN: device is already activated

• ERR_SN: syntax error for “code”

• ERR_VERSION: version error, user must upgrade the device

public long ActivationFinalize(String code, String pin, String name)

Method description: finalizes the device activation process

Parameters:

• code (string) → activation code

• pin (string) → the user’s pin code

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

Returns: an error code

• ERR_OK: no error

• ERR_NETWORK: network error

• ERR_FORBIDDEN: device is already activated

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

• ERR_PINREFUSED: syntax error for “pin”

• ERR_CODE: bad code.

• ERR_SN: syntax error for “code”

• ERR_TIMEOUT: timeout since ActivationStart

public long ResetStart(String code) 

Method description: starts the reset pin process

Parameters:

• code (string)→ unlock code

Returns: an error code

• ERR_OK: no error

• ERR_NETWORK: network error

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

• ERR_CODE: bad code.

• ERR_SN: syntax error for “code”

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

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

 public long ResetFinalize(String code, String pin)

Method description: finalizes the reset pin process

Parameters:

• code (string) → unlock code

• pin (string) → the user’s pin code

Returns: an error code

• ERR_OK: no error

• ERR_NETWORK: network error

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

• ERR_ACCESS: wrong password.

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

• ERR_SN: syntax error for “code”

• ERR_PINREFUSED: syntax error for “password”

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

• ERR_TIMEOUT: timeout since IWResetStart

public long SynchronizeStart()

Method description: starts the synchronization process to synchronize information between the application and TrustBuilderserver.

Returns: an error code

public long SynchronizeFinalize(String pin)

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

Parameters:

• pin (string) → the user’s pin code

Returns: an error code

public long PwdUpdateStart()

Method description: starts the pin update process

Returns: an error code

• ERR_OK: no error

• ERR_NETWORK: network error

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

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

• ERR_VERSION: version error, user must upgrade the device (see NewVersionAvailable)

public long PwdUpdateFinalize(String newpin, String pin)

Method description: finalizes the pin update process

Parameters:

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

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

Returns: an error code

• ERR_OK: no error

• ERR_NETWORK: network error

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

• ERR_ACCESS: wrong password.

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

• ERR_PINREFUSED: syntax error for “password”

• ERR_PINREUSED: new password equals previous password

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

• ERR_TIMEOUT: timeout since IWPwdUpdateStart

public long UnsetBiokeysStart()

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

Returns: an error code

• ERR_OK: no error

• ERR_NETWORK: network error

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

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

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

public long UnsetBiokeysFinalize(String pin)

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

Parameters:

• pin (string) → the user’s pin code

Returns: an error code

• ERR_OK: no error

• ERR_NETWORK: network error

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

• ERR_ACCESS: wrong password.

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

• ERR_TIMEOUT: timeout since UnsetBiokeysStart

public long SetBiokeyStart()

Method description: starts the biometrics registration process

Returns: an error code

• ERR_OK: no error

• ERR_NETWORK: network error

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

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

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

public long SetBiokeyFinalize(String biokey, String pin)

Method description: finalizes the biometrics registration process

Parameters:

• biokey(string) → biometric key

• pin(string) → the user’s pin code

Returns: an error code

• ERR_OK: no error

• ERR_NETWORK: network error

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

• ERR_ACCESS: wrong password.

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

• ERR_TIMEOUT: timeout since IWPwdUpdateStart

public long OnlineOtpStart(int i)

Method 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

• ERR_OK: no error

• ERR_NETWORK: network error

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

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

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

public long OnlineOtpFinalize(int i, String pin)

Method 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 (string) → the user’s pin code

Returns:

• ERR_OK: no error

• ERR_NETWORK: network error

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

• ERR_ACCESS: wrong password.

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

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

• ERR_TIMEOUT: timeout since IWOnlineOtpStart

public String OtpAnswerOtp()

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

Returns: an OTP

public long OnlineOtpFinalizeExt(int i, String pin, long keyType)

Method description: finalizes the “online OTP generation” process with biometric key or pin code.

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 (string) → the user’s pin code or the biokey depending on the keytype value

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

Returns: an error code

• ERR_OK: no error

• ERR_NETWORK: network error

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

• ERR_ACCESS: wrong password.

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

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

• ERR_TIMEOUT: timeout since IWOnlineOtpStart

public long OtpShouldSynchronize(int serviceid)

Method 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

public long OtpModeQuery(int serviceid)

Method 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

public String OtpGenerate(String pin)

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

Parameters:

• pin (string) → the user’s pin code

Returns: an OTP

public long DisplayTime()

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

Returns: Otp.displayTime()

public void SetDeviceOS(String deviceOS)

Method description: defines the device operating system.

Parameters:

• deviceOS (string) → the notification platform used for the application. For Android, it should be set to "firebase".
  ⚠️ If you set it to “android”, it will not work. This was the Google Cloud Messaging (GCM) configuration, which is now obsolete.

Deprecated versions

• Firebase Cloud Messaging (FCM) Legacy API was officially deprecated on June 2024 (More information). If your configuration is still based on FCM Legacy API, you should migrate to API V1. Please refer to this detailed note: How to upgrade to API V1.

• Google Cloud Messaging (GCM) was officially deprecated by Google on April 2018. If your configuration is still based on GCM, you should migrate to Firebase Cloud Messaging.

public long PushRegistrationStart()

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

Returns: an error code

• ERR_OK: no error

• ERR_NETWORK: network error

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

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

public long PushRegistrationFinalize(String push_id)

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

Parameters:

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

Returns: an error code

• ERR_OK: no error

• ERR_NETWORK: network error

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

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

• ERR_TIMEOUT: timeout since IWPushRegistrationStart

public long CheckPush()

Method 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

public String PushAlias()

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

Returns: pushAlias (string)

public String PushAction()

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

Returns: pushAction (string)

public String PushContext()

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

Returns: pushContext (string)

public long OnlineSealStart(int i)

Method 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

public long OnlineSealFinalize(int i, String pin, String sealdata)

Method 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 (string) → the user’s pin code

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

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

public long OnlineSealFinalizeExt(int i, String pin, long keyType, String sealdata)

Method description: finalizes the “online seal generation” process with biometric key or PIN code

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 (string) → the user’s pin code or the biokey depending on the keytype value

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

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

Returns: an error code

public String SealAnswerOtp()

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

Returns: an OTP

public long SealShouldSynchronize(int serviceid)

Method description: indicates if synchronization should be proposed to the user, BEFORE offline sealing. (i.e. before calling IWSealModeQuery ()). A synchronization is required if more than 3 OTPs are generated in less than 2 minutes for the same service

Parameters:

• serviceid (int) → the service identifier

Returns: OtpShouldSynchronize(serviceid)

• 0 → no synchronization required

• 1 → synchronization required

public long SealModeQuery(int serviceid)

Method 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

public String SealGenerate(String pin, String sealdata)

Method description: generates the seal

Parameters:

• pin (string) → the user’s pin code

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

Returns: the generated seal

public void Init(String SN, String appData)

Method description: initializes the library

Parameters:

• SN (string) → the device’s Serial Number - The SN is provided to the System variable Settings.Secure.ANDROID_ID: according to the documentation ‘a 64-bit number (expressed a 64-bit number hexadecimal string), unique to each combination of app-signing key, user, and device.’ More information about Settings.Secure class.

• appData(type) → timestamp of an install directory

SN and appData parameters should be sent as ASCII strings.

public static String VersionGet()

Method description: gets the mAccess library version

Returns: the library version number LIBVERSION()

public void HostVersionSet(String version)

Method description: provides the host/application version number.

Parameters:

• version (string) → 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

public void WsTimeoutSet(long t)

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

Parameters:

• t (long) → the timeout value

public void WsServerSet(String server)

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

Parameters:

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

public void LangSet(String l)

Method description: defines the application language.

Parameters:

• 1(string) → English

• 2(string) → French

public void MaccessSet(String macid)

Method description: provides the mAccess ID associated to its service

Parameters:

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

public long StorageDataChanged()

Method 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

 public String StorageDataGet()

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

public long StorageDataSet(String src)

Method description: provides the stored data to the library. This should be done at the app initialization.

Parameters:

• src (string) → the stored data

 public long PinMode()

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

public long MajorVersionRequired()

Method 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

public String NewVersionAvailable()

Method description: indicates whether a new version of the mAccess library 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.

public String NewVersionURL()

Method 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

public long ShouldAskForMinorUpdate()

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

 public long IsActivated()

Method 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

public long MustUpgrade()

Method 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

public long IsBlocked()

Method 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

public long ServiceNb()

Method description: indicates the number of services

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

public String ServiceName(int i)

Method 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

public String ServiceLogo(int i)

Method 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

public long ServiceDisabled(int i)

Method 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