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.

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.

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:

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:

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.

{
    "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:

GET /v1/mfa/devices/{id}

Response example:

{
    "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:

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:

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

Response example:

{
  "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:

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

Response example:

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

Request URL

POST /mfa/devices/{id}/keys

Example response

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

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

Example response

{
  "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

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

Example response

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