HID Approve SDK Object Model
The following sections describe the object model of the HID Approve SDK.
Entry Point
The mobile device is represented in the HID Approve SDK by the Device interface*.
A Device generally has 1 key container, represented by the Container interface. A Container has one or more keys, represented by the Key interface.
Device Interface
* Here, ‘interface’ means an abstract type that defines behaviors as method signatures. It corresponds to the ‘interface’ statements in Java and C#, and ‘protocol’ statements in Swift and Objective-C.
Device
The single Device instance is responsible for:
- Managing containers (create, delete, find).
- Retrieving transactions.
- Notifying the HID authentication platform of mobile device-level changes.
Container
When registering the mobile device for a service, a container is created. A Container is responsible for:
- Managing keys (find, add, delete, renew).
- Retrieving pending transaction identifiers for the corresponding service.
Keys
Cryptographic keys are the root of the security features provided by the HID Approve SDK.
These keys have a 
label, configured in the HID authentication platform, that can help identify them.
This label must be unique per container. How it is used is determined by the integrator.
A key can have one of the following usages:
Signing authentication requests (the transaction is an authentication).
Encrypting exchanges with the server
Although this key is intended for internal usage, it can be protected by an end-user password.
A key is protected as specified by its associated policy (configured in the HID authentication platform).
Session Transport Key
The Session Transport Key (usage: encrypting exchanges) encrypts and decrypts messages coming from, and sent to, the HID authentication platform. Like other keys, its usage can be protected by a password.
The calling application checks the protection policy of the key and, if needed, prompts the user for the password, then passes it as an argument of the methods where it is expected:
Get server action for transaction
OTP Key
One-Time Passwords are computed based on an OTP Key (usage: generating OTPs).
To generate an OTP, the calling application has to search for the OTP key (by usage and/or label, depending on the integrator’s choice) and retrieve an OTP generator using the Key interface.
Signature Key
A signature key is the private key of a key pair (usage: signing transaction data).
To sign a transaction, get the key from the transaction.
Protection Policies
Protection policies are represented by the Protection Policy class and derived classes.
ProtectionPolicy Class
Protection policies are used to define both a condition of access and to secure cryptographic keys on the mobile device.
The HID Approve SDK supports three policy types:
- DevicePolicy – the credential is protected using a device derived key
- PasswordPolicy – the credential is protected using an end-user password derived key
- BioPasswordPolicy – the credential is protected using an end-user biometrics or password derived key
In conjunction with this policy, a lock type can be used to further limit attempts to gain access via password brute-force attacks:
- NoLockPolicy - access is never locked after failed attempts (not recommended)
- CounterLockPolicy – access will be locked after a configurable number of consecutive failed attempts.
- DelayLockPolicy – access is limited by applying an exponential delay for each consecutive failed attempt.
See:
For further details, see:
ActivID AS Key Protection Policy Parameters
ActivID Appliance Key Protection Policy Parameters
HID Authentication Service Key Protection Policy Parameters
If multiple keys are protected by the container policy, and the container policy type is Password Policy, then those keys are protected by the same password.
The recommended configurations are:
| No password protection at all | Password protection for all keys | Password protection for some of the keys |
|---|---|---|
|
|
|
Transactions
To perform the transaction-signing use case, the mobile application retrieves an instance of the Transaction from a transaction ID sent by the HID authentication platform (for instance, through push notification) or by calling the retrieve transaction ID method.
Once the transaction identifier is retrieved, the application then calls to retrieve the transaction information.
Followed by a call to get the transaction itself.
The application prompts the user to select a status for the Transaction (for example, approve or decline).
The application then calls to set the transaction status with the selected status, signs the transaction, and sends the result to the HID authentication platform for verification.
Transaction Interface
OTP Generator
To perform authentication with an OTP use case, the mobile application retrieves an OTP generator from a key with OTP usage.
OTP Generator Interface
Mapping with the HID Authentication Platform
The Container contents (also known as ‘profile’) are specified by configuring a device type in the HID authentication platform (by default, DT_TDSV4). Upon successful provisioning, a user is created in the HID authentication platform and assigned a device of this type. The Container serial number corresponds to the device serial number in the HID authentication platform.
The container protection policy is the default protection policy for keys. It is also a configuration of the device type in the HID authentication platform.
The Key type and protection policy are specified by configuring a credential type in the HID authentication platform.
For further details, see:
