JWT Signature Verification

[simibac]

I created the following VC:

{
  credentialStatus: {
    type: 'EthrStatusRegistry2019',
    id: 'rinkeby:0x97fd27892cdcD035dAe1fe71235c636044B59348'
  },
  credentialSubject: {
    name: 'Alice',
    id: 'did:ethr:0xc5ed61933bc206b15e14e05a404ed1231abd28e2'
  },
  issuer: { id: 'did:ethr:0xc5ed61933bc206b15e14e05a404ed1231abd28e2' },
  type: [ 'VerifiableCredential', 'Profile' ],
  '@context': [ 'https://www.w3.org/2018/credentials/v1' ],
  issuanceDate: '2021-02-06T23:02:13.000Z',
  proof: {
    type: 'JwtProof2020',
    jwt: 'eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NksifQ.eyJ2YyI6eyJjcmVkZW50aWFsU3ViamVjdCI6eyJuYW1lIjoiQWxpY2UifSwiQGNvbnRleHQiOlsiaHR0cHM6Ly93d3cudzMub3JnLzIwMTgvY3JlZGVudGlhbHMvdjEiXSwidHlwZSI6WyJWZXJpZmlhYmxlQ3JlZGVudGlhbCIsIlByb2ZpbGUiXX0sImNyZWRlbnRpYWxTdGF0dXMiOnsidHlwZSI6IkV0aHJTdGF0dXNSZWdpc3RyeTIwMTkiLCJpZCI6InJpbmtlYnk6MHg5N2ZkMjc4OTJjZGNEMDM1ZEFlMWZlNzEyMzVjNjM2MDQ0QjU5MzQ4In0sInN1YiI6ImRpZDpldGhyOjB4YzVlZDYxOTMzYmMyMDZiMTVlMTRlMDVhNDA0ZWQxMjMxYWJkMjhlMiIsIm5iZiI6MTYxMjY1MjUzMywiaXNzIjoiZGlkOmV0aHI6MHhjNWVkNjE5MzNiYzIwNmIxNWUxNGUwNWE0MDRlZDEyMzFhYmQyOGUyIn0.W4VXt_Wnn0jJt5gqf8S0xBGXlMyykWsdqjXpLe2jUplC4SSpPPKSFhRmuzaQdvu_KBKiinZht007bWorj6E7QQ'
  }
}

For this example, I used the issuer is also the credential subject to make it simple.
did:ethr:0xc5ed61933bc206b15e14e05a404ed1231abd28e2
pubkeyhex: 047bb2b3d12a72570ecbaa4c7c3543f0ac75dd581d5c7450acf3dc730dd03e54d6f51aed1345df3344f06d2d13818c207a319ee73f68db0d2e2967d26a055ae045
privkeyhex: ecc4dc12a04fd90c425932fee1f896d2f4d5ea152631ef46a44257f8ca3267fd84d71a98516dfa6aa0d4528a137c8088ff7684f456d9115abbea2bf01e383dcf90ecf1e52eed1b14c11ceeb460f5f9cd190eda890d1e8723e16bdd3f12c2b36c3ac4d61abbe70936

For validating the signature I use jwt.io. It detects ES256K as the algorithm. However, I am not able to verify the signature by pasting the private key into the secret field. How do you verify that the signature is correct for the given example?

[mirceanis]

Independent verification

You can use did-jwt to do independent verification of JWTs signed by DID issuers.

jwt.io doesn't support the ES256K algorithm, so it's not possible to verify there.

For verification of the ES256K algorithm, the private key is not needed. The verifier only needs to know the public key of the issuer
(or the ethereum address, see note below).

In the case of JWT verifiable credentials, it is common that the issuer is listed as a DID in the iss field of the JWT payload.
The DID can be resolved to get a list of public keys that the DID claims to control.
It is expected that the issuer used one of these public keys to sign the JWT.
The benefit of this system is that the only data you need to verify the JWT is already contained in the JWT.

The did-jwt library performs all these actions and supports ES256K as well as EdDSA algorithms.

Verification using veramo

Veramo doesn't directly expose an explicit verification API yet. This is being discussed in #375.

At the time of this writing, verification of credentials is baked into message handling.
With a default configuration, you can use the @veramo/cli to check the validity of a JWT credential:

npm i -g @veramo/cli
veramo config create
veramo message handle -r "<the JWT you want to verify>"

or programmatically by calling agent.handleMessage({...}):

try {
  const msg = await agent.handleMessage({ raw: '<the JWT to be verified>', metaData: [{ type: 'test' }] });
  console.log('signature is valid');
} catch (e) {
  console.log('signature is not valid')
}

Programmatic verification like this requires an agent the has the @veramo/message-handler plugin with the JwtMessageHandler and W3cMessageHandler in the handler chain, as well as the @veramo/did-resolver plugin with an ethr method resolver.

---

ES256K and ethereum addresses

It is also possible to verify an ES256K signature against an ethereum address instead of a public key.
Given a signature and the data that was signed, it is possible to reconstruct 2 possible public keys of the signer.
One can then compute the ethereum address for each of the possible public keys and if one of the addresses matches the tested address then it is a valid signer.

did-jwt already uses this logic in case the resolved DID document does not list the full public key, but only ethereum address.

Since this verification method is non-standard, the ES256K-R JWT algorithm was proposed to codify this logic.
Also, an extra recovery byte can be embedded in the signature to narrow down the 2 possible public keys to only one.

---

Note on private keys:

(I'm almost certain this is obvious to everyone, but, just in case it's not)
All private keys should remain private and they should not be shared on github, email, websites, etc..
All the private keys that are not kept private should be considered compromised.

[simibac]

From investigating the libraries that support ES256K it seems that no JS (excluding node JS libraries) library supports this algorithm. Does that mean that we cannot verify tokens serverless, or is there a way to make it work?

[sk91]

There should be some implementations based on web assembly

maybe something like https://github.com/bitauth/libauth

I am sure there are others as well