HiveAuth Protocol Update - V1
A few days ago, I announced the decentralization of the HiveAuth infrastructure. If you missed the post, you can read it here.
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 (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
challenge: string
decrypt: boolean = false // protocol >= 1
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 providing a PKSA example has been updated.
Long story made short, the PKSA needs to take care of the following changes:
token
property removed fromauth_req_data
for theauth_req
requesttoken
property removed fromauth_ack_data
for theauth_ack
responsenonce
property added to thesign_req_data
object for thesign_req
requesttoken
property removed from thesign_req
object for thesign_req
requestnonce
property added to thechallenge_req_data
object for thechallenge_req
requesttoken
property removed from thechallenge_req
object for thechallenge_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!
The Hive.Pizza team manually curated this post.
Join us in Discord!
That means that Keychain will be upgraded and it will have some more benefits
I like that...
Nice technical explanation, but on the other hand can you ELI5 how HiveAuth is decentralized and if it is open source or not?
As mentioned, that will be the subject of my next posts.
Wonderful, thank you for being awesome.
Thank you @danieldedosd2
This was really helpful, thanks
technophobes like myself are forever in your debt for the work you put in cheers
Thank you @grindle! I'm glad that my work is helpful to users like you.
it certainly is, though I must admit some are way above my head!
Kudos! Thanks for the updates
Such impressive developments. Look forward to all the beautiful things to be built in the years ahead.
Sorry to reply to a old post but I tried using your recovery account site to change my recovery from steemit to hive but it won't let me do it. It keeps coming up no active key or something of that nature. Do you know what's up with that.
You can use this Discord channel to get help with your issue
I am not on Discord anymore. Always had to wait for the thing to download every time I turned on my computer. I rarely used it so I got rid of it.