Skip to contentSkip to conversation

keyutils: Add some fixes and updates

PATCH In review David Howells 2 participants 14 messages Aug 22, 2025 – Nov 19, 2025 Keys/keyrings

lore
Share & tools
lore

David Howells

author maintainer
#0 lore raw

cover keyutils: Add some fixes and updates

Hi Jarkko,

Here are some patches that I'm proposing to add to keyutils:

(1) Fix a couple of potential signed overflows in the library.

(2) In request-key, fix the mishandling of the last line of the request-key.conf file if it doesn't have a newline at the end.

(3) In the tests, hide the endianness of raw binary content (such as keyring content) by using od to byteswap it appropriately rather than trying to do this manually.

(4) In the tests, add skips for unsupported features.

(5) In request-key, add help text if "--help" is given or no parameters are given.

(6) Add a simpler way to do configuration testing:

	request-key --check [-lnv] type desc [info] [op]

(7) Add support for multiwildcard matching in request-key.conf. This can be tested with:

request-key --match [-v] pattern datum [datum...]

Apologies, some of these should have been committed a while ago.

David

David Howells (7):
lib: Fix a couple of potential signed oveflows
request-key: Fix mishandling of last line of config file
test: Hide endianness
tests: Add skips for testing of unsupported features
request-key: Add help text
request-key: Add a simpler debug test
request-key: Support the promised multiwildcard matching

 keyutils.c                                |   5 +
 man/request-key.8                         |  85 +++-
 request-key.c                             | 504 ++++++++++++++++------
 tests/features/limits/runtest.sh          |   6 +
 tests/hex2bin.pl                          |  21 +
 tests/keyctl/id/bad-args/runtest.sh       |   6 +
 tests/keyctl/id/noargs/runtest.sh         |   6 +
 tests/keyctl/id/valid/runtest.sh          |   6 +
 tests/keyctl/move/bad-args/runtest.sh     |   6 +
 tests/keyctl/move/noargs/runtest.sh       |   6 +
 tests/keyctl/move/recursion/runtest.sh    |   6 +
 tests/keyctl/move/valid/runtest.sh        |   6 +
 tests/keyctl/reading/valid/runtest.sh     |   9 +-
 tests/keyctl/session/valid2/runtest.sh    |   6 +
 tests/keyctl/supports/bad-args/runtest.sh |   6 +
 tests/keyctl/supports/valid/runtest.sh    |   6 +
 tests/prepare.inc.sh                      |  23 +-
 tests/toolbox.inc.sh                      |  69 ++-
 18 files changed, 619 insertions(+), 163 deletions(-)
 create mode 100644 tests/hex2bin.pl
author maintainer
#1 lore raw

PATCH 1/7 lib: Fix a couple of potential signed oveflows

Fix keyctl_read_alloc() to check for a potential unsigned overflow when we allocate a buffer with an extra byte added on the end for a NUL.

Fix keyctl_dh_compute_alloc() for the same thing.

---
 keyutils.c | 5 +++++
 1 file changed, 5 insertions(+)
keyutils.c +5 -0
index 37b6cc3..fd02cda 100644
@@ -18,6 +18,7 @@
 #include <dlfcn.h>
 #include <sys/uio.h>
 #include <errno.h>
+#include <limits.h>
 #include <asm/unistd.h>
 #include "keyutils.h"
 
