infra: document instructions for yubikeys and piv

[ubiratansoares]

Towards rust-lang/team#2501

AI usage disclaimer : the original text was fully written by me. I used an LLM to proofread it and I adopted grammar corrections and minor stylistic suggestions I got from the tool.

r? @marcoieni

Rendered

[marcoieni]

Some initial comments.

Ai disclosure

I found most of the typos with AI.

View changes since this review

[marcoieni]

some simplifications found mainly with AI, so that it is easier to read this document.

View changes since this review

[marcoieni]

what do you mean with "already storing a key"?

[ubiratansoares]

It seems one can store a X.509 certificate only within a PIV slot already storing a private key

ykman piv certificates generate --help
Usage: ykman piv certificates generate [OPTIONS] SLOT PUBLIC-KEY

  Generate a self-signed X.509 certificate.

  A self-signed certificate is generated and written to one of the slots on the YubiKey. A private key must already be present in the corresponding key slot.

# more stuff...

Happy to add a note clarifying that

[marcoieni]

ok, maybe if you can try to reword to add a bit of clarity, because from a first "casual"/"distracted" read I didn't get that
"already storing a key" was referring to the "slot". 🤔

[marcoieni]

Suggested change

	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:

[marcoieni]

Suggested change

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

[marcoieni]

Suggested change

	When creating PIV-backed keys with your YubiKey, you must note the following
	When creating PIV-backed keys, follow these

[marcoieni]

Suggested change

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

[marcoieni]

Suggested change

	* `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)

[marcoieni]

Suggested change

	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/<your-user>.toml`
	Preferably, name each folder you create at `team/hardware-keys` after your YubiKey
	serial number. Check the [TOML schema] for additional details.
	Add these files to the [Project members DB]:
	* Create a directory under [`team/hardware-keys`](https://github.com/rust-lang/team/tree/main/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/<your-user>.toml`.
	See the [TOML schema] for details.

[marcoieni]

in the title you refer to this as "team db". Here as "project members DB". For simplicity we should pick one of those.
I prefer "team db" because it's how the repository is called.

[ubiratansoares]

I'll change that!