JWS: Support for critical custom headers (other than "b64")?

[rjbma]

First of all, congrats for this great library!

I was trying to set some custom protected headers and add them to the crit header, like so:

const encoder = new TextEncoder()
const privateKey = await parseJwk({
          alg: 'ES256',
          crv: 'P-256',
          kty: 'EC',
          d: 'VhsfgSRKcvHCGpLyygMbO_YpXc7bVKwi12KQTE4yOR4',
          x: 'ySK38C1jBdLwDsNWKzzBHqKYEE5Cgv-qjWvorUXk9fw',
          y: '_LeQBw07cf5t57Iavn4j-BqJsAD1dpoz8gokd3sBsOo'
})

const jws = await new FlattenedSign(encoder.encode('It’s a dangerous business, Frodo, going out your door.'))
  .setProtectedHeader({
          alg: 'ES256',
          cust1: 'some_value',
          crit: ['cust1']
  })
  .sign(privateKey)

However, this fails with the following error:

JOSENotSupported: Extension Header Parameter "cust1" is not supported by this implementation

Looking at the code, seems that only b64 is supported.
Is that the case, or am I missing how this can be done?

Thanks!

[panva]

Hi @rjbma and thank you for the kind words.

This implementation does not allow for proprietary (IANA unregistered) critical parameters. "crit" members are typically only required and registered when these alter how the JWS/JWE payloads get processed, e.g. b64 fundamentally changes how the issuer and recipient prepare the payload before sign/verify operations. For all other use-cases, "crit" is unnecessary as it does not change the input/output of sign/verify and you may simply check for the header's presence in your own code.

You do not need a protectedHeader member to be present in "crit" for it to be protected.

[rjbma]

Hi @panva, thanks for the quick response!

That makes a lot of sense. Unfortunately, the spec I'm working with mandates that these proprietary parameters be crit members.

Quick question: I noticed that jose@2 allows for this situation (verifying only that the params are present in the header, of course). Do you think this is something that jose@3 will also support eventually, or is it something that you see as completely out of scope?

[panva]

Do you think this is something that jose@3 will also support eventually, or is it something that you see as completely out of scope?

I am undecided, as I'm not convinced there's any valid use for this. Please link the spec, that's a good start.

[rjbma]

Sure: https://openbankinguk.github.io/read-write-api-site3/v3.1.6/profiles/read-write-data-api-profile.html#step-2-form-the-jose-header

[panva]

sigh, i'll have to think about this. OB is technically not an extension of JWA/JWS specifications so i'd argue its use of "crit" is not 100% warranted.

The "crit" (critical) Header Parameter indicates that extensions to
this specification and/or [JWA] are being used that MUST be
understood and processed. Its value is an array listing the Header
Parameter names present in the JOSE Header that use those extensions.

I'll think about it some more and gather more resources.

[rjbma]

Completely understandable.
Thanks for taking the time to think this through!

[panva]

v3.3.1 is safe to use with a new crit option for all sign/verify/encrypt/decrypt option which lets you ack a proprietary/private crit header.

An object with keys representing recognized "crit" (Critical) Header Parameter
names. The value for those is either true or false. true when the
Header Parameter MUST be integrity protected, false when it's irrelevant.

This makes the "Extension Header Parameter "${parameter}" is not recognized"
error go away.

Use this when a given JWS/JWT/JWE profile requires the use of proprietary
non-registered "crit" (Critical) Header Parameters. This will only make sure
the Header Parameter is syntactically correct when provided and that it is
optionally integrity protected. It will not process the Header Parameter in
any way or reject if the operation if it is missing. You MUST still
verify the Header Parameter was present and process it according to the
profile's validation steps after the operation succeeds.

The JWS extension Header Parameter b64 is always recognized and processed
properly. No other registered Header Parameters that need this kind of
default built-in treatment are currently available.