yubikey-totp(1)

📦 version 1.3.3, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu resolute, ubuntu stonking

💖 NAME 💖

okay so bestie, gather round — this is yubikey-totp, and it produces an OATH TOTP code using a YubiKey. that's the whole vibe. tiny tool, huge slay. 🎀

✨ SYNOPSIS ✨

yubikey-totp [-v] [-h] [--time | --step] [--digits] [--slot] [--debug]

literally that's it. no cap, that's the entire shape of it. 🦋

🌸 DESCRIPTION 🌸

okay so first things first: OATH codes are one time passwords (OTP) that get calculated in a standardized way. like, everyone agreed on the math. iconic behavior honestly.

now, the YubiKey is primarily used with Yubico OTP's, but plot twist — your YubiKey is also capable of producing OATH codes. it contains multitudes. 💅

and OATH generally comes in two flavors:

  • event based — called HOTP 🍓
  • time based — called TOTP ⏰

here's the thing though, and it's giving tragic backstory: the YubiKey does not contain a battery, so it cannot keep track of the current time itself. 😭 it just cannot. so therefor a helper application — such as yubikey-totp — is required to effectively send the current time to the YubiKey, which can then perform the cryptographic calculation needed to produce the OATH code. teamwork!! 🫶

and through the use of a helper application, such as yubikey-totp, the YubiKey can be used with sites offering OATH TOTP authentication, such as Google GMail. yes, that Google GMail. she's everywhere. 👑

💅 OPTIONS 💅

  • -v — enable verbose mode. she talks more. we love her for it. 🗣️
  • -h — show help. your little emergency bestie. 🆘
  • --time — specify the time value to use (in seconds since epoch). yes, seconds since epoch, the classic. ⏳
  • --step — how frequent codes change in your system — typically 30 or 60 seconds. the code rotation schedule fr fr. 🔄
  • --digits — digits in OATH code — typically 6. six little numbers carrying your entire login. iconic. 🔢
  • --slot — YubiKey slot to use — default 2. if you don't pick, she picks for you. 🎯
  • --debug — enable debug output. for when you need to see everything. 🙈

🌈 EXAMPLE 🌈

the YubiKey OATH TOTP operation can be demonstrated using the RFC 6238 test key "12345678901234567890" (ASCII). yes bestie, that's a real test vector, we're not making it up. ⭐

first, program a YubiKey for HMAC-SHA1 Challenge-Response operation with the test vector HMAC key :

$ ykpersonalize -2 -ochal-resp -ochal-hmac -ohmac-lt64 -o serial-api-visible \
     -a 3132333435363738393031323334353637383930

now, send the NIST test challenge to the YubiKey and verify the result matches the expected :

$ yubikey-totp --step 30 --digits 8 --time 1111111109
07081804
$

and that's 07081804 right there. ate. no notes. 🔥

💀 BUGS 💀

found a bug? report yubikey-totp bugs in the issue tracker ⟨https://github.com/Yubico/python-yubico/issues/⟩. she reads her mentions, promise. 🎀

👑 SEE ALSO 👑

YubiKeys can be obtained from Yubico ⟨http://www.yubico.com/⟩. go get you one, you deserve it. ✨

okay that's the whole page bestie, ily, go make some one time passwords 💖

this lil masterpiece is from python-yubico, dated June 2012 — yeah she's vintage, she's still serving. 🦋✨

📦 where this page comes from