From 5c8fbfe25676bcf006db07d9c7c126a2fe14bebf Mon Sep 17 00:00:00 2001 From: Ubiratan Soares Date: Tue, 28 Jul 2026 20:17:18 +0200 Subject: [PATCH 1/3] infra: document instructions for yubikeys and piv --- src/infra/docs/hardware-security-keys.md | 116 +++++++++++++++++++++-- 1 file changed, 108 insertions(+), 8 deletions(-) diff --git a/src/infra/docs/hardware-security-keys.md b/src/infra/docs/hardware-security-keys.md index 4d8ea4f35..10fbe030f 100644 --- a/src/infra/docs/hardware-security-keys.md +++ b/src/infra/docs/hardware-security-keys.md @@ -62,6 +62,13 @@ about subcommands. uvx --from yubikey-manager ykman --help ``` +or alternatively + +```shell +alias ykman="uvx --from yubikey-manager ykman" +ykman --help +``` + ### Multifactor authentication with webauthn Yubico implements the [FIDO2 standard] in all its products, and therefore, @@ -136,7 +143,7 @@ SSH keys are available in your YubiKey either with CLI or Yubico Authenticator app. ```shell -$ uvx --from yubikey-manager ykman fido credentials list +$ ykman fido credentials list Enter your PIN: Credential ID RP ID Username Display name 86707903... ssh:git openssh openssh @@ -144,14 +151,104 @@ Credential ID RP ID Username Display name ![yubikeys ssh setup](img/yubikey-sshkey.jpg) -### PIV and attestations +### PIV-backed keys and attestations YubiKeys are compatible with [Personal Identity Verification (PIV)] for smart cards, which allows using them for encryption and signing operations on top -of this particular standard. +of this particular standard. Project members operating critical infrastructure +or driving releases should mind the following instructions to setup PIV-backed +keys. + +#### Conventions and requirements + +To leverage PIV capabilities, **it's mandatory to change** the PIN and PUK +default values. You can do that using either `ykman` or the Yubico +Authenticator app. + +```shell +ykman piv access change-pin +ykman piv access change-puk +``` + +Although it is possible to create and manage PIV keys using the Yubico +Authenticator, you must use `ykman` to have access to security options +not available through the desktop application. + +#### Generating PIV-backed keys + +When creating PIV-backed keys with your YubiKey, you must note the following +security requirements: + +* `ECCP256` should be favored as the encryption algorithm +* PIN confirmation must be required at least `once` when accessing a PIV slot +* human interaction against the YubiKey (touching it) is always required + +To generate a key and store it into the slot `9a` (authentication use cases) +with recommended security defaults, run: + +```shell +ykman piv keys generate 9a - --algorithm ECCP256 --pin-policy once --touch-policy always +``` + +Similarly, to generate a key and store it into the slot `9c` +(signing use cases): + +```shell +ykman piv keys generate 9c - --algorithm ECCP256 --pin-policy once --touch-policy always +``` + +#### Exporting public keys and certificates from PIV slots + +After generating keys, you can export the public keys related to the PIV +slots and store them externally: + +```shell +ykman piv keys export 9a pubkey-9a.pem +ykman piv keys export 9c pubkey-9c.pem +``` + +These public keys are also required to generate self-signed `X.509` +certificates and to have them physically stored in the same PIV slots. +For example, to generate and store such a certificate for the `9a` PIV slot +already storing a key: + +```shell +ykman piv certificates generate 9a pubkey-9a.pem --subject "CN=" --valid-days 2000 +``` + +Note that: + +* `subject` should be a [RFC-4514 string] +* `valid-days` directly impacts certificate rotation (default is 365 days) + +#### Exporting attestations and sharing them through team DB + +In addition to self-signed certificates, you can also generate an +[attestation certificate] for a PIV-backed key pair. + +```shell +ykman piv keys attest 9a attestation-9a.pem +ykman piv keys attest 9c attestation-9c.pem +``` + +To allow verification for these attestations, you must also export Yubico's +intermediate attestation certificate pre-loaded in the YubiKey and signed +with Yubico's root attestation CA: + +```shell +ykman piv certificates export f9 f9-intermediate.pem +``` + +We expect these files to be shared for further verification through the +[Project members DB]. To bring these files to `team`, you must: + +* create a new folder under `team/hardware-keys` +* add to it any `attestation-9*.pem` files related to the PIV slots you set up +* add to it the `f9-intermediate.pem` attestation file for your YubiKey +* link these files with your member information under `team/people/.toml` -Some capabilities backed by PIV will be introduced later in the Rust Project. -For now, you may want to [watch this issue] to follow-up on this topic. +Preferably, name each folder you create at `team/hardware-keys` after your YubiKey +serial number. Check the [TOML schema] for additional details. ## FAQ @@ -170,8 +267,8 @@ sessions when setting up your CLI configuration. This flow will prompt your 2FA method when signing with your web browser of choice. The Rust infrastructure provides SSO access to Project members through our -[AWS Identity Center configuration]. You still need to configure your YubiKey as your -[MFA method of choice in your AWS user account], though. +[AWS Identity Center configuration]. You still need to configure your YubiKey as +your [MFA method of choice in your AWS user account], though. [Yubico Secure it Forward]: https://www.yubico.com/why-yubico/secure-it-forward [T-infra in Zulip]: https://rust-lang.zulipchat.com/#narrow/channel/242791-t-infra @@ -194,9 +291,12 @@ The Rust infrastructure provides SSO access to Project members through our [options for hardware-backed SSH key pairs]: https://developers.yubico.com/SSH [OpenSSH built-in support for FIDO2 authentication]: https://developers.yubico.com/SSH/Securing_SSH_with_FIDO2.html [Personal Identity Verification (PIV)]: https://developers.yubico.com/PIV -[watch this issue]: https://github.com/rust-lang/team/issues/2501 [web-based authentication flow]: https://docs.cloud.google.com/sdk/docs/authenticate#humans [MFA method in your Google account]: https://support.google.com/accounts/answer/6103523?hl=en&co=GENIE.Platform%3DDesktop [AWS SSO user sessions]: https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-sso.html [AWS Identity Center configuration]: https://forge.rust-lang.org/infra/docs/aws-access.html [MFA method of choice in your AWS user account]: https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_mfa.html +[Project members DB]: https://github.com/rust-lang/team +[RFC-4514 string]: https://www.rfc-editor.org/info/rfc4514/#section-4 +[attestation certificate]: https://developers.yubico.com/PIV/Introduction/PIV_attestation.html +[TOML schema]: https://github.com/rust-lang/team/blob/main/docs/toml-schema.md#people From 14694c1011ca13e6b29d063ab005a149caf79f06 Mon Sep 17 00:00:00 2001 From: Ubiratan Soares Date: Wed, 29 Jul 2026 18:36:29 +0200 Subject: [PATCH 2/3] infra: clarify piv adoption for project members --- src/infra/docs/hardware-security-keys.md | 47 ++++++++++-------------- 1 file changed, 20 insertions(+), 27 deletions(-) diff --git a/src/infra/docs/hardware-security-keys.md b/src/infra/docs/hardware-security-keys.md index 10fbe030f..38f24c70f 100644 --- a/src/infra/docs/hardware-security-keys.md +++ b/src/infra/docs/hardware-security-keys.md @@ -155,33 +155,28 @@ Credential ID RP ID Username Display name YubiKeys are compatible with [Personal Identity Verification (PIV)] for smart cards, which allows using them for encryption and signing operations on top -of this particular standard. Project members operating critical infrastructure -or driving releases should mind the following instructions to setup PIV-backed -keys. +of this particular standard. #### Conventions and requirements -To leverage PIV capabilities, **it's mandatory to change** the PIN and PUK -default values. You can do that using either `ykman` or the Yubico -Authenticator app. +Before using PIV, **you must change** the default PIN and PUK. Use `ykman` or +the Yubico Authenticator app. With `ykman`, run: ```shell ykman piv access change-pin ykman piv access change-puk ``` -Although it is possible to create and manage PIV keys using the Yubico -Authenticator, you must use `ykman` to have access to security options -not available through the desktop application. +Yubico Authenticator can create and manage PIV keys, but some security +options are available only in `ykman`. #### Generating PIV-backed keys -When creating PIV-backed keys with your YubiKey, you must note the following -security requirements: +When creating PIV-backed keys, follow these -* `ECCP256` should be favored as the encryption algorithm -* PIN confirmation must be required at least `once` when accessing a PIV slot -* human interaction against the YubiKey (touching it) is always required +* Prefer the `ECCP256` encryption algorithm. +* Require PIN confirmation at least `once` when accessing a PIV slot. +* Require human interaction against the YubiKey (touching it). To generate a key and store it into the slot `9a` (authentication use cases) with recommended security defaults, run: @@ -209,8 +204,7 @@ ykman piv keys export 9c pubkey-9c.pem These public keys are also required to generate self-signed `X.509` certificates and to have them physically stored in the same PIV slots. -For example, to generate and store such a certificate for the `9a` PIV slot -already storing a key: +For example, to generate and store such a certificate for the `9a` PIV, run: ```shell ykman piv certificates generate 9a pubkey-9a.pem --subject "CN=" --valid-days 2000 @@ -218,8 +212,8 @@ ykman piv certificates generate 9a pubkey-9a.pem --subject "CN=" --va Note that: -* `subject` should be a [RFC-4514 string] -* `valid-days` directly impacts certificate rotation (default is 365 days) +* `subject` should be an [RFC-4514 string] +* `valid-days` sets the certificate lifetime (default is 365 days) #### Exporting attestations and sharing them through team DB @@ -239,16 +233,14 @@ with Yubico's root attestation CA: ykman piv certificates export f9 f9-intermediate.pem ``` -We expect these files to be shared for further verification through the -[Project members DB]. To bring these files to `team`, you must: +Add these files to the [team DB]: -* create a new folder under `team/hardware-keys` -* add to it any `attestation-9*.pem` files related to the PIV slots you set up -* add to it the `f9-intermediate.pem` attestation file for your YubiKey -* link these files with your member information under `team/people/.toml` +* Create a directory under [team/hardware-keys] named after your YubiKey's serial number. +* Add the `attestation-9*.pem` files for the PIV slots you configured. +* Add the YubiKey's `f9-intermediate.pem` attestation file. +* Link to these files from `team/people/.toml`. -Preferably, name each folder you create at `team/hardware-keys` after your YubiKey -serial number. Check the [TOML schema] for additional details. +See the [TOML schema] for details. ## FAQ @@ -296,7 +288,8 @@ your [MFA method of choice in your AWS user account], though. [AWS SSO user sessions]: https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-sso.html [AWS Identity Center configuration]: https://forge.rust-lang.org/infra/docs/aws-access.html [MFA method of choice in your AWS user account]: https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_mfa.html -[Project members DB]: https://github.com/rust-lang/team +[team DB]: https://github.com/rust-lang/team +[team/hardware-keys]: https://github.com/rust-lang/team/tree/main/hardware-keys [RFC-4514 string]: https://www.rfc-editor.org/info/rfc4514/#section-4 [attestation certificate]: https://developers.yubico.com/PIV/Introduction/PIV_attestation.html [TOML schema]: https://github.com/rust-lang/team/blob/main/docs/toml-schema.md#people From 6e73f4fd7196abd4249f9e5eb5ccf8115eb04146 Mon Sep 17 00:00:00 2001 From: Ubiratan Soares Date: Fri, 31 Jul 2026 15:55:46 +0200 Subject: [PATCH 3/3] infra: remove impl detail on piv certificates --- src/infra/docs/hardware-security-keys.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/infra/docs/hardware-security-keys.md b/src/infra/docs/hardware-security-keys.md index 38f24c70f..e56148e0b 100644 --- a/src/infra/docs/hardware-security-keys.md +++ b/src/infra/docs/hardware-security-keys.md @@ -172,7 +172,7 @@ options are available only in `ykman`. #### Generating PIV-backed keys -When creating PIV-backed keys, follow these +When creating PIV-backed keys, follow these security requirements: * Prefer the `ECCP256` encryption algorithm. * Require PIN confirmation at least `once` when accessing a PIV slot. @@ -203,8 +203,8 @@ ykman piv keys export 9c pubkey-9c.pem ``` These public keys are also required to generate self-signed `X.509` -certificates and to have them physically stored in the same PIV slots. -For example, to generate and store such a certificate for the `9a` PIV, run: +certificates. For example, to generate a certificate associated with +the `9a` PIV slot, run: ```shell ykman piv certificates generate 9a pubkey-9a.pem --subject "CN=" --valid-days 2000 @@ -233,7 +233,7 @@ with Yubico's root attestation CA: ykman piv certificates export f9 f9-intermediate.pem ``` -Add these files to the [team DB]: +To add these files to the [team DB], follow the following steps: * Create a directory under [team/hardware-keys] named after your YubiKey's serial number. * Add the `attestation-9*.pem` files for the PIV slots you configured.