checkpassword.login(8)

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

💖 checkpassword.login(8) 💖

okay bestie, pull up a chair, we're doing checkpassword.login from the System Manager's Manual and honestly? it's giving secure. this whole page is about checkpassword, a lil program whose entire job is checking a password, and she does it flawlessly.

✨ NAME ✨

checkpassword — check a password 💅

🌸 SYNOPSIS 🌸

checkpassword prog

🦋 DESCRIPTION 🦋

so here's the tea. checkpassword reads descriptor 3 all the way through end of file, and then it closes descriptor 3. done. bye. and there has to be at most 512 bytes of data before end of file — no cap, that's the cap.

the info you hand over on descriptor 3 is laid out like this, in order:

  1. a login name, terminated by \0
  2. a password, terminated by \0
  3. a timestamp, terminated by \0
  4. and possibly more data after that, if you're feeling extra

and that's literally it — there are no other restrictions on the form of the login name, the password, or the timestamp. go wild, they're just bytes.

now for the exits, and bestie, pay attention because these numbers matter:

  • if the password is unacceptable, checkpassword exits 1.
  • if checkpassword is misused, it may instead exit 2.
  • if there's a temporary problem checking the password, checkpassword exits 111.

but if the password is acceptable? oh she's moving. checkpassword runs prog, and prog consists of one or more arguments. periodt. 👑

🎀 COMPATIBLE TOOLS 🎀

there are other tools out there offering the exact same interface as checkpassword — same energy, different girlies. and apps that use checkpassword are encouraged to take the checkpassword name as an argument, so they can vibe with all the different tools instead of being locked in. flexibility is the moment.

heads up though: these tools do not follow the getopt(3) interface. none of that. optional features are controlled through (1) the tool name and (2) environment variables. that's the whole system, iykyk.

🔐 THE PASSWORD DATABASE 🔐

checkpassword checks the login name and password against /etc/passwd, using the operating system's getpwnam(3) and crypt(3) functions, supplemented by getspnam. she rejects accounts with empty passwords (as she should 💅) and she ignores the timestamp.

other checkpassword-compatible tools interpret login names, passwords, and timestamps differently, so don't assume everyone reads the same. here's the important part: both the login name and the password should be treated as secrets by the application calling checkpassword — the only distinction between them is for administrative convenience. that's it. the timestamp should include any other information that the password is based on; for example, the challenge in a challenge-response system such as APOP.

⚠️ WARNING: getpwnam is inherently unreliable. it fails to distinguish between temporary errors and nonexistent users. future versions of getpwnam(3) should return ETXTBSY to indicate temporary errors and ESRCH to indicate nonexistent users. not her fault, she's just working with what she's got 😭

🌈 PROCESS-STATE CHANGES 🌈

before invoking prog, checkpassword sets up:

  • $USER
  • $HOME
  • $SHELL
  • its supplementary groups
  • its gid
  • its uid
  • its working directory

other checkpassword-compatible tools may make different changes to the process state, so don't just assume. it is crucial for these effects to be documented — different applications have different requirements. no guessing, bestie. 📝

👑 SEE ALSO 👑

and that's the whole page, fr fr 🫶 this was checkpassword.login(8) from the System Manager's Manual, living in checkpassword.login(8) land — signed off, sealed, and absolutely iconic. now go check some passwords responsibly. mwah 💖✨

📦 where this page comes from