Repository navigation
Description
Summary
Add support for accepting a pre-computed clientDataHash (SHA-256) as an alternative to clientDataJSON in the D-Bus API. This aligns with Android and iOS platform APIs, and enables a wider range of WebAuthn integration scenarios.
Background
The CTAP2 specification defines that authenticator operations (authenticatorMakeCredential and authenticatorGetAssertion) accept a hash of the client data, not the raw JSON:
hash (0x01): Hash of the serialized client data, provided by the client.
Reference: FIDO CTAP2 Specification §6.1
While browser-based WebAuthn flows typically construct clientDataJSON locally, there are several scenarios where the caller may already have the hash:
- Cross-device authentication (CTAP2 Hybrid/caBLE) - The initiating device may provide the hash directly
- Native application integrations - Apps may negotiate client data with their backend
- Remote desktop/VDI scenarios - The remote server constructs clientData and transmits only the hash
- Proxy/relay architectures - Intermediate systems may only forward the hash
Prior Art - Platform API Parity
Both Android and iOS platform APIs support this pattern:
Android (Credential Manager API)
val request = GetPublicKeyCredentialOption(
requestJson = "...",
clientDataHash = clientDataHashBytes // Optional pre-computed hash
)Reference: Android Credential Manager Documentation
iOS (ASAuthorizationPublicKeyCredentialProvider)
let request = provider.createCredentialAssertionRequest(challenge: challenge)
request.clientDataHash = clientDataHash // Supports pre-computed hashReference: Apple Developer Documentation
Adding this support to credentialsd would bring Linux to feature parity with these platforms.
Proposed API Change
Add an optional client_data_hash parameter to the D-Bus methods:
Option A: New optional parameter (backward compatible)
<method name="MakeCredential">
<arg name="request_json" type="s" direction="in"/>
<arg name="client_data_hash" type="ay" direction="in"/> <!-- NEW: optional 32-byte SHA-256 -->
<arg name="response" type="a{sv}" direction="out"/>
</method>Behavior:
- If
client_data_hashis provided (non-empty), use it directly - If
client_data_hashis empty, compute hash fromrequest_json.clientDataJSON(current behavior)
Option B: Separate methods
<method name="MakeCredentialWithHash">
<arg name="request_json" type="s" direction="in"/>
<arg name="client_data_hash" type="ay" direction="in"/>
<arg name="response" type="a{sv}" direction="out"/>
</method>Use Case
This feature enables various integration scenarios where the caller has a pre-computed hash rather than raw JSON:
- Cross-device flows where another device initiated the WebAuthn ceremony
- Native applications with custom client data handling
- Remote desktop environments where authentication is redirected to the local machine
- Enterprise SSO integrations with proxy architectures
The key benefit is flexibility - allowing callers to provide either the raw JSON (current behavior) or a pre-computed hash when that's what they have available.
Security Considerations
This change maintains the same security model:
- The authenticator still requires user interaction (touch/PIN)
- The UI still displays the relying party information
- The cryptographic signature is still bound to the hash
The only difference is who computes the hash - the caller vs the credential service.
Implementation Notes
Looking at libwebauthn, the underlying register() and sign() functions may already work with the hash internally. The change would primarily be in:
- D-Bus interface definition (
xyz.iinuwa.credentials.xml) - Request parsing in
credentialsd - Passing the hash through to libwebauthn
Related
- W3C WebAuthn Level 3 §5.8.1 - client data hash computation
- FIDO CTAP2 Specification - authenticator protocol
- Android and iOS platform APIs (referenced above)
Questions
- Would you prefer Option A (optional parameter) or Option B (new method)?
- Are there any security considerations I might have missed?
- Is this something you're planning to implement, or would you be open to accepting a community contribution? I'd be happy to work on a PR if that would be helpful.
Thank you for considering this feature request!
Activity
iinuwa commentedon Feb 5, 2026
Hello! Thanks for submitting this.
This change would push this API toward being a CTAP2 authenticator rather than a WebAuthn API. WebAuthn is more constrained than CTAP2. I agree that accepting clientDataHash would be more flexible, but I'm not sure that flexibility is desired.
Some considerations:
For the use cases you describe:
By this do you mean that the Linux client is acting as an authenticator for another device? I.e., not acting as a client accessing another remote authenticator over FIDO2 hybrid?
With the current scheme, native applications should have their origin specified as their app ID. any custom data can be shared with the backend directly from the user session via some bespoke means; I don't think putting this in CTAP2 client data helps much.
An extension is being defined in WebAuthn to allow for this specific situation (remote desktop support). I haven't checked how far along this is.
This seems interesting to me, but I'm not sure I follow this part; could you explain some more?
I think my first stance is that this would ultimately hurt users more than it may help developers, so I think I would do without it. I am interested in what you think about the above though. I'll leave this open for a while for discussion.
Zhao-code-ai commentedon Feb 5, 2026
Thanks for the clarification question.
No, I mean the opposite: the Linux machine acts as a client that needs to access local authenticators (USB security keys, phones via FIDO2 hybrid, etc.) to complete a WebAuthn ceremony that was initiated elsewhere.
But I understand your concerns about the API design. Thanks for the discussion!
AlfioEmanueleFresta commentedon Jul 7, 2026
I'd be tempted to frame this as a future extension of the entitlements work in #184: an entitlement that lets a trusted caller not only assert an arbitrary origin but also proxy an arbitrary clientDataHash. It should be gated tightly because a pre-computed hash is opaque to us: we can't reverse the hash to show the user what they're signing as per @iinuwa's comment above. That makes it a trusted-caller capability, rather than something most apps should be able to do.
The only case that may genuinely needs raw-hash proxying seems to be remote desktop, where clientData was constructed on a remote host and the local machine only ever sees the hash. I don't think it's a launch requirement.
However, this is only really needed if the remote flow is proxied to our host as an authenticator (like a virtual-authenticator driver on the remote machine), which receives the hash after clientData was already built remotely.
If the remote-desktop integration instead plugs in at a higher, WebAuthn-API level, it can hand us the full request (remote origin included) and we'd only need the arbitrary-origin entitlement (no raw hash).
From a quick look, that higher-level model is what at least Windows seems to do: Windows redirects WebAuthn over RDP at the API layer via a WebAuthn.dll virtual-channel plugin (the request is marshalled to the local WebAuthn stack).
As for Linux, I would argue credentialsd is uniquely placed to solve this issue (this warrants its own dedicated issue.)