Authentication

This authentication method uses server-side session generation, which is available in Protege WX firmware version 4.00.1676 and higher. For older controller versions, see Authentication (Client-Side).

To authenticate API requests as an operator on the controller, clients must log in using the following process:

1. User enters username and password.

2. Client creates SHA hash of password - we'll call this pswdhash.

3. Client requests random number from DLL:

   Copy

   http://192.168.1.2/PRT_CTRL_DIN_ISAPI.dll?Command&Type=Session&SubType=InitSession

4. DLL returns either a success response or an error (detailed below). If successful, DLL returns a Set-Cookie header.

5. Client creates XOR of username and (random number+1).

6. Client generates SHA hash of XOR - we'll call this hashxorusername.

7. Client creates XOR of pswdhash and random number.

8. Client generates SHA hash of XOR - we'll call this hashxorpswdhash.

9. Operating over HTTP:

   • Client sends hashxorusername and hashxorpswdhash to DLL:

     Copy

     http://192.168.1.2/PRT_CTRL_DIN_ISAPI.dll?Command&Type=Session&SubType=CheckPassword&Name=<hashxorusername>&Password=<hashxorpswdhash>

   • DLL returns FAIL if the username or password don't match, or a second random number if successful.

   • Client creates XOR of pswdhash and the second random number.

   • Client generates SHA hash of XOR, and uses first 16 characters as AES key.

   • Client stores the AES Key. All request parameters should be encrypted using this AES key.

10. Operating over HTTPS:

    • Client sends hashxorusername and hashxorpswdhash to DLL:

      Copy

      https://192.168.1.2/PRT_CTRL_DIN_ISAPI.dll?Command&Type=Session&SubType=CheckPasswordServer&Name=<hashxorusername>&Password=<hashxorpswdhash>

      This will initiate a session with encryption disabled and eliminate the need to apply AES encryption to the payload data. Subsequent requests can be sent in plain text.

    • DLL returns FAIL if username or password don't match, or a random number if successful. The random number is not used.

Login Errors

If the username or password are incorrect the following error will be returned.

FAIL
Corrective action: Retry using the correct user name and password.

If the username or password are incorrect and there have been more than three recent incorrect login attempts the following error will be returned.

FAIL 5
Corrective action: Wait 5 seconds then retry using the correct user name and password.

If the username or password are incorrect and there have been more than six recent incorrect log in attempts the following error will be returned.

FAIL 60
Corrective action: Wait 60 seconds then retry using the correct user name and password.

If the controller has been defaulted and the admin:admin credentials are used to log in the following error will be returned.

FAIL. No valid operator login found.
Corrective action: You must update the admin operators user name and password to unique credentials by following the details described in the Operators / Reset admin section.