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 HIDPolicyType values are:

  • HIDPolicyTypeDevice – the object is protected against cloning (that is, it cannot be used outside the mobile device).
  • HIDPolicyTypePassword – the object is also protected by an end-user password.
  • HIDPolicyTypeBioPassword – same as Password but with additional support for an alternative biometric authentication (for example, TouchID/FaceID) 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.

You can define an exclusive numeric (PIN) policy which is more user-friendly in mobile authentication deployments.

As an example, the following parameters can be used to set a numeric-only policy for a 6 to 10-character password length:

  • MinLength = 6
  • MaxLength = 10
  • MinNumeric = 6
  • MaxNumeric = 10
  • maxUpperCase = 0
  • maxLowerCase = 0
  • maxAlpha = 0
  • maxNonAlpha = 0

In the server configuration, this would be defined with the following key protection policy parameters:

UP=0;LOW=0;NUM=6;ALPHA=0;NALPHA=0;MUP=0;MLOW=0;MNUM=8;MALPHA=0;MNALPHA=0;MINLEN=6;MAXLEN=8

For further details, see:

ActivID AS Key Protection Policy Parameters

ActivID Appliance Key Protection Policy Parameters

HID Authentication Service Key Protection Policy Parameters

The SDK provides password caching support for the transaction signing operation (HIDTransaction.setStatus). When enabled, the signing password can be cached for the specified cache timeout period or until used.

To implement password caching in an integrating application when using a password policy:

  1. Retrieve the protection policy information HIDPasswordPolicy.isCacheEnabled.

If yes:

  1. Use the HIDPasswordPolicy.verifyPassword method to validate the password and store it for the HIDPasswordPolicy.getCacheTimeout period (by default, 30 seconds).

  2. To sign the transaction, use the HIDTransaction.setStatus method as usual but the signingPassword parameter can be omitted (it will retrieve the password value from cache).

BioPasswordPolicy – Authentication with Biometrics (TouchID or FaceID)

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 HIDBioPasswordPolicy, extending HIDPasswordPolicy.
Note: If the user’s device does not have a fingerprint sensor (or the manufacturer does not support Biometrics), then the policy is represented by HIDPasswordPolicy.

For further details, see:

ActivID AS Key Protection Policy Parameters

ActivID Appliance Key Protection Policy Parameters

HID Authentication Service Key Protection Policy Parameters

Enabling Authentication with Fingerprint or Face

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

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

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

Sample Enabling Biometric Authentication on iOS

Copy 
do{
        // 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.
        let containerPolicy = try myContainer?.getProtectionPolicy()
        
        // Identify the protection policy with the type BIOPASSWORD
        if(containerPolicy?.policyType()==HIDPolicyTypeBioPassword) {
            // 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.
            let bioPasswordPolicy = containerPolicy as? HIDBioPasswordPolicy
            if( bioPasswordPolicy?.getBioAuthenticationState()==HIDBioAuthenticationStateNotEnabled || bioPasswordPolicy?.getBioAuthenticationState()==HIDBioAuthenticationStateInvalidKey) {
                // You need to prompt the user for his/her password
                // Then enable authentication with biometrics TouchID/FaceID
                let userPassword = self.passwordPrompt()
                try bioPasswordPolicy?.enableBioAuthentication(userPassword)
                NSLog("TouchID/FaceID Enabled")
            }
        }
    }
    catch let error as NSError{
        NSLog("Failed to enable TouchID/FaceID: %@",error.localizedDescription);
    }
