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 receiveduuid
, the accountname
, a session encryption key (auth_key
) and the URL of the HAShost
it is connected to.Theauth_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 theauth_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 accountNote: 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 theauth_payload.uuid
with theauth_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 theauth_payload
- creates an
auth_ack_payload
with the above data (auth_expire
and encrypteduuid
) 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.
Last modified 27d ago