Troubleshooting

View this page for | |

To facilitate troubleshooting and debugging, you can activate the SDK logging feature.

Note: It is recommended that you only enable logging for debugging builds of the integrating application.

HID Approve SDK uses NLog to implement logging. As demonstrated in the sample application, logging can be configured by using a standard NLog configuration file to specify the logging parameters. Alternatively, you can also configure NLog programmatically using the NLog.Config.LoggingConfiguration API.

The configuration file can be stored in either:

  • In the executable's working directory

  • As an injected dependency where NLog will search for the file with the following naming rules:

    • A standard application configuration file (for example, <applicationname>.exe.config)

    • The <applicationname>.exe.nlog file in the application’s directory

    • The NLog.config file in the application’s directory

    • If NLog isn't installed in the .NET Global Assembly Cache (GAC), the NLog.dll.nlog file in the same directory location as NLog.dll

When configuring NLog, it is recommended setting the user's 'LocalApplicationData' directory dedicated to your application as the location for the application logs (where \78A93DD0-94DE-4CA0-8080-95746C379535\ApproveSDK\logs is the output variable defined by the application).

For example, C:\Users\%username%\AppData\Local\Packages\%application_pfn%\LocalCache\78A93DD0-94DE-4CA0-8080-95746C379535\ApproveSDK\logs

Important: The HID Approve SDK logs will not contain any secret, personal data or sensitive information (such as UserID, device friendly name, keys, or passwords).

The logs might contain content required for troubleshooting purposes, such as:

  • DeviceID (unique identifier of a container to map with server-side)

  • Server URL

  • Date information for operations/actions

  • Transaction unique identifiers

Copy

Sample .NET NLog Configuration

<?xml version="1.0" encoding="utf-8" ?>
<!-- XSD manual extracted from package NLog.Schema: https://www.nuget.org/packages/NLog.Schema--><nlog xmlns="http://www.nlog-project.org/schemas/NLog.xsd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    autoReload="true">  <!-- the targets to write to -->
  <targets>
    <!-- write logs to file -->
    <target xsi:type="File" name="logfile" fileName="${specialfolder:folder=LocalApplicationData:cached=true}\78A93DD0-94DE-4CA0-8080-95746C379535\ApproveSDK\logs\ApproveSdk.log"
            layout="${longdate}|${processname}|${threadid}|${level}|${logger}|${message}|${all-event-properties} ${exception:format=tostring}" />
    <target xsi:type="Console" name="logconsole"
            layout="${longdate}|${processname}|${threadid}|${level}|${logger}|${message} |${all-event-properties} ${exception:format=tostring}" />
    <target name="debugger" xsi:type="Debugger" 
            layout="${longdate}|${processname}|${threadid}|${level}|${logger}|${message} |${all-event-properties} ${exception:format=tostring}" />
  </targets>  <!-- rules to map from logger name to target -->
  <rules>
    <logger name="*" minlevel="Trace" writeTo="logfile,logconsole,debugger" />
  </rules>
</nlog>
Note: If you are referencing the user's AppData directory, the physical location might vary depending on the Microsoft Windows platform version. For further information, go to the Microsoft documentation.

Error Codes

The following error codes might be returned by the SDK.

Internal Errors

Error Code Description

(0) Internal

An unexpected error occurred

(1) NotImplemented

The method is not implemented

(2) UnsupportedOperation

The operation is not supported by the object

(3) InvalidArgument

The given parameter is not valid or required

(4) KeyGenerationFailure

Unable to generate internal credential

(5) ProtectionPolicyFailure

Unable to create or locate internal protection policy

(6) SecureDataFailure

Unable to create or locate internal credential data

(7) UnsupportedVersion Container version is not supported and cannot be upgraded
(8) InvalidContainer Container identifier is invalid or does not exist
(9) InexplicitContainer Container is ambiguous and cannot be explicitly determined

Credential Errors

Error Code Description
(100) Authentication

Authentication failed

(101) InvalidPassword

The password fails policy requirements

(102) CredentialsExpired

The credentials used to sign the transaction have expired

(103) PasswordExpired

The password has expired and requires a change of password

Thrown by retrieveTransaction and setStatus when currentAge is greater or equal than maxAge.

(104) PasswordNotYetUpdatable

The password cannot be changed yet

Thrown by change password when currentAge is less than minAge.

(105) PasswordRequired

The required password was not provided

(106) LostCredentials

The provisioning key securing the transaction has been wiped. Most probably due to an update of the device's policy.

A new provisioning operation is required.

(107) InvalidChallengeTooLong

The challenge is too long with respect to the OTP configuration

(108) InvalidChallengeBadFormat

The challenge does not have the format expected by the OTP configuration

(109) PasswordCancelled

The password event has been canceled by the user

Device Errors

Error Code Description
(200) UnsupportedDevice

The device configuration is not supported

This exception can be returned if a given device is not supported by policy or does not have the minimum required security configuration.

(201) UnsafeDevice

The device is not safe enough to store sensitive secrets

For example, starting from LOLLIPOP, provisioning operation are forbidden if the mobile is not protected by a password.

(202) FingerprintNotEnrolled Fingerprints have not been enrolled
(203) UserCancelled The user has canceled the operation
(204) FingerprintAuthenticationRequired Authentication with fingerprint is required to perform the operation
(205) UnsupportedOperationMode Mode of operation required by the server is not supported by the device
(206) GooglePlayServicesObsolete Google Play services is not up to date
(207) BiometricAuthenticationNotEnabled Enabling biometric authentication is required to perform the operation

Communication Errors

Error Code Description
(300) ServerAuthentication Authentication to the server failed
(301) ServerVersion The server protocol version is not supported by the client
(302) ServerProtocol

An unexpected failure has occurred in the implementation layer

The server sent a message not compliant with the protocol version.

(303) Remote Execution of a remote method call failed
(304) ServerUnsupportedOperation The server does not support the requested operation
(305) ServerOperationFailed The server was not able to execute the requested operation
(306) ServerCustomizationInvalid The server's mobile-app customization package is invalid or contains an invalid data

Transaction Errors

Error Code Description
(1000) TransactionExpired The transaction has expired
(1001) TransactionContainerInvalid

The transaction id refers to a container that does not exist

It might happen if the container is deleted locally without notifying the server.