Copy 
NSError* error;
    // 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.
    id<HIDProtectionPolicy> containerPolicy = [myContainer getProtectionPolicy:&error];
    if (containerPolicy != nil) {
    
        // Identify the protection policy with the type BIOPASSWORD
        if ([containerPolicy policyType] == HIDPolicyTypeBioPassword) {
            
            // 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.
            id<HIDBioPasswordPolicy> bioPasswordPolicy = (id<HIDBioPasswordPolicy>)containerPolicy;
            if ([bioPasswordPolicy getBioAuthenticationState] == HIDBioAuthenticationStateNotEnabled || ([bioPasswordPolicy getBioAuthenticationState] == HIDBioAuthenticationStateInvalidKey) {
                // You need to prompt the user for his/her password
                // Then enable authentication with biometrics TouchID/FaceID
                NSString* userPassword = [self passwordPrompt];
                [bioPasswordPolicy enableBioAuthentication:userPassword error:&error];
                
                if (error != nil) {
                    NSLog(@"Failed to enable TouchID/FaceID: %@ (%ld)", [error userInfo], (long)[error code]);
                } else {
                    NSLog(@"TouchID/FaceID Enabled");
                }
            }
        }
    }

Authenticating with Fingerprint or Face

Regardless of the operation to perform (transaction signing, OTP generation…), if the key is protected by HIDBioPasswordPolicy (HIDKey.getProtectionPolicy) and fingerprint or facial authentication is enabled (HIDBioPasswordPolicy.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 HID Approve SDK leverages the iOS keychain capabilities to protect items with ACL.

When performing the requested operation, the SDK accesses an item protected with TouchID or FaceID – the operating system displays a modal dialog box on top of the app. The app does not have control over this dialog box.

The HID Approve SDK method is called with password argument set to null. The method is blocked until the user has provided their fingerprint or face.

  • If fingerprint/face is successfully matched, the method proceeds.
  • If fingerprint/face does not match, the method returns error HIDPasswordRequired.

For further details, see:

ActivID AS Key Protection Policy Parameters

ActivID Appliance Key Protection Policy Parameters

HID Authentication Service Key Protection Policy Parameters

Note: Fingerprint authentication becomes impossible when fingerprints are added or removed at the system level. The app must enable it again.

Sample Fingerprint Authentication on iOS (Objective-C)

Copy 
do{
        
        // Get HIDKey instance as demonstrated for OTP generation

        // 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 userPassword: String?
        let protectionPolicy = try otpKey.getProtectionPolicy()
        
        // Identify the protection policy with the type BIOPASSWORD
        if(protectionPolicy.policyType()==HIDPolicyTypeBioPassword) {
            let bioPasswordPolicy = protectionPolicy as? HIDBioPasswordPolicy
            if( bioPasswordPolicy?.getBioAuthenticationState() != HIDBioAuthenticationStateEnabled) {
                // Biometrics is not enabled
                // Prompt user for password
                userPassword = self.passwordPrompt()
            } else {
                // Biometrics is enabled
                // Password is not needed
                userPassword = nil
            }
        }
        
        // Get default OTP generator for this key
        let otpGenerator = try otpKey.getDefaultOTPGenerator()
        
        // Get the next OTP
        // We assume that the generator is Synchronous (HOTP or TOTP algorithms)
        let syncOtpGenerator = otpGenerator as! HIDSyncOTPGenerator
        let otp = try syncOtpGenerator.getOTP(userPassword)

    }
    catch let error as NSError{
        NSLog("Failed to enable TouchID/FaceID: %@",error.localizedDescription);
    }
Copy 
// Get HIDKey instance as demonstrated for OTP generation 
    
    // 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.
    NSString* userPassword = nil;
    id<HIDProtectionPolicy> protectionPolicy = [pOtpKey getProtectionPolicy:&error];
    if ([protectionPolicy policyType] == HIDPolicyTypeBioPassword) {
        id<HIDBioPasswordPolicy> bioPasswordPolicy = (id<HIDBioPasswordPolicy>)protectionPolicy;
        if ([bioPasswordPolicy getBioAuthenticationState] != HIDBioAuthenticationStateEnabled) {
            // Biometrics is not enabled
            // Prompt user for password
            userPassword = [self passwordPrompt];
        }
        else {
            // Biometrics is enabled
            // Password is not needed
            userPassword = nil;
        }
    }
     
    // Get default OTP generator for this key.
    id<HIDOTPGenerator> pOTPGenerator = [pOtpKey getDefaultOTPGenerator:&error];
     
    // Get the next OTP.
    // We assume the generator is Synchronous (HOTP or TOTP algorithms)
    NSString* otp = [((id<HIDSyncOTPGenerator>)pOTPGenerator) getOTP:userPassword error:&error];

Lock Policy

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

Type

  • HIDLockTypeNone – password never locks.
  • HIDLockTypeLock – password locks after maximum counter value is reached.
  • HIDLockTypeDelay – an exponential delay is inserted between each failed authentication attempt.

  • HIDLockTypeSilent – 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

For further details, see:

ActivID AS Key Protection Policy Parameters

ActivID Appliance Key Protection Policy Parameters

HID Authentication Service Key Protection Policy Parameters