Protection Policy

View this page for | |

The protection policy defines the protection requirements for a provisioned object (Transaction Signing Key, Session Transport Key, or OTP Key).

The PolicyType values are:

DEVICE – the object is protected against cloning (that is, it cannot be used outside the mobile device).
PASSWORD – the object is also protected by an end-user password.
BIOPASSWORD – same as Password but with additional support for an alternative biometric authentication (for example, fingerprint/face/iris) on a hardware-capable device.

For further details, see:

ActivID AS push solution customization

ActivID Appliance push solution customization

HID Authentication Service push solution customization

PasswordPolicy

This policy defines the constraints on the password protecting the object:

Minlength – Minimum password length
Maxlength – Maximum password length
Additional restrictions for alphanumeric format:
- Min Number of UpperCase letters
- Min Number of LowerCase letters
- Min Number of Alpha characters
- Min Number of Numeric characters
- Min Number of Non-Alphanumeric characters
- Maximum Number of UpperCase letters
- Maximum Number of LowerCase letters
- Maximum Number of Alpha characters
- Maximum Number of Numeric characters
- Maximum Number of Non-Alphanumeric characters
History restriction parameters:
- maxHistory – number of unique new passwords that have to be associated with the key before an old password can be reused. 0 authorizes users to reuse current password when password is changed. This value is set by the server.
- minAge – period of time (in days) that a password must be used before the user can change it. It must be less than the maximum password age. 0 allow changes immediately. This value is set by the server.
- maxAge – period of time (in days) users can keep a password before they have to change it. 0 means password never expires. This value is set by the server.
  Note: Password expiration (maxAge) is ignored when the SilentLockPolicy is configured for use.
Caching parameters:
- CacheEnabled - flag indicating if the password cache is enabled
- CacheTimeout - period of time (in seconds) during which with password is stored in the cache (by default, 30 seconds)

Note:

When defining the rules of the password policy, make sure that there are no logical conflicts. For example, do not specify that the minimum number of numeric characters is 8, in combination a maximum password length of 6 characters.
When not set, the maximum values are equal to the maximum length defined for the password.

BioPasswordPolicy – Authentication with Biometrics (Fingerprint/Facial/Iris)

Biometric authentication is a convenient alternative to password authentication for end users.

Importantly, it does not replace the password as users can fallback to password authentication at any time.

In that perspective, provisioning for biometric authentication is the same as Container Provisioning. The user must provide the password during the container creation.

Server-side – the policy to configure at container or key level is ‘biometricorpassword’
Client-side – the policy protecting the keys is represented by BioPasswordPolicy, extending PasswordPolicy.

Note: If the user’s device does not have a fingerprint sensor (or the manufacturer does not support the authorized Biometrics class level), then the policy is represented by PasswordPolicy.

For further details, see:

ActivID AS Key Protection Policy Parameters

ActivID Appliance Key Protection Policy Parameters

HID Authentication Service Key Protection Policy Parameters

To provide a concrete example, most fingerprint authentication sensors are certified as Class 3 (Strong) but facial recognition sensors are often certified as Class 2 (weak) but can vary depending on manufacturer and device capabilities.

An integrator can widen security restrictions to authorize the use of biometric class 2 (weak) authenticators by adding an authentication rule to the device policy rules.

Enabling Authentication with Fingerprint/Face/Iris

By default, biometric authentication is not enabled. That means that BioPasswordPolicy, acts exactly as PasswordPolicy until it is explicitly enabled.

The authentication state can be discovered using BioPasswordPolicy.getBioAuthenticationState. It returns one of the BioAuthenticationState values:

ENABLED – biometric authentication is enabled, the SDK will accept password null in authentication methods
NOT_ENABLED – biometric authentication is not enabled
To enable, a call to BioPasswordPolicy.enableBioAuthentication is required.
NOT_CAPABLE – the device does not have a biometric sensor so biometric authentication is not possible
NOT_ENROLLED – the user has not enrolled biometric features at the device level so biometric authentication cannot be enabled

To enable biometric authentication, the app calls BioPasswordPolicy.enableBioAuthentication as illustrated below.

Sample Enabling Biometric Authentication on Android

Kotlin Java

Copy

