infra: add docs for hardware keys#1074
Open
ubiratansoares wants to merge 2 commits into
Open
Conversation
rustbot
added
the
S-waiting-on-review
ubiratansoares
force-pushed
the
u/hw-keys-docs
branch
from
b6f140a to
33e72f0
Compare
apiraino
reviewed
Jun 24, 2026
apiraino
reviewed
Jun 24, 2026
marcoieni
reviewed
Jun 29, 2026
|
|
||
| ### Hardware security keys in Rust Infrastructure | ||
|
|
||
| Hardware security keys drastically improve security by providing unphishable |
Member
There was a problem hiding this comment.
Suggested change
| Hardware security keys drastically improve security by providing unphishable | |
| Hardware security keys improve security by providing unphishable |
| ### Hardware security keys in Rust Infrastructure | ||
|
|
||
| Hardware security keys drastically improve security by providing unphishable | ||
| protection for sensitive code and infrastructure.The Rust infrastructure team |
Member
There was a problem hiding this comment.
Suggested change
| protection for sensitive code and infrastructure.The Rust infrastructure team | |
| protection for sensitive code and infrastructure. The Rust infrastructure team |
what do you mean with sensitive code?
Comment on lines
+13
to
+15
| to critical infrastructure systems. If you are eligible for such a grant and | ||
| would like to get the recommended YubiKeys for free, get in touch with the | ||
| [T-infra in Zulip]. |
Member
There was a problem hiding this comment.
I would move the "if you are eligible" part after the list below.
| ### Supported models | ||
|
|
||
| The Rust infrastructure team has validated the [Yubico Series 5 USB/NFC models] | ||
| products and will officially support Yubico Series 5 keys for any issues a |
Member
There was a problem hiding this comment.
Suggested change
| products and will officially support Yubico Series 5 keys for any issues a | |
| products and officially supports the Yubico Series 5 keys for any issues a |
| ### Supported firmware versions | ||
|
|
||
| Based on existing [security advisories], only YubiKeys with firmware | ||
| **version v5.7.4** or newer are fully supported. You can use either the `ykman` |
Member
There was a problem hiding this comment.
Suggested change
| **version v5.7.4** or newer are fully supported. You can use either the `ykman` | |
| **version v5.7.4** or newer are allowed. You can use either the `ykman` |
| * Yubico Manager CLI (sources: [yubikey-manager]): for advanced use cases | ||
|
|
||
| As a good first step, the Rust infrastructure team recommends using the Yubico | ||
| Authenticator Desktop app to change the default values for : |
Member
There was a problem hiding this comment.
Suggested change
| Authenticator Desktop app to change the default values for : | |
| Authenticator Desktop app to change the default values for: |
Comment on lines
+58
to
+76
| installations. You can refer to the [ykman online documentation] to learn more | ||
| about subcommands. | ||
|
|
||
| ```shell | ||
| ➜ uvx --from yubikey-manager ykman --help | ||
| Installed 15 packages in 15ms | ||
| Usage: ykman [OPTIONS] COMMAND [ARGS]... | ||
|
|
||
| Configure your YubiKey via the command line. | ||
|
|
||
| Examples: | ||
|
|
||
| List connected YubiKeys, only output serial number: | ||
| $ ykman list --serials | ||
|
|
||
| Show information about YubiKey with serial number 123456: | ||
| $ ykman --device 123456 info | ||
|
|
||
| ``` |
Member
There was a problem hiding this comment.
Suggested change
| installations. You can refer to the [ykman online documentation] to learn more | |
| about subcommands. | |
| ```shell | |
| ➜ uvx --from yubikey-manager ykman --help | |
| Installed 15 packages in 15ms | |
| Usage: ykman [OPTIONS] COMMAND [ARGS]... | |
| Configure your YubiKey via the command line. | |
| Examples: | |
| List connected YubiKeys, only output serial number: | |
| $ ykman list --serials | |
| Show information about YubiKey with serial number 123456: | |
| $ ykman --device 123456 info | |
| ``` | |
| installations: | |
| ```sh | |
| uvx --from yubikey-manager ykman --help |
You can refer to the [ykman online documentation] to learn more
about subcommands.
Imo the stdout of the help menu is not helpful so we could remove it.
|
|
||
| This option provides a way to have working TOTP codes in both a mobile phone | ||
| and a desktop system without relying on third-party cloud systems, but also | ||
| has the con of coupling TOTP code generation with a physical device : similarly |
Member
There was a problem hiding this comment.
Suggested change
| has the con of coupling TOTP code generation with a physical device : similarly | |
| has the con of coupling TOTP code generation with a physical device: similarly |
| losing access to TOTP codes, which requires additional diligence regarding | ||
| backing up recovery codes. | ||
|
|
||
| Note that setting up hardware-backed TOTP codes is totally optional for |
Member
There was a problem hiding this comment.
Suggested change
| Note that setting up hardware-backed TOTP codes is totally optional for | |
| Note that setting up hardware-backed TOTP codes is optional for |
|
|
||
| As an example, this command will define a new resident SSH key through FIDO2 | ||
| and won't prompt your passkey everytime, nor will it require touching the | ||
| hardware key for Git operations. |
Member
There was a problem hiding this comment.
so it only requires the hardware key being connected? Is this what we decided at the all hands?
I think we should suggest touching the hardware key, or at least explain the risk connected to not having to touch the hardware key. Which imo are that if someone has a remote access to your terminal they can run git operations.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
4 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds documentation explaining how to setup hardware keys, and how to use them. We also link the upcoming policy for the sake of reference.
I'll update this doc as soon as the policy lands and we also move with rust-lang/team#2501
r? @marcoieni
Rendered