1REQUEST-KEY.CONF(5)     Linux Key Management Utilities     REQUEST-KEY.CONF(5)
2
3
4

NAME

6       request-key.conf - Instantiation handler configuration file
7

DESCRIPTION

9       This  file  is used by the /sbin/request-key program to determine which
10       program it should run to instantiate a key.
11
12       request-key works scans through the file a line  at  a  time  until  it
13       finds  a  match,  which  it  will then use. If it doesn't find a match,
14       it'll return an error and the kernel will automatically negate the key.
15
16       Any blank line or line beginning with a hash mark '#' is considered  to
17       be a comment and ignored.
18
19       All  other lines are assumed to be command lines with a number of white
20       space separated fields:
21
22       <op> <type> <description> <callout-info> <prog> <arg1> <arg2> ...
23
24       The first four fields are  used  to  match  the  parameters  passed  to
25       request-key by the kernel. op is the operation type; currently the only
26       supported operation is "create".
27
28       type, description and callout-info match the three parameters passed to
29       keyctl  request2  or  the  request_key() system call. Each of these may
30       contain one or more  asterisk  '*'  characters  as  wildcards  anywhere
31       within the string.
32
33       Should a match be made, the program specified by <prog> will be exec'd.
34       This must have a fully qualified path name. argv[0] will  be  set  from
35       the part of the program name that follows the last slash '/' character.
36
37       If the program name is prefixed with a pipe bar character '|', then the
38       program will be forked and exec'd attached to three pipes. The  callout
39       information  will be piped to it on it's stdin and the intended payload
40       data will be retrieved from its stdout. Anything sent to stderr will be
41       posted  in  syslog. If the program exits 0, then /sbin/request-key will
42       attempt to instantiate the key with the data read from  stdout.  If  it
43       fails  in  any  other way, then request-key will attempt to execute the
44       appropriate 'negate' operation command.
45
46       The program arguments can be substituted with various macros. Only com‐
47       plete argument substitution is supported - macro substitutions can't be
48       embedded. All macros begin with a percent character  '%'.  An  argument
49       beginning with two percent characters will have one of them discarded.
50
51       The following macros are supported:
52
53              %o    Operation type
54              %k    Key ID
55              %t    Key type
56              %d    Key description
57              %c    Callout information
58              %u    Key UID
59              %g    Key GID
60              %T    Requestor's thread keyring
61              %P    Requestor's process keyring
62              %S    Requestor's session keyring
63
64       There's  another  macro substitution too that permits the interpolation
65       of the contents of a key:
66
67              %{<type>:<description>}
68
69       This performs a lookup for a key of the given type and  description  on
70       the  requestor's  keyrings,  and if found, substitutes the contents for
71       the macro. If not found an error will be logged and the key under  con‐
72       struction will be negated.
73

EXAMPLE

75       A  basic  file  will  be  installed  in the /etc. This will contain two
76       debugging lines that can be used to test the installation:
77
78              create user debug:* negate /bin/keyctl negate %k 30 %S
79              create user debug:loop:* * |/bin/cat
80              create user debug:*  *  /usr/share/keyutils/request-key-debug.sh
81              %k %d %c %S
82              negate * * * /bin/keyctl negate %k 30 %S
83
84       This is set up so that something like:
85
86              keyctl request2 user debug:xxxx negate
87
88       will create a negative user-defined key, something like:
89
90              keyctl request2 user debug:yyyy spoon
91
92       will  create an instantiated user-defined key with "Debug spoon" as the
93       payload, and something like:
94
95              keyctl request2 user debug:loop:zzzz abcdefghijkl
96
97       will create an instantiated user-defined key with the callout  informa‐
98       tion as the payload.
99

FILES

101       /etc/request-key.conf
102

SEE ALSO

104       keyctl(1), request-key.conf(5)
105
106
107
108Linux                            11 July 2005              REQUEST-KEY.CONF(5)
Impressum