Digipass S3 is now DigipassONE. This section is currently being updated to reflect our new name.

PIN Management Library

  • Published on Nov 24, 2025
  • 4 minute(s) read
Prev Next

The PIN Management Library is used to simplify PIN-based authenticator development. It encapsulates the main PIN-specific functionality, such as:

  • Storing PIN

  • Verifying PIN

  • Deleting PIN

  • Changing PIN

  • Anti-hammering support

In addition, the library includes a class called PinInputLayoutBase. Use this class to create a smarter UI for entering a PIN. For example, it can enforce checks on minimum and maximum PIN length at the UI level. It has a simple API with common methods for PIN input such as appending or deleting digits with common logic, as well as an abstract drawing method. Create a derived class to provide custom UI implementation. For more information please refer to the Javadoc.

The Authenticator SDK contains the asm_sample_service project which includes sample code that demonstrates usage of all PIN functionality.

Adding Library Dependencies to an Existing Project

The PIN Management Library and the dependent modules are delivered as AAR packages. The following instructions describe how to add dependency from asmsdk_pin_mgt to an existing project.

Update the top-level build.gradle file of your project and add the asmsdk_pin_mgt AAR folders to the repository. For example:

allprojects {
    repositories {
        jcenter()
        maven { url "${rootProject.projectDir}/../m2repository" }
    }
}

Add the dependencies to your app. To do this, edit the app-module-specific build.gradle file to add these dependencies:

dependencies { 
    . . . 
    // These are the common dependencies for any ASM
    compile "com.noknok:asmsdk_uaf:9.3.0"
    // This is dependency for asmsdk_pin_mgt
    compile "com.noknok:asmsdk_pin_mgt:9.3.0"
}

For an example of asmsdk_pin_mgt dependency, see the asm_sample_service project.

PinManager Class Usage

PinManager is the main entry point class for the PIN Management Library. To use the library features, you must first instantiate PinManager using the following statement:

mPinManager = PinManager(aaid, context, antiHammeringCallback)

The aaid and antiHammeringCallback parameters should be taken from matcherInParams. The created object could be stored as a member for further use. The PinManager class could be used both from the authenticator matcher implementation or from the authenticator UI activity, depending on the required design.

In the case of using PinManager in the matcher class, the matcher should open the UI and get PIN from it. After closing the UI, it should call the appropriate PinManager methods.

In the second case, you must implement some way to pass the aaid and antiHammeringCallback parameters available in the matcher to the authenticator activity.

For more details, see the asm_sample_service project.

Enrollment

To enroll a new PIN, use the following call:

mPinManager.enroll(pinToEnroll);

This method gets the pinToEnroll parameter which is the PIN entered by the user in String format. It returns a boolean result: true if enrollment completed successfully and false otherwise.

Verification

To verify the PIN, use the following call:

PinManager.VerifyStatus status = mPinManager.verify(pinToVerify);

This method gets the pinToVerify parameter which is the PIN entered by user in String format. It returns the result of PinManager.VerifyStatus type, which is an enumeration containing all possible verification results:

  • SUCCESS - Operation completed successfully

  • FAILED - Operation failed for some reason not related with PIN verification

  • PIN_INVALID - Verification failed, invalid PIN provided

  • PIN_ERASED - PIN data erased due to too many failed attempts

After completing verification, the return value should be analyzed to take the appropriate action.

Change PIN

To change the existing PIN, use the following call:

PinManager.VerifyStatus status = mPinManager.changePin(oldPin, newPin);

This method gets the oldPin and newPin parameters in String format. It verifies the old PIN and if valid, replaces it with the new PIN. It returns the result of the PinManager.VerifyStatus type as described above.

Remove PIN

To permanently remove the previously enrolled PIN, use the following call:

mPinManager.removePin();

This method has no parameters and is void. It just removes all PIN-related data from the database.

Is Enrolled

To check if there are any PIN enrollments, use the following call:

mPinManager.isEnrolled();

This method returns boolean true if there are any enrollments and false otherwise.

Get PIN Configuration

To get the supported PIN configuration parameters, use the following call:

PinDatabase.PinConfig limits = mPinManager.getPinConfig()

This method returns the pinConfig object which contains the PIN creation rules and constraints including minLength, maxLength, maxRepeatDigits, maxSequentialDigits, confirmationButton, and nonReusableOldPINs. In addition, pinConfig contains 3 parameters for anti-hammering configuration: maxFalseAttempts, probationPeriod, and lockoutPeriod. However, you could configure these values by adding the following to the mfac_config.json file:

{
    "pinConfig":{
        "minLength": 4,
        "maxLength": 4,
        "maxRepeatDigits": 0,
        "maxSequentialDigits": 0,
        "confirmationButton": true,
        "maxFalseAttempts": 10,
        "probationPeriod": 0,
        "lockoutPeriod": 0,
        "nonReusableOldPINs": 0
    }
}

The above example shows the default values.

Get Current PIN Length

To get the actual length of an already enrolled PIN, use the following call:

int pinLength = mPinManager.getPinLength();

This method returns the length of the enrolled PIN or 0 if there are no enrollments.

Handling Anti-Hammering

Use the antiHammeringCallback object to implement anti-hammering functionality. Note that there is no need to instantiate this object. To work properly, you must pass the antiHammeringCallback object received in matcherInParams to the PinManager constructor. The same object can be used to get the current number of failed attempts.

In the current PIN Management Library implementation, the maximum failed attempts count is set to 10, by default. After 10 failures, PIN data is automatically erased and the PIN_ERASED PIN verification status is returned. You can override the default value by using setMaxFalseAttempts(int maxFalseAttempts). You can also configure probation period and lockout period. By default, both values are set to 0 which means that the probation period is infinite and, instead of lockout, the PIN is erased when the end user reaches MaxFalseAttempts. Use setProbationPeriod(long probationPeriod) to set the new probation period in seconds. Use setLockoutPeriod(long lockoutPeriod) to set the lockout period in seconds.

No action is required to increase or reset the failed attempts count. These actions are automatically performed on each verify or changePin call, depending on the PIN verification result. But if you have a requirement to show a different warning message based on the current number of failed attempts, you can get that number with the following call:

int failedCount = antiHammeringCallback.getFailedCount();

So each time PIN verification fails, you can retrieve this count and display the appropriate message based on the returned count.