Skip to content

feat: handle user supplied secret like Go tkeyclient v1.3.0#5

Open
agren wants to merge 2 commits intomainfrom
uss-handling
Open

feat: handle user supplied secret like Go tkeyclient v1.3.0#5
agren wants to merge 2 commits intomainfrom
uss-handling

Conversation

@agren
Copy link
Copy Markdown
Member

@agren agren commented Mar 19, 2026

Description

Using a passphrase and sending that directly, without hashing, uses only the first 32 bytes of the passphrase even if the passphrase is longer. The recommendation to send a hash digest was missing from the documentation of the prototocol. It has now been fixed in the Dev Handbook: "The uss should be the BLAKE2s hash of a passphrase selected by the user."

We would like to get identical key material regardless of using Python or Go. If what is sent as the USS differs, the keys will of course be different even if the same device and app is used.

load_app() is modified to handle the USS in the same way as the Go tkeyclient v1.3.0. Instead of sending the USS phrase directly, it is first ran through the BLAKE2s hash function, and the digest is sent.

This allows the user to get the same CDI when loading a device app using tkeyclient-py as when using tkeyclient (Go).

This is a breaking change and will change the CDI for all device apps if a USS is used. In practice this means that if a USS is used then a tkey-device-signer app loaded with an earlier commit will not have the same signing keys.

Modeled after:
https://github.com/tillitis/tkeyclient/blob/v1.3.0/tkeyclient.go#L389

Type of change

  • Feature (non breaking change which adds functionality)
  • Breaking Change (a change which would cause existing functionality to not work as expected)

Submission checklist

  • My code follows the style guidelines of this project
  • I have performed a self-review of my changes
  • I have tested and verified my changes on target
  • My changes are well written and CI is passing
  • I have squashed my work to relevant commits and rebased on main for linear history
  • I have added a "Co-authored-by: x" if several people contributed, either pair programming or by squashing commits from different authors.
  • I have updated the documentation where relevant (readme, dev.tillitis.se etc.)
  • QEMU is updated to reflect changes

load_app() is modified to handle the USS in the same way as the Go
tkeyclient library v1.3.0. Instead of sending the USS phrase directly,
it is first ran through the BLAKE2s hash function.

Modeled after:
https://github.com/tillitis/tkeyclient/blob/v1.3.0/tkeyclient.go#L389
@agren agren marked this pull request as ready for review March 19, 2026 11:00
@agren agren requested review from kchr and mchack-work March 19, 2026 11:00
@kchr kchr self-assigned this Mar 25, 2026
@kchr
Copy link
Copy Markdown
Collaborator

kchr commented Mar 25, 2026

@agren The implementation looks good, but there is no mention of the actual reason for this change (just what the impact will be). Maybe include that in the description of the PR, and do a small update to the README describing why the change is needed?

@mchack-work
Copy link
Copy Markdown
Member

mchack-work commented Mar 28, 2026

I agree that we need more explanation. As I see it:

  • Using a passphrase and sending that directly, without hashing, uses only the first 32 bytes of the passphrase even if the passphrase is longer. The recommendation to send a hash digest was missing from the documentation of the prototocol. I'm sorry. It has now been fixed in the Dev Handbook: "The uss should be the BLAKE2s hash of a passphrase selected by the user."

  • It would be nice to get identical key material regardless of using Python or Go. If what is sent as the USS differs, the keys will of course be different even if the same device and app is used.

@agren
Copy link
Copy Markdown
Member Author

agren commented Apr 9, 2026

@kchr Yes, I agree. The README should be updated, and the reason can be made clearer.

@mchack-work That's how I see it as well.

@mchack-work
Copy link
Copy Markdown
Member

I edited the PR and added a warning to the README. Let me know what you think.

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.

3 participants