HiveAuth Protocol Update

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 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!