For the complete documentation index, see llms.txt

Hardware-protected keys

In addition to dynamically generated software keys, we use hardware-protected keys to strengthen proof-of-possession and maximise device security.

The probability that an attacker is able to obtain the private keys that are stored in the secure hardware on a device and then use them outside the device without breaking it on a hardware level is very low.

How do hardware-protected keys work?

A hardware-protected key pair is generated in hardware, typically on a trusted execution environment (TEE) or trusted platform module (TPM). The private key will never leave the hardware.

As a result, all operations that require the private key are performed in the secure hardware on the device. For example, operations like encrypt, decrypt, sign and verify that use the private key are performed in the secure hardware.

Even a rooted device still protects the hardware keys from extraction, and cloning of a key can not be performed on a rooted device. It is therefore very unlikely that an attacker is able to steal a key stored in the secure hardware and use it outside of the device.

Activation

Sequence diagram showing hardware-protected keys activation

A typical flow for activation of a hardware-protected key is as follows:

1. The Encap SDK generates a key pair in the secure hardware.
2. The secure hardware returns the public hardware (HW) key to the Encap SDK.
3. The Encap SDK returns this key to the Encap server over the secure channel in the finish activation request.
4. The Encap server stores the public HW key on the registration, and this key will be used to verify all future authentications.

Authentication

Sequence diagram showing hardware-protected keys authentication

For a device that is activated with HW keys, an additional security check will be executed for each authentication. The flow is as follows:

1. The Encap SDK signs the authentication challenge received from the Encap server in the start authentication request, with the hardware-protected private key.
2. The signed challenge is passed back to the Encap server in the finish authentication request over the secure channel.
3. The signed challenge is verified on the server side with the HW public key.

How to implement hardware-protected keys

Note

This feature does not require any client configuration to enable it.

Prerequisites

All devices that have support for hardware keys use this security feature by default. These are:

• Most devices using Android 6 devices.
• All devices using Android 7 or later.
• All devices using iOS 10 or later / devices with Secure Enclave.

Important

Devices that do not support hardware-protected keys will only use software keys.

1. Choose a validation strategy

We offer three validation strategies, each of which involves validating the hardware signature on the Encap server. You need to choose which validation strategy you want to set.

Note

Only Encap server versions 3.22 and above support the REQUIRED strategy.

2. Configure the application configuration

To set your chosen validation strategy, you need to configure the application configuration on the Encap server using the following parameter:

3. Enable risk data

When risk data is enabled, the result of the hardware signature validation is returned as part of the risk data set. To enable this, you need to configure the application on the Encap server using the following parameter:

4. Validation result

When the risk attributes are enabled, the result of the hardware-protected key validation is returned to you in the following risk attributes:

Note

For possible values, see the tables under Hardware protected key client statuses and Hardware protected key server result in our API reference documentation.