Device Verification

In this page you will get to know how the middleware securely handles the request coming from the user's actual device and how you can make the request for it to successfully work.

Summary

When making an important request, for example: approving a transfer or maybe cancelling a transfer. These operations are sensitive and if not careful they can be a major problem for the user. That's why the API endpoint requires the user to solve a 'Challenge' and here this can be a situation where the user has to enter the account PIN.

Steps to Generate a Signature

1. Get Challenge Response

The public key is required for this step. Below is a sample dart code that is generating the body for the load challenge POST request:

    var publicKey = await AppStorage.read(ConstantText.securityKey);

    var hash = await AppSignature.getHash(publicKey);
    var body = jsonEncode(
      {
        "deviceId": hash,
        "username": await AppStorage.read(ConstantText.username),
      },
    );
    
    final Response response = await post(
      Uri.parse(AppConfig.mwURL + "sessions/challenges"),
      headers: await Utils.getHeader(),
      body: body,
    );

On line 1, the public key is retrieved from the device storage and on the 2nd line, the hash is generated by a package that uses RSA encryption. On the 4th line, the body of the request is json encoded. Finally, the POST request is being made on the 11th line with the body and the headers on /sessions/challenges.

Our goal in this step is to get the challenge id that will be sent from the server for the above request.

2. Preparing the data for making the signature

Now, we have the challenge id from the previous step, we need the username of the account as well. We have to add the following information in the header:

"X-AAZZUR-DEVICE-CHALLENGE": challenges.challengeID,
"X-AAZZUR-SIGNATURE": signature.toString(),
"X-AAZZUR-PIN": data.pin

As you can see that the pin is required for this and there is a signature field as well. The signature field contains the following information:

{
    "username": "john-doe",
    "challenge": 12345,
    "httpMethod": "POST",
    "requestUri": "URL",
    "queryParams": "",
    "body": ""
}

Now, the header is ready and we can make the request to see if everything is working properly or not.

For example: when approving a transfer request, the request should be like the following:

      final Response response = await post(
        Uri.parse(AppConfig.mwAuthURL + data.requestURI),
        headers: {
          ...await Utils.getHeader(),
          ...{
            "X-AAZZUR-DEVICE-CHALLENGE": challenges.challengeID,
            "X-AAZZUR-SIGNATURE": signature.toString(),
            "X-AAZZUR-PIN": data.pin
          },
        },
      );

Here the signature and the pin number is added in the header as the signature is required to approve the transfer.