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.
Note: In the rest of this documentation, it is assumed that there is only one container.

Keys

Cryptographic keys are the root of the security features provided by the HID Approve SDK.

These keys have a Closedlabel, 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 Closedusages:

ClosedSigning authentication requests (the transaction is an authentication).

ClosedEncrypting exchanges with the server
Although this key is intended for internal usage, it can be protected by an end-user password.

ClosedSigning transaction data

ClosedGenerating OTPs

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:

ClosedSet transaction action status

ClosedGet server action for transaction

ClosedUpdate device information

ClosedRenew container

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, Closedget the key from the transaction.

Protection Policies

Protection policies are represented by the ClosedProtection Policy class and derived classes.

ProtectionPolicy Class

Note: Keys can be protected by either the container policy or a specific policy.

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.
  • SilentLockPolicy – access is limited by delegating validation and blocking to server-side controls (such as exhausting the failed authentication counter)

See:

Protection policy for iOS

Protection policy for Android

Protection policy for Windows

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 ClosedPassword 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
  • Define the container policy as ‘device’
  • Specify policy ‘container’ for all keys
  • Define the container policy as ‘password’
  • Specify policy ‘container’ for all keys
  • Specify policy 'device' for Session Transport Key
  • Define the container policy as ‘password’
  • Specify policy ‘container’ for keys that you want to protect with a password
  • Specify policy ‘device’ for other keys
  • Specify policy 'device' for Session Transport Key

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 Closedretrieve transaction ID method.

Once the transaction identifier is retrieved, the application then calls to Closedretrieve the transaction information.

Followed by a call to Closedget 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:

Configuring ActivID AS

Configuring the ActivID Appliance

Configuring the HID Authentication Service