diff --git a/src/SUMMARY.md b/src/SUMMARY.md index ca8815dc2..9a704cc7b 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -112,6 +112,7 @@ - [Domain names and DNS](./infra/docs/dns.md) - [docs.rs](./infra/docs/docs-rs.md) - [ECS services management](./infra/docs/ecs-services.md) + - [Hardware Security Keys](./infra/docs/hardware-security-keys.md) - [Monitoring](./infra/docs/monitoring.md) - [Renovate](./infra/docs/renovate.md) - [rust-bots server](./infra/docs/rust-bots.md) diff --git a/src/infra/docs/hardware-security-keys.md b/src/infra/docs/hardware-security-keys.md new file mode 100644 index 000000000..e4d5d89ad --- /dev/null +++ b/src/infra/docs/hardware-security-keys.md @@ -0,0 +1,202 @@ +# Hardware Security Keys in the Rust Project + +## Overview + +### Hardware security keys in Rust Infrastructure + +Hardware security keys improve security by providing unphishable +protection for sensitive systems and infrastructure. The Rust infrastructure +team officially supports hardware security keys in partnership with +[Yubico Secure it Forward] program. + +Currently, the members of the following teams are eligible for this grant: + +* `infra` +* `crates.io` +* `docs.rs` +* `release` +* `triagebot` +* `bors` + +The Rust Foundation provides YubiKeys to Rust Project members who need access +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]. + +## YubiKeys support in the Rust infrastructure + +### Supported models + +The Rust infrastructure team has validated the [Yubico Series 5 USB/NFC models] +products and officially supports the Yubico Series 5 keys for any issues a +Project member might have. + +### Supported firmware versions + +Based on existing [security advisories], only YubiKeys with firmware +**version v5.7.4** or newer are allowed. You can use either the `ykman` +CLI or Yubico Authenticator to [check the current firmware version] of a YubiKey. + +### Recommended first steps + +There are at least two official open-source tools provided by Yubico tools that +help setting up an Yubikey: + +* [Yubico Authenticator] (sources : [Desktop and Android] | [iOS]): + * The Desktop app is pretty capable of handling most of the tasks. + * You can download the Mobile App directly on Google Play or Apple App Store. +* 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: + +* The [Passkeys PIN default value reference] +* The [PIV app PIN and PUK default values reference] + +For those who prefer the CLI, [uvx] might be an alternative to run the `ykman` +Python utility without installing it globally in your system or managing Python +installations. You can refer to the [ykman online documentation] to learn more +about subcommands. + +```shell +uvx --from yubikey-manager ykman --help +``` + +### Multifactor authentication with webauthn + +Yubico implements the [FIDO2 standard] in all its products, and therefore, +setting up YubiKeys as a multi-factor authenticator device **should just work** +without any additional configuration for any web systems that support second +authentication factors on top of [webauthn]. + +As an example, to set up a YubiKey to MFA in Github, you can refer to these +[official steps]. At some point, you'll be prompted with the following dialog: + +![yubikeys gh setup](img/yubikey-gh-setup.jpg) + +The setup flow will vary depending on the system, and might also change +according to web browser extensions you have installed (e.g. 1password, +which offers itself as an option during such a setup) but in general you +should mind the *security key* web browser dialog. + +This step triggers the check for the human presence against the hardware +key. Touch your YubiKey to confirm the authentication. + +Our [upcoming infrastructure policy] mandates using this option for all +compatible critical Rust Infrastructure systems. + +### Hardware-backed multi factor authentication + +For systems that require multi-factor authentication but only support TOTP +codes as a secure MFA method, YubiKeys can still work as an alternative to +existing solutions like Google Authenticator. In this case, you can use the +Yubico Authenticator app to set up [hardware-backed TOTP code generation]. + +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 +to using an offline-only TOTP authenticator app, losing the Yubikey means +losing access to TOTP codes, which requires additional diligence regarding +backing up recovery codes. + +Note that setting up hardware-backed TOTP codes is optional for Rust Project +members. + +### Hardware-backed SSH keys + +For those who want additional security for SSH authentication, YubiKeys +offer different [options for hardware-backed SSH key pairs]. Having your +SSH keys hardware-backed makes private SSH keys effortlessly portable across +different machines. + +For example, if you want to use a Yubikey-backed SSH key with your Github account, +[OpenSSH built-in support for FIDO2 authentication] may be the easiest way to get +started. + +The setup will differ depending on your operating system, but keep in mind that +you may also need to tweak your Git configuration to make sure that operations +like commit signing continue to work as expected. In particular, we recommend +not prompting the passkey PIN for every Git operation, since it might be +counterproductive. + +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. + +```shell +ssh-keygen -t ed25519-sk \ + -O resident \ + -O application=ssh:git \ + -C "me@email.com" +``` + +Hardware-backed SSH keys are optional for now, but might be required for certain +administrative infrastructure tasks in the future. You can check which resident +SSH keys are available in your YubiKey either with CLI or Yubico Authenticator +app. + +```shell +$ uvx --from yubikey-manager ykman fido credentials list +Enter your PIN: +Credential ID RP ID Username Display name +86707903... ssh:git openssh openssh +``` + +![yubikeys ssh setup](img/yubikey-sshkey.jpg) + +### PIV 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. + +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. + +## FAQ + +### Which services should I use 2FA with my YubiKey? + +Please check our [upcoming infrastructure policy]. + +### How do I handle my preferred cloud CLI authentication with my YubiKey? + +For Gcloud CLI, the [web-based authentication flow] will automatically prompt your +2FA method of choice, and after that, no additional steps are required. You just +need to configure it as your preferred [MFA method in your Google account]. + +For AWS CLI, you should stick with [AWS SSO user sessions] rather than IAM user +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. + +[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 +[Yubico Series 5 USB/NFC models]: https://www.yubico.com/products/yubikey-5-overview +[security advisories]: https://www.yubico.com/support/security-advisories +[check the current firmware version]: https://support.yubico.com/s/article/Where-to-find-YubiKey-firmware-details +[Yubico Authenticator]: https://www.yubico.com/products/yubico-authenticator +[Desktop and Android]: https://github.com/Yubico/yubioath-flutter +[iOS]: https://github.com/Yubico/yubioath-ios +[yubikey-manager]: https://github.com/Yubico/yubikey-manager +[Passkeys PIN default value reference]: https://support.yubico.com/s/article/Understanding-YubiKey-PINs +[PIV app PIN and PUK default values reference]: https://developers.yubico.com/PIV/Introduction/YubiKey_and_PIV.html +[uvx]: https://docs.astral.sh/uv/guides/tools +[ykman online documentation]: https://docs.yubico.com/software/yubikey/tools/ykman +[FIDO2 standard]: https://fidoalliance.org/specifications +[webauthn]: https://en.wikipedia.org/wiki/WebAuthn +[official steps]: https://docs.github.com/en/authentication/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication#configuring-two-factor-authentication-using-a-security-key +[upcoming infrastructure policy]: https://github.com/rust-lang/rust-forge/pull/1051 +[hardware-backed TOTP code generation]: https://support.yubico.com/s/article/Using-your-YubiKey-with-authenticator-codes +[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 diff --git a/src/infra/docs/img/yubikey-gh-setup.jpg b/src/infra/docs/img/yubikey-gh-setup.jpg new file mode 100644 index 000000000..0b30ca3f2 Binary files /dev/null and b/src/infra/docs/img/yubikey-gh-setup.jpg differ diff --git a/src/infra/docs/img/yubikey-sshkey.jpg b/src/infra/docs/img/yubikey-sshkey.jpg new file mode 100644 index 000000000..233891fef Binary files /dev/null and b/src/infra/docs/img/yubikey-sshkey.jpg differ