Authentication

The initiator is the first peer who requests a connection, usually the APP reacting to a login request made by the User. The APP needs to authenticate the account that the User wants to log in with. The User has just to provide a Hive account name. No password or private key is required.

1. The APP sends an auth_req command to the HAS.

2. The HAS provides the APP with a request identifier (uuid) and a request expiration time (auth_req_expire)

3. The APP builds an authentication payload (auth_payload) which contains the received uuid, the account name, a session encryption key (auth_key) and the URL of the HAS host it is connected to.

   The auth_payload will be shared with the PKSA offline using a QR code or deep linking. The APP asks the User to start its PKSA and scan the QR Code or it triggers the PKSA using deep linking when on mobile.

4. The User starts the PKSA.

   Note: the PKSA can be started before or after the user starts the authentication process. It doesn't matter.

5. The User scans the QR code using the PKSA.

   Note: This step is optional when the APP is a mobile application. The PKSA can retrieve the auth_payload from the deep link that triggered it.

6. The PKSA asks the HAS for its public encryption key to securely register the account (name) found in the auth_req_payload.

7. The HAS provides its public key to the PKSA (key_server)

8. The PKSA asks the HAS to register the account in order to receive account-related pending requests.

9. The HAS validates against the blockchain that the account exists and that the PKSA stores a valid private key from the account

   Note: The key ownership validation can be performed with any key. We recommend performing this process using the one that has the least permissions among those available.

10. Upon successful account validation, the HAS will forward the pending auth_req to the PKSA.

    Note: The PKSA must match the auth_payload.uuid with the auth_req.uuid it receives to ensure it is processing the correct request.

11. The PKSA asks the User to approve or reject the authentication request.

12. The User approves or rejects the authentication request.

13. Depending on the user reaction:

    1. if the User approves the authentication request, the PKSA:

       • creates an auth_expire and stores it

       • encrypts the uuid with the key (key_app) found in the auth_payload

       • creates an auth_ack_payload with the above data (auth_expire and encrypted uuid) and sends it with an authentication request approval message (auth_ack) to the HAS.

    2. If the user rejects the authentication request, the PKSA sends an authentication refusal (auth_nack) to the HAS.

       Note: This operation is not depicted in the above diagram for clarity.

14. The HAS forwards the authentication approval and its payload (auth_ack) or the authentication refusal (auth_nack) to the APP.

The encryption performed at step 13.1 ensures that a malicious actor operating a HAS cannot bypass the PKSA to approve an authentication request by itself.

Remember that the HAS doesn't have access to key_app. Therefore, by matching the decrypted auth_ack_payload.uuid using its encryption key (key_app) with the pending request uuid it received from the HAS with the sign_wait event, the APP has 100% certainty that the encryption process was made by the PKSA.

Note: The default maximum delay to approve an authentication request is 60 seconds. The HAS will discard any pending request with a longer timeout.