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) and the 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.

info

See the Strong customer authentication guide 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

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.
  4. The Solaris API verifies the customer's information, stores the public key in the database, and then returns a 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.
  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. 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:

Copy
Copied
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.
Copy
Copied
{
    "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.

GET Retrieve device

This method retrieves information about an existing bound device.

Request URL:

Copy
Copied
GET /v1/mfa/devices/{id}

Response example:

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

Click here to view the full API reference.

DEL Delete device

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

Request URL:

Copy
Copied
DELETE /v1/mfa/devices/{id}

Click here to view the full API reference.

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:

Copy
Copied
GET /v1//mfa/challenges/signatures/{signature_id}

Response example:

Copy
Copied
{
  "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.


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:

Copy
Copied
PUT /v1/mfa/challenges/signatures/{id}

Response example:

Copy
Copied
HTTP/1.1 204 Challenge successful

Click here to view the full API reference.


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. signaturenewkey = registeredprivatekey.sign(hashSHA256(newpublickey)

Request URL

Copy
Copied
POST /mfa/devices/{id}/keys

Example response

Copy
Copied
HTTP/1.1 201 Created
{
  "id": "20f892fdc6414320b5b1df612f833edb"
}

Click here to view the full API reference.

GET Retrieve a device key

This endpoint retrieves a specific key linked to a device.

Request URL

Copy
Copied
GET /mfa/devices/{id}/keys/{key_id}

Example response

Copy
Copied
{
  "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.

GET Retrieve all device keys

This endpoint retrieves all keys linked to a device.

Request URL

Copy
Copied
GET /mfa/devices/:{id}/keys

Example response

Copy
Copied
[
  {
    "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.