Lib: Add recursive keyring tree scanning functions to the library

Add a pair of depth-first recursive key scanning functions to the library.

The first applies the named function to all the accessible keys in the keyring
tree rooted at key:

	int recursive_key_scan(key_serial_t key,
			       recursive_key_scanner_t func,
			       void *data);

The second is the same as the first, with the calling process's session
keyring as the root keyring:

	int recursive_key_session_scan(recursive_key_scanner_t func,
				       void *data);

Both functions take a pointer to a callback function to be applied and a data
item to pass to it.  The callback function should fit the following template:

	typedef int (*recursive_key_scanner_t)(
		key_serial_t parent, key_serial_t key,
		char *desc, int desc_len,
		void *data);

The parameters are: the keyring currently being scanned (parent); the key
linked to by the current slot in that keyring (key); the raw description of
that key (desc) as fetched by keyctl_describe or NULL if it couldn't be
fetched; the length of the raw description (desc_len) or -1 if
keyctl_describe_alloc() returned an error; and the data passed to whichever
scanning function was called.

Keyrings must grant View and Read permission to be iterated through.  Target
keys need not grant any permissions to have the callback function applied.

The return value of the scanning functions is the sum of the return values of
the callback function applied to each key.  Errors are ignored.

Signed-off-by: David Howells <dhowells@redhat.com>

1 files changed, 2 insertions, 0 deletions

diff --git a/Makefile b/Makefile
index 724e28f..9e3fa9b 100644
--- a/Makefile
+++ b/Makefile
@@ -176,6 +176,8 @@ endif
 	$(INSTALL) -D -m 0644 keyctl_set_reqkey_keyring.3 $(DESTDIR)$(MAN3)/keyctl_set_reqkey_keyring.3
 	$(INSTALL) -D -m 0644 keyctl_set_timeout.3 $(DESTDIR)$(MAN3)/keyctl_set_timeout.3
 	$(INSTALL) -D -m 0644 keyctl_update.3 $(DESTDIR)$(MAN3)/keyctl_update.3
+	$(INSTALL) -D -m 0644 recursive_key_scan.3 $(DESTDIR)$(MAN3)/recursive_key_scan.3
+	$(LNS) recursive_key_scan.3 $(DESTDIR)$(MAN3)/recursive_session_key_scan.3
 	$(INSTALL) -D -m 0644 request-key.conf.5 $(DESTDIR)$(MAN5)/request-key.conf.5
 	$(INSTALL) -D -m 0644 request-key.8 $(DESTDIR)$(MAN8)/request-key.8
 	$(INSTALL) -D -m 0644 key.dns_resolver.8 $(DESTDIR)$(MAN8)/key.dns_resolver.8