1096 lines
33 KiB
HTML
1096 lines
33 KiB
HTML
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<HTML><HEAD><TITLE>Man page of KEYCTL</TITLE>
|
|
</HEAD><BODY>
|
|
<H1>KEYCTL</H1>
|
|
Section: Linux Key Management Utilities (1)<BR>Updated: 20 Feb 2014<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>
|
|
|
|
keyctl - key management facility control
|
|
<A NAME="lbAC"> </A>
|
|
<H2>SYNOPSIS</H2>
|
|
|
|
<B>keyctl</B> --version
|
|
<BR>
|
|
|
|
<B>keyctl</B> show [-x] [<keyring>]
|
|
<BR>
|
|
|
|
<B>keyctl</B> add <type> <desc> <data> <keyring>
|
|
<BR>
|
|
|
|
<B>keyctl</B> padd <type> <desc> <keyring>
|
|
<BR>
|
|
|
|
<B>keyctl</B> request <type> <desc> [<dest_keyring>]
|
|
<BR>
|
|
|
|
<B>keyctl</B> request2 <type> <desc> <info> [<dest_keyring>]
|
|
<BR>
|
|
|
|
<B>keyctl</B> prequest2 <type> <desc> [<dest_keyring>]
|
|
<BR>
|
|
|
|
<B>keyctl</B> update <key> <data>
|
|
<BR>
|
|
|
|
<B>keyctl</B> pupdate <key>
|
|
<BR>
|
|
|
|
<B>keyctl</B> newring <name> <keyring>
|
|
<BR>
|
|
|
|
<B>keyctl</B> revoke <key>
|
|
<BR>
|
|
|
|
<B>keyctl</B> clear <keyring>
|
|
<BR>
|
|
|
|
<B>keyctl</B> link <key> <keyring>
|
|
<BR>
|
|
|
|
<B>keyctl</B> unlink <key> [<keyring>]
|
|
<BR>
|
|
|
|
<B>keyctl</B> search <keyring> <type> <desc> [<dest_keyring>]
|
|
<BR>
|
|
|
|
<B>keyctl</B> restrict_keyring <keyring> [<type> [<restriction>]]
|
|
<BR>
|
|
|
|
<B>keyctl</B> read <key>
|
|
<BR>
|
|
|
|
<B>keyctl</B> pipe <key>
|
|
<BR>
|
|
|
|
<B>keyctl</B> print <key>
|
|
<BR>
|
|
|
|
<B>keyctl</B> list <keyring>
|
|
<BR>
|
|
|
|
<B>keyctl</B> rlist <keyring>
|
|
<BR>
|
|
|
|
<B>keyctl</B> describe <keyring>
|
|
<BR>
|
|
|
|
<B>keyctl</B> rdescribe <keyring> [sep]
|
|
<BR>
|
|
|
|
<B>keyctl</B> chown <key> <uid>
|
|
<BR>
|
|
|
|
<B>keyctl</B> chgrp <key> <gid>
|
|
<BR>
|
|
|
|
<B>keyctl</B> setperm <key> <mask>
|
|
<BR>
|
|
|
|
<B>keyctl</B> new_session
|
|
<BR>
|
|
|
|
<B>keyctl</B> session
|
|
<BR>
|
|
|
|
<B>keyctl</B> session - [<prog> <arg1> <arg2> ...]
|
|
<BR>
|
|
|
|
<B>keyctl</B> session <name> [<prog> <arg1> <arg2> ...]
|
|
<BR>
|
|
|
|
<B>keyctl</B> instantiate <key> <data> <keyring>
|
|
<BR>
|
|
|
|
<B>keyctl</B> pinstantiate <key> <keyring>
|
|
<BR>
|
|
|
|
<B>keyctl</B> negate <key> <timeout> <keyring>
|
|
<BR>
|
|
|
|
<B>keyctl</B> reject <key> <timeout> <error> <keyring>
|
|
<BR>
|
|
|
|
<B>keyctl</B> timeout <key> <timeout>
|
|
<BR>
|
|
|
|
<B>keyctl</B> security <key>
|
|
<BR>
|
|
|
|
<B>keyctl</B> reap [-v]
|
|
<BR>
|
|
|
|
<B>keyctl</B> purge <type>
|
|
<BR>
|
|
|
|
<B>keyctl</B> purge [-i] [-p] <type> <desc>
|
|
<BR>
|
|
|
|
<B>keyctl</B> purge -s <type> <desc>
|
|
<BR>
|
|
|
|
<B>keyctl</B> get_persistent <keyring> [<uid>]
|
|
<BR>
|
|
|
|
<B>keyctl</B> dh_compute <private> <prime> <base>
|
|
<BR>
|
|
|
|
<B>keyctl</B> dh_compute_kdf <private> <prime> <base> <output_length> <hash_type>
|
|
<BR>
|
|
|
|
<B>keyctl</B> dh_compute_kdf_oi <private> <prime> <base> <output_length> <hash_type>
|
|
<BR>
|
|
|
|
<B>keyctl</B> pkey_query <key> <pass> [k=v]*
|
|
<BR>
|
|
|
|
<B>keyctl</B> pkey_encrypt <key> <pass> <datafile> [k=v]* ><encfile>
|
|
<BR>
|
|
|
|
<B>keyctl</B> pkey_decrypt <key> <pass> <encfile> [k=v]* ><datafile>
|
|
<BR>
|
|
|
|
<B>keyctl</B> pkey_sign <key> <pass> <datafile> [k=v]* ><sigfile>
|
|
<BR>
|
|
|
|
<B>keyctl</B> pkey_decrypt <key> <pass> <datafile> <sigfile> [k=v]*
|
|
<A NAME="lbAD"> </A>
|
|
<H2>DESCRIPTION</H2>
|
|
|
|
This program is used to control the key management facility in various ways
|
|
using a variety of subcommands.
|
|
<A NAME="lbAE"> </A>
|
|
<H2>KEY IDENTIFIERS</H2>
|
|
|
|
The key identifiers passed to or returned from keyctl are, in general, positive
|
|
integers. There are, however, some special values with special meanings that
|
|
can be passed as arguments:
|
|
<DL COMPACT>
|
|
<DT id="1">No key: <B>0</B><DD>
|
|
<DT id="2">Thread keyring: <B>@t</B> or <B>-1</B><DD>
|
|
Each thread may have its own keyring. This is searched first, before all
|
|
others. The thread keyring is replaced by (v)fork, exec and clone.
|
|
<DT id="3">Process keyring: <B>@p</B> or <B>-2</B><DD>
|
|
Each process (thread group) may have its own keyring. This is shared between
|
|
all members of a group and will be searched after the thread keyring. The
|
|
process keyring is replaced by (v)fork and exec.
|
|
<DT id="4">Session keyring: <B>@s</B> or <B>-3</B><DD>
|
|
Each process subscribes to a session keyring that is inherited across (v)fork,
|
|
exec and clone. This is searched after the process keyring. Session keyrings
|
|
can be named and an extant keyring can be joined in place of a process's
|
|
current session keyring.
|
|
<DT id="5">User specific keyring: <B>@u</B> or <B>-4</B><DD>
|
|
This keyring is shared between all the processes owned by a particular user. It
|
|
isn't searched directly, but is normally linked to from the session keyring.
|
|
<DT id="6">User default session keyring: <B>@us</B> or <B>-5</B><DD>
|
|
This is the default session keyring for a particular user. Login processes that
|
|
change to a particular user will bind to this session until another session is
|
|
set.
|
|
<DT id="7">Group specific keyring: <B>@g</B> or <B>-6</B><DD>
|
|
This is a place holder for a group specific keyring, but is not actually
|
|
implemented yet in the kernel.
|
|
<DT id="8">Assumed request_key authorisation key: <B>@a</B> or <B>-7</B><DD>
|
|
This selects the authorisation key provided to the
|
|
<B>request_key</B>()
|
|
|
|
helper to
|
|
permit it to access the callers keyrings and instantiate the target key.
|
|
<DT id="9">Keyring by name: <B>%:<name></B><DD>
|
|
A named keyring. This will be searched for in the process's keyrings and in
|
|
<I>/proc/keys</I>.
|
|
|
|
<DT id="10">Key by name: <B>%<type>:<name></B><DD>
|
|
A named key of the given type. This will be searched for in the process's
|
|
keyrings and in
|
|
<I>/proc/keys</I>.
|
|
|
|
</DL>
|
|
<A NAME="lbAF"> </A>
|
|
<H2>COMMAND SYNTAX</H2>
|
|
|
|
Any non-ambiguous shortening of a command name may be used in lieu of the full
|
|
command name. This facility should not be used in scripting as new commands may
|
|
be added in future that then cause ambiguity.
|
|
<A NAME="lbAG"> </A>
|
|
<H3>Display the package version number</H3>
|
|
|
|
<B>keyctl --version</B>
|
|
<P>
|
|
This command prints the package version number and build date and exits:
|
|
<P>
|
|
<DL COMPACT><DT id="11"><DD>
|
|
<PRE>
|
|
$ keyctl --version
|
|
keyctl from keyutils-1.5.3 (Built 2011-08-24)
|
|
</PRE>
|
|
|
|
</DL>
|
|
|
|
<A NAME="lbAH"> </A>
|
|
<H3>Show process keyrings</H3>
|
|
|
|
<B>keyctl show [-x] [<keyring>]</B>
|
|
<P>
|
|
By default this command recursively shows what keyrings a process is subscribed
|
|
to and what keys and keyrings they contain. If a keyring is specified then
|
|
that keyring will be dumped instead. If <B>-x</B> is specified then the keyring
|
|
IDs will be dumped in hex instead of decimal.
|
|
<A NAME="lbAI"> </A>
|
|
<H3>Add a key to a keyring</H3>
|
|
|
|
<B>keyctl add</B> <type> <desc> <data> <keyring>
|
|
<BR>
|
|
|
|
<B>keyctl padd</B> <type> <desc> <keyring>
|
|
<P>
|
|
This command creates a key of the specified type and description; instantiates
|
|
it with the given data and attaches it to the specified keyring. It then prints
|
|
the new key's ID on stdout:
|
|
<P>
|
|
<DL COMPACT><DT id="12"><DD>
|
|
<PRE>
|
|
$ keyctl add user mykey stuff @u
|
|
26
|
|
</PRE>
|
|
|
|
</DL>
|
|
|
|
<P>
|
|
The <B>padd</B> variant of the command reads the data from stdin rather than
|
|
taking it from the command line:
|
|
<P>
|
|
<DL COMPACT><DT id="13"><DD>
|
|
|
|
$ echo -n stuff | keyctl padd user mykey @u
|
|
26
|
|
|
|
</DL>
|
|
|
|
<A NAME="lbAJ"> </A>
|
|
<H3>Request a key</H3>
|
|
|
|
<B>keyctl request</B> <type> <desc> [<dest_keyring>]
|
|
<BR>
|
|
|
|
<B>keyctl request2</B> <type> <desc> <info> [<dest_keyring>]
|
|
<BR>
|
|
|
|
<B>keyctl prequest2</B> <type> <desc> [<dest_keyring>]
|
|
<P>
|
|
These three commands request the lookup of a key of the given type and
|
|
description. The process's keyrings will be searched, and if a match is found
|
|
the matching key's ID will be printed to stdout; and if a destination keyring
|
|
is given, the key will be added to that keyring also.
|
|
<P>
|
|
If there is no key, the first command will simply return the error ENOKEY and
|
|
fail. The second and third commands will create a partial key with the type and
|
|
description, and call out to
|
|
<I>/sbin/request-key</I>
|
|
|
|
with that key and the
|
|
extra information supplied. This will then attempt to instantiate the key in
|
|
some manner, such that a valid key is obtained.
|
|
<P>
|
|
The third command is like the second, except that the callout information is
|
|
read from stdin rather than being passed on the command line.
|
|
<P>
|
|
If a valid key is obtained, the ID will be printed and the key attached as if
|
|
the original search had succeeded.
|
|
<P>
|
|
If there wasn't a valid key obtained, a temporary negative key will be attached
|
|
to the destination keyring if given and the error "Requested key not available"
|
|
will be given.
|
|
<P>
|
|
<DL COMPACT><DT id="14"><DD>
|
|
<PRE>
|
|
$ keyctl request2 user debug:hello wibble
|
|
23
|
|
$ echo -n wibble | keyctl prequest2 user debug:hello
|
|
23
|
|
$ keyctl request user debug:hello
|
|
23
|
|
</PRE>
|
|
|
|
</DL>
|
|
|
|
<A NAME="lbAK"> </A>
|
|
<H3>Update a key</H3>
|
|
|
|
<B>keyctl update</B> <key> <data>
|
|
<BR>
|
|
|
|
<B>keyctl pupdate</B> <key>
|
|
<P>
|
|
This command replaces the data attached to a key with a new set of data. If the
|
|
type of the key doesn't support update then error "Operation not supported"
|
|
will be returned.
|
|
<P>
|
|
<DL COMPACT><DT id="15"><DD>
|
|
<PRE>
|
|
$ keyctl update 23 zebra
|
|
</PRE>
|
|
|
|
</DL>
|
|
|
|
<P>
|
|
The <B>pupdate</B> variant of the command reads the data from stdin rather than
|
|
taking it from the command line:
|
|
<P>
|
|
<DL COMPACT><DT id="16"><DD>
|
|
<PRE>
|
|
$ echo -n zebra | keyctl pupdate 23
|
|
</PRE>
|
|
|
|
</DL>
|
|
|
|
<A NAME="lbAL"> </A>
|
|
<H3>Create a keyring</H3>
|
|
|
|
<B>keyctl newring</B> <name> <keyring>
|
|
<P>
|
|
This command creates a new keyring of the specified name and attaches it to the
|
|
specified keyring. The ID of the new keyring will be printed to stdout if
|
|
successful.
|
|
<P>
|
|
<DL COMPACT><DT id="17"><DD>
|
|
<PRE>
|
|
$ keyctl newring squelch @us
|
|
27
|
|
</PRE>
|
|
|
|
</DL>
|
|
|
|
<A NAME="lbAM"> </A>
|
|
<H3>Revoke a key</H3>
|
|
|
|
<B>keyctl revoke</B> <key>
|
|
<P>
|
|
This command marks a key as being revoked. Any further operations on that key
|
|
(apart from unlinking it) will return error "Key has been revoked".
|
|
<P>
|
|
<DL COMPACT><DT id="18"><DD>
|
|
<PRE>
|
|
$ keyctl revoke 26
|
|
$ keyctl describe 26
|
|
keyctl_describe: Key has been revoked
|
|
</PRE>
|
|
|
|
</DL>
|
|
|
|
<A NAME="lbAN"> </A>
|
|
<H3>Clear a keyring</H3>
|
|
|
|
<B>keyctl clear</B> <keyring>
|
|
<P>
|
|
This command unlinks all the keys attached to the specified keyring. Error
|
|
"Not a directory" will be returned if the key specified is not a keyring.
|
|
<P>
|
|
<DL COMPACT><DT id="19"><DD>
|
|
<PRE>
|
|
$ keyctl clear 27
|
|
</PRE>
|
|
|
|
</DL>
|
|
|
|
<A NAME="lbAO"> </A>
|
|
<H3>Link a key to a keyring</H3>
|
|
|
|
<B>keyctl link</B> <key> <keyring>
|
|
<P>
|
|
This command makes a link from the key to the keyring if there's enough
|
|
capacity to do so. Error "Not a directory" will be returned if the destination
|
|
is not a keyring. Error "Permission denied" will be returned if the key doesn't
|
|
have link permission or the keyring doesn't have write permission. Error "File
|
|
table overflow" will be returned if the keyring is full. Error "Resource
|
|
deadlock avoided" will be returned if an attempt was made to introduce a
|
|
recursive link.
|
|
<P>
|
|
<DL COMPACT><DT id="20"><DD>
|
|
<PRE>
|
|
$ keyctl link 23 27
|
|
$ keyctl link 27 27
|
|
keyctl_link: Resource deadlock avoided
|
|
</PRE>
|
|
|
|
</DL>
|
|
|
|
<A NAME="lbAP"> </A>
|
|
<H3>Unlink a key from a keyring or the session keyring tree</H3>
|
|
|
|
<B>keyctl unlink</B> <key> [<keyring>]
|
|
<P>
|
|
If the keyring is specified, this command removes a link to the key from the
|
|
keyring. Error "Not a directory" will be returned if the destination is not a
|
|
keyring. Error "Permission denied" will be returned if the keyring doesn't have
|
|
write permission. Error "No such file or directory" will be returned if the key
|
|
is not linked to by the keyring.
|
|
<P>
|
|
If the keyring is not specified, this command performs a depth-first search of
|
|
the session keyring tree and removes all the links to the nominated key that it
|
|
finds (and that it is permitted to remove). It prints the number of successful
|
|
unlinks before exiting.
|
|
<P>
|
|
<DL COMPACT><DT id="21"><DD>
|
|
<PRE>
|
|
$ keyctl unlink 23 27
|
|
</PRE>
|
|
|
|
</DL>
|
|
|
|
<A NAME="lbAQ"> </A>
|
|
<H3>Search a keyring</H3>
|
|
|
|
<B>keyctl search</B> <keyring> <type> <desc> [<dest_keyring>]
|
|
<P>
|
|
This command non-recursively searches a keyring for a key of a particular type
|
|
and description. If found, the ID of the key will be printed on stdout and the
|
|
key will be attached to the destination keyring if present. Error "Requested
|
|
key not available" will be returned if the key is not found.
|
|
<P>
|
|
<DL COMPACT><DT id="22"><DD>
|
|
<PRE>
|
|
$ keyctl search @us user debug:hello
|
|
23
|
|
$ keyctl search @us user debug:bye
|
|
keyctl_search: Requested key not available
|
|
</PRE>
|
|
|
|
</DL>
|
|
|
|
<A NAME="lbAR"> </A>
|
|
<H3>Restrict a keyring</H3>
|
|
|
|
<B>keyctl restrict_keyring</B> <keyring> [<type> [<restriction>]]
|
|
<P>
|
|
This command limits the linkage of keys to the given keyring using a provided
|
|
restriction scheme. The scheme is associated with a given key type, with
|
|
further details provided in the restriction option string. Options typically
|
|
contain a restriction name possibly followed by key ids or other data relevant
|
|
to the restriction. If no restriction scheme is provided, the keyring will
|
|
reject all links.
|
|
<P>
|
|
<DL COMPACT><DT id="23"><DD>
|
|
<PRE>
|
|
$ keyctl restrict_keyring $1 asymmetric builtin_trusted
|
|
</DL>
|
|
</PRE><A NAME="lbAS"> </A>
|
|
<H3>Read a key</H3>
|
|
|
|
<B>keyctl read</B> <key>
|
|
<BR>
|
|
|
|
<B>keyctl pipe</B> <key>
|
|
<BR>
|
|
|
|
<B>keyctl print</B> <key>
|
|
<P>
|
|
These commands read the payload of a key. "read" prints it on stdout as a hex
|
|
dump, "pipe" dumps the raw data to stdout and "print" dumps it to stdout
|
|
directly if it's entirely printable or as a hexdump preceded by ":hex:" if not.
|
|
<P>
|
|
If the key type does not support reading of the payload, then error "Operation
|
|
not supported" will be returned.
|
|
<P>
|
|
<DL COMPACT><DT id="24"><DD>
|
|
<PRE>
|
|
$ keyctl read 26
|
|
1 bytes of data in key:
|
|
62
|
|
$ keyctl print 26
|
|
b
|
|
$ keyctl pipe 26
|
|
$
|
|
</PRE>
|
|
|
|
</DL>
|
|
|
|
<A NAME="lbAT"> </A>
|
|
<H3>List a keyring</H3>
|
|
|
|
<B>keyctl list</B> <keyring>
|
|
<BR>
|
|
|
|
<B>keyctl rlist</B> <keyring>
|
|
<P>
|
|
These commands list the contents of a key as a keyring. "list" pretty prints
|
|
the contents and "rlist" just produces a space-separated list of key IDs.
|
|
<P>
|
|
No attempt is made to check that the specified keyring is a keyring.
|
|
<P>
|
|
<DL COMPACT><DT id="25"><DD>
|
|
<PRE>
|
|
$ keyctl list @us
|
|
2 keys in keyring:
|
|
22: vrwsl---------- 4043 -1 keyring: _uid.4043
|
|
23: vrwsl---------- 4043 4043 user: debug:hello
|
|
$ keyctl rlist @us
|
|
22 23
|
|
</PRE>
|
|
|
|
</DL>
|
|
|
|
<A NAME="lbAU"> </A>
|
|
<H3>Describe a key</H3>
|
|
|
|
<B>keyctl describe</B> <keyring>
|
|
<BR>
|
|
|
|
<B>keyctl rdescribe</B> <keyring> [sep]
|
|
<P>
|
|
These commands fetch a description of a keyring. "describe" pretty prints the
|
|
description in the same fashion as the "list" command; "rdescribe" prints the
|
|
raw data returned from the kernel.
|
|
<P>
|
|
<DL COMPACT><DT id="26"><DD>
|
|
<PRE>
|
|
$ keyctl describe @us
|
|
-5: vrwsl---------- 4043 -1 keyring: _uid_ses.4043
|
|
$ keyctl rdescribe @us
|
|
keyring;4043;-1;3f1f0000;_uid_ses.4043
|
|
</PRE>
|
|
|
|
</DL>
|
|
|
|
<P>
|
|
The raw string is "<type>;<uid>;<gid>;<perms>;<description>", where <I>uid</I>
|
|
and <I>gid</I> are the decimal user and group IDs, <I>perms</I> is the
|
|
permissions mask in hex, <I>type</I> and <I>description</I> are the type name and
|
|
description strings (neither of which will contain semicolons).
|
|
<A NAME="lbAV"> </A>
|
|
<H3>Change the access controls on a key</H3>
|
|
|
|
<B>keyctl chown</B> <key> <uid>
|
|
<BR>
|
|
|
|
<B>keyctl chgrp</B> <key> <gid>
|
|
<P>
|
|
These two commands change the UID and GID associated with evaluating a key's
|
|
permissions mask. The UID also governs which quota a key is taken out of.
|
|
<P>
|
|
The chown command is not currently supported; attempting it will earn the error
|
|
"Operation not supported" at best.
|
|
<P>
|
|
For non-superuser users, the GID may only be set to the process's GID or a GID
|
|
in the process's groups list. The superuser may set any GID it likes.
|
|
<P>
|
|
<DL COMPACT><DT id="27"><DD>
|
|
<PRE>
|
|
$ sudo keyctl chown 27 0
|
|
keyctl_chown: Operation not supported
|
|
$ sudo keyctl chgrp 27 0
|
|
</PRE>
|
|
|
|
</DL>
|
|
|
|
<A NAME="lbAW"> </A>
|
|
<H3>Set the permissions mask on a key</H3>
|
|
|
|
<B>keyctl setperm</B> <key> <mask>
|
|
<P>
|
|
This command changes the permission control mask on a key. The mask may be
|
|
specified as a hex number if it begins "0x", an octal number if it begins "0"
|
|
or a decimal number otherwise.
|
|
<P>
|
|
The hex numbers are a combination of:
|
|
<P>
|
|
<DL COMPACT><DT id="28"><DD>
|
|
<PRE>
|
|
Possessor UID GID Other Permission Granted
|
|
======== ======== ======== ======== ==================
|
|
01000000 00010000 00000100 00000001 View
|
|
02000000 00020000 00000200 00000002 Read
|
|
04000000 00040000 00000400 00000004 Write
|
|
08000000 00080000 00000800 00000008 Search
|
|
10000000 00100000 00001000 00000010 Link
|
|
20000000 00200000 00002000 00000020 Set Attribute
|
|
3f000000 003f0000 00003f00 0000003f All
|
|
</PRE>
|
|
|
|
</DL>
|
|
|
|
<P>
|
|
<I>View</I> permits the type, description and other parameters of a key to be
|
|
viewed.
|
|
<P>
|
|
<I>Read</I> permits the payload (or keyring list) to be read if supported by the
|
|
type.
|
|
<P>
|
|
<I>Write</I> permits the payload (or keyring list) to be modified or updated.
|
|
<P>
|
|
<I>Search</I> on a key permits it to be found when a keyring to which it is
|
|
linked is searched.
|
|
<P>
|
|
<I>Link</I> permits a key to be linked to a keyring.
|
|
<P>
|
|
<I>Set Attribute</I> permits a key to have its owner, group membership,
|
|
permissions mask and timeout changed.
|
|
<P>
|
|
<DL COMPACT><DT id="29"><DD>
|
|
<PRE>
|
|
$ keyctl setperm 27 0x1f1f1f00
|
|
</PRE>
|
|
|
|
</DL>
|
|
|
|
<A NAME="lbAX"> </A>
|
|
<H3>Start a new session with fresh keyrings</H3>
|
|
|
|
<B>keyctl session</B>
|
|
<BR>
|
|
|
|
<B>keyctl session</B> - [<prog> <arg1> <arg2> ...]
|
|
<BR>
|
|
|
|
<B>keyctl session</B> <name> [<prog> <arg1> <arg2> ...]
|
|
<P>
|
|
These commands join or create a new keyring and then run a shell or other
|
|
program with that keyring as the session key.
|
|
<P>
|
|
The variation with no arguments just creates an anonymous session keyring and
|
|
attaches that as the session keyring; it then exec's $SHELL.
|
|
<P>
|
|
The variation with a dash in place of a name creates an anonymous session
|
|
keyring and attaches that as the session keyring; it then exec's the supplied
|
|
command, or $SHELL if one isn't supplied.
|
|
<P>
|
|
The variation with a name supplied creates or joins the named keyring and
|
|
attaches that as the session keyring; it then exec's the supplied command, or
|
|
$SHELL if one isn't supplied.
|
|
<P>
|
|
<DL COMPACT><DT id="30"><DD>
|
|
<PRE>
|
|
$ keyctl rdescribe @s
|
|
keyring;4043;-1;3f1f0000;_uid_ses.4043
|
|
|
|
$ keyctl session
|
|
Joined session keyring: 28
|
|
|
|
$ keyctl rdescribe @s
|
|
keyring;4043;4043;3f1f0000;_ses.24082
|
|
|
|
$ keyctl session -
|
|
Joined session keyring: 29
|
|
$ keyctl rdescribe @s
|
|
keyring;4043;4043;3f1f0000;_ses.24139
|
|
|
|
$ keyctl session - keyctl rdescribe @s
|
|
Joined session keyring: 30
|
|
keyring;4043;4043;3f1f0000;_ses.24185
|
|
|
|
$ keyctl session fish
|
|
Joined session keyring: 34
|
|
$ keyctl rdescribe @s
|
|
keyring;4043;4043;3f1f0000;fish
|
|
|
|
$ keyctl session fish keyctl rdesc @s
|
|
Joined session keyring: 35
|
|
keyring;4043;4043;3f1f0000;fish
|
|
</PRE>
|
|
|
|
</DL>
|
|
|
|
<A NAME="lbAY"> </A>
|
|
<H3>Instantiate a key</H3>
|
|
|
|
<B>keyctl instantiate</B> <key> <data> <keyring>
|
|
<BR>
|
|
|
|
<B>keyctl pinstantiate</B> <key> <keyring>
|
|
<BR>
|
|
|
|
<B>keyctl negate</B> <key> <timeout> <keyring>
|
|
<BR>
|
|
|
|
<B>keyctl reject</B> <key> <timeout> <error> <keyring>
|
|
<P>
|
|
These commands are used to attach data to a partially set up key (as created by
|
|
the kernel and passed to
|
|
<I>/sbin/request-key</I>).
|
|
|
|
"instantiate" marks a key as
|
|
being valid and attaches the data as the payload. "negate" and "reject" mark a
|
|
key as invalid and sets a timeout on it so that it'll go away after a while.
|
|
This prevents a lot of quickly sequential requests from slowing the system down
|
|
overmuch when they all fail, as all subsequent requests will then fail with
|
|
error "Requested key not found" (if negated) or the specified error (if
|
|
rejected) until the negative key has expired.
|
|
<P>
|
|
Reject's error argument can either be a UNIX error number or one of
|
|
<B></B>'<B>rejected</B>', '<B>expired</B>' or '<B>revoked</B>'.
|
|
|
|
<P>
|
|
The newly instantiated key will be attached to the specified keyring.
|
|
<P>
|
|
These commands may only be run from the program run by request-key - a special
|
|
authorisation key is set up by the kernel and attached to the request-key's
|
|
session keyring. This special key is revoked once the key to which it refers
|
|
has been instantiated one way or another.
|
|
<P>
|
|
<DL COMPACT><DT id="31"><DD>
|
|
<PRE>
|
|
$ keyctl instantiate $1 "Debug $3" $4
|
|
$ keyctl negate $1 30 $4
|
|
$ keyctl reject $1 30 64 $4
|
|
</PRE>
|
|
|
|
</DL>
|
|
|
|
<P>
|
|
The <B>pinstantiate</B> variant of the command reads the data from stdin rather
|
|
than taking it from the command line:
|
|
<P>
|
|
<DL COMPACT><DT id="32"><DD>
|
|
<PRE>
|
|
$ echo -n "Debug $3" | keyctl pinstantiate $1 $4
|
|
</PRE>
|
|
|
|
</DL>
|
|
|
|
<A NAME="lbAZ"> </A>
|
|
<H3>Set the expiry time on a key</H3>
|
|
|
|
<B>keyctl timeout</B> <key> <timeout>
|
|
<P>
|
|
This command is used to set the timeout on a key, or clear an existing timeout
|
|
if the value specified is zero. The timeout is given as a number of seconds
|
|
into the future.
|
|
<P>
|
|
<DL COMPACT><DT id="33"><DD>
|
|
<PRE>
|
|
$ keyctl timeout $1 45
|
|
</PRE>
|
|
|
|
</DL>
|
|
|
|
<A NAME="lbBA"> </A>
|
|
<H3>Retrieve a key's security context</H3>
|
|
|
|
<B>keyctl security</B> <key>
|
|
<P>
|
|
This command is used to retrieve a key's LSM security context. The label is
|
|
printed on stdout.
|
|
<P>
|
|
<DL COMPACT><DT id="34"><DD>
|
|
<PRE>
|
|
$ keyctl security @s
|
|
unconfined_u:unconfined_r:unconfined_t:s0-s0:c0.c1023
|
|
</PRE>
|
|
|
|
</DL>
|
|
|
|
<A NAME="lbBB"> </A>
|
|
<H3>Give the parent process a new session keyring</H3>
|
|
|
|
<B>keyctl new_session</B>
|
|
<P>
|
|
This command is used to give the invoking process (typically a shell) a new
|
|
session keyring, discarding its old session keyring.
|
|
<P>
|
|
<DL COMPACT><DT id="35"><DD>
|
|
<PRE>
|
|
$ keyctl session foo
|
|
Joined session keyring: 723488146
|
|
$ keyctl show
|
|
Session Keyring
|
|
-3 --alswrv 0 0 keyring: foo
|
|
$ keyctl new_session
|
|
490511412
|
|
$ keyctl show
|
|
Session Keyring
|
|
-3 --alswrv 0 0 keyring: _ses
|
|
</PRE>
|
|
|
|
</DL>
|
|
|
|
<P>
|
|
Note that this affects the <I>parent</I> of the process that invokes the system
|
|
call, and so may only affect processes with matching credentials.
|
|
Furthermore, the change does not take effect till the parent process next
|
|
transitions from kernel space to user space - typically when the <B>wait</B>()
|
|
system call returns.
|
|
<A NAME="lbBC"> </A>
|
|
<H3>Remove dead keys from the session keyring tree</H3>
|
|
|
|
<B>keyctl reap</B>
|
|
<P>
|
|
This command performs a depth-first search of the caller's session keyring tree
|
|
and attempts to unlink any key that it finds that is inaccessible due to
|
|
expiry, revocation, rejection or negation. It does not attempt to remove live
|
|
keys that are unavailable simply due to a lack of granted permission.
|
|
<P>
|
|
A key that is designated reapable will only be removed from a keyring if the
|
|
caller has Write permission on that keyring, and only keyrings that grant
|
|
Search permission to the caller will be searched.
|
|
<P>
|
|
The command prints the number of keys reaped before it exits. If the <B>-v</B>
|
|
flag is passed then the reaped keys are listed as they're being reaped,
|
|
together with the success or failure of the unlink.
|
|
<A NAME="lbBD"> </A>
|
|
<H3>Remove matching keys from the session keyring tree</H3>
|
|
|
|
<B>keyctl</B> purge <type>
|
|
<BR>
|
|
|
|
<B>keyctl</B> purge [-i] [-p] <type> <desc>
|
|
<BR>
|
|
|
|
<B>keyctl</B> purge -s <type> <desc>
|
|
<P>
|
|
These commands perform a depth-first search to find matching keys in the
|
|
caller's session keyring tree and attempts to unlink them. The number of
|
|
keys successfully unlinked is printed at the end.
|
|
<P>
|
|
The keyrings must grant Read and View permission to the caller to be searched,
|
|
and the keys to be removed must also grant View permission. Keys can only be
|
|
removed from keyrings that grant Write permission.
|
|
<P>
|
|
The first variant purges all keys of the specified type.
|
|
<P>
|
|
The second variant purges all keys of the specified type that also match the
|
|
given description literally. The -i flag allows a case-independent match and
|
|
the -p flag allows a prefix match.
|
|
<P>
|
|
The third variant purges all keys of the specified type and matching
|
|
description using the key type's comparator in the kernel to match the
|
|
description. This permits the key type to match a key with a variety of
|
|
descriptions.
|
|
<A NAME="lbBE"> </A>
|
|
<H3>Get persistent keyring</H3>
|
|
|
|
<B>keyctl</B> get_persistent <keyring> [<uid>]
|
|
<P>
|
|
This command gets the persistent keyring for either the current UID or the
|
|
specified UID and attaches it to the nominated keyring. The persistent
|
|
keyring's ID will be printed on stdout.
|
|
<P>
|
|
The kernel will create the keyring if it doesn't exist and every time this
|
|
command is called, will reset the expiration timeout on the keyring to the
|
|
value in:
|
|
<DL COMPACT>
|
|
<DT id="36"><DD>
|
|
/proc/sys/kernel/keys/persistent_keyring_expiry
|
|
</DL>
|
|
<P>
|
|
|
|
(by default three days). Should the timeout be reached, the persistent keyring
|
|
will be removed and everything it pins can then be garbage collected.
|
|
<P>
|
|
If a UID other than the process's real or effective UIDs is specified, then an
|
|
error will be given if the process does not have the CAP_SETUID capability.
|
|
<A NAME="lbBF"> </A>
|
|
<H3>Compute a Diffie-Hellman shared secret or public key</H3>
|
|
|
|
<B>keyctl</B> dh_compute <private> <prime> <base>
|
|
<P>
|
|
This command computes either a Diffie-Hellman shared secret or the
|
|
public key corresponding to the provided private key using the
|
|
payloads of three keys. The computation is:
|
|
<DL COMPACT>
|
|
<DT id="37"><DD>
|
|
base ^ private (mod prime)
|
|
</DL>
|
|
<P>
|
|
|
|
The three inputs must be user keys with read permission. If the
|
|
provided base key contains the shared generator value, the public key
|
|
will be computed. If the provided base key contains the remote public
|
|
key value, the shared secret will be computed.
|
|
<P>
|
|
The result is printed to stdout as a hex dump.
|
|
<P>
|
|
<DL COMPACT><DT id="38"><DD>
|
|
<PRE>
|
|
$ keyctl dh_compute $1 $2 $3
|
|
8 bytes of data in result:
|
|
00010203 04050607
|
|
</DL>
|
|
</PRE><A NAME="lbBG"> </A>
|
|
<H3>Compute a Diffie-Hellman shared secret and derive key material</H3>
|
|
|
|
<B>keyctl</B> dh_compute_kdf <private> <prime> <base> <output_length> <hash_type>
|
|
<P>
|
|
This command computes a Diffie-Hellman shared secret and derives
|
|
key material from the shared secret using a key derivation function (KDF).
|
|
The shared secret is derived as outlined above and is input to the KDF
|
|
using the specified hash type. The hash type must point to a hash name
|
|
known to the kernel crypto API.
|
|
<P>
|
|
The operation derives key material of the length specified by the caller.
|
|
<P>
|
|
The operation is compliant to the specification of SP800-56A.
|
|
<P>
|
|
The result is printed to stdout as hex dump.
|
|
<A NAME="lbBH"> </A>
|
|
<H3>Compute a Diffie-Hellman shared secret and apply KDF with other input</H3>
|
|
|
|
<B>keyctl</B> dh_compute_kdf_oi <private> <prime> <base> <output_length> <hash_type>
|
|
<P>
|
|
This command is identical to the command
|
|
<I>dh_compute_kdf</I>
|
|
|
|
to generate a Diffie-Hellman shared secret followed by a key derivation
|
|
operation. This command allows the caller to provide the other input data
|
|
(OI data) compliant to SP800-56A via stdin.
|
|
|
|
|
|
<A NAME="lbBI"> </A>
|
|
<H3>Perform public-key operations with an asymmetric key</H3>
|
|
|
|
<B>keyctl</B> pkey_query <key> <pass> [k=v]*
|
|
<BR>
|
|
|
|
<B>keyctl</B> pkey_encrypt <key> <pass> <datafile> [k=v]* > <encfile>
|
|
<BR>
|
|
|
|
<B>keyctl</B> pkey_decrypt <key> <pass> <encfile> [k=v]* > <datafile>
|
|
<BR>
|
|
|
|
<B>keyctl</B> pkey_sign <key> <pass> <datafile> [k=v]* > <sigfile>
|
|
<BR>
|
|
|
|
<B>keyctl</B> pkey_verify <key> <pass> <datafile> <sigfile> [k=v]*
|
|
<P>
|
|
|
|
These commands query an asymmetric key, encrypt data with it, decrypt the
|
|
encrypted data, generate a signature over some data and verify that signature.
|
|
For encrypt, decrypt and sign, the resulting data is written to stdout; verify
|
|
reads the data and the signature files and compares them.
|
|
<P>
|
|
|
|
[<B>!</B>] NOTE that the data is of very limited capacity, with no more bits
|
|
than the size of the key. For signatures, the caller is expected to digest
|
|
the actual data and pass in the result of the digest as the datafile. The
|
|
name of the digest should be specified on the end of the command line as
|
|
"hash=<name>".
|
|
<P>
|
|
|
|
The
|
|
<I>key</I>
|
|
|
|
ID indicates the key to use;
|
|
<I>pass</I>
|
|
|
|
is a placeholder for future password provision and should be "0" for the
|
|
moment;
|
|
<I>datafile</I>
|
|
|
|
is the unencrypted data to be encrypted, signed or to have its signature
|
|
checked;
|
|
<I>encfile</I>
|
|
|
|
is a file containing encrypted data; and
|
|
<I>sigfile</I>
|
|
|
|
is a file containing a signature.
|
|
<P>
|
|
|
|
A list of parameters in "key[=val]" form can be included on the end of the
|
|
command line. These specify things like the digest algorithm used
|
|
("hash=<name>") or the encoding form ("enc=<type>").
|
|
<P>
|
|
|
|
<DL COMPACT><DT id="39"><DD>
|
|
<PRE>
|
|
k=`keyctl padd asymmetric "" @s <key.pkcs8.der`
|
|
keyctl pkey_query $k 0 enc=pkcs1 hash=sha256
|
|
keyctl pkey_encrypt $k 0 foo.hash enc=pkcs1 >foo.enc
|
|
keyctl pkey_decrypt $k 0 foo.enc enc=pkcs1 >foo.hash
|
|
keyctl pkey_sign $k 0 foo.hash enc=pkcs1 hash=sha256 >foo.sig
|
|
keyctl pkey_verify $k 0 foo.hash foo.sig enc=pkcs1 hash=sha256
|
|
</PRE>
|
|
|
|
</DL>
|
|
|
|
<P>
|
|
|
|
See <A HREF="/cgi-bin/man/man2html?7+asymmetric-key">asymmetric-key</A>(7) for more information.
|
|
<P>
|
|
<A NAME="lbBJ"> </A>
|
|
<H2>ERRORS</H2>
|
|
|
|
There are a number of common errors returned by this program:
|
|
<P>
|
|
"Not a directory" - a key wasn't a keyring.
|
|
<P>
|
|
"Requested key not found" - the looked for key isn't available.
|
|
<P>
|
|
"Key has been revoked" - a revoked key was accessed.
|
|
<P>
|
|
"Key has expired" - an expired key was accessed.
|
|
<P>
|
|
"Permission denied" - permission was denied by a UID/GID/mask combination.
|
|
<A NAME="lbBK"> </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?2+keyctl">keyctl</A></B>(2),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?2+request_key">request_key</A></B>(2),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?3+keyctl">keyctl</A></B>(3),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?5+request-key.conf">request-key.conf</A></B>(5),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?7+keyrings">keyrings</A></B>(7),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?8+request-key">request-key</A></B>(8)
|
|
|
|
<P>
|
|
|
|
<HR>
|
|
<A NAME="index"> </A><H2>Index</H2>
|
|
<DL>
|
|
<DT id="40"><A HREF="#lbAB">NAME</A><DD>
|
|
<DT id="41"><A HREF="#lbAC">SYNOPSIS</A><DD>
|
|
<DT id="42"><A HREF="#lbAD">DESCRIPTION</A><DD>
|
|
<DT id="43"><A HREF="#lbAE">KEY IDENTIFIERS</A><DD>
|
|
<DT id="44"><A HREF="#lbAF">COMMAND SYNTAX</A><DD>
|
|
<DL>
|
|
<DT id="45"><A HREF="#lbAG">Display the package version number</A><DD>
|
|
<DT id="46"><A HREF="#lbAH">Show process keyrings</A><DD>
|
|
<DT id="47"><A HREF="#lbAI">Add a key to a keyring</A><DD>
|
|
<DT id="48"><A HREF="#lbAJ">Request a key</A><DD>
|
|
<DT id="49"><A HREF="#lbAK">Update a key</A><DD>
|
|
<DT id="50"><A HREF="#lbAL">Create a keyring</A><DD>
|
|
<DT id="51"><A HREF="#lbAM">Revoke a key</A><DD>
|
|
<DT id="52"><A HREF="#lbAN">Clear a keyring</A><DD>
|
|
<DT id="53"><A HREF="#lbAO">Link a key to a keyring</A><DD>
|
|
<DT id="54"><A HREF="#lbAP">Unlink a key from a keyring or the session keyring tree</A><DD>
|
|
<DT id="55"><A HREF="#lbAQ">Search a keyring</A><DD>
|
|
<DT id="56"><A HREF="#lbAR">Restrict a keyring</A><DD>
|
|
<DT id="57"><A HREF="#lbAS">Read a key</A><DD>
|
|
<DT id="58"><A HREF="#lbAT">List a keyring</A><DD>
|
|
<DT id="59"><A HREF="#lbAU">Describe a key</A><DD>
|
|
<DT id="60"><A HREF="#lbAV">Change the access controls on a key</A><DD>
|
|
<DT id="61"><A HREF="#lbAW">Set the permissions mask on a key</A><DD>
|
|
<DT id="62"><A HREF="#lbAX">Start a new session with fresh keyrings</A><DD>
|
|
<DT id="63"><A HREF="#lbAY">Instantiate a key</A><DD>
|
|
<DT id="64"><A HREF="#lbAZ">Set the expiry time on a key</A><DD>
|
|
<DT id="65"><A HREF="#lbBA">Retrieve a key's security context</A><DD>
|
|
<DT id="66"><A HREF="#lbBB">Give the parent process a new session keyring</A><DD>
|
|
<DT id="67"><A HREF="#lbBC">Remove dead keys from the session keyring tree</A><DD>
|
|
<DT id="68"><A HREF="#lbBD">Remove matching keys from the session keyring tree</A><DD>
|
|
<DT id="69"><A HREF="#lbBE">Get persistent keyring</A><DD>
|
|
<DT id="70"><A HREF="#lbBF">Compute a Diffie-Hellman shared secret or public key</A><DD>
|
|
<DT id="71"><A HREF="#lbBG">Compute a Diffie-Hellman shared secret and derive key material</A><DD>
|
|
<DT id="72"><A HREF="#lbBH">Compute a Diffie-Hellman shared secret and apply KDF with other input</A><DD>
|
|
<DT id="73"><A HREF="#lbBI">Perform public-key operations with an asymmetric key</A><DD>
|
|
</DL>
|
|
<DT id="74"><A HREF="#lbBJ">ERRORS</A><DD>
|
|
<DT id="75"><A HREF="#lbBK">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:05:17 GMT, March 31, 2021
|
|
</BODY>
|
|
</HTML>
|