KEYUTILS(7)

✨ KEYUTILS ✨

okay bestie, so the manual name is keyutils and this is section 7 of the man pages — it's giving "in-kernel key management utilities" and it's literally the front door to the whole keyutils situation 💖

🌸 NAME 🌸

keyutils — in-kernel key management utilities. yes that's the whole name. short. iconic. periodt.

💅 DESCRIPTION 💅

so the keyutils package is two things, and you need to know about both:

• a library, and
• a set of utilities

…and both of them exist so you can access the kernel's keyrings facility. that's the whole vibe. 🗝️✨

There's a header file you get, and it hands you all the definitions and declarations you need to actually talk to the library:

#include <keyutils.h>

and when you're linking against the library, you gotta tell the linker this:

-lkeyutils

that's it. that's the link flag. don't forget it, bestie, or the linker will be like "who? never heard of her" 😭

🦋 Three system calls, and yes you need all three

• add_key(2) — supplies a brand new key to the kernel. new key, who dis 💅
• request_key(2) — goes looking for an existing key you can use, or, if you want, it'll make one for you when there's not one already there.
• keyctl(2) — controls a key in a whole bunch of different ways. ok but listen: the library ships a variety of wrappers around this system call, and you should be using those wrappers, not calling it directly. like, fr fr. use the wrappers.

go read the add_key(2), request_key(2), and keyctl(2) manual pages if you want more, because there's more. 🌈

and the keyctl() wrappers? they're all listed on the keyctl(3) manual page. that's where they live. 👑

🎀 UTILITIES 🎀

There's a program you get, and it lets you interact with the kernel facility through a bunch of subcommands. for example:

keyctl add user foo bar @s

look at her go. ✨

The keyctl(1) manual page has all the info on that program, so go there for the details.

🧚 the upcall thing (iykyk)

The kernel has this ability to upcall to userspace to fabricate new keys. 😳

This can be triggered by request_key() — but here's the tea: userspace is better off using add_key() instead if it possibly can. like, if you have the option, take the option. 💀

This upcalling mechanism is usually routed through the request-key(8) program. What that program does with any particular key is configurable, and the config lives here:

/etc/request-key.conf
/etc/request-key.d/

See the request-key.conf(5) and the request-key(8) manual pages for more information. 🫶

🔥 SEE ALSO 🔥

• keyctl(1)
• keyctl(3)
• keyrings(7)
• persistent-keyring(7)
• process-keyring(7)
• session-keyring(7)
• thread-keyring(7)
• user-keyring(7)
• user-session-keyring(7)
• pam_keyinit(8)

okay that's the whole page, you ate it, you understood it, I'm so proud of you 💜

this one came from Linux, dated 21 Feb 2014 — so go forth and manage those keys, bestie, you've got this 🎀💖✨