Skip to content

verify: Add method that accepts unhashed message as arg#144

Merged
DarkaMaul merged 5 commits intotrailofbits:mainfrom
jku:handle-hashing-in-verify
May 14, 2025
Merged

verify: Add method that accepts unhashed message as arg#144
DarkaMaul merged 5 commits intotrailofbits:mainfrom
jku:handle-hashing-in-verify

Conversation

@jku
Copy link
Contributor

@jku jku commented May 9, 2025

Fixes #130, provides a new verification method with (unhashed) message as argument.

This way handling timestamp_response.tst_info.message_imprint.hash_algorithm is not the callers problem anymore.

The implementation could have been squeezed into verify() but then the method signature would be more complex: I think separate methods may be cleaner.

I orignally planned to add the modern ones from
https://www.iana.org/assignments/hash-function-text-names/hash-function-text-names.xhtml but testing difficulties lead me to only handling SHA-{256,384,512}: adding more is easy as long as we have a TSA to create the test material with.

CC @ramonpetgrave64 : I think this will work for you in sigstore-python?

This way handling timestamp_response.tst_info.message_imprint.hash_algorithm
is not the callers problem.

The implementation could have been squeezed into verify() but then the
method signature would be more complex: I think separate methods may be
cleaner.

Support the six last algorithms in
https://www.iana.org/assignments/hash-function-text-names/hash-function-text-names.xhtml
@CLAassistant
Copy link

CLAassistant commented May 9, 2025

CLA assistant check
All committers have signed the CLA.

@jku
Copy link
Contributor Author

jku commented May 9, 2025

we ask that you sign our Contributor License Agreement

ah, well I guess I'll start the process on that then :(

@jku
Copy link
Contributor Author

jku commented May 9, 2025

I guess it's worth pointing out that the request code only supports SHA256 and SHA512, and I think that's fine. I can use only those two here if that's preferred (I just think verify can support more algorithms for increased compatibility with timestamps coming from other implementations). The main issue with supporting more algorithms in verify is that creating test data is a bit more work.

EDIT: and after looking into it, I think the testing aspect is annoying enough that I'll stick to SHA256 and SHA512 and maybe SHA384 that I can easily generate test data for

* Add tests and assets for sha{256,384,512}
* Remove support for SHAKE and SHA224 as it turned out finding a
  TSA that supports those was difficult

The test implementation is not ideal as the new assets use a different
TSA (timestamp.sigstage.dev supports SHA-384) so we need more
certificates etc... On the other hand testing with multiple timestamp
sources seems also good.
@jku
Copy link
Contributor Author

jku commented May 9, 2025

  • I've added a new method instead of making the existing method more complicated: let me know if you have opinions
  • The test implementation is not ideal as the new assets use a different TSA (timestamp.sigstage.dev supports SHA-384) so we need more certificates etc... On the other hand testing with multiple timestamp sources seems also good 🤷

* Remove unneeded mention of checking algorithm
* Point to correct cert chain path in test/fixtures/sigstage/README.md
@jku jku force-pushed the handle-hashing-in-verify branch from e5b1f5f to 76d01e3 Compare May 9, 2025 14:00
verifier = VerifierBuilder().add_root_certificate(certificate).build()
try:
verifier.verify(timestamp_response, message_hash)
verifier.verify_message(timestamp_response, message)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Keep the original example that accepts a pre-hashed message, in case folks are using other hash algorithms that this library doesn't directly support.

Copy link
Contributor Author

@jku jku May 9, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I feel like an example in the README should just show the intended golden path (which I think the new method is)... Of course it would be nice to have API docs so the options were visible there.

@jku jku marked this pull request as ready for review May 13, 2025 11:21
@jku
Copy link
Contributor Author

jku commented May 13, 2025

✔️ CLA sorted

@DarkaMaul
Copy link
Collaborator

Hi - thanks a lot for the PR here.

Just a few comments before I review this:

  • I think having a new method verify_message along with verify is better than other options (like having a more complicated signature on the verify functions).
  • I also agree that having the simpler method (verify_message) in the main README is a better option. There should be only one recommended way accessible in the initial documentation.
  • I like testing with multiple TSAs. Maybe we could slightly refactor our tests here and move existing certificates to fixtures/timestamp-authority, so they are all at the same level (per TSA).

* add comment on OIDs
* more accurate certificate handling in tests
* refactor the the response loading fixture in tests
@jku jku force-pushed the handle-hashing-in-verify branch from 4931eb5 to 265b807 Compare May 14, 2025 08:13
@jku
Copy link
Contributor Author

jku commented May 14, 2025

Fixed a lint issue in last commit

@jku
Copy link
Contributor Author

jku commented May 14, 2025

Maybe we could slightly refactor our tests here and move existing certificates to fixtures/timestamp-authority, so they are all at the same level (per TSA).

This feels like a good idea.

  • As a start, could have a single positive test that verifies each response in test/fixtures/tsas/*/*.tsr using the cert chain in the same directory
  • In current test suite there are only two verifying timestamps though so immediate benefit would be fairly small:
    • 1 timestamp from timestamp.identrust.com (regressions/issue-104.tsr)
    • 1 timestamp from unknown test TSA (response.tsr)
    • this PR adds 3 more timestamps from timestamp.sigstage.dev

I would suggest this refactor is not part of this PR but I can add it here if you'd like.

@DarkaMaul
Copy link
Collaborator

I would suggest this refactor is not part of this PR but I can add it here if you'd like.

Let's open another PR for this, it doesn't really belong here.

I added a CHANGELOG entry and will merge this once the CI has finished. Thanks again for the work here!

@DarkaMaul DarkaMaul merged commit 10dd28e into trailofbits:main May 14, 2025
36 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Inconsistent API when building Request and Verifying Response

4 participants