Skip to content

Feature Request: Support pre-computed clientDataHash (parity with Android/iOS APIs) #124

Open

Description

@Zhao-code-ai

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:

  1. Cross-device authentication (CTAP2 Hybrid/caBLE) - The initiating device may provide the hash directly
  2. Native application integrations - Apps may negotiate client data with their backend
  3. Remote desktop/VDI scenarios - The remote server constructs clientData and transmits only the hash
  4. 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 hash

Reference: 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_hash is provided (non-empty), use it directly
  • If client_data_hash is empty, compute hash from request_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:

  1. D-Bus interface definition (xyz.iinuwa.credentials.xml)
  2. Request parsing in credentialsd
  3. Passing the hash through to libwebauthn

Related

Questions

  1. Would you prefer Option A (optional parameter) or Option B (new method)?
  2. Are there any security considerations I might have missed?
  3. 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

  1. iinuwa commented on Feb 5, 2026

    @iinuwa
    Member

    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:

    • return type: If we accepted clientDataHash, we could sign it, but we couldn't return clientDataJSON in the response. I haven't thought about this much, but I think this would have to make this an entirely separate method.
    • origin display: If we don't required the origin to be passed along with the clientDataHash, we would not have an origin to display to the user on prompt. If we do require the origin to be passed, the origin may not be contained in the data that produced the hash, which can lead to a mismatch in what the user thinks they're signing and what the RP receives.
    • privacy leak: A client could pass arbitrary client data, which may leak privacy data without non-repudiation (since their authenticator signed it.)

    For the use cases you describe:

    Cross-device flows where another device initiated the WebAuthn ceremony

    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?

    Native applications with custom client data handling

    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.

    Remote desktop environments where authentication is redirected to the local machine

    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.

    Enterprise SSO integrations with proxy architectures

    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.

  2. Zhao-code-ai commented on Feb 5, 2026

    @Zhao-code-ai
    Author

    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!

  3. AlfioEmanueleFresta commented on Jul 7, 2026

    @AlfioEmanueleFresta
    Member

    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.)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions