!!!!! WARNING !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! this is a quick lookup, not the best security practice! Do not follow this unless you know what you are doing! For a sane guide: see e.g. https://drduh.github.io/YubiKey-Guide Software / System deps ------------------------------------------------ software : yubikey-manager (ykman) : yubikey-personalization (ykpersonalize) : age-plugin-yubikey : pcsc-tools (dep for age-plugin) : yubico-piv-tool : libfido2 (e.g. ssh + fido) Deamon : pcscd / pcsclite : start pcscd.service Access control: PINs and CODE ----------------------------------------- You have different pins/codes for each function OpenPGP - PIN : normal auth - PUK (reset pin) : to reset counter / PIN - Admin PIN : can be used to reset PIN / PUK : to manage keys FIDO - PIN: if you forget it, you can only reset all fido credentials PIV - PIN and PUK - Management Key (24 Bytes) OATH - by default this is not protected (i.e. if someone has your key, they can access your TOTP) - password is optional - if you forget the password you have to reset all OATH accounts OTP (challenge-response, static, hotp, yubiotp...) - AFAIK this is not PIN/password protected. - I have little idea why anyone should use this function HSMAUTH (what is this ??) - management password openPGP smart card ---------------------------------------------------- * generate gpg key (skipped) * setup PINs $ ykman openpgp access change-admin-pin $ ykman openpgp access change-pin $ ykman openpgp access change-reset-code $ ykman openpgp access set-retries 5 5 5 * setup card info $ pgp * configure touch (require touch for any action after PIN unlock) $ ykman openpgp keys set-touch dec on $ ykman openpgp keys set-touch sig on $ ykman openpgp keys set-touch aut on * avoid repeated prompts $ echo "disable-ccid" >>scdaemon.conf HARD RESET (wipe all stored openpgp keys) $ pkman openpgp reset OTP ------------------------------------------------------------------- 2 slots are provided for this feature, accessible by short and long button presses respectively. Each can be configured with one of the following: !! don't overwrite the factory OTP on slot 1 unless you have to. !! Yubico OTP (default on SLOT 1) OATH-HOTP OATH-TOTP Challenge-response Static Password Each function has several configuration options provided at the time of creation, but once set they cannot be read back. It is possible to swap slots 1 and 2, with ykman otp swap. OATH + TOTP ----------------------------------------------------------- $ ykman oath accounts uri $ ykman oath accounts code SSH ------------------------------------------------------------------- There are 4 ways you can use yubikey for SSH - with fido resident key - with fido non-resident key - with OpenPGP (ssh-agent -> gpg-agent) - with piv ... SSH (FIDO2 resident key) ---------------------------------------------- generate a private key on the ybk. This will also put the keyid file and pubkey on the host machine. The keyid file is alike but NOT a private key. It's a handle to the ybk. $ ssh-keygen -t ed25519-sk -O resident -O verify-required \ -O application=app_name -C "email@example.com" then copy the generated to whatever host.. To use the ssh key on a different machine: $ ssh-add -K # temporarily add the key to memory $ ssh-keygen -K # download the key (and pub) The above two commands, like previous ssh-keygen, retrieves the private key handle,NOT the actual private key onto the machine. It's impossible to export the private key from ybk! FIDO(TODO) ------------------------------------------------------------ $ ykman fido access change-pin delete individual credentials: $ ykman fido credentials delete QUERY Reset all credentials and PIN: $ ykman fido reset EMAIL ----------------------------------------------------------------- 1. thunderbird + external gpg (for E2EE) 2. mbsync + pass (to manage credentials) 3. open keyring (android) + thunderbird mobile PIV ------------------------------------------------------------------- - PIN (123456) to access stuffs - PUK (12345678) to reset PIN (retries) - MANAGEMENT KEY to import / reset keys slots: 82 - Retired 1 83 - Retired 2 84 ~ 94 ... 95 - retired 20 S/MIME + PIV ---------------------------------------------------------- you can import pcks (.p12) certificate / key with $ ykman import But I don't know how to actually use this key stored in the ybk to sign things ... AGE WITH PIV ---------------------------------------------------------- It seems that the age-plugin-yubikey does not support importing an already-existing age identity.. I guess we'll use the piv-tool manually https://github.com/str4d/age-plugin-yubikey/pull/3 https://github.com/str4d/age-plugin-yubikey/issues/75 https://github.com/str4d/age-plugin-yubikey/issues/207 > manual setup: https://gist.github.com/franchb/b3e7f3ee55f210177d4af3b64c7860fb https://pablo.tools/blog/computers/one-age-identity-multiple-yubikeys/ NOTE: the age-plugin-yubikey is leaking support for firmware 5.7.x MISC ------------------------------------------------------------------- * reset gpg-agent (sind SIGHUP) $ kill -1 $(pidof gpg-agent) The default user pin is 123456 and the default admin pin is 12345678. The default PUK is also 12345678. Remember to change all 3. * TODO: air-gapped VM env for key management. * cheatsheet https://debugging.works/blog/yubikey-cheatsheet/ * more readings https://www.sweharris.org/post/2024-09-05-broken-yubikey/ https://developers.yubico.com/SSH/Securing_SSH_with_FIDO2.html -- vi: tw=72