v1.0 (#1) by expede · Pull Request #18 · ChainAgnostic/varsig

expede · 2025-05-07T22:12:08Z

This has been sitting on a fork for a while. It makes a bunch of parts of the spec more consistent, and addresses design criticism of the v0.1. It also includes (IMO) better examples.

expede · 2025-05-07T22:29:02Z

(cc @hugomrdias if you have time)

hugomrdias · 2025-05-09T14:00:52Z

 2. Such a strategy also MAY require accounting for revocation of the signing keys themselves. In this case, the cache would need to include additional information about the signing key.

-## 2.2 Raw (Noncanonicalized) Data
+# Format


everything above this section IMO should be removed! IPLD, CID, etc, etc
this spec SHOULD not care about any of it

This spec is for signing over IPLD data — the motivation came from being unable to sign IPLD payloads. It would be called "multisig" except that's the name of an existing concept (namespace conflict). Part of the motivation is that we can't sign over IPLD data without knowing the serialisation and whatnot. If someone wants to sign non-IPLD data, they can use the raw encoding prefix.

We could split these into separate specs, but I'm not sure how different that would look in practice compared to us having the payload encoding at the final field. There exist canonicalisation attacks possible if you don't include the exact encoding detail in the header (JWT etc also do this for the same reason)

it has that benefit of helping ipld data signatures but not restrict to it.
we talk about EIP191 and JWT in which the payload is not ipld data (or may not be).

If someone wants to sign non-IPLD data, they can use the raw encoding prefix.

what does this mean? itsnt varsig just a bunch of prefixes?

On the other hand, the non-IPLD data schemes we want to support are strange to combine with varsig,

JWT: i dont even know how to do JWT with varsig cause JWT is kinda similar to varsig just a json header

EIP191: you are supposed to sign UTF8 string using personal_sign but you can encode varsig+payload and it works

webauthn: still need to recheck this but im guessing we will put varsig+payload in the challenge as a string or a CID

expede · 2025-05-09T16:38:02Z

For anyone following along, Hugo and I chatted out of band about design motivation and mostly I need to explain what is in and what's out for the spec ("it's all metadata")

Co-authored-by: Hugo Dias <hugomrdias@gmail.com>

hugomrdias

LGTM 🎉🎉🎉

hugomrdias · 2025-05-28T13:55:52Z

@expede let's merge this ?

MichaelMure · 2025-05-29T06:22:42Z

+> The JSON above contains a duplicate `role` key.

-Next, the application parses the JSON with the browser's native JSON parser.
+Next, the application parses the JSON with the browser's native JSON parser. Only one `role` key is possible in a JavaScript object, and which one is kept is not consistency across implementations.


Suggested change

Next, the application parses the JSON with the browser's native JSON parser. Only one `role` key is possible in a JavaScript object, and which one is kept is not consistency across implementations.

Next, the application parses the JSON with the browser's native JSON parser. Only one `role` key is possible in a JavaScript object, and which one is kept is not consistent across implementations.

smoyer64 · 2025-06-17T11:54:15Z

-
-message-byte-length = unsigned-varint
+```abnf
+varsig-header = %x34 signature-algorithm-metadata payload-encoding-metadata


This is folded when I view the mark-down, so maybe my obsession with formal grammars finally helped someone :) - The ABNF needs a version field right after the prefix. Since v0 is implied if this field is absent, I guess it's optional here.

smoyer64 · 2025-06-17T16:27:24Z

+
+        algo_header["Algorithm"]
+
+        block:AlgoBody


In v0.1.0-rc1, the order of the signing algorithm fields for RSA was RSA=0x1205, hash=SHA2-256=0x12, key length - is there a rationale for switching the order of the latter two fields?

Looking closer, the examples in common.md have the same field order as the v0.1.0-rc1 documentation so I think this is just a typo in the diagram.

smoyer64 · 2025-07-07T16:13:18Z

+| Segment                | Hexadecimal | Unsigned Varint | Comment                          |
+|------------------------|-------------|-----------------|----------------------------------|
+| `eddsa-prefix`         | `0xED`      | `0xED01`        | EdDSA prefix                     |
+| `eddsa-curve`          | `0xED`      | `0xEC01`        | edwards25519 [multicodec] prefix |


Typo in conversion to uvarint

smoyer64 · 2025-07-08T15:47:19Z

+
+| Segment                | Hexadecimal | Unsigned Varint | Comment                          |
+|------------------------|-------------|-----------------|----------------------------------|
+| `eddsa-prefix`         | `0xED`      | `0xED01`        | EdDSA prefix                     |


There's a draft multicodec.Code for EdDSA that's 0xd0ed and is labeled that it was created for varsig, should that be used here since 0xed is specifically the Ed25519 curve (technically the pub key)

When working with Varsig, you can safely ignore Multicodec entries.

Varsig sometimes puns on Multicodec values, but they're distinct values. Varsig's only relationship to multicodec is that Varsig itself has an entry in Multicodec. Multicodec is very difficult to get changes into (sometime 6+ months lag time), so we can add stuff to this spec much more easily.

smoyer64 · 2025-07-08T16:50:31Z

-1. Signing CIDs enables a simple strategy for caching validation by CID.
-2. Such a strategy also MAY require accounting for revocation of the signing keys themselves. In this case, the cache would need to include additional information about the signing key.
+* [Prefix]: The Varsig [multicodec] prefix `0x34`
+* [Version]: The Varsig version number `0x01`


I'm happy to see the addition of a version number for the varsig encoding. This may very well be the wrong spot for this question but ... In this section of the UCAN spec, the .1.h field description says it's a Varsig v1 header. In the example JSON just below the diagram, the value NBIFEgEAcQ decodes to a Varsig v0 that's missing its signature bytes. The go-varsig implementation therefore currently allows Varsig v0 decoding that have the correct number of signature bytes OR with zero signature bytes (in which case both an error is returned as well as the decoded value - ugh). I'm hoping you'll tell us to go fix our UCAN implementation and that we can deprecate the v0 code in go-varsig.

Yes, feel free to deprecate any Varsig v0 code. I'll update the UCAN spec to fix that prefix, and I'll merge this PR momentarily to clear up the Varsig end 👍

expede · 2025-07-09T18:42:53Z

@expede let's merge this ?

Done ✅

v0.2 (#1)

b809004

expede requested review from Gozala and oed as code owners May 7, 2025 22:12

cla-bot Bot added the cla-signed label May 7, 2025

hugomrdias suggested changes May 9, 2025

View reviewed changes

Comment thread common.md

Comment thread common.md Outdated

Comment thread common.md Outdated

Comment thread common.md

Comment thread common.md

Comment thread common.md Outdated

Comment thread common.md Outdated

Comment thread common.md

hugomrdias suggested changes May 9, 2025

View reviewed changes

expede and others added 6 commits May 10, 2025 15:27

Feedback from Hugo

0c8b5ca

Update README.md

5724c68

Co-authored-by: Hugo Dias <hugomrdias@gmail.com>

Update README.md

0d1bb56

Co-authored-by: Hugo Dias <hugomrdias@gmail.com>

Update common.md

1f7fe62

Co-authored-by: Hugo Dias <hugomrdias@gmail.com>

Update common.md

2a3e2f3

Co-authored-by: Hugo Dias <hugomrdias@gmail.com>

Update common.md

8ca48ab

Co-authored-by: Hugo Dias <hugomrdias@gmail.com>

expede commented May 10, 2025

View reviewed changes

Comment thread common.md

expede added 2 commits May 10, 2025 15:46

Updates per Hugo

4ab4bc7

Parity bits

86aa4c6

hugomrdias reviewed May 13, 2025

View reviewed changes

Comment thread README.md Outdated

Siwtch to mermaid

3864dc0

expede changed the title ~~v0.2 (#1)~~ v1.0 (#1) May 14, 2025

expede added 9 commits May 14, 2025 14:23

Working through more Hugo feedback

08408dd

Reduce dependency on IPLD

e2e2d8d

Remove many IPLD references

2398db6

Internal links

3a62841

MIssing link

aa42ba0

Missing link

73750fd

Remove unused file

5306991

Remove sig-bytes

2f02d63

typo

d27cdee

expede added 4 commits May 16, 2025 12:49

Spell check

2aafe1f

Pick up the dictionary

14714dd

Put path back

46c14e7

Sort dict

13ef318

hugomrdias suggested changes May 20, 2025

View reviewed changes

expede and others added 10 commits May 20, 2025 23:08

Update common.md

69b37d0

Co-authored-by: Hugo Dias <hugomrdias@gmail.com>

Update common.md

7a7d591

Co-authored-by: Hugo Dias <hugomrdias@gmail.com>

Update common.md

7a6b15b

Co-authored-by: Hugo Dias <hugomrdias@gmail.com>

Update common.md

ef3e048

Co-authored-by: Hugo Dias <hugomrdias@gmail.com>

Update common.md

ae4dd87

Co-authored-by: Hugo Dias <hugomrdias@gmail.com>

Update common.md

2413fd8

Co-authored-by: Hugo Dias <hugomrdias@gmail.com>

Update common.md

93e8892

Co-authored-by: Hugo Dias <hugomrdias@gmail.com>

Update common.md

e507d5f

Co-authored-by: Hugo Dias <hugomrdias@gmail.com>

Update common.md

e9f9848

Co-authored-by: Hugo Dias <hugomrdias@gmail.com>

Update common.md

41b0b59

Co-authored-by: Hugo Dias <hugomrdias@gmail.com>

hugomrdias approved these changes May 21, 2025

View reviewed changes

MichaelMure reviewed May 29, 2025

View reviewed changes

smoyer64 reviewed Jun 17, 2025

View reviewed changes

smoyer64 reviewed Jul 7, 2025

View reviewed changes

expede added 4 commits July 7, 2025 15:38

Specify ECDSA raw encoding

ddf5a50

Typo

546aea3

Fix mathtext typo

8b15b55

Add to dictionary

4edbf73

smoyer64 reviewed Jul 8, 2025

View reviewed changes

Fix a couple typos

11eec4a

expede merged commit 5a5b0af into ChainAgnostic:main Jul 9, 2025
2 checks passed

	Next, the application parses the JSON with the browser's native JSON parser. Only one `role` key is possible in a JavaScript object, and which one is kept is not consistency across implementations.
	Next, the application parses the JSON with the browser's native JSON parser. Only one `role` key is possible in a JavaScript object, and which one is kept is not consistent across implementations.

Conversation

expede commented May 7, 2025

Uh oh!

expede commented May 7, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

expede May 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

expede commented May 9, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

hugomrdias left a comment

Choose a reason for hiding this comment

Uh oh!

hugomrdias commented May 28, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

expede commented Jul 9, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

expede May 10, 2025 •

edited

Loading