Hive Authentication Services - Protocol description

Yesterday, I introduced you to Hive Authentication Services. On purpose, I deliberately did not tackle the technical details of the project so as not to drown the less tech-savvy reader in too much information.



If you haven't already done so, support the project and vote for its proposal on Peakd, Ecency, hive.blog or using HiveSigner

I also invite you to read:


Today we're going to dive a little deeper into how HAS provides its services and interconnect third-party applications and your favourite wallet app which stores your precious private keys.

What are Hive Authentication Services (a quick reminder)?

The Hive Authentication Services (HAS) provide user authentication for any applications, either web, desktop, or mobile. It also allows applications to sign and broadcast transactions to the Hive blockchain without asking their users to provide them with any private key.

How does it work?

Hive Authentication Services (HAS) architecture consists of a WebSocket server acting as a middleware between any Application (App) supporting the HAS protocol and any Private Key Storage Application (PKSA) supporting the HAS protocol.

Beware, the content of the post will now become far more technical. Fasten your seatbelts!

1. Authentication

The initiator is the first peer who requests a connection, usually the App reacting to a login request made by the User.

The application login form will only require the account name (@username). No password will be required.

When the User hit the sign-in button, the App will then try to authenticate them with their Hive account. Here is the diagram describing the HAS authentication process.

  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 (key_app) and the URL of the HAS host it is connected to. The auth_payload will be shared with the PKSA off-band using a QR code or deep linking.The App asks the User to start its PKSA and scan the auth_payload QR Code or trigger the PKSA using a deep link when on mobile.
  4. the User starts the PKSA.
  5. the user reads the QR code using the PKSA. This step is optional when on mobile because the PKSA can retrieve the auth_req_payload from the deep link that triggered it.
  6. to securely register the account (name) found in the auth_req_payload, the PKSA asks the HAS for a public encryption key.
  7. the HAS provides its public key key_server
  8. the PKSA can ask the HAS to register the account in order to receive subsequent transactions requests
  9. the HAS validate that the account exists and that the PKSA store valid private keys from the account against the blockchain.
  10. Upon successful validation, the HAS will forward the auth_req to the PKSA. The PKSA should wait for it and match both uuid to ensure the User has scanned the right QR code.
  11. the PKSA asks the User to approve or reject the authentication request.
  12. the User approves or rejects the authentication request.
  13. when the User approves the authentication request, the PKSA:
    • creates an auth_token and anauth_token_expire
    • stores them locally
    • encrypt the uuid with the key (key_app) found in the auth_payload and add it to the auth_ack_payload
    • create an auth_ack_payload with the above data and send it with an authentication request approval to the HAS.
  14. the HAS forward the authentication approval and its payload to the App.

The encryption performed at step 13 is to ensure that a malicious actor operating a HAS cannot bypass the PKSA to approve an authentication request. 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, the App has 100% certainty that the encryption process was made by the PKSA.

Once the account is authenticated against the App, the application login process can go on et the App will be allowed to sign or broadcast transactions (with the user's consent, of course).

2. Broadcasting Transactions

This part only concerns applications that interact with the Hive blockchain. Following an action by the User within the App, the last one now wants to record a transaction in the blockchain.

Here is the diagram describing the process:

  1. the App sends a sign_req command to the HAS with a valid auth_token.
  2. the HAS check the auth_token and provides the App with a request identifier (uuid) and its expiration time (sign_req_expire) in a sign_wait message.
  3. [Optional] the App shows information about the pending request to the user. It may also ask them to (re)start their PKSA to approve the transaction within the allowed delay.
    Note: the PKSA can be started before or after the transaction request is issued. It doesn't matter.
  4. the HAS then forwards the sign_req command to the PKSA
  5. the PKSA prompts the user to approve or reject the transaction
  6. If the user approves the transaction. (For clarity, transaction refusal is not depicted in the above diagram. See below.)
  7. the PKSA signs the transaction and broadcasts it to the blockchain.
  8. If the transaction broadcast is successful, the PKSA sends a sign_ack to the HAS with the blockchain transaction ID (txID)
  9. the HAS forward the sign_ack message with the blockchain transaction ID (txID) to the App.

3. Signing Transactions

The application may wish to manage the sending of the transaction to the blockchain itself. In this case, it will ask PKSA to only sign the transaction.

Here is the diagram describing the process:

  1. the App sends a sign_req command to the HAS with a valid auth_token.
  2. the HAS check the auth_token and provides the App with a request identifier (uuid) and its expiration time (sign_req_expire) in a sign_wait message.
  3. [Optional] the App shows information about the pending request to the user. It may also ask them to (re)start their PKSA to approve the transaction within the allowed delay.
    Note: the PKSA can be started before or after the transaction request is issued. It doesn't matter.
  4. the HAS then forwards the sign_req command to the PKSA
  5. the PKSA prompts the User to approve or reject the transaction
  6. the User approves the transaction.
  7. the PKSA signs the transaction the PKSA sends a sign_ack to the HAS with the signed_transaction
  8. the HAS sends a sign_ack command to the App with the signed_transaction.
  9. It's now up to the App to broadcast the signed transaction to the blockchain.

About request timeout or refusal

Timeout
The maximum delay to approve an authentication or transaction request is 2 minutes.

This should give the user enough time to grab their mobile and launch their Wallet App (PKSA), if they have not already done so, and approve or reject the incoming request.

Note: the PKSA can be started before or after an App sends a request to process. It doesn't matter.

Request refusal
For clarity, the transaction refusal step was not included in the above diagrams, but the process is fairly simple:

When the user rejects a request:

  • the PKSA sends an auth_nack or sign_nack message to the HAS with the uuid of the request.
  • the HAS forwards the above message to the App

Wrap up

Hope you now have a better view and understanding of what has been put in place with Hive Authentication Services.

The HAS protocol may look complex for the authentication phase, but that's what enables its transactions counterpart to be way more simple but still secure.

In the next article, we'll dive even deeper into the mechanics of the HAS protocol. You will discover how HAS relies heavily on encryption to protect the use of your private keys, to identify various parties involved and to secure the data they exchange.

UPDATE: The HAS Developer Guide - Part 1 is now available for reading.

Thanks for reading.


Do not forget to support the HAS project:


Check out my apps and services


Vote for me as a witness

H2
H3
H4
3 columns
2 columns
1 column
31 Comments