# Device binding

## Introduction

This guide contains all the relevant information about the device binding
feature, including the key concepts and necessary endpoints to implement the
feature in your banking solution.

### What is device binding?

The device binding API provides endpoints for customers to register their
devices for use with your solution and create public/private key pairs for
authenticating multi-factor authentication (MFA) challenges.

Device binding is a required component of [Strong Customer Authentication (SCA)](/guides/authentication/strong-customer-authentication/) and the
[device signing](/guides/authentication/strong-customer-authentication/#implement-device-signing)
authentication method, in which the customer verifies that their request
originates from their registered device.

Once a customer binds their device, they will receive authentication challenges
that they must confirm using the device (e.g., logging in, changing their data,
authorizing transactions). Customers can create multiple **restricted** or
**unrestricted** key pairs.

### Restricted and unrestricted key pairs

Your customers can authorize actions using either a restricted or an unrestricted key pair depending on the type of action:

- **Unrestricted key** pair does not require user authentication.
- **Restricted key** pair requires user authentication via biometrics (e.g., Touch ID or Face ID). For example, you need to combine the `privateKeyUsageflag` with the `userPresence` or `touchIDAny` in `iOS` or `setUserAuthenticationParameters()` in `Android`.


See the [Strong customer authentication guide](/guides/authentication/strong-customer-authentication/) for more
information about device signing and the full list of use cases requiring
restricted and unrestricted keys.

### Security requirements

You must ensure that your device binding implementation meets the following
security requirements:

- A customer may only have a maximum of **five** registered devices.
- Each device must meet the minimum operating system requirements: **Android
8.0** or above, or **iOS 12** or above.
- Each device must support hardware-backed and strong security services via
separate secure execution environments, e.g., Secure Enclave in iOS or TEE in
Android OS.
- Your frontend must enforce a minimum device access security policy, such as
requiring the user to set a device passcode.
- You must store personalized security credentials and cryptographic keys in a
separate secure environment.


## Integration flow

The following diagram gives an overview of the integration flow for device binding:

![Diagram: Device binding implementation flow](/assets/device-binding-flow.6c3b22bf45778a838886f9ef82c55b87d5e1c92093a85d8ff61829afec33b046.21ca1051.svg)

### Integration steps

1. The customer initiates the device binding process and enters the device's
information through your application.
2. Your application generates a private/public key pair in `ecdsa-p256` format.
3. Send the public key (in raw hex-encoded format) and the customer's information
to Solaris using [POST Create device](#post-create-device).
4. The Solaris API verifies the customer's information, stores the public
key in the database, and then returns a [change request](/guides/authentication/strong-customer-authentication#change-request)
object that your customer must confirm.
5. Solaris sends a six-digit one-time password (OTP) via SMS to the customer's registered mobile number.
6. The customer receives the OTP via SMS and enters it through your app.
7. The customer signs the OTP with the private key and creates a signature on your application.
8. Send the customer's signature to Solaris for verification by calling [PUT
Verify the signature](#put-verify-the-signature).
9. Solaris verifies the signature challenge and, if valid, registers the
device and binds it to the customer.
10. Create additional keys if required.


## Step 1: Create a device

In this step, your customer must enter the required information about their
device on your frontend. The device must meet the [minimum security
requirements](#security-requirements). Afterward, your application must create a
private/public key pair in `ecdsa-p256` format for the customer.

### POST Create device

This endpoint creates a device and attaches it to a specific customer. You must
include the following attributes in the request body:

- `person_id`: The unique `person_id` for the customer on Solaris' system.
- `key_type`: The supported format of the key type. Currently, only `ecdsa-p256`
is supported, and you must send it to Solaris in raw hex-encoded format.
- `challenge_type`: The type of challenge to be used to verify the device. The
default value is `sms`.
- `name`: The customer's device name. It must be the device's actual model—for
example, Samsung Galaxy S10, Samsung Galaxy Note, etc.
- `key_purpose`: Possible values are `restricted` or `unrestricted`.
- `key`: The hex-encoded public key generated for the device to be registered.


**Request URL:**


```shell
POST /v1/mfa/devices
```

**Response example:**

After receiving this request, Solaris verifies the customer's information
and creates a temporary, unverified device with a unique `id`. Afterward,
Solaris sends the following to verify the device:

- A six-digit one-time password (OTP) sent via SMS to the customer's registered
mobile number.
- A signature challenge on the SMS code that is valid for five minutes with a
unique `id`.



```json
{
    "id": "string",
    "key_id": "string",
    "challenge":
    {
        "id": "string",
        "type": "signature",
        "created_at": "2019-08-21T12:16:17Z",
        "expires_at": "2019-08-21T12:21:17Z"
    }
}
```

[Click here to view the full API reference.](/api-reference/onboarding/device-management/#tag/Device-binding/paths/~1v1~1mfa~1devices/post)

### GET Retrieve device

This method retrieves information about an existing bound device.

**Request URL:**


```shell
GET /v1/mfa/devices/{id}
```

**Response example:**


```json
{
    "id": "string",
    "name": "Samsung Galaxy S10",
    "person_id": "dc1a6812a14f6cc338cd084208535bcdcper",
    "created_at": "string",
    "deleted_at": null
}
```

[Click here to view the full API reference.](/api-reference/onboarding/device-management/#tag/Device-binding/paths/~1v1~1mfa~1devices~1%7Bid%7D/get)

### DEL Delete device

This endpoint deletes an existing bound device associated with a specific customer.

**Request URL:**


```shell
DELETE /v1/mfa/devices/{id}
```

[Click here to view the full API reference.](/api-reference/onboarding/device-management/#tag/Device-binding/paths/~1v1~1mfa~1devices~1%7Bid%7D/delete)

### GET Retrieve signature challenge

This endpoint retrieves the details of the signature challenge generated after creating a device. The challenge is valid for 5 minutes.

**Request URL:**


```shell
GET /v1/mfa/challenges/signatures/{signature_id}
```

**Response example:**


```json
{
  "created_at": "2019-08-21T12:16:17Z",
  "type": "sms",
  "id": "string",
  "expires_at": "2019-08-21T12:21:17Z"
}
```

[Click here to view the full API reference.](/api-reference/onboarding/device-management/#tag/Device-binding/paths/~1v1~1mfa~1challenges~1signatures~1%7Bid%7D/get)

## Step 2: Verify the signature with the SMS challenge

Once they receive the six-digit OTP, the customer must enter it in your app
along with the private key to create a `signature`. Then, you must call the
following endpoint to verify the `signature`. The `signature` is the input code
delivered with the SMS and provided by the customer.

**How to create the signature:**

1. Create a hash (SHA256) with the OTP.
2. Sign the hash with the private key.
3. Encode the signature in `ASN.1` format.
4. Hex encode the `ASN.1` format signature.
5. Send the hex-encoded signature in the request payload.


### PUT Verify the signature

This method verifies the signature created by the customer.

**Request URL:**


```shell
PUT /v1/mfa/challenges/signatures/{id}
```

**Response example:**


```shell
HTTP/1.1 204 Challenge successful
```

[Click here to view the full API reference.](/api-reference/onboarding/device-management/#tag/Device-binding/paths/~1v1~1mfa~1challenges~1signatures~1%7Bid%7D/put)

## Step 3: Create additional keys

After a successful device binding, the customer can create additional keys
(either restricted or unrestricted) and add them to the device.

### POST Add new key to device

This endpoint adds a new `restricted` or `unrestricted` key to an existing device.

**How to encode the public key:**

1. Generate a public/private key pair (ECC curve name: ECDSA-P256).
2. Hex encode the raw public key.


**Request attributes**

| Attribute | Type | Description |
|  --- | --- | --- |
| `key` | `string` | The new hex-encoded public key created on the customer's bound device. |
| `key_type` | `string` | Type of key pair. Possible values are `ecdsa-p256`. |
| `key_purpose` | `string` | Purpose of the key. Possible values are `restricted` or `unrestricted`. |
| `device_signature` | `object` | Object containing the information about the previously registered key and the signature of the new key. |
| `signature_key_purpose` | `string` | Purpose of the previously registered key used to sign the new key. Possible values are `restricted` or `unrestricted`. |
| `signature` | `string` | Signature of the new key to be added signed with the previously registered private key on the same device. signature_new_key = registered_private_key.sign(hashSHA256(new_public_key) |


**Request URL**


```shell
POST /mfa/devices/{id}/keys
```

**Example response**


```shell
HTTP/1.1 201 Created
{
  "id": "20f892fdc6414320b5b1df612f833edb"
}
```

[Click here to view the full API reference.](/api-reference/onboarding/device-management/#tag/Device-binding/paths/~1v1~1mfa~1devices~1%7Bid%7D~1keys/post)

### GET Retrieve a device key

This endpoint retrieves a specific key linked to a device.

**Request URL**


```shell
GET /mfa/devices/{id}/keys/{key_id}
```

**Example response**


```json
{
  "key_id": "3e1415b8-901d-4c1a-8950-f3a1083c6c3b",
  "key_purpose": "unrestricted",
  "key_type": "ecdsa-p256",
  "used_at": "2022-03-18T14:55:04Z"
}
```

[Click here to view the full API reference.](/api-reference/onboarding/device-management/#tag/Device-binding/paths/~1v1~1mfa~1devices~1%7Bid%7D~1keys~1%7Bkey_id%7D/get)

### GET Retrieve all device keys

This endpoint retrieves all keys linked to a device.

**Request URL**


```shell
GET /mfa/devices/:{id}/keys
```

**Example response**


```json
[
  {
    "device_id": "6642d15e-8f6b-4d28-9186-cdd61d80032a",
    "person_id": "ec3d16cbc106f481b72d881d90c89cc5cper",
    "name": "Test device",
    "created_at": "2022-03-18T14:50:04Z",
    "deleted_at": "2022-04-18T14:55:04Z",
    "keys": [
      {
        "key_id": "3e1415b8-901d-4c1a-8950-f3a1083c6c3b",
        "key_purpose": "unrestricted",
        "used_at": "2022-03-18T14:55:04Z"
      }
    ]
  }
]
```

[Click here to view the full API reference.](/api-reference/onboarding/device-management/#tag/Device-binding/paths/~1v1~1mfa~1devices~1%7Bid%7D~1keys/get)