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
- Allow/prohibit sequential 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.
-
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)
-
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.
Authenticating with Password
For further details about each specific API call, refer to the API references.
-
HIDAuthentication – raised when the provided password is incorrect
-
If a HIDLockTypeLock lock policy is used, HID_ERROR_AUTH_REMAINING_TRIES in the NSError userInfo dictionary will return the remaining tries
-
-
HIDPasswordRequired – raised when a password is required but was not provided
-
HIDPasswordExpired – raised when the provided password has expired (changePassword is required)
Using a PIN or Numeric 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
Enabling Password Caching
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:
-
Retrieve the protection policy information HIDPasswordPolicy.isCacheEnabled.
If yes:
-
Use the HIDPasswordPolicy.verifyPassword method to validate the password and store it for the HIDPasswordPolicy.getCacheTimeout period (by default, 30 seconds).
-
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.
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:
- HIDBioAuthenticationStateEnabled – biometric authentication is enabled, the SDK will accept password null in authentication methods
- HIDBioAuthenticationStateNotEnabled – biometric authentication is not enabled
To enable, a call to HIDBioPasswordPolicy.enableBioAuthentication is required
- HIDBioAuthenticationStateNotCapable – the device does not have a biometric sensor so biometric authentication is not possible
- HIDBioAuthenticationStateNotEnrolled – the user has not enrolled biometric features at the device level so biometric authentication cannot be enabled
-
HIDBioAuthenticationStateInvalidKey - biometric authentication has been invalidated by the platform following an update to system enrolled biometric data
To re-enable, a call to HIDBioPasswordPolicy.enableBioAuthentication is required
To enable biometric authentication, the app calls HIDBioPasswordPolicy.enableBioAuthentication as illustrated below.
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);
}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
The behavior depends on the platform.
The HID Approve SDK leverages the iOS/macOS 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 match fails, then the system will prompt the user to try again
-
Control is only returned to the integrating application if the user cancels or has reached the number of match attempts allowed
The authentication dialog has three possible outcomes:
- If fingerprint/face is successfully matched, the method proceeds
- If fingerprint/face match is locked by the system (for example, due to consecutive failures), the method returns error HIDPasswordRequired
-
If the user chooses to cancel the dialog, the method returns HIDUserCancelled
An integrating application can then choose to fallback to PIN/password mode upon failure.
It is also possible to disable biometric support by calling HIDBioPasswordPolicy.enableBioAuthentication with an empty or nil password value.
For further details, see:
ActivID AS Key Protection Policy Parameters
ActivID Appliance Key Protection Policy Parameters
HID Authentication Service Key Protection Policy Parameters
Sample Fingerprint Authentication on iOS/macOS
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);
}// 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
- initialDelay – initial delay value in seconds (in HIDLockTypeDelay type).
- maxCounterValue – maximum counter value after which exponential delay is fixed in HIDLockTypeDelay type, or maximum counter value after which no more authentication attempts are allowed in HIDLockTypeLock type.
For further details, see:
ActivID AS Key Protection Policy Parameters