@@ -442,6 +443,8 @@ int keyctl_read_alloc(key_serial_t id, void **_buffer)
 		return -1;
 
 	for (;;) {
+		if (ret == LONG_MAX)
+			return -EFBIG; /* Don't let buflen+1 overflow. */
 		buflen = ret;
 		buf = malloc(buflen + 1);
 		if (!buf)
@@ -515,6 +518,8 @@ int keyctl_dh_compute_alloc(key_serial_t priv, key_serial_t prime,
 	if (ret < 0)
 		return -1;
 
+	if (ret == LONG_MAX)
+		return -EFBIG; /* Don't let buflen+1 overflow. */
 	buflen = ret;
 	buf = malloc(buflen + 1);
 	if (!buf)
maintainer Reviewed-by on v1 1/7
#2 lore raw

Re: [PATCH 1/7] lib: Fix a couple of potential signed oveflows

Quoted 33 lines · David Howells

Fix keyctl_read_alloc() to check for a potential unsigned overflow when we allocate a buffer with an extra byte added on the end for a NUL.

Fix keyctl_dh_compute_alloc() for the same thing.

---
 keyutils.c | 5 +++++
 1 file changed, 5 insertions(+)
keyutils.c +3 -0
index 37b6cc3..fd02cda 100644
@@ -18,6 +18,7 @@
 #include <dlfcn.h>
 #include <sys/uio.h>
 #include <errno.h>
+#include <limits.h>
 #include <asm/unistd.h>
 #include "keyutils.h"
 
@@ -442,6 +443,8 @@ int keyctl_read_alloc(key_serial_t id, void **_buffer)
 		return -1;
 
 	for (;;) {
+		if (ret == LONG_MAX)
+			return -EFBIG; /* Don't let buflen+1 overflow. */
 		buflen = ret;
 		buf = malloc(buflen + 1);
 		if (!buf)

keyutils.c int keyctl_dh_compute_alloc(key_serial_t priv, key_serial_t prime, · line 525

Quoted 8 lines
keyutils.c +2 -0
@@ -515,6 +518,8 @@ int keyctl_dh_compute_alloc(key_serial_t priv, key_serial_t prime,
 	if (ret < 0)
 		return -1;
 
+	if (ret == LONG_MAX)
+		return -EFBIG; /* Don't let buflen+1 overflow. */
 	buflen = ret;
 	buf = malloc(buflen + 1);
 	if (!buf)

BR, Jarkko

author maintainer
#3 lore raw

PATCH 2/7 request-key: Fix mishandling of last line of config file

In reply to David Howells

Fix mishandling of the config file by /sbin/request-key whereby the last line of a file, if it is lacking a newline, will trim off the last character and then try and use that. Return an error instead if we find a line without a newline char at the end.

---
 request-key.c | 2 ++
 1 file changed, 2 insertions(+)
request-key.c +2 -0
index bf47c0a..d1feec3 100644
@@ -367,6 +367,8 @@ static void scan_conf_file(struct parameters *params, int dirfd, const char *con
 		/* ignore blank lines and comments */
 		if (len == 1 || buf[0] == '#' || isspace(buf[0]))
 			continue;
+		if (len == 0 || buf[len - 1] != '\n')
+			line_error("Line missing newline\n");
 
 		buf[--len] = 0;
 		p = buf;
maintainer Reviewed-by on v1 2/7
#4 lore raw

Re: [PATCH 2/7] request-key: Fix mishandling of last line of config file

Quoted 16 lines · David Howells

Fix mishandling of the config file by /sbin/request-key whereby the last line of a file, if it is lacking a newline, will trim off the last character and then try and use that. Return an error instead if we find a line without a newline char at the end.

---
 request-key.c | 2 ++
 1 file changed, 2 insertions(+)
request-key.c +0 -0
index bf47c0a..d1feec3 100644

request-key.c static void scan_conf_file(struct parameters *params, int dirfd, const char *con · line 374

Quoted 8 lines
request-key.c +2 -0
@@ -367,6 +367,8 @@ static void scan_conf_file(struct parameters *params, int dirfd, const char *con
 		/* ignore blank lines and comments */
 		if (len == 1 || buf[0] == '#' || isspace(buf[0]))
 			continue;
+		if (len == 0 || buf[len - 1] != '\n')
+			line_error("Line missing newline\n");
 
 		buf[--len] = 0;
 		p = buf;

Looks good to me. And the next question is not directly related to this patch per se.

Just a hypothetical question. What if for spurious reasons the config file would have carriage returns?

BR, Jarkko

author maintainer
#5 lore raw

Re: [PATCH 2/7] request-key: Fix mishandling of last line of config file

Quoted 2 lines · Jarkko Sakkinen

Just a hypothetical question. What if for spurious reasons the config file would have carriage returns?

isspace() considers them as whitespace, so they should be treated as trailing spaces and ignored normally.

David

author maintainer
#6 lore raw

PATCH 3/7 test: Hide endianness

In reply to David Howells

Hide the endianness of the raw binary contents of a keyring by passing it through /usr/bin/od which will automatically byteswap it in 4-byte chunks rather than trying to detect the endianness by examining what may be a binary file to obtain a string the format of which changes over time.

---
 tests/keyctl/reading/valid/runtest.sh |  9 ++-----
 tests/toolbox.inc.sh                  | 36 +++++++++++++++++----------
 2 files changed, 25 insertions(+), 20 deletions(-)
tests/keyctl/reading/valid/runtest.sh +2 -7
index 2fb88b9..2527f13 100644
@@ -40,13 +40,8 @@ expect_payload payload "67697a7a 617264"
 
 # read the contents of the keyring as hex and match it to the key ID
 marker "READ KEYRING"
-read_key $keyringid
-tmp=`printf %08x $keyid`
-if [ "$endian" = "LE" ]
-then
-    tmp=`echo $tmp | sed 's/\(..\)\(..\)\(..\)\(..\)/\4\3\2\1/'`
-fi
-expect_payload payload $tmp
+pipe_key_int32 $keyringid
+expect_payload payload $keyid
 
 # remove read permission from the key and try reading it again
 # - we should still have read permission because it's searchable in our
tests/toolbox.inc.sh +23 -13
index 609a6c7..6f4fb18 100644
@@ -12,19 +12,6 @@
 
 echo === $OUTPUTFILE ===
 
-endian=`file -L /proc/$$/exe`
-if expr "$endian" : '.* MSB \+\(pie executable\|executable\|shared object\).*' >&/dev/null
-then
-    endian=BE
-elif expr "$endian" : '.* LSB \+\(pie executable\|executable\|shared object\).*' >&/dev/null
-then
-    endian=LE
-else
-    echo -e "+++ \e[31;1mCan't Determine Endianness\e[0m"
-    echo "+++ Can't Determine Endianness" >>$OUTPUTFILE
-    exit 2
-fi
-
 maxtypelen=31
 maxtype=`for ((i=0; i<$((maxtypelen)); i++)); do echo -n a; done`
 
@@ -1055,6 +1042,29 @@ function pipe_key ()
     fi
 }
 
+###############################################################################
+#
+# pipe a key's raw payload to od to stdout, displaying it as a sequence of
+# 32-bit numbers, appropriately byteswapped.
+#
+###############################################################################
+function pipe_key_int32 ()
+{
+    my_exitval=0
+    if [ "x$1" = "x--fail" ]
+    then
+	my_exitval=1
+	shift
+    fi
+
+    echo keyctl pipe $1 \| od -t u4 -A none >>$OUTPUTFILE
+    echo `keyctl pipe $1 | od -t u4 -A none` >>$OUTPUTFILE 2>&1
+    if [ $? != $my_exitval ]
+    then
+	failed
+    fi
+}
+
 ###############################################################################
 #
 # pipe a key's raw payload through md5sum
author maintainer
#7 lore raw

PATCH 4/7 tests: Add skips for testing of unsupported features

In reply to David Howells

Add skips for features that are either unsupported by the kernel or by the keyutils package.

---
 tests/features/limits/runtest.sh          |  6 +++++
 tests/hex2bin.pl                          | 21 +++++++++++++++
 tests/keyctl/id/bad-args/runtest.sh       |  6 +++++
 tests/keyctl/id/noargs/runtest.sh         |  6 +++++
 tests/keyctl/id/valid/runtest.sh          |  6 +++++
 tests/keyctl/move/bad-args/runtest.sh     |  6 +++++
 tests/keyctl/move/noargs/runtest.sh       |  6 +++++
 tests/keyctl/move/recursion/runtest.sh    |  6 +++++
 tests/keyctl/move/valid/runtest.sh        |  6 +++++
 tests/keyctl/session/valid2/runtest.sh    |  6 +++++
 tests/keyctl/supports/bad-args/runtest.sh |  6 +++++
 tests/keyctl/supports/valid/runtest.sh    |  6 +++++
 tests/prepare.inc.sh                      | 23 +++++++++++++++-
 tests/toolbox.inc.sh                      | 33 ++++++++++++++++++-----
 14 files changed, 136 insertions(+), 7 deletions(-)
 create mode 100644 tests/hex2bin.pl
tests/features/limits/runtest.sh +6 -0
index 3af2f5a..7642071 100644
@@ -9,6 +9,12 @@
 result=PASS
 echo "++++ BEGINNING TEST" >$OUTPUTFILE
 
+if ! keyutils_at_or_later_than 1.6.2
+then
+    toolbox_skip_test $TEST "SKIPPING DUE TO LACK OF 'keyctl --test'"
+    exit 0
+fi
+
 # This doesn't work on MIPS earler than 3.19 because of a kernel bug
 kver=`uname -r`
 kmch=`uname -m`
tests/hex2bin.pl new file +21 -0
new file mode 100644
index 0000000..4f0f27a
@@ -0,0 +1,21 @@
+#!/usr/bin/perl -w
+use strict;
+
+die "Format:\n\t$0 <hex> [<hex>]*\n\t$0 -\n" unless (@ARGV);
+
+my $str = "";
+
+if ($ARGV[0] eq "-") {
+    shift(@ARGV);
+    $str .= $_ while (<STDIN>);
+} else {
+    $str = join("", @ARGV);
+}
+
+$str =~ s/[ \t\n]//g;
+die "odd length string\n" if (length($str) & 1);
+
+for (; $str; $str = substr($str, 2)) {
+    my $pair = hex(substr($str, 0, 2));
+    print pack("C", $pair);
+}
tests/keyctl/id/bad-args/runtest.sh +6 -0
index 957d1a5..bba62c6 100644
@@ -6,6 +6,12 @@
 
 # ---- do the actual testing ----
 
+if [ $have_id_command = 0 ]
+then
+    toolbox_skip_test $TEST "SKIPPING DUE TO LACK OF 'keyctl id'"
+    exit 0
+fi
+
 result=PASS
 echo "++++ BEGINNING TEST" >$OUTPUTFILE
 
tests/keyctl/id/noargs/runtest.sh +6 -0
index aff9de6..b95c596 100644
@@ -6,6 +6,12 @@
 
 # ---- do the actual testing ----
 
+if [ $have_id_command = 0 ]
+then
+    toolbox_skip_test $TEST "SKIPPING DUE TO LACK OF 'keyctl id'"
+    exit 0
+fi
+
 result=PASS
 echo "++++ BEGINNING TEST" >$OUTPUTFILE
 
tests/keyctl/id/valid/runtest.sh +6 -0
index ffed995..2c06b3d 100644
@@ -6,6 +6,12 @@
 
 # ---- do the actual testing ----
 
+if [ $have_id_command = 0 ]
+then
+    toolbox_skip_test $TEST "SKIPPING DUE TO LACK OF 'keyctl id'"
+    exit 0
+fi
+
 result=PASS
 echo "++++ BEGINNING TEST" >$OUTPUTFILE
 
tests/keyctl/move/bad-args/runtest.sh +6 -0
index b1c7e66..9410941 100644
@@ -6,6 +6,12 @@
 
 # ---- do the actual testing ----
 
+if [ $have_move_key = 0 ]
+then
+    toolbox_skip_test $TEST "SKIPPING DUE TO LACK OF 'keyctl move'"
+    exit 0
+fi
+
 result=PASS
 echo "++++ BEGINNING TEST" >$OUTPUTFILE
 
tests/keyctl/move/noargs/runtest.sh +6 -0
index 29a91f1..8ad91e9 100644
@@ -6,6 +6,12 @@
 
 # ---- do the actual testing ----
 
+if [ $have_move_key = 0 ]
+then
+    toolbox_skip_test $TEST "SKIPPING DUE TO LACK OF 'keyctl move'"
+    exit 0
+fi
+
 result=PASS
 echo "++++ BEGINNING TEST" >$OUTPUTFILE
 
tests/keyctl/move/recursion/runtest.sh +6 -0
index 36cd5cb..8b90be8 100644
@@ -6,6 +6,12 @@
 
 # ---- do the actual testing ----
 
+if [ $have_move_key = 0 ]
+then
+    toolbox_skip_test $TEST "SKIPPING DUE TO LACK OF 'keyctl move'"
+    exit 0
+fi
+
 result=PASS
 echo "++++ BEGINNING TEST" >$OUTPUTFILE
 
tests/keyctl/move/valid/runtest.sh +6 -0
index 31b51d7..20ccff2 100644
@@ -6,6 +6,12 @@
 
 # ---- do the actual testing ----
 
+if [ $have_move_key = 0 ]
+then
+    toolbox_skip_test $TEST "SKIPPING DUE TO LACK OF 'keyctl move'"
+    exit 0
+fi
+
 result=PASS
 echo "++++ BEGINNING TEST" >$OUTPUTFILE
 
tests/keyctl/session/valid2/runtest.sh +6 -0
index 12ad234..1642395 100644
@@ -6,6 +6,12 @@
 
 # ---- do the actual testing ----
 
+if [ $have_id_command = 0 ]
+then
+    toolbox_skip_test $TEST "SKIPPING DUE TO LACK OF 'keyctl id'"
+    exit 0
+fi
+
 result=PASS
 echo "++++ BEGINNING TEST" >$OUTPUTFILE
 
tests/keyctl/supports/bad-args/runtest.sh +6 -0
index 05581a4..f87f517 100644
@@ -6,6 +6,12 @@
 
 # ---- do the actual testing ----
 
+if [ $have_capabilities = 0 ]
+then
+    toolbox_skip_test $TEST "SKIPPING DUE TO LACK OF 'keyctl supports'"
+    exit 0
+fi
+
 result=PASS
 echo "++++ BEGINNING TEST" >$OUTPUTFILE
 
tests/keyctl/supports/valid/runtest.sh +6 -0
index 2c62ef2..4e41200 100644
@@ -6,6 +6,12 @@
 
 # ---- do the actual testing ----
 
+if [ $have_capabilities = 0 ]
+then
+    toolbox_skip_test $TEST "SKIPPING DUE TO LACK OF 'keyctl supports'"
+    exit 0
+fi
+
 result=PASS
 echo "++++ BEGINNING TEST" >$OUTPUTFILE
 
tests/prepare.inc.sh +22 -1
index 4033d69..be134da 100644
@@ -112,11 +112,14 @@ then
     esac
 fi
 
+have_capabilities=0
 have_key_invalidate=0
 have_big_key_type=0
 have_dh_compute=0
-have_restrict_keyring=0
+have_move_key=0
 have_notify=0
+have_public_key=0
+have_restrict_keyring=0
 
 if keyctl supports capabilities >&/dev/null
 then
@@ -179,3 +182,21 @@ if [ "$SKIPINSTALLREQ" = "yes" ]
 then
     skip_install_required=1
 fi
+
+#
+# Check if "keyctl id" is supported
+#
+have_id_command=0
+if keyutils_at_or_later_than 1.6.2
+then
+    have_id_command=1
+fi
+
+#
+# Check if "keyctl pkey_*" are supported
+#
+have_pkey_commands=0
+if keyutils_at_or_later_than 1.6
+then
+    have_pkey_commands=1
+fi
tests/toolbox.inc.sh +27 -6
index 6f4fb18..212b353 100644
@@ -613,8 +613,15 @@ function create_key ()
 	my_keyring=$4
     fi
 
-    echo keyctl add "$@" >>$OUTPUTFILE
-    keyctl add "$@" >>$OUTPUTFILE 2>&1
+    if [ "$1" = "-x" ] && version_less_than $OSRELEASE 9
+    then
+	shift
+	echo perl ../../../hex2bin.pl "$3" "|" keyctl padd "$1 $2 $4" >>$OUTPUTFILE
+	perl ../../../hex2bin.pl "$3" | keyctl padd "$1" "$2" "$4" >>$OUTPUTFILE
+    else
+	echo keyctl add "$@" >>$OUTPUTFILE
+	keyctl add "$@" >>$OUTPUTFILE 2>&1
+    fi
     e=$?
     if [ $e == $my_exitval ]
     then
@@ -682,8 +689,15 @@ function pcreate_key ()
 	my_keyring=$3
     fi
 
-    echo echo -n $data \| keyctl padd "$@" >>$OUTPUTFILE
-    echo -n $data | keyctl padd "$@" >>$OUTPUTFILE 2>&1
+    if [ "$1" = "-x" ] && version_less_than $OSRELEASE 9
+    then
+	shift
+	echo echo -n $data \| perl ../../../hex2bin.pl "|" keyctl padd "$@" >>$OUTPUTFILE
+	echo -n $data | perl ../../../hex2bin.pl - | keyctl padd "$@" >>$OUTPUTFILE
+    else
+	echo echo -n $data \| keyctl padd "$@" >>$OUTPUTFILE
+	echo -n $data | keyctl padd "$@" >>$OUTPUTFILE 2>&1
+	fi
     e=$?
     if [ $e == $my_exitval ]
     then
@@ -1232,8 +1246,15 @@ function update_key ()
 	shift
     fi
 
-    echo keyctl update "$@" >>$OUTPUTFILE
-    keyctl update "$@" >>$OUTPUTFILE 2>&1
+    if [ "x$1" = "x-x" ] && version_less_than $OSRELEASE 9
+    then
+	shift
+	echo perl ../../../hex2bin.pl "$2" "|" keyctl pupdate "$1" >>$OUTPUTFILE
+	perl ../../../hex2bin.pl "$2" | keyctl pupdate "$1" >>$OUTPUTFILE
+    else
+	echo keyctl update "$@" >>$OUTPUTFILE
+	keyctl update "$@" >>$OUTPUTFILE 2>&1
+    fi
     e=$?
     if [ $e == $my_exitval ]
     then
author maintainer
#8 lore raw

PATCH 5/7 request-key: Add help text

In reply to David Howells

Add --help text to /sbin/request-key.

---
 man/request-key.8 | 42 +++++++++++++++++++++++++++-------
 request-key.c     | 57 ++++++++++++++++++++++++++++++++++++++++++-----
 2 files changed, 85 insertions(+), 14 deletions(-)
man/request-key.8 +34 -8
index 50a7506..15b6bb8 100644
@@ -7,20 +7,37 @@
 .\" as published by the Free Software Foundation; either version
 .\" 2 of the License, or (at your option) any later version.
 .\"
-.TH REQUEST-KEY 8 "15 Nov 2011" Linux "Linux Key Management Utilities"
+.TH REQUEST-KEY 8 "22 Aug 2025" Linux "Linux Key Management Utilities"
 .SH NAME
 request\-key \- handle key instantiation callback requests from the kernel
 .SH SYNOPSIS
-\fB/sbin/request\-key \fR<op> <key> <uid> <gid> <threadring> <processring>
-	<sessionring> [<info>]
+.nf
+\fB/sbin/request\-key\fP [\fB--help\fP|\fB--version\fP]
+\fB/sbin/request\-key\fP \fIop key uid gid t-ring p-ring s-ring\fP [\fIinfo\fP]
+\fB/sbin/request\-key -d [-lnv] -D\fP \fIdesc\fP \fIop key\fP...
+.fi
 .SH DESCRIPTION
 This program is invoked by the kernel when the kernel is asked for a key that
 it doesn't have immediately available. The kernel creates a partially set up
-key and then calls out to this program to instantiate it. It is not intended
-to be called directly.
+key and then calls out to this program to instantiate it. It is not intended to
+be called directly.  A debugging capability is available through command line
+options, however, to aid in testing and in debugging configuration.
 .PP
-However, for debugging purposes, it can be given some options on the command
-line:
+The normally required parameters are:
+.IP \fBop\fP
+The operation being done, such as "create" if a key is being instantiated for
+creation.
+.IP \fBkey\fP
+The ID of the key being operated upon.
+.IP "\fBuid\fP, \fBgid\fP"
+The ownership of the task that caused the key to be created.
+.IP "\fBt-ring\fP, \fBp-ring\fP, \fBs-ring\fP"
+The thread, process and session keyrings of the task that caused the key to be
+created.
+.IP \fBinfo\fP
+The optional callout info that can be passed by \fIrequest_key(2)\fP.
+.PP
+The options that may also be supplied are:
 .IP \fB-d\fP
 Turn on debugging mode.  In this mode, no attempts are made to access any keys
 and, if a handler program is selected, it won't be executed; instead, this
@@ -39,10 +56,19 @@ will be copied to the system log - this will prevent that.
 .IP \fB-v\fP
 Turn on debugging output.  This may be specified multiple times to produce
 increasing levels of verbosity.
+.IP \fB--help\fP
+Print help text and exit.
 .IP \fB--version\fP
 Print the program version and exit.
+.SH EXAMPLES
+When using the debugging mode, all the parameters must be given, though a lot
+of them don't matter and can be just set to 0, e.g.:
+.PP
+.nf
+request-key -d -D "user;0;0;0;debug:bar" create 0 0 0 0 0 0 foo
+.fi
 .SH ERRORS
-All errors will be logged to the syslog.
+All errors will be logged to the syslog unless the \fB-n\fP option is given.
 .SH FILES
 .ul
 /etc/request\-key.d/*.conf
request-key.c +51 -6

83 lines not on this page · raw message

maintainer Reviewed-by on v1 5/7
#9 lore raw

Re: [PATCH 5/7] request-key: Add help text

Quoted 4 lines · David Howells

Add --help text to /sbin/request-key.

---

Quoted 155 lines
 man/request-key.8 | 42 +++++++++++++++++++++++++++-------
 request-key.c     | 57 ++++++++++++++++++++++++++++++++++++++++++-----
 2 files changed, 85 insertions(+), 14 deletions(-)
man/request-key.8 +34 -8
index 50a7506..15b6bb8 100644
@@ -7,20 +7,37 @@
 .\" as published by the Free Software Foundation; either version
 .\" 2 of the License, or (at your option) any later version.
 .\"
-.TH REQUEST-KEY 8 "15 Nov 2011" Linux "Linux Key Management Utilities"
+.TH REQUEST-KEY 8 "22 Aug 2025" Linux "Linux Key Management Utilities"
 .SH NAME
 request\-key \- handle key instantiation callback requests from the kernel
 .SH SYNOPSIS
-\fB/sbin/request\-key \fR<op> <key> <uid> <gid> <threadring> <processring>
-	<sessionring> [<info>]
+.nf
+\fB/sbin/request\-key\fP [\fB--help\fP|\fB--version\fP]
+\fB/sbin/request\-key\fP \fIop key uid gid t-ring p-ring s-ring\fP [\fIinfo\fP]
+\fB/sbin/request\-key -d [-lnv] -D\fP \fIdesc\fP \fIop key\fP...
+.fi
 .SH DESCRIPTION
 This program is invoked by the kernel when the kernel is asked for a key that
 it doesn't have immediately available. The kernel creates a partially set up
-key and then calls out to this program to instantiate it. It is not intended
-to be called directly.
+key and then calls out to this program to instantiate it. It is not intended to
+be called directly.  A debugging capability is available through command line
+options, however, to aid in testing and in debugging configuration.
 .PP
-However, for debugging purposes, it can be given some options on the command
-line:
+The normally required parameters are:
+.IP \fBop\fP
+The operation being done, such as "create" if a key is being instantiated for
+creation.
+.IP \fBkey\fP
+The ID of the key being operated upon.
+.IP "\fBuid\fP, \fBgid\fP"
+The ownership of the task that caused the key to be created.
+.IP "\fBt-ring\fP, \fBp-ring\fP, \fBs-ring\fP"
+The thread, process and session keyrings of the task that caused the key to be
+created.
+.IP \fBinfo\fP
+The optional callout info that can be passed by \fIrequest_key(2)\fP.
+.PP
+The options that may also be supplied are:
 .IP \fB-d\fP
 Turn on debugging mode.  In this mode, no attempts are made to access any keys
 and, if a handler program is selected, it won't be executed; instead, this
@@ -39,10 +56,19 @@ will be copied to the system log - this will prevent that.
 .IP \fB-v\fP
 Turn on debugging output.  This may be specified multiple times to produce
 increasing levels of verbosity.
+.IP \fB--help\fP
+Print help text and exit.
 .IP \fB--version\fP
 Print the program version and exit.
+.SH EXAMPLES
+When using the debugging mode, all the parameters must be given, though a lot
+of them don't matter and can be just set to 0, e.g.:
+.PP
+.nf
+request-key -d -D "user;0;0;0;debug:bar" create 0 0 0 0 0 0 foo
+.fi
 .SH ERRORS
-All errors will be logged to the syslog.
+All errors will be logged to the syslog unless the \fB-n\fP option is given.
 .SH FILES
 .ul
 /etc/request\-key.d/*.conf
request-key.c +44 -6
index d1feec3..9a7d741 100644
@@ -111,7 +111,7 @@ static void error(const char *fmt, ...)
 {
 	va_list va;
 
-	if (verbosity) {
+	if (verbosity || debug_mode) {
 		va_start(va, fmt);
 		vfprintf(stderr, fmt, va);
 		va_end(va);
@@ -138,6 +138,45 @@ static void oops(int x)
 	error("Died on signal %d", x);
 }
 
+static const char help_text[] =
+	"Usage: request-key [OPTIONS] [PARAMS]\n"
+	"       request-key [OPTIONS] -d -D <desc> [PARAMS]\n"
+	"\n"
+	"Where the required parameters, [PARAMS], are, in order:\n"
+	"  <op>     : The operation type (e.g. 'create')\n"
+	"  <key>    : The ID of the key to be operated upon\n"
+	"  <uid>    : The UID of the requesting process\n"
+	"  <gid>    : The GID of the requesting process\n"
+	"  <t-ring> : The thread keyring of the requesting process (or 0)\n"
+	"  <p-ring> : The process keyring of the requesting process (or 0)\n"
+	"  <s-ring> : The session keyring of the requesting process (or 0)\n"
+	"  <callout>: The callout data supplied to the request\n"
+	"\n"
+	"and [OPTIONS] are none or more of\n"
+	"  -d       : Debug mode for direct cmdline testing\n"
+	"  -D <desc>: Description for debug mode\n"
+	"  -l       : Use config from local dir, not /etc\n"
+	"  -n       : Don't log to syslog\n"
+	"  -v       : Turn up verbosity (can use multiple times)\n"
+	"  --version: Print version and exit\n"
+	"  --help   : Print this text and exit\n"
+	"\n"
+	"Service program lookup testing can be done with the '-d' option, but\n"
+	"as there is no actual key to query, the called must supply the key's\n"
+	"attributes manually using '-D' in the form returned by the\n"
+	"'keyctl rdescribe' command, for example:\n"
+	"\n"
+	"  ./request-key -d -D \"user;0;0;0;debug:bar\" create 0 0 0 0 0 0 foo\n"
+	"\n"
+	"where 'user' is the key type and 'debug:bar' is the key description.\n"
+	;
+
+static struct option long_options[] = {
+	{ .name = "help",	.val = 1 },
+	{ .name = "version",	.val = 2 },
+	{}
+};
+
 /*****************************************************************************/
 /*
  *
@@ -149,19 +188,25 @@ int main(int argc, char *argv[])
 	char *buf;
 	int ret, ntype, dpos, n, fd, opt;
 
-	if (argc == 2 && strcmp(argv[1], "--version") == 0) {
-		printf("request-key from %s (Built %s)\n",
-		       keyutils_version_string, keyutils_build_string);
-		return 0;
+	if (argc == 1) {
+		fputs(help_text, stderr);
+		exit(2);
 	}
 
 	signal(SIGSEGV, oops);
 	signal(SIGBUS, oops);
 	signal(SIGPIPE, SIG_IGN);
 
-	while (opt = getopt(argc, argv, "D:dlnv"),
+	while (opt = getopt_long(argc, argv, "D:dlnv", long_options, NULL),
 	       opt != -1) {
 		switch (opt) {

request-key.c int main(int argc, char *argv[]) · line 212

Quoted 10 lines
request-key.c +7 -0
+		case 1:
+			fputs(help_text, stderr);
+			exit(2);
+		case 2:
+			printf("request-key from %s (Built %s)\n",
+			       keyutils_version_string, keyutils_build_string);
+			return 0;
 		case 'D':
 			test_desc = optarg;
 			break;

BR, Jarkko

author maintainer
#10 lore raw

PATCH 6/7 request-key: Add a simpler debug test

In reply to David Howells

Add a simpler debug test to avoid the need to supply all the parameters that don't take part in the matching. This looks like:

	request-key --check <type> <desc> [<callout>] [<op>]
	request-key --check user debug:bar

The unspecified parameters are just defaulted.

---
 man/request-key.8 |  38 ++++++---
 request-key.c     | 203 ++++++++++++++++++++++++++++++----------------
 2 files changed, 161 insertions(+), 80 deletions(-)
man/request-key.8 +28 -10
index 15b6bb8..90121d9 100644
@@ -14,14 +14,18 @@ request\-key \- handle key instantiation callback requests from the kernel
 .nf
 \fB/sbin/request\-key\fP [\fB--help\fP|\fB--version\fP]
 \fB/sbin/request\-key\fP \fIop key uid gid t-ring p-ring s-ring\fP [\fIinfo\fP]
-\fB/sbin/request\-key -d [-lnv] -D\fP \fIdesc\fP \fIop key\fP...
+\fB/sbin/request\-key -d\fP [\fB-lnv\fP] [\fB-D\fP \fIdesc\fP] \fIop key\fP...
+\fB/sbin/request\-key --check\fP [\fB-lnv\fP] \fItype desc\fP [\fIinfo\fP] [\fIop\fP]
 .fi
 .SH DESCRIPTION
 This program is invoked by the kernel when the kernel is asked for a key that
 it doesn't have immediately available. The kernel creates a partially set up
-key and then calls out to this program to instantiate it. It is not intended to
-be called directly.  A debugging capability is available through command line
-options, however, to aid in testing and in debugging configuration.
+key and then calls out to this program to instantiate it. It is not generally
+intended to be called directly.
+.PP
+Debugging capabilities are also available through command line options to aid
+in testing and in configuration debugging.
+.SH COMMAND-LINE OPTIONS
 .PP
 The normally required parameters are:
 .IP \fBop\fP
@@ -39,12 +43,12 @@ The optional callout info that can be passed by \fIrequest_key(2)\fP.
 .PP
 The options that may also be supplied are:
 .IP \fB-d\fP
-Turn on debugging mode.  In this mode, no attempts are made to access any keys
+Debug the lookup.  If this is supplied, no attempts are made to access any keys
 and, if a handler program is selected, it won't be executed; instead, this
-program will print a message and exit 0.
-.IP \fB-D <description>\fP
-In debugging mode, use the proposed key description specified with this rather
-than the sample ("user;0;0;1f0000;debug:1234") built into the program.
+program will print a message and exit.
+.IP "\fB-D\fP \fIdescription\fP"
+Use with \fB-d\fP to provide a specific key description rather than using the
+sample ("user;0;0;1f0000;debug:1234") built into the program.
 .IP \fB-l\fP
 Use configuration from the current directory.  The program will use
 .IR request-key.d/* " and " request-key.conf
@@ -56,6 +60,9 @@ will be copied to the system log - this will prevent that.
 .IP \fB-v\fP
 Turn on debugging output.  This may be specified multiple times to produce
 increasing levels of verbosity.
+.IP \fB--check\fP
+If this is provide, then a simpler debugging mode is engaged that defaults most
+of the arguments, but otherwise operates much the same as '-d'.
 .IP \fB--help\fP
 Print help text and exit.
 .IP \fB--version\fP
@@ -67,8 +74,19 @@ of them don't matter and can be just set to 0, e.g.:
 .nf
 request-key -d -D "user;0;0;0;debug:bar" create 0 0 0 0 0 0 foo
 .fi
+.PP
+With the simple check mode, the parameters that aren't involved in matching
+are just defaulted and only those that are necessary are given; further, only
+the basic key description needs be supplied, e.g.:
+.PP
+.nf
+request-key --check user debug:bar
+request-key --check user debug:bar foo
+request-key --check user debug:bar foo create
+.fi
 .SH ERRORS
-All errors will be logged to the syslog unless the \fB-n\fP option is given.
+All errors will be logged to the syslog unless \fB-n\fP or \fB--check\fP are
+given.  Errors will also be logged to stderr if \fB-v\fP is given.
 .SH FILES
 .ul
 /etc/request\-key.d/*.conf
request-key.c +133 -70

275 lines not on this page · raw message

maintainer Tested-by Reviewed-by on v1 6/7
#11 lore raw

Re: [PATCH 6/7] request-key: Add a simpler debug test

Quoted 9 lines · David Howells

Add a simpler debug test to avoid the need to supply all the parameters that don't take part in the matching. This looks like:

	request-key --check <type> <desc> [<callout>] [<op>]
	request-key --check user debug:bar

The unspecified parameters are just defaulted.

BR, Jarkko

author maintainer
#12 lore raw

PATCH 7/7 request-key: Support the promised multiwildcard matching

In reply to David Howells

The manual page for request-key.conf says that multiple wildcards can be used in match elements in the config files, so implement this feature.

Also add a flag, "--test-match", to allow that match function to be tested directly, e.g.:

  request-key --test-match "**a*a***i**a**a**" antidisestablishmentarianism
---
 man/request-key.8 |  19 +++-
 request-key.c     | 252 ++++++++++++++++++++++++++++++++++++----------
 2 files changed, 217 insertions(+), 54 deletions(-)
man/request-key.8 +17 -2
index 90121d9..7cec6e8 100644
@@ -16,6 +16,7 @@ request\-key \- handle key instantiation callback requests from the kernel
 \fB/sbin/request\-key\fP \fIop key uid gid t-ring p-ring s-ring\fP [\fIinfo\fP]
 \fB/sbin/request\-key -d\fP [\fB-lnv\fP] [\fB-D\fP \fIdesc\fP] \fIop key\fP...
 \fB/sbin/request\-key --check\fP [\fB-lnv\fP] \fItype desc\fP [\fIinfo\fP] [\fIop\fP]
+\fB/sbin/request\-key --match\fP [\fB-v\fP] \fIpattern datum\fP [\fIdatum...\fP]
 .fi
 .SH DESCRIPTION
 This program is invoked by the kernel when the kernel is asked for a key that
@@ -65,6 +66,10 @@ If this is provide, then a simpler debugging mode is engaged that defaults most
 of the arguments, but otherwise operates much the same as '-d'.
 .IP \fB--help\fP
 Print help text and exit.
+.IP \fB--match\fP
+Test the pattern matcher.  The first parameter is the pattern and all
+subsequent parameters are strings to try matching against that.  The program
+exits 1 if any match failure occurs, 0 if all succeed.
 .IP \fB--version\fP
 Print the program version and exit.
 .SH EXAMPLES
@@ -84,9 +89,19 @@ request-key --check user debug:bar
 request-key --check user debug:bar foo
 request-key --check user debug:bar foo create
 .fi
+.PP
+Pattern match testing can be done directly without invoking any of the lookup
+code and without reference to the configuration, e.g.:
+.PP
+.nf
+request-key --match "debug:*" debug:a user:b user:debug:c
+request-key --match -v "*a*a***a*a**a**" antidisestablishmentarianism
+.fi
+.PP
 .SH ERRORS
-All errors will be logged to the syslog unless \fB-n\fP or \fB--check\fP are
-given.  Errors will also be logged to stderr if \fB-v\fP is given.
+All errors will be logged to the syslog unless one of \fB-n\fP, \fB--check\fP
+or \fB--match\fP are given.  Errors will also be logged to stderr if \fB-v\fP
+is given.
 .SH FILES
 .ul
 /etc/request\-key.d/*.conf
request-key.c +200 -52

371 lines not on this page · raw message

maintainer Reviewed-by on v1 7/7
#13 lore raw

Re: [PATCH 7/7] request-key: Support the promised multiwildcard matching

Quoted 9 lines · David Howells

The manual page for request-key.conf says that multiple wildcards can be used in match elements in the config files, so implement this feature.

Also add a flag, "--test-match", to allow that match function to be tested directly, e.g.:

  request-key --test-match "**a*a***i**a**a**" antidisestablishmentarianism

BR, Jarkko