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

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

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

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

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

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

public String ServiceLogo(int i)

Method 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

public long ServiceDisabled(int i)

Method 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