KEYFILE(5)

📦
version 1.8.16.1 · 10 versions
, in ubuntu stonking

💖 KEYFILE(5) — the AFS File Reference glow-up ✨

okay bestie, gather round, because this is KeyFile from section 5 of the manual — the file that literally defines AFS server encryption keys. it lives in the AFS File Reference corner of the man pages and it is, no cap, kind of the main character of server auth. let's get into it 🫶

🌸 NAME 🌸

KeyFile — defines AFS server encryption keys. slay. that's the whole vibe. 💅

✨ DESCRIPTION ✨

so the KeyFile file is the thing that defines the server encryption keys that the AFS server processes running on the machine use to decrypt the tickets that clients hand over during the mutual authentication process. think of it as the server's little velvet rope 🌈 — a client shows up with a ticket, and the server only lets it through if that ticket is encrypted with one of the keys chilling in this file.

and here's the thing, bestie: AFS server processes perform privileged actions only for clients that possess a ticket encrypted with one of the keys from the file. so if your key isn't in there? you're not getting past the bouncer, sorry 😭

the file must live in the /etc/openafs/server directory on every server machine. every single one. no skipping. and if you want the deep lore on mutual authentication and server encryption keys, go read the OpenAFS Administration Guide — it's giving textbook, but it's good.

🔑 keys, key version numbers, and the whole situation

every key has a corresponding key version number that tells it apart from all the other keys. iconic. and the tickets that clients present are also marked with a key version number, so the server process knows exactly which key to use to decrypt it. it's a matching game and it is highkey important.

here's the rule that will ruin your whole week if you break it: the KeyFile file must always include a key with the same key version number and the same contents as the key currently listed for the "afs/cell" principal in the associated Kerberos v5 realm or Authentication Database.

a couple of little footnotes on that, because apparently nothing is ever simple:

  • the principal "afs" may be used if the cell and realm names are the same, but adding the cell name to the principal is recommended even in this case.
  • "afs" must be used as the principal name if the cell uses the Authentication Server rather than a Kerberos v5 realm.

and the key must be a DES key — no stronger encryption type is supported. I know, I know. we don't make the rules. 💀

🧚 it's binary, bestie (so don't you dare)

the KeyFile file is in binary format, which means you always use either the asetkey command or the appropriate commands from the bos command suite to administer it. do not open it in a text editor, do not pass go. just use the tools:

  • asetkey add or bos addkey — to add a new key 🔥
  • asetkey list or bos listkeys — to display the keys 🌸
  • asetkey delete or bos removekey — to remove a key from the file 💅

run-location tea: the asetkey commands must be run on the same server as the KeyFile file you're updating. the bos commands, though, may be run remotely. fancy.

and normally? new keys should be added from a Kerberos v5 keytab using asetkey add. bos addkey is normally only used if the Authentication Server is in use instead of a Kerberos v5 realm. iykyk.

🌈 update server girlies, this one's for you

in cells that use the Update Server to distribute the contents of the /etc/openafs/server directory, it's customary to edit only the copy of the file stored on the system control machine. everyone else gets it handed to them.

otherwise — and this is the less glamorous timeline — you edit the file on each server machine individually. one by one. rip. 🙈

⚠️ CAUTIONS ⚠️

okay this is the part where I hold your hand, because this is where people get humbled.

the most common error caused by changes to KeyFile is adding a key that does not match the corresponding key for the Kerberos v5 principal or Authentication Server database entry. both the key and the key version number must match the key for the corresponding principal — either "afs/cell" or "afs" — in the Kerberos v5 realm or Authentication Database.

and for a Kerberos v5 realm specifically: that principal must only have DES encryption types in the Kerberos KDC. only DES. that's it. that's the list.

now for the unusual case 🫣 — if you're using bos addkey to add a key with a known password that matches a password used to generate Kerberos v5 keys, the keys in the Kerberos v5 KDC database must use "afs3" salt, not the default Kerberos v5 salt. get this wrong and it will not work, periodt.

good news though: the salt doesn't matter for the more normal procedure of extracting a keytab and then adding the key using asetkey. so like... do that instead, bestie. 🎀

👑 SEE ALSO 👑

go read these, they're all icons:

also the OpenAFS Administration Guide at <http://docs.openafs.org/AdminGuide/> — literally the mothership.

IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.

This documentation is covered by the IBM Public License Version 1.0. It was converted from HTML to POD by software written by Chas Williams and Russ Allbery, based on work by Alf Wachsmann and Elizabeth Cassell. absolute legends, all of them 🫶

and that's the whole page, bestie!! ✨ this was OpenAFS, dated 2026-07-27, and it's the KEYFILE(5) page — go forth and never hardcode a mismatched key again, mwah 💖🌈💅

📦 where this page comes from