YKPAMCFG(1)

💖 YKPAMCFG — ok bestie, let's talk about your YubiKey 💖

So like… this is the Yubico PAM Module Manual page for ykpamcfg, and fr fr it's the little tool that manages user settings for the Yubico PAM module. It's giving "I hold the keys to your login" energy and honestly? Obsessed. 🎀

---

✨ SYNOPSIS ✨

ykpamcfg [-1 | -2] [-A] [-p] [-i] [-v] [-V] [-h]

That's the whole vibe. Short. Iconic. Slays. 💅

---

🦋 OPTIONS 🦋

• -1 — use slot 1. This is the default, so if you just roll up with nothing, slot 1 is what you get. Main character default energy. 👑
• -2 — use slot 2 instead. The sequel. The upgrade. The other one. ✨
• -A action — pick which action you wanna perform. The deets live down in ACTIONS below, bestie, go read 'em. 💜
• -p path — tell it where to write the output file. Default is ~/.yubico/challenge, so like, if you don't say anything it just vibes in your home dir. 🏠
• -i iterations — how many iterations to use for PBKDF2 of the expected response. Number goes up, number goes down, you decide. 🔢
• -v — verbose mode!! Turn this on and it actually talks to you about what it's doing. Highly recommend. 🗣️
• -V — display version and dip out. Bye bestie. 👋
• -h — display help and dip out. Also bye. 🙈

---

🌸 ACTIONS 🌸

add_hmac_chalresp

Okay so this one's the moment. The PAM module can utilize the HMAC-SHA1 Challenge-response (C/R) mode — the way that it's found in YubiKeys starting with version 2.2 — for offline authentication. No internet required, she's self-sufficient, she's independent. 💅

This action creates the initial state information with the C/R to be issued at the next logon. Setting up the first date so the next login knows what to expect. Cute. 🎀

The utility currently outputs the state information to a file in the current user's home directory:

• ~/.yubico/challenge-123456 — for a YubiKey with serial number API readout enabled
• ~/.yubico/challenge — for one without it

The PAM module supports a system-wide directory for these state files (in case the user's home directories are encrypted — shoutout to everyone whose /home is locked down 🔐), but in a system-wide directory, the challenge part should be replaced with the username.

Example: /var/yubico/challenges/alice-123456

To use the system-wide mode, you currently have to move the generated state files manually and configure the PAM module accordingly. No auto-magic. You do it. With your hands. 😭

---

⭐ EXAMPLES ⭐

First, program a YubiKey for challenge-response on slot 2:

$ ykpersonalize -2 -ochal-resp -ochal-hmac -ohmac-lt64 -oserial-api-visible
...
Commit? (y/n) [n]: y

Now, set the current user to require this YubiKey for logon:

$ ykpamcfg -2 -v
...
Stored initial challenge and expected response in '/home/alice/.yubico/challenge-123456'.

Look at that. It stored it. She ate. 🔥

Then, configure authentication with PAM for example like this (make a backup first — I am BEGGING you, back it up 🙏):

/etc/pam.d/common-auth (from Ubuntu 10.10):

auth  required        pam_unix.so nullok_secure try_first_pass
auth  [success=1 new_authtok_reqd=ok ignore=ignore default=die] pam_yubico.so mode=challenge-response
auth  requisite       pam_deny.so
auth  required        pam_permit.so
auth  optional        pam_ecryptfs.so unwrap

---

💀 BUGS 💀

Found a bug? Report ykpamcfg bugs in the issue tracker, bestie:

https://github.com/Yubico/yubico-pam/issues

(Not me begging you to actually file it instead of just complaining in the group chat. 🙈)

---

🫶 SEE ALSO 🫶

• pam_yubico(8) — the sibling. The co-star. Go read it too.
• The yubico-pam home page: https://developers.yubico.com/yubico-pam/
• YubiKeys can be obtained from Yubico: http://www.yubico.com/ — go get you one, treat yourself. 💖

---

Okay that's the whole page!! This little slice of heaven comes to you courtesy of yubico-pam, Version 2.27. Mwah. Stay authenticated, bestie. 🎀✨💅