ASETKEY(8)

📦
version 1.8.16.1 · 10 versions
, in ubuntu stonking

💖 ASETKEY(8) 💖

okay bestie, listen up — this is asetkey from the AFS Command Reference, and she is that girl. she adds a key from a keytab to an AFS KeyFile or KeyFileExt, and she does it locally, no cap. let's get into it 🦋

✨ NAME ✨

asetkey — add a key from a keytab to an AFS KeyFile or KeyFileExt 🎀

🌸 SYNOPSIS 🌸

asetkey add <kvno> <keyfile> <principal>

asetkey add <kvno> <key>

asetkey add <type> <kvno> <subtype> <key>

asetkey add <type> <kvno> <subtype> <keyfile> <princ>

asetkey delete <kvno>

asetkey delete <type> <kvno>

asetkey delete <type> <kvno> <subtype>

asetkey list

like… look at all those forms. she's flexible, she's versatile, she contains multitudes 💅

💜 DESCRIPTION 💜

so the whole point of asetkey is that it takes a key from a Kerberos keytab and drops it into an AFS KeyFile or KeyFileExt. that's it. that's the job. 🫶

she's like bos addkey's cooler cousin, with two major differences:

  • she has to be run locally on the system where the KeyFile or KeyFileExt actually lives (no remote vibes here, she's a homebody)
  • she pulls the new key from a Kerberos 5 keytab instead of prompting you for the password like some kind of interrogation 😭

and it doesn't stop at add:

  • asetkey delete deletes a key (cousin of bos removekeys)
  • asetkey list lists the keys in a KeyFile and the keys in a KeyFileExt — similar to bos listkeys but more fully featured, because bos listkeys literally cannot list the contents of a KeyFileExt. not her fault, she's just built different 👑

now, when do you reach for her? when your AFS cell's authentication is provided by a Kerberos 5 KDC and not by the deprecated kaserver. the key for the "afs" or "afs/cell name" principal in the Kerberos 5 KDC has to match the key stored in the AFS KeyFileExt on all the AFS database servers and file servers. ✨matcha✨ or ✨mismatch✨, there is no in between.

how you do it, step by step, no skipping:

  1. create a keytab containing that key using the standard Kerberos commands — generally the "ktadd" function of the kadmin command 📝
  2. then, on each AFS database server and each file server, add that key to the KeyFileExt with asetkey add
  3. the <kvno> you pick should match the kvno in the Kerberos KDC (check it with kvno or with the "getprinc" function of kadmin) 🧐
  4. <principal> should be the name of the AFS principal in the keytab, and it has to be either "afs" or "afs/cell name" — those are the only two options, bestie, that's the rule

⚠️ CAUTIONS ⚠️

okay this is the part where we get serious because these are real, and I need you to actually read them. 😤

historically, AFS only supported des-cbc-crc:v4 Kerberos keys. in environments that have not been upgraded to use the rxkad-k5 extension, when you create the keytab with "ktadd", you must pass -e des-cbc-crc:v4 to force the encryption type. if you don't? AFS authentication may just… not work. 💀
the moment a new keytab is created with "ktadd", new AFS service tickets will start using the new key. but tokens formed from those service tickets will only work if that new key is present in the KeyFileExt on the AFS file server. so there's an outage window between when the new keytab gets created and when the key has been added to the KeyFileExt of all AFS servers with asetkey — and during that window, newly obtained AFS tokens will not work properly. plan for it. 😭
every single KeyFileExt entry must match the key in the Kerberos KDC, but every time "ktadd" is run it creates a new key. so you need to either use some secure mechanism to distribute the KeyFileExt to all the servers, or use the same keytab with asetkey on each server. pick one, be consistent, please 🙏

🌈 EXAMPLES 🌈

the rxkad-k5 glow-up ✨

in a cell that is using the rxkad-k5 extension (iconic behaviour), these commands create a new keytab for the principal "afs/cell name" and then import its keys into the KeyFileExt. note the kvno in the output from "ktadd". 👀

the values 18, 17, and 16 are the assigned numbers corresponding to the kerberos enctypes in the keytab. you can figure out those numbers from your system's krb5 headers. 📚

% kadmin
Authenticating as principal kaduk/admin@ZONE.MIT.EDU with password.
Password for kaduk/admin@ZONE.MIT.EDU:
kadmin:  ktadd -k /tmp/afs.keytab afs/disarray.mit.edu
Entry for principal afs/disarray.mit.edu with kvno 4, encryption type
aes256-cts-hmac-sha1-96 added to keytab WRFILE:/tmp/afs.keytab.
Entry for principal afs/disarray.mit.edu with kvno 4, encryption type
aes128-cts-hmac-sha1-96 added to keytab WRFILE:/tmp/afs.keytab.
Entry for principal afs/disarray.mit.edu with kvno 4, encryption type
des3-cbc-sha1 added to keytab WRFILE:/tmp/afs.keytab.
kadmin:  exit
% asetkey add rxkad_krb5 4 18 /tmp/afs.keytab afs/disarray.mit.edu
% asetkey add rxkad_krb5 4 17 /tmp/afs.keytab afs/disarray.mit.edu
% asetkey add rxkad_krb5 4 16 /tmp/afs.keytab afs/disarray.mit.edu

see how it's three separate add calls? one per enctype number? yeah. that's the whole vibe. 🎀

👑 PRIVILEGE REQUIRED 👑

to even think about running her, the issuer must be able to:

  • read the KeyFileExt for asetkey list 👀
  • write the KeyFileExt for asetkey add and asetkey delete ✍️

that KeyFileExt is normally /etc/openafs/server/KeyFileExt. in practice this means the issuer has to be the local superuser "root" on the AFS file server or database server. sorry bestie, no regular-user shortcuts here 💅

and one more thing: for asetkey add, the issuer must also be able to read the specified keytab file. 📖

🕰️ HISTORICAL COMPATIBILITY 🕰️

a modern AFS cell should be using the rxkad-k5 extension, or it risks terribly insecure operation — and by that I mean a complete cell compromise for $100 in 1 day. 😭 not a vibe. be modern.

  • rxkad-k5 operation stores its keys in the KeyFileExt ✨
  • cells not using the rxkad-k5 extension (i.e., stock rxkad) use keys of the des-cbc-crc encryption type, stored in the KeyFile 🗿

asetkey retains the functionality needed to support stock rxkad operation, but its use is disrecommended. like, strongly.

a bare 8-byte hex key can be added with:

% asetkey add I<kvno> I<key>

key should be an 8 byte hex representation. an example using a kvno of 3:

% asetkey add 3 80b6a7cd7a9dadb6

and these commands create a new keytab for the principal "afs" and then import the key into the KeyFile. note the kvno in the output from "ktadd":

% kadmin
Authenticating as principal rra/admin@stanford.edu with password.
Password for rra/admin@stanford.edu:
kadmin:  ktadd -k /tmp/afs.keytab -e des-cbc-crc:v4 afs
Entry for principal afs with kvno 3, encryption type DES cbc mode
with CRC-32 added to keytab WRFILE:/tmp/afs.keytab.
kadmin:  exit
% asetkey add 3 /tmp/afs.keytab afs

pro tip from the page itself: you may want to use "afs/cell name" instead of "afs", particularly if you may have multiple AFS cells for a single Kerberos realm. just saying. 🦋

🫶 SEE ALSO 🫶

go read these too, bestie, they're all connected:

Copyright 2006 Russ Allbery <rra@stanford.edu> Copyright 2013,2015 Massachusetts Institute of Technology

this documentation is covered by the IBM Public License Version 1.0. this man page was written by Russ Allbery for OpenAFS, and updated for the rxkad-k5 extension by Benjamin Kaduk. absolute legends, honestly 🫡

and that's the whole page!! you made it to the end, I'm so proud of you 🥹💖 this edition came to you from OpenAFS, dated 2026-07-27, and it lives at ASETKEY(8). now go add those keys. slay, but carefully. periodt. 💅✨

📦 where this page comes from