Creating a cryptolink claim from node to node (cross-signing claims)

[joshuakarp]

This will be resolved in !209 https://gitlab.com/MatrixAI/Engineering/Polykey/js-polykey/-/merge_requests/209

Specification

!195 has changed the way that node -> node cryptolink claims will need to be created.

Recall that a claim (e.g. a cryptolink) has the following structure:

{
  signatures: [
    {
      signature: <base64 encoding of signature, signed on header + payload>,
      protected: <base64 encoding of serialized header (currently containing signing algorithm + node ID of signee>
    }, 
    ...
  ],
  payload: <base64 encoding of serialized payload (see Claim type for payload contents)>
}

For a keynode, these claims are stored on the node's sigchain.

Therefore, suppose a node X wants to establish a cryptolink to node Y. Both nodes require a claim on their respective sigchain that states they have a cryptolink to the other.

However, we require that any claim from a node -> node be signed by both nodes. Therefore, node X will need to sign both its own claim, and Y's claim on its sigchain (and vice-versa).

This allows any arbitrary node to easily verify the claim. Suppose A receives the cryptolink claim from X, stating that it has a cryptolink to Y. A would verify the claim with X's public key, but importantly, A doesn't need to see the corresponding claim on Y's sigchain - it only needs to verify this claim on X's sigchain with Y's public key.

We need a procedure in place to synchronise the creation of these claims between nodes.

Additional context

• original idea discussed here https://gitlab.com/MatrixAI/Engineering/Polykey/js-polykey/-/merge_requests/195#note_624698872

Tasks

This will likely make use of the notifications domain. The following process (or some other variation of it) will need to be implemented:

To create a cryptolink from X to Y:

1. X sends a "cryptolink request" of some sort to Y
2. Y (at some point in time) accepts this request.
3. X creates the claim, and transfers the 'unsigned' claim to Y
4. Y checks the claim to see its correct, signs it, and sends it back to X
5. X checks the claim again and signs it itself.
6. X adds this claim to its sigchain
7. Repeat steps 3-6 in the reverse order to create a claim to store on Y's sigchain

See the following code snippet for a working prototype of this process:

import type { NodeId } from './src/nodes/types';

import * as sigchainUtils from './src/sigchain/utils';
import * as claimsUtils from './src/claims/utils';
import * as keysUtils from './src/keys/utils';
import { KeyManager } from './src/keys';
import { GeneralSign } from 'jose/jws/general/sign';
import canonicalize from 'canonicalize';
import { createPrivateKey } from 'crypto'

async function main() {

  // We want to establish a cryptolink connection between:
  // Node A <--> Node C

  // On Node A:
  const aKeyPair = await keysUtils.generateKeyPair(4096);
  const aKeyPairPem = keysUtils.keyPairToPem(aKeyPair);
  const aPrivateKey = createPrivateKey(aKeyPairPem.privateKey);
  const aHashPrev = 'hashA';
  const aSeq = 2;

  // On Node C:
  const cKeyPair = await keysUtils.generateKeyPair(4096);
  const cKeyPairPem = keysUtils.keyPairToPem(cKeyPair);
  const cPrivateKey = createPrivateKey(cKeyPairPem.privateKey);
  const cHashPrev = 'hashC';
  const cSeq = 5;

  // 1. On Node A:
  // Node A constructs a claim from A -> C
  const payload = {
    hPrev: aHashPrev,
    seq: aSeq,
    data: {
      type: 'node',
      node1: 'A' as NodeId,
      node2: 'C' as NodeId,
    },
    iat: Date.now()
  }
  const canonicalizedPayload = canonicalize(payload);
  const byteEncoder = new TextEncoder();
  const claim = new GeneralSign(byteEncoder.encode(canonicalizedPayload));
  // Node A sends this claim over to Node C

  // 2. On Node C:
  // Node C should check the fields of the claim and make sure they're correct
  // Then, Node C signs the claim
  claim.addSignature(cPrivateKey).setProtectedHeader({ alg: 'RS256', kid: 'C' });
  // Node C sends this signed claim back to Node A

  // 3. On Node A:
  // Node A should check the fields of the signed claim and make sure they're correct
  // Then, Node A also signs the claim
  claim.addSignature(aPrivateKey).setProtectedHeader({ alg: 'RS256', kid: 'A' });
  // Finally, we perform the '.sign' operation
  const jws = await claim.sign();
  console.log(jws);
  // Node A stores this JWS claim on its signchain
}

main();

This will require refactoring the createClaim utility function in claims/utils. See this todo note:

// TODO: Potentially need a createUnsignedClaim function that returns a
// claim = new GeneralSign(payload). This will be needed to sign the claim by
// both nodes, when creating a node -> node claim.

utils.test.ts should be extended to ensure multiple signatures can be added and subsequently verified (currently, they only test claims where 1 signature exists).

[CMCDragonkai]

Adding @emmacasolin here into this as there is some cross over between the notifications work and this work.

You 2 should meet up to plan out and work out the kinks of the design of this system.

[CMCDragonkai]

Consider this the next priority after you finish up with the Notifications and Gestalts article @emmacasolin and when @joshuakarp finishes up with the R&D article, (while also reviewing my post-merge review of the nodes cli).

[joshuakarp]

To create a cryptolink from X to Y:

1. X sends a "cryptolink request" (a notification with some expected string) to Y
2. Y (at some point in time) reads this notification and can accept this request (if desired).
3. If accepting, Y will need to send a notification back to X to say "I accept"
4. X creates the claim, and transfers the 'unsigned' claim to Y
5. Y checks the claim to see its correct, signs it, and sends it back to X
6. X checks the claim again and signs it itself.
7. X adds this claim to its sigchain
8. Repeat steps 3-6 in the reverse order to create a claim to store on Y's sigchain

[joshuakarp]

From chat with @emmacasolin , I envisage the above process should work out of the box with the notifications domain.

I think the only issue I see is steps 2 and 3. If Y reads the notification at some later date, but X is offline, obviously it can't send this "I accept" notification back. At the present time, I don't believe any kind of async messaging for notifications is possible https://en.wikipedia.org/wiki/Message_passing#Asynchronous_message_passing.

However, take a step back and think of the use case of establishing a claim between nodes. The 2 nodes are likely to be owned by the same entity/person, so I don't think it's an issue to assume they need to be online at the same time.

[CMCDragonkai]

This is why notification sending should be delay-tolerant. They enter a queue for sending. So if they cannot be sent now, it can be retried later. This is basically the same as email. This queuing can be done later, we can add delay tolerant feature for after release.

…

On 8/13/21 3:37 PM, Josh wrote: From chat with @emmacasolin <https://github.com/emmacasolin> , I envisage the above process should work out of the box with the |notifications| domain. I think the only issue I see is steps 2 and 3. If |Y| reads the notification at some later date, but |X| is offline, obviously it can't send this "I accept" notification back. At the present time, I don't believe any kind of async messaging for notifications is possible https://en.wikipedia.org/wiki/Message_passing#Asynchronous_message_passing <https://en.wikipedia.org/wiki/Message_passing#Asynchronous_message_passing>. However, take a step back and think of the use case of establishing a claim between nodes. The 2 nodes are likely to be owned by the same entity/person, so I don't think it's an issue to assume they need to be online at the same time. — You are receiving this because you commented. Reply to this email directly, view it on GitHub <#213 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAE4OHJV2MKAWG52JXKRYUTT4SVRBANCNFSM5AZCAPUQ>.

[CMCDragonkai]

Clarifying the steps. This is currently fully synchronous, no delay tolerance.

X -> sends notification to (to start cross signing request)( -> Y
X <- calls cross signing grpc request and sends its signed claim (intermediate) <- Y (use bidirectional stream and lock the sigchain on Y and X)
X -> responds with double signing the Y signed claim, and also bundles it with its own signed claim (intermediate) -> Y
X <- responds with double signing the X signed claim <- Y

So you have to use a bidirectional grpc stream because Y has to send a message to X, and X has to respond with a message and Y has to respond again.

[CMCDragonkai]

For the bidirectional grpc streaming see the grpc utils. And the tests associated. It shows how to use the async generator abstractions for reading and writing on a bidirectional stream. It's better than using stream API. It fits into the promise style.

So Y has to do write, read, write.

X has to do read, write, read.

You'll need to have a timeout applied to both sides. So that the transaction is completed with a certain amount of time. If there's no timeout, it's possible to lock the sigchain forever. Make sure that if any exception occurs that there's a finally block that unlocks the sigchain. If the connection breaks, you must make sure the sigchain gets unlocked.