Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

x/mod/sumdb/note: documentation for key formats is incomplete #56358

Open
arai-fortanix opened this issue Oct 20, 2022 · 1 comment
Open

x/mod/sumdb/note: documentation for key formats is incomplete #56358

arai-fortanix opened this issue Oct 20, 2022 · 1 comment
Labels
Documentation NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one.
Milestone

Comments

@arai-fortanix
Copy link

The sumdb note documentation for key formats is incomplete. https://pkg.go.dev/golang.org/x/mod@v0.6.0/sumdb/note

The documentation states that The standard implementation of a Verifier is constructed by NewVerifier starting from a verifier key, which is a plain text string of the form "<name>+<hash>+<keydata>".

It appears that the hash is in hexadecimal, while the keydata is base64-encoded. I cannot find a description of this anywhere in the documentation. The documentation does say that the key hash is an unsigned 32 bit integer.

Also, the keydata is one byte of key type followed by the actual bytes of the key. The documentation does say this: There is only one key type, Ed25519 with algorithm identifier 1. New key types may be introduced in the future as needed, although doing so will require deploying the new algorithms to all clients before starting to depend on them for signatures.. I don't see anywhere in the documentation that says that this algorithm identifier is the first byte of the keydata.

Having this fully documented is useful when you have signatures produced in the sumdb note and key format, and you want to verify those signatures using a program written in another language.

@seankhliao seankhliao changed the title affected/package: sumdb note documentation for key formats is incomplete x/mod/sumdb/note: documentation for key formats is incomplete Oct 20, 2022
@seankhliao seankhliao added the NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. label Oct 20, 2022
@gopherbot gopherbot added this to the Unreleased milestone Oct 20, 2022
@hickford
Copy link

hickford commented Jan 18, 2023

I also found the docs hard to follow. https://go.dev/ref/mod#checksum-database doesn't mention the hash part.

If it helps anyone else, starting from

var knownGOSUMDB = map[string]string{
"sum.golang.org": "sum.golang.org+033de0ae+Ac4zctda0e5eza+HJyk9SxEdh+s3Ux18htTTAD8OuAn8",
}

Split on separator + into exactly three parts and take the third part Ac4zctda0e5eza+HJyk9SxEdh+s3Ux18htTTAD8OuAn8. This you have to base64 decode then drop the first byte to get a 32 byte ed25519 public key compatible with https://pkg.go.dev/crypto/ed25519#Verify . In base64, this public key is zjNy11rR7l7Nr4cnKT1LER2H6zdTHXyG1NMAPw64Cfw=

PKIX marshalled and PEM encoded:

-----BEGIN PUBLIC KEY-----
MCowBQYDK2VwAyEAzjNy11rR7l7Nr4cnKT1LER2H6zdTHXyG1NMAPw64Cfw=
-----

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Documentation NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one.
Projects
None yet
Development

No branches or pull requests

4 participants