Signature

As we have already seen in previous chapters, there are 2 main mechanisms of signatures in NextGraph :

• each commit is signed by its author, in order to prove authenticity of the data, and to verify permissions. Only authorized editors can add certain types of commits. This signature is only available to other editors in the Repo (because the USerId is hashed and only the editors know who is part of the list of editors). This signature is useless to anybody outside the Repo (external readers)

• we added a mechanism of threshold signature, that can be used in async or sync mode, and that involves another type of users: the signers. Editors and Signers do not have to be the same users within a repo. By example, signers can be some observers that are not capable of editing the document, but hat will guarantee the integrity of the repo. Those threshold signatures are not systematic, and need to be requested on a case by case basis. We distinguish 2 types of threshold signatures :

  • asynchronous : used for CRDT operations. The request for signature must happen after the commit has been attached to the DAG and sent in the pub/sub.

  • synchronous : this signature will add some guarantees on finality, sequence, and consistency of the transaction. The request for signing happens before the commits are added to the DAG or sent in the pub/sub. In fact, the commits are embedded with the signature, and cannot be seen by others if the signature hasn’t been validated first. As requesting and obtaining the signature is a synchronous operation, at least all the quorum needs to be online before the transaction can be accepted. For this reason, signers of the synchronous quorum, should rather be online often. (async and sync signatures have 2 distinct quorums, for that reason).

We will only deal with threshold signatures here in this chapter.

What is implemented so far:

The user can ask for the commits at the HEAD (the latest commits received by the replica) to be signed, if they are not signed already. This will be an async signature.

Alternatively, the user can ask for a snapshot to be taken first (which will merge all the current HEADs) and then to ask for this snapshot to be signed.

The snapshot can then be shared with external users by using its Nuri, and the external user will be able to read it, and also to verify its signature.

A snapshot contains the integrality of the content of the branch (both the discrete and graph parts) serialized as JSON.

The signature contains a certificate, that is a chain of proofs that has at its root, the RepoID (which is a public key). This way, the snapshot can be authenticated as authored by the editors of the Repo/Document.

The same goes for the HEAD commits that get signed.

When the external users retrieves those commits (or the snapshot), they use the Ext Protocol, which does not require any authentication from the user.

As a security measure, the commits and any block received on the Ext Protocol, will be stripped from their header. It means that it will be impossible to access the causal past of the commits, and impossible to reconstruct the DAG.

This security feature is important, as external users should only be able to read what has been shared with them. If a commit has been shared, then only the transaction within the commit can be read. If a snapshot, then all the current content of the branch can be read, but it cannot be subscribed to for future updates.

If the user should be able to subscribe to the topic of the branch in order to receive updates, then a ReadCap of the branch should be share with them instead. Those branch ReadCap do not need to be signed with threshold signature because they are already signed internally with at least the first commit of the branch (the Branch commit) that has been signed with a synchronous signature when the branch was created. And because the user will be able to reconstruct the whole DAG up to this first commit (by doing the a sync operation) they will be able to verify the authenticity of the branch. If the authenticity of the content should also be verifiable, then an async signature must be added at the HEADs, and the user who got the branch ReadCap will get it too, and will be able to verify the authenticity of the content as well.

For now, the ext protocol and the reading of async signatures, snapshots, and commits, can be done with the CLI. Soon, APIs in the SDK will also be added.

More work is needed on the signature feature in general, stay tuned!