220 lines
5.4 KiB
HTML
220 lines
5.4 KiB
HTML
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<HTML><HEAD><TITLE>Man page of REQUEST-KEY.CONF</TITLE>
|
|
</HEAD><BODY>
|
|
<H1>REQUEST-KEY.CONF</H1>
|
|
Section: Linux Key Management Utilities (5)<BR>Updated: 15 November 2011<BR><A HREF="#index">Index</A>
|
|
<A HREF="/cgi-bin/man/man2html">Return to Main Contents</A><HR>
|
|
|
|
<A NAME="lbAB"> </A>
|
|
<H2>NAME</H2>
|
|
|
|
request-key.conf - Instantiation handler configuration file
|
|
<A NAME="lbAC"> </A>
|
|
<H2>DESCRIPTION</H2>
|
|
|
|
<P>
|
|
|
|
These files are used by the /sbin/request-key program to determine which
|
|
program it should run to instantiate a key.
|
|
<P>
|
|
|
|
request-key looks for the best match, reading all the following files:
|
|
<DL COMPACT>
|
|
<DT id="1"><DD>
|
|
<TT> </TT>/etc/request-key.d/*.conf<BR>
|
|
<BR>
|
|
|
|
<TT> </TT>/etc/request-key.conf<BR>
|
|
</DL>
|
|
<P>
|
|
|
|
If it doesn't find a match, it will return an error
|
|
and the kernel will automatically negate the key.
|
|
<P>
|
|
|
|
The best match is defined as the line with the shortest wildcard skips, ranking
|
|
the columns in order left to right. If two lines have the same length skips,
|
|
then the first read is the one taken.
|
|
<P>
|
|
|
|
In the files, 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. <I>op</I> is the operation type; currently the only supported
|
|
operation is "create".
|
|
<P>
|
|
|
|
<I>type</I>, <I>description</I> and <I>callout-info</I> match the three
|
|
parameters passed to <B>keyctl request2</B> or the <B>request_key()</B> system
|
|
call. Each of these may contain one asterisk '*' character as a wildcard
|
|
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>
|
|
|
|
<DL COMPACT><DT id="2"><DD>
|
|
%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
|
|
</DL>
|
|
|
|
<P>
|
|
|
|
There's another macro substitution too that permits the interpolation of the
|
|
contents of a key:
|
|
<P>
|
|
|
|
<DL COMPACT><DT id="3"><DD>
|
|
%{<type>:<description>}
|
|
</DL>
|
|
|
|
<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.
|
|
<A NAME="lbAD"> </A>
|
|
<H2>EXAMPLE</H2>
|
|
|
|
<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>
|
|
|
|
<DL COMPACT><DT id="4"><DD>
|
|
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
|
|
</DL>
|
|
|
|
<P>
|
|
|
|
This is set up so that something like:
|
|
<P>
|
|
|
|
<DL COMPACT><DT id="5"><DD>
|
|
keyctl request2 user debug:xxxx negate
|
|
</DL>
|
|
|
|
<P>
|
|
|
|
will create a negative user-defined key, something like:
|
|
<P>
|
|
|
|
<DL COMPACT><DT id="6"><DD>
|
|
keyctl request2 user debug:yyyy spoon
|
|
</DL>
|
|
|
|
<P>
|
|
|
|
will create an instantiated user-defined key with "Debug spoon" as the payload,
|
|
and something like:
|
|
<P>
|
|
|
|
<DL COMPACT><DT id="7"><DD>
|
|
keyctl request2 user debug:loop:zzzz abcdefghijkl
|
|
</DL>
|
|
|
|
<P>
|
|
|
|
will create an instantiated user-defined key with the callout information as
|
|
the payload.
|
|
<A NAME="lbAE"> </A>
|
|
<H2>FILES</H2>
|
|
|
|
|
|
/etc/request-key.conf
|
|
|
|
<BR>
|
|
|
|
|
|
/etc/request-key.d/*.conf
|
|
|
|
<A NAME="lbAF"> </A>
|
|
<H2>SEE ALSO</H2>
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?1+keyctl">keyctl</A></B>(1), <B><A HREF="/cgi-bin/man/man2html?5+request-key.conf">request-key.conf</A></B>(5)
|
|
<P>
|
|
|
|
<HR>
|
|
<A NAME="index"> </A><H2>Index</H2>
|
|
<DL>
|
|
<DT id="8"><A HREF="#lbAB">NAME</A><DD>
|
|
<DT id="9"><A HREF="#lbAC">DESCRIPTION</A><DD>
|
|
<DT id="10"><A HREF="#lbAD">EXAMPLE</A><DD>
|
|
<DT id="11"><A HREF="#lbAE">FILES</A><DD>
|
|
<DT id="12"><A HREF="#lbAF">SEE ALSO</A><DD>
|
|
</DL>
|
|
<HR>
|
|
This document was created by
|
|
<A HREF="/cgi-bin/man/man2html">man2html</A>,
|
|
using the manual pages.<BR>
|
|
Time: 00:06:04 GMT, March 31, 2021
|
|
</BODY>
|
|
</HTML>
|