Integration of the User Input ASM

Android iOS

Integration of the User Input ASM (PIN/password)

The User Input ASM can optionally be included in your app. This ASM authenticates the user during FIDO operations. It ASM contains two sets of authenticators to handle a local secret: one for PIN and one for password. Each of the authenticators can handle only one local secret.

The ASM requests the user to manually enter a local secret known only by the user. This local secret can be a PIN or a password. The characters of the secret the user enters are hidden. Once the local secret has been entered and confirmed, the enrollment is completed. The weakness of the local secret can be verified during the enrollment, if this option is enabled.

When several accounts are registered with these authenticators, the first account enrolls a local secret; for the other accounts the user must authenticate by entering the same local secret. This has to be repeated until all the accounts registered with a given authenticator are deregistered.

Weak password control

User Input ASM authenticator uses the weak password control mechanism, the detection rules for weak passwords are:

• The difference between consecutive digits of the password must vary. Example: 12345 is a weak password because the difference between the consecutive digits is always +1.

• A row of 0s (N-1 0s for a PIN of N digits) followed by a number (e.g. 00003) or a number followed by a row of 0s (e.g. 2000) are not valid. (This is the ATM mimic.)

Weak password control is used during the activation process and on password change.

Android

Dependencies

To integrate this ASM, first add the Common ASM to your application’s module build.gradle file. See Dependencies for more information about the Common ASM Android dependencies.

Next, add the User Input ASM artifact and ConstraintLayout dependency. After adding these items, the build.gradle file should look like this:

dependencies {
   // CommonASM and its dependencies
   api files("path to library/FIDOUAFUserInputASM.aar")
   api "androidx.constraintlayout:constraintlayout:2.0.4"
   implementation "androidx.annotation:annotation:1.2.0"
   implementation "com.esotericsoftware:kryo:5.1.1"
   implementation "org.bouncycastle:bcprov-jdk15on:1.65"
    }

Permission

The following Android permission will be added automatically to your binary:

• android.permission.VIBRATE: The phone will vibrate when the user clicks buttons on the PIN pad, or when a wrong PIN is entered.

Descriptor and metadata

According to your requirements (i.e. use PIN or Password authenticators independently or at the same time), add the following lines to the descriptorclass array in your res/raw/asmdescriptors.json file:

• com.vasco.fido.uaf.asm.presence.PinASMDescriptor

• com.vasco.fido.uaf.asm.presence.PasswordASMDescriptor

See Embedding of an authenticator for more details.

The ASM is delivered with the following metadata files for Android:

• PIN

  • BD51#0005 (secure hardware protected devices with ECDSA)

  • BD51#0007 (software protected devices with ECDSA)

• Password

  • BD51#0008 (secure hardware protected devices with ECDSA)

  • BD51#000A (software protected devices with ECDSA)

Customization

You can omit the customization of the ASM—this is an optional feature of the FIDO Authentication Solution!

PIN customization

To facilitate the customization, you can use the default resources from the package (FIDO UAF SDK /Android/User Input ASM/Values).

You can use the Android XML system to customize the ASM.

To facilitate the customization, you can use the default resources from the package (FIDO UAF SDK /Android/User Input ASM/Values).

User Input ASM—PIN Registration on Android shows the customized PIN registration screen on an Android device.

Functional data

The following functional data (as integer values) can be customized via the integers.xml file:

Strings

The following raw string values can be customized via the strings.xml file:

Colors

The following colors in #argb and #rgb hex format can be customized via the colors.xml file.

Dimensions

The following dimen-type dimensions with values like dp, px, or sp can be customized via the dimens.xml file.

Icon

You can customize the icon that is displayed when the user has to choose between authenticators. It depends on the following resource string:

• vds_asm_pin_icon_drawable_name

The string value (by default vds_asm_pin_icon) corresponds to the name of a drawable resource, usually located in the drawable part of the Android resources system (e.g. res/drawable/vds_asm_pin_icon.png).

Password customization

To facilitate the customization, you can use the default resources from the package (FIDO UAF SDK /Android/User Input ASM/Values).

You can use the Android XML system to customize the ASM.

To facilitate the customization, you can use the default resources from the package (FIDO UAF SDK /Android/User Input ASM/Values).

User Input ASM—Password Registration on Android shows the customized password registration screen on an Android device.

Functional data

The following data (as integer values) can be customized via the integers.xml file:

Strings

The following raw string values can be customized via the strings.xml file:

Colors

The following colors in #argb and #rgb hex format can be customized via the colors.xml file.

Dimensions

The following dimen-type dimensions with values like dp, px, or sp can be customized via the dimens.xml file.

Icon

