request-key.conf

REQUEST-KEY.CONF(5)	Linux Key Management Utilities	  REQUEST-KEY.CONF(5)



NAME
       request-key.conf - Instantiation handler configuration file

DESCRIPTION
       This  file is used by the /sbin/request-key program to determine which
       program it should run to instantiate a key.

       request-key works scans through the file a 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.

       Any blank line or line beginning with a hash mark ’#’ is considered to
       be a comment and ignored.

       All other lines are assumed to be command lines with a number of white
       space separated fields:

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

       The  first  four	 fields	 are  used  to match the parameters passed to
       request-key by the kernel. op is the  operation	type;  currently  the
       only supported operation is "create".

       type,  description  and callout-info match the three parameters passed
       to keyctl request2 or the request_key() system call. Each of these may
       contain	one  or	 more  asterisk	 ’*’ characters as wildcards anywhere
       within the string.

       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.

       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.

       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.

       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

       There’s another macro substitution too that 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. If not found an error will be logged and the key under con-
       struction will be negated.

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 informa-
       tion as the payload.

FILES
       /etc/request-key.conf

SEE ALSO
       keyctl(1), request-key.conf(5)



Linux				 11 July 2005		  REQUEST-KEY.CONF(5)