REQUEST-KEY.CONF(5)

✨ request-key.conf — the instantiation handler config file, bestie ✨

okay so you found the request-key.conf manpage and honestly? you're about to have a great time. this is the config file for the Linux Key Management Utilities and it's lowkey the backstage pass of key instantiation. let's get into it 💅

---

🎀 NAME 🎀

request-key.conf — the instantiation handler configuration file. yes queen, it's the file that tells request-key who to call when a key needs to be brought into existence. main character energy fr fr.

---

💖 DESCRIPTION 💖

so. these files are the little instruction manuals that /sbin/request-key reads to figure out which program it should run to instantiate a key. that's the whole job. that's the assignment.

request-key is a best match girlie — she reads all of the following files looking for the best match:

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

and if she doesn't find a match? she returns an error and the kernel automatically negates the key. brutal. no key for you. 😭

so what even is the "best match"? okay bestie, listen up:

• the best match is the line with the shortest wildcard skips, ranking the columns in order from left to right.
• and if two lines have the same length skips? then the first read is the one taken. first come, first served, no cap.

now, inside these files, the vibe check is simple: any blank line, or any line beginning with a hash mark #, is considered a comment and gets ignored. bye. not invited. 🙈

every other line is assumed to be a command line with a bunch of white-space-separated fields, like:

<op> <type> <description> <callout-info> <prog> <arg1> <arg2> ...

the first four fields are what's used to match the parameters that the kernel passed to request-key. let's break them down 🧚

• op is the operation type. and currently? the only supported operation is "create". that's it. that's the whole menu.
• type, description and callout-info match the three parameters passed to keyctl request2 or the request_key() system call. and here's the fun part — each of these may contain one asterisk '*' character as a wildcard anywhere within the string. anywhere!! wild.

so should a match be made? the program specified by <prog> will be exec'd. iconic. but heads up:

<prog> must have a fully qualified path name. no shortcuts, no vibes-based guessing. and argv[0] will be set from the part of the program name that follows the last slash '/' character. 💅

---

🦋 the pipe bar thing (this part is so cool) 🦋

if the program name is prefixed with a pipe bar character '|', then the program will be forked and exec'd attached to three pipes. yes, three. a whole trio.

here's how that goes:

• the callout information will be piped to it on its stdin
• the intended payload data will be retrieved from its stdout
• anything sent to stderr will be posted in syslog

and then the moment of truth: if the program exits 0, then /sbin/request-key will attempt to instantiate the key with the data read from stdout. slay. ✨

but if it fails in any other way? then request-key will attempt to execute the appropriate 'negate' operation command. it's giving consequences.

---

🌸 the macros (aka the glow-up section) 🌸

the program arguments can be substituted with various macros. but bestie, listen carefully — only complete argument substitution is supported. macro substitutions can't be embedded. no mixing, no remixing.

all macros begin with a percent character '%'. and an argument beginning with two percent characters will have one of them discarded. cute little escape hatch.

the following macros are supported:

• %o — Operation type
• %k — Key ID
• %t — Key type
• %d — Key description
• %c — Callout information
• %u — Key UID
• %g — Key GID
• %T — Requestor's thread keyring
• %P — Requestor's process keyring
• %S — Requestor's session keyring

---

💜 and there's another macro substitution too 💜

it permits the interpolation of the contents of a key:

%{<type>:<description>}

this performs a lookup for a key of the given type and description on the requestor's keyrings, and if found, substitutes the contents for the macro. found it, got it, gorgeous. 🫶

but if it's not found? an error will be logged and the key under construction will be negated. tragic. the key never makes it to the group chat.

---

🔥 EXAMPLE 🔥

a basic file will be installed in the /etc. this will contain two debugging lines that can be used to test the installation:

create user debug:* negate /bin/keyctl negate %k 30 %S
create user debug:loop:* * |/bin/cat
create user debug:* * /usr/share/keyutils/request-key-debug.sh %k %d %c %S
negate * * * /bin/keyctl negate %k 30 %S

this is set up so that something like:

keyctl request2 user debug:xxxx negate

will create a negative user-defined key, something like:

keyctl request2 user debug:yyyy spoon

will create an instantiated user-defined key with "Debug spoon" as the payload, and something like:

keyctl request2 user debug:loop:zzzz abcdefghijkl

will create an instantiated user-defined key with the callout information as the payload. obsessed. 😌

---

🍓 FILES 🍓

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

---

👑 SEE ALSO 👑

• keyctl(1)
• request-key.conf(5)

---

and that's the whole page, bestie 💖 this one came from the Linux keyutils fam, dated 15 November 2011 — old but still absolutely eating, periodt. ✨🌈