1 files changed, 141 insertions, 0 deletions
diff --git a/keyutils-1.5.6/request-key.conf.5 b/keyutils-1.5.6/request-key.conf.5
new file mode 100644
index 0000000..73e0dcb
--- /dev/null
+++ b/keyutils-1.5.6/request-key.conf.5
@@ -0,0 +1,141 @@
+.\" -*- nroff -*-
+.\" Copyright (C) 2005 Red Hat, Inc. All Rights Reserved.
+.\" Written by David Howells (dhowells@redhat.com)
+.\"
+.\" This program is free software; you can redistribute it and/or
+.\" modify it under the terms of the GNU General Public License
+.\" as published by the Free Software Foundation; either version
+.\" 2 of the License, or (at your option) any later version.
+.\"
+.TH REQUEST-KEY.CONF 5 "15 November 2011" Linux "Linux Key Management Utilities"
+.SH NAME
+request-key.conf - Instantiation handler configuration file
+.SH DESCRIPTION
+.P
+This file and its associated key-type specific variants are used by the
+/sbin/request-key program to determine which program it should run to
+instantiate a key.
+.P
+request-key looks first in /etc/request-key.d/ for a file of the key type name
+plus ".conf" that it can use.  If that is not found, it will fall back to
+/etc/request-key.conf.
+.P
+request-key scans through the chosen file one line at a time until it
+finds a match, which it will then use. If it doesn't find a match, it'll return
+an error and the kernel will automatically negate the key.
+.P
+Any blank line or line beginning with a hash mark '#' is considered to be a
+comment and ignored.
+.P
+All other lines are assumed to be command lines with a number of white space
+separated fields:
+.P
+<op> <type> <description> <callout-info> <prog> <arg1> <arg2> ...
+.P
+The first four fields are used to match the parameters passed to request-key by
+the kernel. \fIop\fR is the operation type; currently the only supported
+operation is "create".
+.P
+\fItype\fR, \fIdescription\fR and \fIcallout-info\fR match the three parameters
+passed to \fBkeyctl request2\fR or the \fBrequest_key()\fR system call. Each of
+these may contain one or more asterisk '*' characters as wildcards anywhere
+within the string.
+.P
+Should a match be made, the program specified by <prog> will be exec'd. This
+must have a fully qualified path name. argv[0] will be set from the part of the
+program name that follows the last slash '/' character.
+.P
+If the program name is prefixed with a pipe bar character '|', then the program
+will be forked and exec'd attached to three pipes. The callout information will
+be piped to it on it's stdin and the intended payload data will be retrieved
+from its stdout. Anything sent to stderr will be posted in syslog. If the
+program exits 0, then /sbin/request-key will attempt to instantiate the key
+with the data read from stdout. If it fails in any other way, then request-key
+will attempt to execute the appropriate 'negate' operation command.
+.P
+The program arguments can be substituted with various macros. Only complete
+argument substitution is supported - macro substitutions can't be embedded. All
+macros begin with a percent character '%'. An argument beginning with two
+percent characters will have one of them discarded.
+.P
+The following macros are supported:
+.P
+.RS
+%o    Operation type
+.br
+%k    Key ID
+.br
+%t    Key type
+.br
+%d    Key description
+.br
+%c    Callout information
+.br
+%u    Key UID
+.br
+%g    Key GID
+.br
+%T    Requestor's thread keyring
+.br
+%P    Requestor's process keyring
+.br
+%S    Requestor's session keyring
+.RE
+.P
+There's another macro substitution too that permits the interpolation of the
+contents of a key:
+.P
+.RS
+%{<type>:<description>}
+.RE
+.P
+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. If
+not found an error will be logged and the key under construction will be
+negated.
+.SH EXAMPLE
+.P
+A basic file will be installed in the /etc. This will contain two debugging
+lines that can be used to test the installation:
+.P
+.RS
+create user debug:* negate /bin/keyctl negate %k 30 %S
+.br
+create user debug:loop:* * |/bin/cat
+.br
+create user debug:* * /usr/share/keyutils/request-key-debug.sh %k %d %c %S
+.br
+negate * * * /bin/keyctl negate %k 30 %S
+.RE
+.P
+This is set up so that something like:
+.P
+.RS
+keyctl request2 user debug:xxxx negate
+.RE
+.P
+will create a negative user-defined key, something like:
+.P
+.RS
+keyctl request2 user debug:yyyy spoon
+.RE
+.P
+will create an instantiated user-defined key with "Debug spoon" as the payload,
+and something like:
+.P
+.RS
+keyctl request2 user debug:loop:zzzz abcdefghijkl
+.RE
+.P
+will create an instantiated user-defined key with the callout information as
+the payload.
+.SH FILES
+.ul
+/etc/request-key.conf
+.ul 0
+.br
+.ul
+/etc/request-key.d/<keytype>.conf
+.ul 0
+.SH SEE ALSO
+\fBkeyctl\fR(1), \fBrequest-key.conf\fR(5)