SSH agent: per-key destination filtering using OpenSSH session binding

[V1rg1lee]

Select Topic Area

✅ Code Contribution Proposal

Code Contribution Proposal

Background

The Bitwarden SSH agent currently exposes all eligible SSH identities to the SSH client.

This can cause connections to fail on servers with a low MaxAuthTries value when the correct key is reached too late. This is the problem described in:

• ssh-agent - 'Too many authentication failures' #13401
• https://community.bitwarden.com/t/ssh-agent-allow-specifying-limiting-private-key-offers/79954

I ran into the same issue with a vault containing several SSH keys. In my test case, the agent returned 6 identities and the server disconnected with Too many authentication failures before OpenSSH reached the correct key.

Proposed UX

Add an optional SSH agent destinations section to SSH key items in the Desktop client.

A user can associate an SSH key with one or more SHA256 SSH host-key fingerprints:

SHA256:...

Leaving the list empty keeps the current behavior for that key: it remains available for any destination.

The setting is Desktop-local and is not added to the synchronized cipher data.

Configured destination

The field accepts multiple destination fingerprints and validates non-empty values as SHA256 host-key fingerprints.

Validation error

Agent behavior

The SSH agent protocol's normal REQUEST_IDENTITIES message does not include a hostname or IP address, so this proposal does not attempt to infer one.

OpenSSH does, however, support the session-bind@openssh.com extension. Bitwarden's SSH Agent v2 already verifies this session binding and has access to the destination host-key fingerprint.

When a verified destination fingerprint is available, identities are returned in this order:

1. keys explicitly configured for that destination;
2. unrestricted keys (no destinations configured).

Keys that are restricted to other destinations are omitted.

Ordering is stable within each group.

If no verified session binding is available, all keys are returned as before. This preserves compatibility with SSH clients that do not provide destination information.

This is intended as an identity-selection/ordering optimization, not as an authorization or security boundary.

Why prioritize instead of only filtering

A user should not have to configure every SSH key before seeing a benefit.

For example, if a vault contains six unrestricted keys and the user associates only the correct key with a server, that explicit match is returned before the other unrestricted Bitwarden identities.

Unrestricted keys are still available afterwards, so configuring a destination for one key does not make unrelated unrestricted keys unusable for the same host.

Testing

I tested the change against a real OpenSSH server on Windows.

Before configuring a destination:

• Bitwarden returned 6 agent identities.
• The required key was reached too late.
• The server disconnected with Too many authentication failures.

With the destination configured on the correct key:

• OpenSSH successfully bound the agent connection to the server host key.
• The destination-matched Bitwarden key was returned before unrestricted identities.
• The server accepted the correct RSA key and public-key authentication succeeded.

I also tested the stricter case where unrelated keys are configured for different destinations; in that case only the matching key is returned.

The implementation includes Rust unit/integration coverage for filtering, prioritization, stable ordering and the no-session-bind fallback, as well as Desktop/UI tests for local persistence, Save/Cancel behavior and validation.

Scope

The proposed change is intentionally limited to Desktop SSH Agent v2:

• no hostname/IP matching;
• no DNS lookup or ssh-keyscan;
• no automatic trust of host keys;
• no synchronized cipher schema changes;
• no server changes;
• no changes to signing authorization behavior.

I'd appreciate feedback on the UX and on using verified host-key fingerprints as the destination identifier.

[github-actions[bot]]

✨ Thank you for your code contribution proposal! While the Bitwarden team reviews your submission, we encourage you to check out our contribution guidelines.

Please ensure that your code contribution includes a detailed description of what you would like to contribute, along with any relevant screenshots and links to existing feature requests. This information helps us gather feedback from the community and Bitwarden team members before you start writing code.

To keep discussions focused, posts that do not include a proposal for a code contribution will be removed.

• 💡 For feature requests and general discussion, please visit the Bitwarden Community Forums.
• ℹ️ For questions and support, visit the Bitwarden Help Center.
• 🐛 To report a potential bug, please visit the corresponding repo. Server | Clients | iOS | Android

Thank you for contributing to Bitwarden!