// You can check the policy protecting the container, or alternatively a policy protecting a key.
    // Unless a specific configuration is used, they will be the same.
    var containerPolicy: ProtectionPolicy? = null
    try {
        containerPolicy = myContainer.protectionPolicy
    } catch (e: UnsupportedDeviceException) {
        e.printStackTrace()
    } catch (e: InternalException) {
        e.printStackTrace()
    } catch (e: LostCredentialsException) {
        e.printStackTrace()
    }
    // Identify the protection policy with the type BIOPASSWORD
    if (containerPolicy!!.type == ProtectionPolicy.PolicyType.BIOPASSWORD.toString()) {
        // The BIOPASSWORD policy enables you to rely on the biometric API of the device
        // The first step is to enable the usage of the biometric API in replacement of the password.
        val bioPasswordPolicy = containerPolicy as BioPasswordPolicy?
        try {
            if (bioPasswordPolicy!!.bioAuthenticationState == BioAuthenticationState.NOT_ENABLED || bioPasswordPolicy!!.bioAuthenticationState == BioAuthenticationState.INVALID_KEY) {
                // You need to prompt the user for his/her password
                // Then enable authentication with fingerprint
                val userPassword = "userPassword".toCharArray()
                bioPasswordPolicy.enableBioAuthentication(userPassword)
            }
        } catch (e: InternalException) {
            e.printStackTrace()
        } catch (e: UnsupportedDeviceException) {
            e.printStackTrace()
        } catch (e: LostCredentialsException) {
            e.printStackTrace()
        } catch (e: AuthenticationException) {
            e.printStackTrace()
        } catch (e: FingerprintNotEnrolledException) { // The user has not enrolled its biometric data in the device.
            e.printStackTrace()
        } catch (e: FingerprintAuthenticationRequiredException) { //Authentication with fingerprint is required to perform the operation.
            e.printStackTrace()
        } catch (e: PasswordExpiredException) { // !!!  PasswordExpiredException if expired password is given (changePassword required). !!!
            e.printStackTrace()
        }
    }

Copy

// You can check the policy protecting the container, or alternatively a policy protecting a key.
    // Unless a specific configuration is used, they will be the same.
    ProtectionPolicy containerPolicy = null;
    try {
        containerPolicy = myContainer.getProtectionPolicy();
    } catch (UnsupportedDeviceException | InternalException | LostCredentialsException e) {
        e.printStackTrace();
    }
    
    // Identify the protection policy with the type BIOPASSWORD
    if (containerPolicy.getType().equals(ProtectionPolicy.PolicyType.BIOPASSWORD.toString())) {

        // The BIOPASSWORD policy enables you to rely on the biometric API of the device
        // The first step is to enable the usage of the biometric API in replacement of the password.
        BioPasswordPolicy bioPasswordPolicy = (BioPasswordPolicy) containerPolicy;
        try {
            if (bioPasswordPolicy.getBioAuthenticationState() == BioAuthenticationState.NOT_ENABLED || bioPasswordPolicy.getBioAuthenticationState() == BioAuthenticationState.INVALID_KEY) {
                // You need to prompt the user for his/her password
                // Then enable authentication with fingerprint
                char[] userPassword = "userPassword".toCharArray();
                bioPasswordPolicy.enableBioAuthentication(userPassword);
            }
        } catch (InternalException | UnsupportedDeviceException | LostCredentialsException | AuthenticationException e) {
            e.printStackTrace();
        } catch (FingerprintNotEnrolledException e) { // The user has not enrolled its biometric data in the device.
            e.printStackTrace();
        } catch (FingerprintAuthenticationRequiredException e) { //Authentication with fingerprint is required to perform the operation.
            e.printStackTrace();
        } catch (PasswordExpiredException e) { // !!!  PasswordExpiredException if expired password is given (changePassword required). !!!
            e.printStackTrace();
        }
    }

Authenticating with Fingerprint/Face/Iris

Regardless of the operation to perform (transaction signing, OTP generation…), if the key is protected by BioPasswordPolicy, (Key.getProtectionPolicy) and fingerprint authentication is enabled (BioPasswordPolicy.getBioAuthenticationState), then the app does not have to prompt the end user for their password. Instead, the app calls the SDK methods, passing null value as the password.

The behavior depends on the platform.

The SDK leverages the Android Biometrics Jetpack Library (androidx.biometric API). The framework handles the UI display for the app and notifies fingerprint or biometric sensor events through a callback for all Android 6.0 (API level 23) devices and later. Refer to the Android documentation for details.

Before performing the intended operation, the app needs to pass a FragmentActivity or Fragment, AuthenticationCallback, and PromptInfo structure to the HID Approve SDK using setBiometricPrompt:

FragmentActivity or Fragment to reference the application’s activity.
AuthenticationCallback to be notified of sensor events.
PromptInfo to provide a system dialog prompt.

Then, the app calls the SDK method, passing null value as the password.

During this operation, the Android platform biometrics framework is triggered to display a dialog using the provided PromptInfo and invoke the provided AuthenticationCallback delegate for any additional handling of sensor events.

The resetBiometricPrompt method will release objects stored during the setBiometricPrompt method call. This method should be called when the app wants to disable SDK biometric support.

The following sample illustrates the required calls (for readability, the snippet does not include problems related to UI refresh):

Sample Fingerprint Authentication on Android

Kotlin Java

Copy

// You need to define and registered the callback for the biometric authentication
    // https://developer.android.com/reference/androidx/biometric/BiometricPrompt.AuthenticationCallback
    val customAuthenticationCallback: BiometricPrompt.AuthenticationCallback =
        object : BiometricPrompt.AuthenticationCallback() {
            override fun onAuthenticationFailed() {
                // The biometric data provided are incorrect
            }

            override fun onAuthenticationError(errorCode: Int, errString: CharSequence) {
                //Called when an unrecoverable error has been encountered and authentication has stopped.
            }

            override fun onAuthenticationSucceeded(result: BiometricPrompt.AuthenticationResult) {
                // The biometric data provided are correct
            }
        }
    if (customAuthenticationCallback != null) {
        // You can check the policy protecting the container, or alternatively a policy protecting a key.
        // Unless a specific configuration is used, they will be the same.
        var protectionPolicy: ProtectionPolicy? = null
        try {
            protectionPolicy = myContainer.protectionPolicy
        } catch (e: UnsupportedDeviceException) {
            e.printStackTrace()
        } catch (e: InternalException) {
            e.printStackTrace()
        } catch (e: LostCredentialsException) {
            e.printStackTrace()
        }
        if (protectionPolicy is BioPasswordPolicy) {
            // You need to configure the prompt that will be displayed to the user
            // https://developer.android.com/reference/androidx/biometric/BiometricPrompt.PromptInfo
            val promptInfo = PromptInfo.Builder()
                .setTitle("Confirm fingerprint to continue")
                .setNegativeButtonText("Cancel")
                .build()
            // Provide the activity or fragment you will associate with the prompt
            protectionPolicy.setBiometricPrompt(
                myActivity,
                customAuthenticationCallback,
                promptInfo
            )
        }
    }
    // ............
    // You can now perform the requested operation without providing password.
    // you will be prompted by the promptInfo you defined earlier
    // Authentication error will be handle by customAuthenticationCallback
    // For example getOTP :
    try {
        val otp = otpGenerator!!.getOTP(null)
    } catch (e: AuthenticationException) {
        e.printStackTrace()
    } catch (e: InternalException) {
        e.printStackTrace()
    } catch (e: PasswordExpiredException) {
        e.printStackTrace()
    } catch (e: FingerprintAuthenticationRequiredException) {
        e.printStackTrace()
    } catch (e: PasswordRequiredException) {
        e.printStackTrace()
    }

Copy

// You need to define and registered the callback for the biometric authentication
    // https://developer.android.com/reference/androidx/biometric/BiometricPrompt.AuthenticationCallback

    BiometricPrompt.AuthenticationCallback customAuthenticationCallback = new BiometricPrompt.AuthenticationCallback() {
        @Override
        public void onAuthenticationFailed() {
            // The biometric data provided are incorrect
        }
        @Override
        public void onAuthenticationError(int errorCode, CharSequence errString) {
            //Called when an unrecoverable error has been encountered and authentication has stopped.
        }

        @Override
        public void onAuthenticationSucceeded(BiometricPrompt.AuthenticationResult result) {
            // The biometric data provided are correct
        }
    };


    if (customAuthenticationCallback != null) {
        // You can check the policy protecting the container, or alternatively a policy protecting a key.
        // Unless a specific configuration is used, they will be the same.
        ProtectionPolicy protectionPolicy = null;
        try {
            protectionPolicy = myContainer.getProtectionPolicy();
        } catch (UnsupportedDeviceException e) {
            e.printStackTrace();
        } catch (InternalException e) {
            e.printStackTrace();
        } catch (LostCredentialsException e) {
            e.printStackTrace();
        }
        if (protectionPolicy instanceof BioPasswordPolicy) {
            // You need to configure the prompt that will be displayed to the user
            // https://developer.android.com/reference/androidx/biometric/BiometricPrompt.PromptInfo
            androidx.biometric.BiometricPrompt.PromptInfo promptInfo =
                    new androidx.biometric.BiometricPrompt.PromptInfo.Builder()
                            .setTitle("Confirm fingerprint to continue")
                            .setNegativeButtonText("Cancel")
                            .build();
            // Provide the activity or fragment you will associate with the prompt
            ((BioPasswordPolicy) protectionPolicy).setBiometricPrompt( myActivity , customAuthenticationCallback, promptInfo );
        }
    }
    // ------
    // You can now perform the requested operation without providing password.
    // you will be prompted by the promptInfo you defined earlier
    // For example getOTP :
    try {
        char[] otp = otpGenerator.getOTP(null);
    } catch (AuthenticationException e) {
        e.printStackTrace();
    } catch (InternalException e) {
        e.printStackTrace();
    } catch (PasswordExpiredException e) {
        e.printStackTrace();
    } catch (FingerprintAuthenticationRequiredException e) {
        e.printStackTrace();
    } catch (PasswordRequiredException e) {
        e.printStackTrace();
    }

For further details, see:

ActivID AS Key Protection Policy Parameters

ActivID Appliance Key Protection Policy Parameters

HID Authentication Service Key Protection Policy Parameters

Lock Policy

The following sections define the LockType type and parameters for the password and lock.

Type

NONE – password never locks.
LOCK – password locks after maximum counter value is reached.
DELAY – an exponential delay is inserted between each failed authentication attempt.
SILENT – any password is accepted without providing indication of an incorrect password when offline (delegating control, auditing, and verification of cryptographic operations to the server-side).

Parameters

initialDelay – initial delay value in seconds (in delayLock type).
maxCounterValue – maximum counter value after which exponential delay is fixed in delayLock type, or maximum counter value after which no more authentication attempts are allowed in counterLock type.

For further details, see:

ActivID AS Key Protection Policy Parameters

ActivID Appliance Key Protection Policy Parameters

HID Authentication Service Key Protection Policy Parameters