TCB_CONVERT(8)

💅 tcb_convert, tcb_unconvert — the manual, but make it make sense

okay so bestie, this is the page for tcb_convert and tcb_unconvert — the two little utilities that move you to and from the tcb password shadowing scheme. that's it, that's the vibe. 🎀

---

✨ SYNOPSIS ✨

tcb_convert
tcb_unconvert

no flags, no arguments, no drama. they just go. periodt. 💅

---

🌸 DESCRIPTION 🌸

tcb_convert takes /etc/shadow and converts it into a whole set of files living under /etc/tcb/ — you can read all about that in tcb(5). and while it's doing this, it locks /etc/shadow, so nobody's out here editing it mid-conversion. icons only. 🔒

tcb_unconvert does the reverse — it scoops all the files under /etc/tcb/ back into /etc/shadow. and here's the tea: it is literally impractical to lock every single tcb shadow file, so instead it temporarily changes the group ownership on /etc/tcb/ to the group "sys". the result? passwd(1) will flat-out refuse to work while the conversion is happening. it's giving bouncer at the club. 🚫

---

🦋 MIGRATING TO TCB 🦋

so you wanna move a system from the classic /etc/passwd + /etc/shadow setup to the tcb password shadowing scheme? say less. here's the whole checklist, in order, no skips:

1. install the tcb package, plus tcb-aware shadow-utils. 🫶
2. create the group "auth" if it isn't already there.
3. if you want processes that possess both the "shadow" and "auth" groups to have read-only access to all tcb files, add (or uncomment) this line in /etc/login.defs:

TCB_AUTH_GROUP yes

4. as root, execute tcb_convert. 👑
5. in /etc/nsswitch.conf, find the "shadow" entry and swap the "files" method out for "tcb". the edited line should look exactly like this:

shadow: tcb

6. in the /etc/pam.d/ files, change every occurrence of pam_unix.so or pam_pwdb.so (if any) to pam_tcb.so. and honestly? you may wish to browse the pam_tcb(8) manual for info on additional tuning — there's lore in there. 📖
7. in each file under /etc/pam.d/ that has a "password" line (most notably /etc/pam.d/passwd), add the write_to=tcb option to the instance of pam_tcb used as the password changing module. the line should look similar to this:

password required /lib/security/pam_tcb.so shadow use_authtok write_to=tcb

8. edit /etc/login.defs so it contains this line, uncommented:

USE_TCB yes

9. now remove the /etc/shadow file and its backups (if any), like /etc/shadow-. and bestie, this one is important — you gotta do it so that processes possessing the "shadow" group don't get read access to all your old password hashes (many of which may stay valid for quite a while 😭). delete them. fr fr.
10. as root:

chown root:shadow /usr/bin/passwd /etc/pam.d/passwd
chmod 2711 /usr/bin/passwd
chmod 640 /etc/pam.d/passwd

11. test that everything actually works properly — most notably, logging in to the system. do not skip the vibe check on this one. 🙈

---

💜 THE RETURN TO SHADOW 💜

if for some reason you decide to go back from tcb to the traditional password shadowing scheme — no judgement, it happens — you can do it with tcb_unconvert, plus reverting some of the actions listed up in "MIGRATING TO TCB". that's the whole exit strategy. 💫

---

🔥 SEE ALSO 🔥

login.defs(5), tcb(5), pam_tcb(8)

---

ngl this one's short but it's load-bearing. read step 9 twice. 💀

---

with love from the Openwall Project, dated 18 April 2003 — yeah she's vintage, but she still slays 🌈✨