![](https://i.imgur.com/ePqTuLS.png) A few days ago, I introduced the [Hive Authentication Services](/@arcange/hive-authentication-services-proposal) and its [protocol description](/@arcange/hive-authentication-services-protocol-description). So far, I have approached the details of these new services in a fairly comprehensive manner in order to give you an overview of the possibilities that will be offered to you. I now suggest you dive deeper with a more technical description aimed at developers who would like to integrate the HAS protocol into their applications. As usual, I will also try to be as educational as possible so that the layman can also find information that may be of interest to him. --- ###### If you haven't already done so, **support the project and vote for its proposal** on [Peakd](https://peakd.com/me/proposals/194), [Ecency](https://ecency.com/proposals/194), [hive.blog](https://wallet.hive.blog/proposals) or using [HiveSigner](https://hivesigner.com/sign/update_proposal_votes?proposal_ids=%5B%22194%22%5D&approve=true) I also invite you to read: - [the HAS introductory post](https://peakd.com/hive-139531/@arcange/hive-authentication-services-proposal) to discover the project and its related proposal. - [the HAS protocol description](/@arcange/hive-authentication-services-protocol-description) to get a better understanding on how HAS parties interact together. - [the HAS Developer Guide - PKSA Integration](/@arcange/hive-authentication-services-developer-guide-part-2) --- ## HAS Integration The Hive Authentication Services (**HAS**) rely on the WebSocket protocol to exchange data between Applications (**APP**) and the Private Keys Storage Application (**PKSA**) via persistent connections. The data can be passed in both directions as “payloads”, without breaking the connection and additional HTTP requests. The **APP** opens a WebSocket connection to the **HAS** endpoint and sends authentication and transactions requests to it. The **PKSA** opens a WebSocket connection to the **HAS** endpoint, requests an encryption key from the server, registers the account(s) for which he will process requests, and wait for incoming authentication and transactions requests. The **HAS** will queue requests from the **APP** and forward them to any newly or already connected **PKSA**. it will also relay back approval or refusal of the requests. The dialogue between the different parties is done by means of JSON structured messages, each containing a `cmd` field that defines the nature of the message. ### 1. Connection The first thing an APP needs to do is to open a WebSocket connection with a **HAS** server. Once connected, the **HAS** will send a `connected` message with the additional information. ``` js { cmd: "connected", server: string, socketid: string, timeout: number } ``` * `server`: hostname you are connected to (ex: "has-server.domain.com") * `socketid`: WebSocket connection identifier * `timeout`: time in seconds before the server considers requests to be expired. Default is 120 seconds (2 minutes) ### 2. Authentication When a user starts an **APP**, the first thing the **APP** needs to do is authenticate the user, especially if the **APP** wants to interact later with the Hive blockchain. Usually, this is done by entering a username and password and matching it against similar data stored somewhere. Hive Authentications Services enables applications to authenticate their users by simply providing a username and relieving the applications from storing additional credentials data. The credentials are stored in the **PKSA** local storage and act as a Two-Factor Authentication (2FA) provider. The users only need to trust one **PKSA**, where they safely store their private keys. They no more will be required to provide any key to any **HAS** enabled application. Likewise, they are guaranteed that their keys will never leave the **PKSA**. After the user has provided the **APP** with their account name, the **APP** will perform the authentication process. #### 2.1 Authentication request Before sending its request, the **APP** must create an "authentication request data" object (`auth_data`) it will send to the **PKSA** The structure of the `auth_data` is: ``` js { token: string = undefined, app: { name: string, description: string = undefined, icon: string = undefined pubkey: string = undefined, } } ``` - `token`: *optional* a valid session token previously received from the **PKSA** - `app`: an object describing the application - `name`: short name of the app (ex: "peakd") - `description`: *optional* description of the app (ex: "Peakd for Hive") - `icon`: *optional* URL to retrieve the application icon (ex: `"https://peakd.com/logo.png"`) - `pubkey`: *optional* a public key that the PKSA can use to return the account name encrypted with the account private posting key (`challengeAccount`). The encrypted data returned can be used by the app or its backend, if any, to validate the account against its public posting key. The **APP** must then encrypt the `auth_data` object using the encryption key previously shared with the **PKSA** (`auth_key`). By encrypting the `auth_data` object, the **HAS** will be unaware of what's going on between the app and the PKSA and unable to tamper with the authentication request process. Finally, the **APP** sends its request to the **HAS** using the following message: ``` js { cmd: "auth_req", account: string, data: string } ``` - `account`: the Hive account name that the application wants to authenticate - `data`: the Base64 representation of an encrypted `auth_data` object The **HAS** will reply with an `auth_wait` message: ``` js { cmd: "auth_wait", uuid: string, expire: number, account: string } ``` - `uuid`: a unique identifier given by the **HAS** to the request - `expire`: UNIX timestamp when the authentication request will expire - `account`: account doing the authentication request #### 2.2 Off-line Authentication Key Once the **APP** receives the request confirmation (`auth_wait` and `uuid`), it should tell the user to start its **PKSA** to approve or reject the authentication request before the request expires. The application must provide the user with out-of-band data. These data will be read by the **PKSA** in order to know which **HAS** server to connect to and to privately share an authentication key (`auth_key`) used to encrypt payloads. This can be done by providing the user with a deep link or QR code representation of that deep link. To create the deep link: 1. create an `auth_payload` object: ``` js { account: string uuid: string, key: string, host: string } ``` * `account`: the username of the account performing the authentication * `uuid`: the request identifier received with the `auth_wait` reply. * `key`: an app-generated encryption key (we recommend using a uuid) * `host`: URL of the **HAS** server to connect to (ex: "wss://has-server.domain.com") 2. convert the `auth_payload` object to a base64 string (`auth_payload_base64`) The URI for the deep link will be: `has://auth_req/{{auth_payload_base64}}` **Example:** The following auth_payload ``` { "account":"arcange", "uuid":"9b0e2dc3-f574-4766-abdd-c429dce11284", "key":"03f63469-5a35-47cb-a6b4-e8c4d3144cf9", "host":"wss://has-server.domain.com" } ``` will generate the following URI: `has://auth_req/eyJhY2NvdW50IjoiYXJjYW5nZSIsInV1aWQiOiI2NThmYzczYi1jN2MyLTQ3ODQtYWE2ZC04Mjk0MGUwNzg2OTgiLCJrZXkiOiJkOWY2OTY4NS1jMTYxLTQ2MWMtYmNkYS0wMzY4NTE3YjQzNmMiLCJob3N0Ijoid3NzOi8vaGl2ZS1hdXRoLmFyY2FuZ2UuZXUifQ` and will produce the following QR code ![](https://i.imgur.com/nYcCKtd.png) #### 2.3 Authentication approval If the user approves the authentication request with its **PKSA**, the latest will send an `auth_ack` message to the **HAS** with an access token and its expiration. When the **HAS** will receive the user approval from its **PKSA**, it will forward it to the **APP** which will receive the following message: ``` js { cmd: "auth_ack", uuid: string, data: string } ``` - `uuid`: the request identifier - `data`: `auth_req_data` encrypted with the `auth_key` and converted to Base64 The **APP** must validate the received `uuid` against the request ID (`uuid`) that it received from the **HAS** in the `auth_wait` message and ignore the `auth_ack` message if they don't match. The **APP** must decrypt the `auth_ack_data` object using the encryption key previously shared with the **PKSA** (`auth_key`). If the **APP** cannot decrypt and parse `auth_ack_data`, the **APP** must ignore the `auth_ack` message. > This `auth_ack_data` encryption/decryption process has been put in place to ensure that a malicious actor operating a **HAS** cannot bypass the **PKSA** to approve an authentication request. > >As the encryption key has been provided off-line to the **PKSA**, the **HAS** has no access to it and is therefore unable to decrypt, tamper then (re-)encrypt any data exchanged between the **APP** and the **PKSA**. The structure of the `auth_ack_data` is: ``` js { token: string, expire: number, challenge: string = undefined } ``` - `token`: session token - `expire`: UNIX timestamp when the token will expire - `challenge`: *optional* if the *APP* provided a public key to the **PKSA**, it contains the account name encrypted with the account private posting key. The application should store the token safely. This token will be used with each subsequent request. It also prevents the need for the user to re-authenticate while their token is not expired. It is up to the **APP** to reuse the token for as long as it is valid or to shorten its life by reinitiating a new authentication process without providing the existing token back to the **PKSA**. When the token expires, any transactions request will be rejected with an `unauthorized` error message sent to the application (see below) #### 2.4 Authentication refusal If the user doesn't approve the authentication request, the **PKSA** will send a refusal message to the **HAS**. The **HAS** will then forward the following message to the **APP**: ``` js { cmd: "auth_nack", uuid: string, challenge: string } ``` - `uuid`: the request identifier - `challenge`: the `uuid` encrypted with the authentication key provided off-line (see `auth_key` above) #### 2.5 Errors If for any reason the **PKSA** fails to process the authentication request, it can send an error message to the **HAS** that will forward it to the **APP**. The same applies if the error is generated by the **HAS**. In both cases, the **APP** will receive the following message: ``` js { cmd: "auth_err", uuid: string, error: string } ``` - `uuid`: the request identifier - `error`: an error message #### 2.6 Expiration It may come that the **APP** never receives any reply to its request from the **HAS**. There can be many reasons for this, like users not starting their **PKSA** or not approving or denying authentication requests they receive. The **APP** should monitor requests' expiration against the `expire` timeout provided in the `auth_wait` message. They should abort the authentication process and discard pending requests as well as any related reply they may receive. ### 3. Transactions Once the user is authenticated, they can start to transact with the Hive blockchain through the **APP**. The **APP** can now either request the **PKSA** to only sign transactions (in order to broadcast the transactions by itself to the blockchain) or ask the **PKSA** to sign and directly broadcast the signed transaction to the blockchain. #### 3.1 Transaction request The **APP** can request the **PKSA** to sign and/or broadcast a transaction. Before sending its request, the **APP** must create a "sign request data" object (`sign_data`) it will send to the **PKSA** The structure of the `sign_data` is: ``` js { key_type: string, ops: string, broadcast: boolean } ``` - `key_type`: the key type required to sign the transactions. It can be one of `posting`|`active`|`memo`. - `ops`: an array of operations - `broadcast`: `true` if the **PKSA** must broadcast the transaction to the blockchain. `false` if the **PKSA** must return a signed transaction but not broadcast it to the blockchain. The **APP** must then encrypt the `sign_data` object using the encryption key previously shared with the **PKSA** (`auth_key`). By encrypting the `sign_data` object, the **HAS** will be unaware of what's going on between the app and the PKSA and unable to tamper with the sign request process. Finally, the **APP** sends its request to the **HAS** using the following message: ``` js { cmd: "sign_req", account: string, token: string, data: string } ``` - `account`: the Hive account name - `token`: the authentication token - `data`: the Base64 representation of an encrypted `sign_data` object The **HAS** will reply with a `sign_wait` message: ``` js { cmd: "sign_wait", uuid: string, expire: number } ``` - `uuid`: a unique identifier given by the **HAS** to the request - `expire`: UNIX timestamp when the request will expire #### 3.2 Feedback to user Once the **APP** receives the request confirmation (`sign_wait` + `uuid`), it should tell the user to start its **PKSA** to approve the transaction request before the request expires. **Note:** It is strongly suggested to the **APP** and the **PKSA** to display part or all of the uuid of the request to the user. This will allow them to match it on both sides and be sure to approve the right transaction #### 3.3 Transaction approval If the user approves the transaction request with its **PKSA**, the latest will send a `sign_ack` message to the **HAS**. The **HAS** will then forward the following message to the **APP**: ``` js { cmd: "sign_ack", uuid: string, broadcast: boolean, data: object } ``` - `uuid`: the transaction request identifier - `broadcast`: `true` if the transaction was broadcasted to the blockchain by the **PKSA**, otherwise `false` - `data`: contains either the transaction id (txid) if the transaction has been broadcasted or the signed transactions (signed_tx) if it has not been broadcasted. #### 3.4 Transaction refusal If the user doesn't approve the transaction request, the **PKSA** will send a refusal message to the **HAS**. The **HAS** will then forward the following message to the **APP**: ``` js { cmd: "sign_nack", uuid: string } ``` - `uuid`: the transaction request identifier #### 3.5 Errors If for any reason the **PKSA** fails to process the transaction request, it can send an error message to the **HAS** that will forward it to the **APP**. The same applies if the error is generated by the **HAS**. In both cases, the **APP** will receive the following message: ``` js { cmd: "sign_err", uuid: string, error: string } ``` - `uuid`: the transaction request identifier - `error`: an error message #### 3.6 Expiration It may come that the App never any reply to its request from the **HAS**. There can be many reasons for this like users not starting their **PKSA** or not approving or refusing transaction requests they receive. The **APP** should monitor requests' expiration against the `expire` timeout provided in the `sign_wait` message. They should abort the authentication process and discard pending requests as well as any related reply they may receive. ### 4. Code example Here is a simple example of how an HTML web page can interact with the **HAS** infrastructure. ``` js ``` ## Wrap up In this (long) post, I have described all the steps to integrate the **HAS** protocol into your application and how easy it is to interact with the **HAS**. In the next post, I will explain what is happening on the **PKSA** side and how you can run your own Private Key Storage Application. Thanks for reading. --- |

Support the HAS project!

| |-| |[Vote for the proposal on PeakD](https://peakd.com/me/proposals/194)
[Vote for the proposal on Ecency](https://ecency.com/proposals/194)
[vote for the proposal on Hive.blog](https://wallet.hive.blog/proposals)
[Vote for the proposal using HiveSigner](https://hivesigner.com/sign/update_proposal_votes?proposal_ids=%5B%22194%22%5D&approve=true)| ### [Vote for me as a witness ![](https://i.imgur.com/2bi4SnT.png)](https://hivesigner.com/sign/account-witness-vote?witness=arcange&approve=1)

**Support the **HAS** project!**

Support the HAS project!

ausbitbank