HiveAuth Protocol Update - V1

 A few days ago, I announced the [decentralization](/@arcange/hiveauth-decentralization) of the HiveAuth infrastructure. If you missed the post, you can read it [here](/@arcange/hiveauth-decentralization). With the deployment of this new HiveAuth feature comes an update of the communication protocol that is used between applications (APP), HiveAuth infrastructure servers (HAS) and authentication applications (PKSA) such as Hive Keychain for Mobile. The content of this post will therefore be more technical than the previous one because it is mainly aimed at application developers. However, I will try to be exhaustive in the explanations so that even people who are not part of this target audience can find educational information there. ## HAS Protocol Changes I will now describe all the changes that have taken place and require modification of existing applications supporting HiveAuth. I will also provide advice to make them compatible with the two protocol versions, the current v0.8 and v1 which will be put into production soon. This will allow for a smooth transition between the two protocol versions before then permanently removing support for v0.8 which will become obsolete. ### 1. Applications In this section, I will describe the changes made to the HAS V1 protocol that have an impact on applications. This will let developers know what changes they need to make to their code to support the new protocol. #### **1.1 Connection** To be able to use the HiveAuth infrastructure, the first thing an application does is connect to a HAS server. Previously, the HAS server returned the protocol version as `major.minor`. As of V1, it will return only one number (major). In this way, it follows the [Semantic Versioning standard](https://semver.org/) (which states that if a breaking change occurs, the major number must change) while not getting bogged down with 'minor' info. With more than a year of good and loyal service since its release, the HiveAuth protocol has not undergone any breaking changes for APPs or PKSAs. But I knew a major update was coming that would pave the way for a multi-node version of the protocol. That being said, it is very likely that this will be one of the last, hence the move from version 0.x to version 1 #### **1.2 Authentication request** When authenticating a user, the APP has to prepare an `auth_req_data` object that it will encrypt and send to the HAS. With protocol V0.8, this object contains a `token` property. ``` { app: { name: string, description: string = undefined, icon: string = undefined }, token: string = undefined, // protocol < 1 only challenge: object = undefined } ``` This property is **no longer required** with protocol V1. If present, it will be ignored by the new protocol. Operating without additional data like a token exchanged between parties and relying solely on cryptography for user identification and authentication reduces the potential attack surface and provides a **higher level of security**. #### **1.3 Authentication approval** When a user approves an authentication request, the PKSA returns an `auth_ack_data` object via the HAS server. With protocol V0.8, this object contains a `token` property. ``` { token: string, // protocol < 1.0 only expire: number, challenge_data: object = undefined } ``` This property **no longer exists** with protocol V1. If present, it will be ignored by the new protocol. #### **1.4 Transaction request** When signing or broadcasting a transaction, the APP has to prepare a `sign_req_data` object. The V1 protocol adds a **new `nonce` property** to that object: ``` sign_req_data { key_type: string, ops: string, broadcast: boolean, nonce: number } ``` The **nonce** value must be the **current UNIX time** (`Date.now()` in Javascript). If a transaction request ever fails, do **NOT** reuse the `sign _req_data` object **before first updating the nonce** otherwise your request will be rejected! #### **1.4 Challenge request** When submitting a challenge for the PKSA to sign it, the APP has to prepare a `challenge_req_data` object. The V1 protocol adds a **new `nonce` property** to that object: ``` challenge_req_data { key_type: string, ops: string, broadcast: boolean, nonce: number } ``` The **nonce** value must be the **current UNIX time** (`Date.now()` in Javascript). If a transaction request ever fails, do **NOT** reuse the `challenge _req_data` object **before first updating the nonce** otherwise your request will be rejected! #### **1.5 Summary** As you can see, updating an APP to support HAS protocol V1 is pretty easy to do. However, if their applications already support HiveAuth, I recommend that developers process in **two phases** in order to maintain compatibility with the current versions of HAS and Keychain: ***1. Support both V0.8 and V1*** Keep managing the `token` property. If you connect to a HAS V1, it will be ignored but it would break connectivity with HAS V0.8 if you remove it. Add the `nonce` property in your `sign_req_data` and `challenge_req_data` objects. If you connect to a HAS V0.8 it will be ignored but it would lead to an error if you connect to a HAS V1 without it being there. By doing so, you will get the best of both worlds. ***2. Deprecate support for V0.8*** Once the V1 protocol is deployed and the V0.8 protocol is no longer supported, all developers have to do is drop any code related to the `token` property, including its storage by the APP. From this moment, I strongly recommend enforcing the protocol version's validation at the APP level and refusing to connect to a HAS node using a protocol version different from the one supported by the APP. ### 2. Private Key Storage Apps (PKSA) Keychain Mobile being the only publicly available PKSA currently, I have communicated all required changes to be made to its developers. For those who are impatient or wish to deploy their own PKSA, the [repository on GitHub](https://github.com/hiveauth/hive-auth-pksa) providing a PKSA example has been updated. Long story made short, the PKSA needs to take care of the following changes: * `token` property removed from `auth_req_data` for the `auth_req` request * `token` property removed from `auth_ack_data` for the `auth_ack` response * `nonce` property added to the `sign_req_data` object for the `sign_req` request * `token` property removed from the `sign_req` object for the `sign_req` request * `nonce` property added to the `challenge_req_data` object for the `challenge_req` request * `token` property removed from the `challenge_req` object for the `challenge_req` request ## What's next? As mentioned in my previous post, the Keychain team is working on an update of Keychain Mobile that supports the HAS protocol V1. Once a beta version is available for testing, I will deploy a new HAS server supporting the protocol V1 so developers can test their apps in live conditions. In the meantime, in my next posts, I will describe why the changes in the protocol, how the new multi-node version of the HiveAuth infrastructure works and how to deploy a node if you wish to contribute to the HiveAuth network. Stay tuned! --- ### Check out my apps and services ### [Vote for me as a witness ](https://vote.hive.uno/@arcange)