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.

	HID_KEY_PROPERTY_LABEL
	KEY_PROPERTY_LABEL
	KEY_PROPERTY_LABEL

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:

	HID_KEY_PROPERTY_USAGE
	KEY_PROPERTY_USAGE
	KEY_PROPERTY_USAGE

Signing authentication requests (the transaction is an authentication).

	HID_KEY_PROPERTY_USAGE_AUTH
	KEY_PROPERTY_USAGE_AUTH
	KEY_PROPERTY_USAGE_AUTH

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

	HID_KEY_PROPERTY_USAGE_TXPROTECT
	KEY_PROPERTY_USAGE_TXPROTECT
	KEY_PROPERTY_USAGE_TXPROTECT

Signing transaction data

	HID_KEY_PROPERTY_USAGE_SIGN
	KEY_PROPERTY_USAGE_SIGN
	KEY_PROPERTY_USAGE_SIGN

Generating OTPs

	HID_KEY_PROPERTY_USAGE_OTP
	KEY_PROPERTY_USAGE_OTP
	KEY_PROPERTY_USAGE_OTP

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:

Set transaction action status

	HIDTransaction.setStatus
	Transaction.setStatus
	ITransaction.SetStatus

Get server action for transaction

	HIDServerAction.getAction
	ServerActionInfo.getAction
	IServerActionInfo.GetServerAction

Update device information

	HIDContainer.updateDeviceInfo
	Container.updateDeviceInfo
	IContainer.UpdateDeviceInfo

Renew container

	HIDContainer.isRenewable HIDContainer.renew
	Container.isRenewable Container.renew
	IContainer.isRenewable IContainer.Renew

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.

	getSigningKey
	Transaction.getSigningKey
	ITransaction.GetSigningKey

Protection Policies

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

	HIDProtectionPolicy
	ProtectionPolicy
	IProtectionPolicy

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.
• 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/macOS

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 Password Policy, then those keys are protected by the same password.

	HIDPasswordPolicy
	PasswordPolicy
	IPasswordPolicy

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

	HIDContainer.retrieveTransactionIds
	Container.retrieveTransactionIds
	IContainer.RetrieveTransactionsIds

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

	HIDDevice.retrieveActionInfo
	Device.retrieveActionInfo
	IDevice.RetrieveActionInfo

Followed by a call to get the transaction itself.

	(id<HIDTransaction>) HIDServerAction.getAction
	(Transaction) ServerActionInfo.getAction
	IServerActionInfo.GetServerAction

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