Implement draft-ietf-httpbis-message-signatures-04

[aljones15]

Latest Spec for Signing HTTP Messages Issue Tracker for Spec

Implementation:

Add

• [x] See related issue on supporting structured fields.
  • Due to issues with structured-headers (see issue above) all examples in this issue use structured-field-values
• Use the new Signature-Input header in api.parseRequest:
  • [x] This is a structured field dictionary
  • [x] it can contain more than one signature
  • [x] each signature entry is a structured field list that contains the covered-content as the sf value
    • parse this: ("sig1=(\"host\")"
    • get this: {sig1: Item {value: [[Item]]}}
  • [ ] each Signature-Input entry covered content list should contain @request-target
  • [ ] each Signature-Input entry should contain an sf param created as a unix time stamp
    • parse this: "sig1=(\"host\" \"host\");created=1"
    • get this: {sig1: Item {value: [[Item], [Item]], params: {created: 1}}}
  • [ ] each Signature-Input entry may contain an sf param keyid
    • This is new keyid is now optional (we can throw at another layer such as zvap-verify or invoke.)
  • [x] Add support for the key sf param in content identifiers
    • parse this: "sig1=(\"foo\";key=a)"
    • get this: [ Item { value: 'foo', params: { key: Symbol(a) } } ]
    • [x] if a value has a param key parse the corresponding header field value as a dictionary
  • [x] throw if a content identifier contains key and the corresponding header field value
    • [x] is not an sf dictionary
    • [x] does not contain the key
  • [x] Add support for the prefix sf param in content identifiers
    • parse this: sig1=(\"foo\";prefix=1)"
    • get this: [ Item { value: 'foo', params: { prefix: 1 } } ]
    • [x] if a value has a param prefix parse the corresponding header field value as a list
  • [x] throw if the content identifier contains prefix and the corresponding header field value
    • [x] is not an sf list
    • [x] if the prefix is out of the lists bounds (larger than the list size)
  • [x] this method returns a Map with each signature key returning a data structure described below:
    • {signingString: 'bar', signature: 'foo', signatureInput: {}}
    • each entry in the Map can be iterated over to verify the entire request
    • Alternatively a key can be used to verify a single signature for a resource
• createSignatureInputHeader
  • [x] this creates a structured field dictionary with keys for each signature
  • [x] this method takes in a Map with a key set to the signature name, and the value is an object
    • [x] the map's value is an object with the properties coveredContent & params
    • [x] params is an object ex: {created: 12354532, expires: 9999999}
    • [x] coveredContent is an array.
      • [x] each item in coveredContent can be a string or {value: 'foo', params: {prefix: 1}}
    • [x] this method returns the fs dictionary serialized as a string
• createSignatureHeader
  • [x] this is an fs dictionary that can contain multiple signatures
  • [x] each entry in the dictionary contains a key with a signature constructed using the covered content from the Sig-Input dictionary with the same key example: sig1 from input constructs sig1 in the Signature header.
  • [x] ensure input string is US-ASCII
  • [x] this method returns the fs dictionary serialized as a string
• _signingString
  • [x] use \\n at the end of each value

Remove

• [ ] Remove list prefixes
• [x] parseSignatureHeader in favor of a structured field parser that assumes the header is an sf dictionary
• [x] extractPseudoHeaders
• [x] api.createAuthzHeader
• [x] Support for Authorization headers
  • [x] Remove options.authorizationHeaderName from api.parseRequest

Change

1. keyid is always lowercase
2. use alg instead of algorithm
3. psuedo headers are not @signature-parameters

Remains

1. lowercase all content identifiers
2. checks for created and expires do not change (unix time stamp integer)
3. support for x-date
4. validateDateRange
5. api.parseRequest

Optional These 2 address a previous issue while solving issues related to where we validate key type via alg:

• [ ] Add signRequest issue: https://github.com/digitalbazaar/http-signature-header/issues/33
• [ ] Add signResponse issue: https://github.com/digitalbazaar/http-signature-header/issues/33
• [ ] Use the alg param to check the key type in the sign functions
• [ ] Add support for all signature algorithms listed in the registry (there are quite a few)
  • This should probably be its own module with rules/validators for each alg

Questions

1. Are we still using hs2019 as the alg?
2. Do psuedo-header now called @signature-params still need to be in (parenthesis)?
   • looks like the answer to this is no, but not sure.
3. I see that @request-target has an @ at the beginning, should I use @created for the created sig param?
   • It looks like the answer to this is no, but not sure.
4. If I define created as a param of a signature input: do I just include it in the signature string?
   • Example: Signature-Input: sig1=("@request-target" "host" "date" "cache-control" \ "x-empty-header" "x-example");created=1618884475;\ keyid="test-key-rsa-pss"
   • created is not in the covered content list, but is defined as a sf parameter of sig1
   • it looks like you do include created in the signing string here, but not sure.
   • it looks like created is included in the @signature-params part of the signing string creation
     • turn the signature input entry into a string again and use it for @signature-params
5. What happens if I have multiple signatures in Signature-Input & one of them throws before verification?
   • Do I return the request with say 2/3 signatures filled?
6. What happens if I have multiple signatures in Signature & only one of them fails verification?

Tests

1. add tests for all @request-target examples from the spec
2. Change all tests to use Signature-Input & Signature headers over Authorization header
3. Change all tests to loop over two situations:
   1. single signature
   2. multiple signatures (we'll say 3)
4. Add tests for structured field value issues
   • should throw if prefix is out of bounds
   • should throw if key is not found
   • should throw if not an sf list
   • should throw if not an sf dictionary

[msporny]

Are we still using hs2019 as the alg?

No, but we need one for ed25519... let's create one called ed25519-2021 -- we'll have to lobby to get this added to the official specification.

What happens if I have multiple signatures in Signature-Input & one of them throws before verification?

By default, if one signature fails, the call to verify should fail. We may want to provide an option where you get back a list of all signatures that succeeded/failed.

Do I return the request with say 2/3 signatures filled?

Always design security systems to fail closed by default. So, by default, you say the signature verification for what was passed in failed. If we provide details in the error code/response, we should state which signatures failed and for what reason like: "unknown signature suite", "unknown keyid", "could not dereference keyid", etc.

What happens if I have multiple signatures in Signature & only one of them fails verification?

Fail closed. If one signature fails, the verification function should return false.

[gausnes]

No, but we need one for ed25519... let's create one called ed25519-2021 -- we'll have to lobby to get this added to the official specification.

It looks like ed25519 was added to the latest version of the draft as an official enumeration.

By default, if one signature fails, the call to verify should fail. We may want to provide an option where you get back a list of all signatures that succeeded/failed.

I don't think this captures the specification intention of multiple signature support. I think that the invoker should specify the signature identifier they are wishing to inspect. If you inspect the example in the latest draft, you can see the proxy need to override the authority. This would cause the proxied request to no longer have the context to validate sig1.