You can customize the icon that is displayed when the user has to choose between authenticators. It depends on the following resource string:

• vds_asm_password_icon_drawable_name

The string value (by default vds_asm_password_icon) corresponds to the name of a drawable resource, usually located in the in the drawable part of the Android resources system (e.g. res/drawable/vds_asm_password_icon.png).

You can use the Android XML system to customize the ASM. User Input ASM—Password Registration on Android shows the customized password registration screen on an Android device.

iOS

Dependencies

To integrate this ASM, add the following dependencies to your app:

• All the Common ASM iOS dependencies as listed in Dependencies.

• FIDOUAFUserInputASMResources.bundle (linked framework and libraries)

• FIDOUAFUserInputASM.xcframework (linked framework and libraries)

Initialization and metadata

To integrate the PIN or password authenticator with C++

• According to your requirements (i.e. use PIN or password authenticators independently or at the same time), add the following lines to AppDelegate in the didFinishLaunchingWithOptions: method:

  #import <FIDOUAFUserInputASM/FIDOUserInputASMInstanceCreator.hpp>
  asmcore::ASMFactory::addAuthenticator
  (FIDOUserInputASMInstanceCreator::createPinInstance());
  asmcore::ASMFactory::addAuthenticator
  (FIDOUserInputASMInstanceCreator::createPasswordInstance());

  See Embedding of an authenticator for more details.

  The ASM is delivered with the following metadata files for iOS:

  • PIN

    • BD51#000B (secure hardware protected devices with ECDSA)

  • Password

    • BD51#000D (secure hardware protected devices with ECDSA)

To integrate the PIN or password authenticator with Swift/Objective-C

• According to your requirements (i.e. use PIN or password authenticators independently or at the same time), add the following lines to AppDelegate in the didFinishLaunchingWithOptions: method:

  import FIDOUAFUserInputASM
  // Add user input PIN authenticator to ASM
  FIDOUserInputASM.registerPinAuthenticator()
  // Add user input password to ASM
  FIDOUserInputASM.registerPasswordAuthenticator() 

  See Embedding of an authenticator for more details.

  The ASM is delivered with the following metadata files for iOS:

  • PIN

    • BD51#000B (secure hardware protected devices with ECDSA)

  • Password

    • BD51#000D (secure hardware protected devices with ECDSA)

Customization

You can omit the customization of the ASM—this is an optional feature of the FIDO Authentication Solution!

PIN customization

You can use the iOS Localizable.strings to customize the ASM. User Input ASM—PIN Registration on iOS shows the customized PIN registration screen on an iOS device.

The following keys are available for the customization of this authenticator:

Icon

You can customize the icon that is displayed when the user has to choose between authenticators. It depends on the following resource string:

• vds_asm_pin_icon

The string value (by default user_input_pin) corresponds to the name of a drawable resource, usually located in the drawable part of the iOS resources system (e.g. userinput_pin.png).

Dark mode support

The Tutorial App is delivered with a storyboard called FIDO_UAF_UserInputPinASM.storyboard (see Tutorial App—User Input ASM PIN Storyboard).

By modifying it, it is possible to customize fonts and colors. The Dark mode is managed by declaring named colors in the Assets catalog Images.xcassets. This feature requires iOS 11 or later.  The storyboard takes over the string customization of colors as soon as it is added in the integrating project.

This storyboard contains several links to outlets that are defined inside the FIDOUAFUserInputASM.xcframework. These links cannot be restored if they are removed.

The error in the storyboard (see Tutorial App User Input ASM PIN Storyboard—Error Message) is displayed by default and does not indicate that the compilation has failed.

Password customization

You can use the iOS Localizable.strings to customize the ASM. User Input ASM—Password Registration on iOS shows the customized password registration screen on an iOS device.

Customization keys

The following keys are available for the customization of this authenticator:

Icon

You can customize the icon that is displayed when the user has to choose between authenticators. It depends on the following resource string:

• vds_asm_password_icon

The string value (by default userinput_password) corresponds to the name of a drawable resource, usually located in the iOS resources system (e.g. vds_asm_password_icon).

Dark mode support

The Tutorial App is delivered with a storyboard called FIDO_UAF_UserInputPasswordASM.storyboard (see Tutorial App—User Input ASM Password Storyboard).

Modify this storyboard to customize fonts and colors. To manage the Dark mode, declare named colors in the Assets catalog Images.xcassets.  The storyboard takes over the string customization of colors as soon as it is added in the integrating project.

This feature requires iOS 11 or later.

This storyboard contains several links to outlets that are defined inside the FIDOUAFUserInputASM.xcframework. These links cannot be restored if they are removed.