3032 lines
75 KiB
HTML
3032 lines
75 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 Calls (2)<BR>Updated: 2019-03-06<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 - manipulate the kernel's key management facility
|
|
<A NAME="lbAC"> </A>
|
|
<H2>SYNOPSIS</H2>
|
|
|
|
<PRE>
|
|
<B>#include <<A HREF="file:///usr/include/sys/types.h">sys/types.h</A>></B>
|
|
<B>#include <<A HREF="file:///usr/include/keyutils.h">keyutils.h</A>></B>
|
|
|
|
<B>long keyctl(int </B><I>operation</I><B>, ...)</B>
|
|
|
|
<B>/* For direct call via <A HREF="/cgi-bin/man/man2html?2+syscall">syscall</A>(2): */</B>
|
|
<B>#include <<A HREF="file:///usr/include/asm/unistd.h">asm/unistd.h</A>></B>
|
|
<B>#include <<A HREF="file:///usr/include/linux/keyctl.h">linux/keyctl.h</A>></B>
|
|
<B>#include <<A HREF="file:///usr/include/unistd.h">unistd.h</A>></B>
|
|
|
|
<B>long syscall(__NR_keyctl, int </B><I>operation</I><B>, __kernel_ulong_t </B><I>arg2</I><B>,</B>
|
|
<B> __kernel_ulong_t </B><I>arg3</I><B>, __kernel_ulong_t </B><I>arg4</I><B>,</B>
|
|
<B> __kernel_ulong_t </B><I>arg5</I><B>);</B>
|
|
</PRE>
|
|
|
|
<P>
|
|
|
|
No glibc wrapper is provided for this system call; see NOTES.
|
|
<A NAME="lbAD"> </A>
|
|
<H2>DESCRIPTION</H2>
|
|
|
|
<B>keyctl</B>()
|
|
|
|
allows user-space programs to perform key manipulation.
|
|
<P>
|
|
|
|
The operation performed by
|
|
<B>keyctl</B>()
|
|
|
|
is determined by the value of the
|
|
<I>operation</I>
|
|
|
|
argument.
|
|
Each of these operations is wrapped by the
|
|
<I>libkeyutils</I>
|
|
|
|
library (provided by the
|
|
<I>keyutils</I>
|
|
|
|
package) into individual functions (noted below)
|
|
to permit the compiler to check types.
|
|
<P>
|
|
|
|
The permitted values for
|
|
<I>operation</I>
|
|
|
|
are:
|
|
<DL COMPACT>
|
|
<DT id="1"><B>KEYCTL_GET_KEYRING_ID</B> (since Linux 2.6.10)
|
|
|
|
<DD>
|
|
Map a special key ID to a real key ID for this process.
|
|
<DT id="2"><DD>
|
|
This operation looks up the special key whose ID is provided in
|
|
<I>arg2</I>
|
|
|
|
(cast to
|
|
<I>key_serial_t</I>).
|
|
|
|
If the special key is found,
|
|
the ID of the corresponding real key is returned as the function result.
|
|
The following values may be specified in
|
|
<I>arg2</I>:
|
|
|
|
<DL COMPACT><DT id="3"><DD>
|
|
<DL COMPACT>
|
|
<DT id="4"><B>KEY_SPEC_THREAD_KEYRING</B>
|
|
|
|
<DD>
|
|
This specifies the calling thread's thread-specific keyring.
|
|
See
|
|
<B><A HREF="/cgi-bin/man/man2html?7+thread-keyring">thread-keyring</A></B>(7).
|
|
|
|
<DT id="5"><B>KEY_SPEC_PROCESS_KEYRING</B>
|
|
|
|
<DD>
|
|
This specifies the caller's process-specific keyring.
|
|
See
|
|
<B><A HREF="/cgi-bin/man/man2html?7+process-keyring">process-keyring</A></B>(7).
|
|
|
|
<DT id="6"><B>KEY_SPEC_SESSION_KEYRING</B>
|
|
|
|
<DD>
|
|
This specifies the caller's session-specific keyring.
|
|
See
|
|
<B><A HREF="/cgi-bin/man/man2html?7+session-keyring">session-keyring</A></B>(7).
|
|
|
|
<DT id="7"><B>KEY_SPEC_USER_KEYRING</B>
|
|
|
|
<DD>
|
|
This specifies the caller's UID-specific keyring.
|
|
See
|
|
<B><A HREF="/cgi-bin/man/man2html?7+user-keyring">user-keyring</A></B>(7).
|
|
|
|
<DT id="8"><B>KEY_SPEC_USER_SESSION_KEYRING</B>
|
|
|
|
<DD>
|
|
This specifies the caller's UID-session keyring.
|
|
See
|
|
<B><A HREF="/cgi-bin/man/man2html?7+user-session-keyring">user-session-keyring</A></B>(7).
|
|
|
|
<DT id="9"><B>KEY_SPEC_REQKEY_AUTH_KEY</B> (since Linux 2.6.16)
|
|
|
|
<DD>
|
|
|
|
This specifies the authorization key created by
|
|
<B><A HREF="/cgi-bin/man/man2html?2+request_key">request_key</A></B>(2)
|
|
|
|
and passed to the process it spawns to generate a key.
|
|
This key is available only in a
|
|
<B><A HREF="/cgi-bin/man/man2html?8+request-key">request-key</A></B>(8)-style
|
|
|
|
program that was passed an authorization key by the kernel and
|
|
ceases to be available once the requested key has been instantiated; see
|
|
<B><A HREF="/cgi-bin/man/man2html?2+request_key">request_key</A></B>(2).
|
|
|
|
<DT id="10"><B>KEY_SPEC_REQUESTOR_KEYRING</B> (since Linux 2.6.29)
|
|
|
|
<DD>
|
|
|
|
This specifies the key ID for the
|
|
<B><A HREF="/cgi-bin/man/man2html?2+request_key">request_key</A></B>(2)
|
|
|
|
destination keyring.
|
|
This keyring is available only in a
|
|
<B><A HREF="/cgi-bin/man/man2html?8+request-key">request-key</A></B>(8)-style
|
|
|
|
program that was passed an authorization key by the kernel and
|
|
ceases to be available once the requested key has been instantiated; see
|
|
<B><A HREF="/cgi-bin/man/man2html?2+request_key">request_key</A></B>(2).
|
|
|
|
</DL>
|
|
</DL>
|
|
|
|
<DT id="11"><DD>
|
|
The behavior if the key specified in
|
|
<I>arg2</I>
|
|
|
|
does not exist depends on the value of
|
|
<I>arg3</I>
|
|
|
|
(cast to
|
|
<I>int</I>).
|
|
|
|
If
|
|
<I>arg3</I>
|
|
|
|
contains a nonzero value, then---if it is appropriate to do so
|
|
(e.g., when looking up the user, user-session, or session key)---a new key
|
|
is created and its real key ID returned as the function result.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Otherwise, the operation fails with the error
|
|
<B>ENOKEY</B>.
|
|
|
|
<DT id="12"><DD>
|
|
If a valid key ID is specified in
|
|
<I>arg2</I>,
|
|
|
|
and the key exists, then this operation simply returns the key ID.
|
|
If the key does not exist, the call fails with error
|
|
<B>ENOKEY</B>.
|
|
|
|
<DT id="13"><DD>
|
|
The caller must have
|
|
<I>search</I>
|
|
|
|
permission on a keyring in order for it to be found.
|
|
<DT id="14"><DD>
|
|
The arguments
|
|
<I>arg4</I>
|
|
|
|
and
|
|
<I>arg5</I>
|
|
|
|
are ignored.
|
|
<DT id="15"><DD>
|
|
This operation is exposed by
|
|
<I>libkeyutils</I>
|
|
|
|
via the function
|
|
<B><A HREF="/cgi-bin/man/man2html?3+keyctl_get_keyring_ID">keyctl_get_keyring_ID</A></B>(3).
|
|
|
|
<DT id="16"><B>KEYCTL_JOIN_SESSION_KEYRING</B> (since Linux 2.6.10)
|
|
|
|
<DD>
|
|
Replace the session keyring this process subscribes to with
|
|
a new session keyring.
|
|
|
|
|
|
<DT id="17"><DD>
|
|
If
|
|
<I>arg2</I>
|
|
|
|
is NULL,
|
|
an anonymous keyring with the description "_ses" is created
|
|
and the process is subscribed to that keyring as its session keyring,
|
|
displacing the previous session keyring.
|
|
<DT id="18"><DD>
|
|
Otherwise,
|
|
<I>arg2</I>
|
|
|
|
(cast to
|
|
<I>char *</I>)
|
|
|
|
is treated as the description (name) of a keyring,
|
|
and the behavior is as follows:
|
|
<DL COMPACT><DT id="19"><DD>
|
|
<DL COMPACT>
|
|
<DT id="20">*<DD>
|
|
If a keyring with a matching description exists,
|
|
the process will attempt to subscribe to that keyring
|
|
as its session keyring if possible;
|
|
if that is not possible, an error is returned.
|
|
In order to subscribe to the keyring,
|
|
the caller must have
|
|
<I>search</I>
|
|
|
|
permission on the keyring.
|
|
<DT id="21">*<DD>
|
|
If a keyring with a matching description does not exist,
|
|
then a new keyring with the specified description is created,
|
|
and the process is subscribed to that keyring as its session keyring.
|
|
</DL>
|
|
</DL>
|
|
|
|
<DT id="22"><DD>
|
|
The arguments
|
|
<I>arg3</I>,
|
|
|
|
<I>arg4</I>,
|
|
|
|
and
|
|
<I>arg5</I>
|
|
|
|
are ignored.
|
|
<DT id="23"><DD>
|
|
This operation is exposed by
|
|
<I>libkeyutils</I>
|
|
|
|
via the function
|
|
<B><A HREF="/cgi-bin/man/man2html?3+keyctl_join_session_keyring">keyctl_join_session_keyring</A></B>(3).
|
|
|
|
<DT id="24"><B>KEYCTL_UPDATE</B> (since Linux 2.6.10)
|
|
|
|
<DD>
|
|
Update a key's data payload.
|
|
<DT id="25"><DD>
|
|
The
|
|
<I>arg2</I>
|
|
|
|
argument (cast to
|
|
<I>key_serial_t</I>)
|
|
|
|
specifies the ID of the key to be updated.
|
|
The
|
|
<I>arg3</I>
|
|
|
|
argument (cast to
|
|
<I>void *</I>)
|
|
|
|
points to the new payload and
|
|
<I>arg4</I>
|
|
|
|
(cast to
|
|
<I>size_t</I>)
|
|
|
|
contains the new payload size in bytes.
|
|
<DT id="26"><DD>
|
|
The caller must have
|
|
<I>write</I>
|
|
|
|
permission on the key specified and the key type must support updating.
|
|
<DT id="27"><DD>
|
|
A negatively instantiated key (see the description of
|
|
<B>KEYCTL_REJECT</B>)
|
|
|
|
can be positively instantiated with this operation.
|
|
<DT id="28"><DD>
|
|
The
|
|
<I>arg5</I>
|
|
|
|
argument is ignored.
|
|
<DT id="29"><DD>
|
|
This operation is exposed by
|
|
<I>libkeyutils</I>
|
|
|
|
via the function
|
|
<B><A HREF="/cgi-bin/man/man2html?3+keyctl_update">keyctl_update</A></B>(3).
|
|
|
|
<DT id="30"><B>KEYCTL_REVOKE</B> (since Linux 2.6.10)
|
|
|
|
<DD>
|
|
Revoke the key with the ID provided in
|
|
<I>arg2</I>
|
|
|
|
(cast to
|
|
<I>key_serial_t</I>).
|
|
|
|
The key is scheduled for garbage collection;
|
|
it will no longer be findable,
|
|
and will be unavailable for further operations.
|
|
Further attempts to use the key will fail with the error
|
|
<B>EKEYREVOKED</B>.
|
|
|
|
<DT id="31"><DD>
|
|
The caller must have
|
|
<I>write</I>
|
|
|
|
or
|
|
<I>setattr</I>
|
|
|
|
permission on the key.
|
|
|
|
|
|
|
|
<DT id="32"><DD>
|
|
The arguments
|
|
<I>arg3</I>,
|
|
|
|
<I>arg4</I>,
|
|
|
|
and
|
|
<I>arg5</I>
|
|
|
|
are ignored.
|
|
<DT id="33"><DD>
|
|
This operation is exposed by
|
|
<I>libkeyutils</I>
|
|
|
|
via the function
|
|
<B><A HREF="/cgi-bin/man/man2html?3+keyctl_revoke">keyctl_revoke</A></B>(3).
|
|
|
|
<DT id="34"><B>KEYCTL_CHOWN</B> (since Linux 2.6.10)
|
|
|
|
<DD>
|
|
Change the ownership (user and group ID) of a key.
|
|
<DT id="35"><DD>
|
|
The
|
|
<I>arg2</I>
|
|
|
|
argument (cast to
|
|
<I>key_serial_t</I>)
|
|
|
|
contains the key ID.
|
|
The
|
|
<I>arg3</I>
|
|
|
|
argument (cast to
|
|
<I>uid_t</I>)
|
|
|
|
contains the new user ID (or -1 in case the user ID shouldn't be changed).
|
|
The
|
|
<I>arg4</I>
|
|
|
|
argument (cast to
|
|
<I>gid_t</I>)
|
|
|
|
contains the new group ID (or -1 in case the group ID shouldn't be changed).
|
|
<DT id="36"><DD>
|
|
The key must grant the caller
|
|
<I>setattr</I>
|
|
|
|
permission.
|
|
<DT id="37"><DD>
|
|
For the UID to be changed, or for the GID to be changed to a group
|
|
the caller is not a member of, the caller must have the
|
|
<B>CAP_SYS_ADMIN</B>
|
|
|
|
capability (see
|
|
<B><A HREF="/cgi-bin/man/man2html?7+capabilities">capabilities</A></B>(7)).
|
|
|
|
<DT id="38"><DD>
|
|
If the UID is to be changed, the new user must have sufficient
|
|
quota to accept the key.
|
|
The quota deduction will be removed from the old user
|
|
to the new user should the UID be changed.
|
|
<DT id="39"><DD>
|
|
The
|
|
<I>arg5</I>
|
|
|
|
argument is ignored.
|
|
<DT id="40"><DD>
|
|
This operation is exposed by
|
|
<I>libkeyutils</I>
|
|
|
|
via the function
|
|
<B><A HREF="/cgi-bin/man/man2html?3+keyctl_chown">keyctl_chown</A></B>(3).
|
|
|
|
<DT id="41"><B>KEYCTL_SETPERM</B> (since Linux 2.6.10)
|
|
|
|
<DD>
|
|
Change the permissions of the key with the ID provided in the
|
|
<I>arg2</I>
|
|
|
|
argument (cast to
|
|
<I>key_serial_t</I>)
|
|
|
|
to the permissions provided in the
|
|
<I>arg3</I>
|
|
|
|
argument (cast to
|
|
<I>key_perm_t</I>).
|
|
|
|
<DT id="42"><DD>
|
|
If the caller doesn't have the
|
|
<B>CAP_SYS_ADMIN</B>
|
|
|
|
capability, it can change permissions only for the keys it owns.
|
|
(More precisely: the caller's filesystem UID must match the UID of the key.)
|
|
<DT id="43"><DD>
|
|
The key must grant
|
|
<I>setattr</I>
|
|
|
|
permission to the caller
|
|
<I>regardless</I>
|
|
|
|
of the caller's capabilities.
|
|
|
|
|
|
<DT id="44"><DD>
|
|
The permissions in
|
|
<I>arg3</I>
|
|
|
|
specify masks of available operations
|
|
for each of the following user categories:
|
|
<DL COMPACT><DT id="45"><DD>
|
|
<DL COMPACT>
|
|
<DT id="46"><I>possessor</I> (since Linux 2.6.14)
|
|
|
|
<DD>
|
|
|
|
This is the permission granted to a process that possesses the key
|
|
(has it attached searchably to one of the process's keyrings);
|
|
see
|
|
<B><A HREF="/cgi-bin/man/man2html?7+keyrings">keyrings</A></B>(7).
|
|
|
|
<DT id="47"><I>user</I>
|
|
|
|
<DD>
|
|
This is the permission granted to a process
|
|
whose filesystem UID matches the UID of the key.
|
|
<DT id="48"><I>group</I>
|
|
|
|
<DD>
|
|
This is the permission granted to a process
|
|
whose filesystem GID or any of its supplementary GIDs
|
|
matches the GID of the key.
|
|
<DT id="49"><I>other</I>
|
|
|
|
<DD>
|
|
This is the permission granted to other processes
|
|
that do not match the
|
|
<I>user</I>
|
|
|
|
and
|
|
<I>group</I>
|
|
|
|
categories.
|
|
</DL>
|
|
</DL>
|
|
|
|
<DT id="50"><DD>
|
|
The
|
|
<I>user</I>,
|
|
|
|
<I>group</I>,
|
|
|
|
and
|
|
<I>other</I>
|
|
|
|
categories are exclusive: if a process matches the
|
|
<I>user</I>
|
|
|
|
category, it will not receive permissions granted in the
|
|
<I>group</I>
|
|
|
|
category; if a process matches the
|
|
<I>user</I>
|
|
|
|
or
|
|
<I>group</I>
|
|
|
|
category, then it will not receive permissions granted in the
|
|
<I>other</I>
|
|
|
|
category.
|
|
<DT id="51"><DD>
|
|
The
|
|
<I>possessor</I>
|
|
|
|
category grants permissions that are cumulative with the grants from the
|
|
<I>user</I>,
|
|
|
|
<I>group</I>,
|
|
|
|
or
|
|
<I>other</I>
|
|
|
|
category.
|
|
<DT id="52"><DD>
|
|
Each permission mask is eight bits in size,
|
|
with only six bits currently used.
|
|
The available permissions are:
|
|
<DL COMPACT><DT id="53"><DD>
|
|
<DL COMPACT>
|
|
<DT id="54"><I>view</I>
|
|
|
|
<DD>
|
|
This permission allows reading attributes of a key.
|
|
<DT id="55"><DD>
|
|
This permission is required for the
|
|
<B>KEYCTL_DESCRIBE</B>
|
|
|
|
operation.
|
|
<DT id="56"><DD>
|
|
The permission bits for each category are
|
|
<B>KEY_POS_VIEW</B>,
|
|
|
|
<B>KEY_USR_VIEW</B>,
|
|
|
|
<B>KEY_GRP_VIEW</B>,
|
|
|
|
and
|
|
<B>KEY_OTH_VIEW</B>.
|
|
|
|
<DT id="57"><I>read</I>
|
|
|
|
<DD>
|
|
This permission allows reading a key's payload.
|
|
<DT id="58"><DD>
|
|
This permission is required for the
|
|
<B>KEYCTL_READ</B>
|
|
|
|
operation.
|
|
<DT id="59"><DD>
|
|
The permission bits for each category are
|
|
<B>KEY_POS_READ</B>,
|
|
|
|
<B>KEY_USR_READ</B>,
|
|
|
|
<B>KEY_GRP_READ</B>,
|
|
|
|
and
|
|
<B>KEY_OTH_READ</B>.
|
|
|
|
<DT id="60"><I>write</I>
|
|
|
|
<DD>
|
|
This permission allows update or instantiation of a key's payload.
|
|
For a keyring, it allows keys to be linked and unlinked from the keyring,
|
|
<DT id="61"><DD>
|
|
This permission is required for the
|
|
<B>KEYCTL_UPDATE</B>,
|
|
|
|
<B>KEYCTL_REVOKE</B>,
|
|
|
|
<B>KEYCTL_CLEAR</B>,
|
|
|
|
<B>KEYCTL_LINK</B>,
|
|
|
|
and
|
|
<B>KEYCTL_UNLINK</B>
|
|
|
|
operations.
|
|
<DT id="62"><DD>
|
|
The permission bits for each category are
|
|
<B>KEY_POS_WRITE</B>,
|
|
|
|
<B>KEY_USR_WRITE</B>,
|
|
|
|
<B>KEY_GRP_WRITE</B>,
|
|
|
|
and
|
|
<B>KEY_OTH_WRITE</B>.
|
|
|
|
<DT id="63"><I>search</I>
|
|
|
|
<DD>
|
|
This permission allows keyrings to be searched and keys to be found.
|
|
Searches can recurse only into nested keyrings that have
|
|
<I>search</I>
|
|
|
|
permission set.
|
|
<DT id="64"><DD>
|
|
This permission is required for the
|
|
<B>KEYCTL_GET_KEYRING_ID</B>,
|
|
|
|
<B>KEYCTL_JOIN_SESSION_KEYRING</B>,
|
|
|
|
<B>KEYCTL_SEARCH</B>,
|
|
|
|
and
|
|
<B>KEYCTL_INVALIDATE</B>
|
|
|
|
operations.
|
|
<DT id="65"><DD>
|
|
The permission bits for each category are
|
|
<B>KEY_POS_SEARCH</B>,
|
|
|
|
<B>KEY_USR_SEARCH</B>,
|
|
|
|
<B>KEY_GRP_SEARCH</B>,
|
|
|
|
and
|
|
<B>KEY_OTH_SEARCH</B>.
|
|
|
|
<DT id="66"><I>link</I>
|
|
|
|
<DD>
|
|
This permission allows a key or keyring to be linked to.
|
|
<DT id="67"><DD>
|
|
This permission is required for the
|
|
<B>KEYCTL_LINK</B>
|
|
|
|
and
|
|
<B>KEYCTL_SESSION_TO_PARENT</B>
|
|
|
|
operations.
|
|
<DT id="68"><DD>
|
|
The permission bits for each category are
|
|
<B>KEY_POS_LINK</B>,
|
|
|
|
<B>KEY_USR_LINK</B>,
|
|
|
|
<B>KEY_GRP_LINK</B>,
|
|
|
|
and
|
|
<B>KEY_OTH_LINK</B>.
|
|
|
|
<DT id="69"><I>setattr</I> (since Linux 2.6.15).
|
|
|
|
<DD>
|
|
This permission allows a key's UID, GID, and permissions mask to be changed.
|
|
<DT id="70"><DD>
|
|
This permission is required for the
|
|
<B>KEYCTL_REVOKE</B>,
|
|
|
|
<B>KEYCTL_CHOWN</B>,
|
|
|
|
and
|
|
<B>KEYCTL_SETPERM</B>
|
|
|
|
operations.
|
|
<DT id="71"><DD>
|
|
The permission bits for each category are
|
|
<B>KEY_POS_SETATTR</B>,
|
|
|
|
<B>KEY_USR_SETATTR</B>,
|
|
|
|
<B>KEY_GRP_SETATTR</B>,
|
|
|
|
and
|
|
<B>KEY_OTH_SETATTR</B>.
|
|
|
|
</DL>
|
|
</DL>
|
|
|
|
<DT id="72"><DD>
|
|
As a convenience, the following macros are defined as masks for
|
|
all of the permission bits in each of the user categories:
|
|
<B>KEY_POS_ALL</B>,
|
|
|
|
<B>KEY_USR_ALL</B>,
|
|
|
|
<B>KEY_GRP_ALL</B>,
|
|
|
|
and
|
|
<B>KEY_OTH_ALL</B>.
|
|
|
|
<DT id="73"><DD>
|
|
The
|
|
<I>arg4</I> and <I>arg5</I>
|
|
|
|
arguments are ignored.
|
|
<DT id="74"><DD>
|
|
This operation is exposed by
|
|
<I>libkeyutils</I>
|
|
|
|
via the function
|
|
<B><A HREF="/cgi-bin/man/man2html?3+keyctl_setperm">keyctl_setperm</A></B>(3).
|
|
|
|
<DT id="75"><B>KEYCTL_DESCRIBE</B> (since Linux 2.6.10)
|
|
|
|
<DD>
|
|
Obtain a string describing the attributes of a specified key.
|
|
<DT id="76"><DD>
|
|
The ID of the key to be described is specified in
|
|
<I>arg2</I>
|
|
|
|
(cast to
|
|
<I>key_serial_t</I>).
|
|
|
|
The descriptive string is returned in the buffer pointed to by
|
|
<I>arg3</I>
|
|
|
|
(cast to
|
|
<I>char *</I>);
|
|
|
|
<I>arg4</I>
|
|
|
|
(cast to
|
|
<I>size_t</I>)
|
|
|
|
specifies the size of that buffer in bytes.
|
|
<DT id="77"><DD>
|
|
The key must grant the caller
|
|
<I>view</I>
|
|
|
|
permission.
|
|
<DT id="78"><DD>
|
|
The returned string is null-terminated and
|
|
contains the following information about the key:
|
|
<DT id="79"><DD>
|
|
|
|
<I>type</I>;<I>uid</I>;<I>gid</I>;<I>perm</I>;<I>description</I>
|
|
|
|
|
|
<DT id="80"><DD>
|
|
In the above,
|
|
<I>type</I>
|
|
|
|
and
|
|
<I>description</I>
|
|
|
|
are strings,
|
|
<I>uid</I>
|
|
|
|
and
|
|
<I>gid</I>
|
|
|
|
are decimal strings, and
|
|
<I>perm</I>
|
|
|
|
is a hexadecimal permissions mask.
|
|
The descriptive string is written with the following format:
|
|
<DT id="81"><DD>
|
|
<BR> %s;%d;%d;%08x;%s
|
|
<DT id="82"><DD>
|
|
<B>Note: the intention is that the descriptive string should</B>
|
|
|
|
<B>be extensible in future kernel versions.</B>
|
|
|
|
In particular, the
|
|
<I>description</I>
|
|
|
|
field will not contain semicolons;
|
|
|
|
|
|
|
|
|
|
|
|
it should be parsed by working backwards from the end of the string
|
|
to find the last semicolon.
|
|
This allows future semicolon-delimited fields to be inserted
|
|
in the descriptive string in the future.
|
|
<DT id="83"><DD>
|
|
Writing to the buffer is attempted only when
|
|
<I>arg3</I>
|
|
|
|
is non-NULL and the specified buffer size
|
|
is large enough to accept the descriptive string
|
|
(including the terminating null byte).
|
|
|
|
|
|
|
|
In order to determine whether the buffer size was too small,
|
|
check to see if the return value of the operation is greater than
|
|
<I>arg4</I>.
|
|
|
|
<DT id="84"><DD>
|
|
The
|
|
<I>arg5</I>
|
|
|
|
argument is ignored.
|
|
<DT id="85"><DD>
|
|
This operation is exposed by
|
|
<I>libkeyutils</I>
|
|
|
|
via the function
|
|
<B><A HREF="/cgi-bin/man/man2html?3+keyctl_describe">keyctl_describe</A></B>(3).
|
|
|
|
<DT id="86"><B>KEYCTL_CLEAR</B>
|
|
|
|
<DD>
|
|
Clear the contents of (i.e., unlink all keys from) a keyring.
|
|
<DT id="87"><DD>
|
|
The ID of the key
|
|
(which must be of keyring type)
|
|
|
|
is provided in
|
|
<I>arg2</I>
|
|
|
|
(cast to
|
|
<I>key_serial_t</I>).
|
|
|
|
|
|
|
|
|
|
|
|
<DT id="88"><DD>
|
|
The caller must have
|
|
<I>write</I>
|
|
|
|
permission on the keyring.
|
|
<DT id="89"><DD>
|
|
The arguments
|
|
<I>arg3</I>,
|
|
|
|
<I>arg4</I>,
|
|
|
|
and
|
|
<I>arg5</I>
|
|
|
|
are ignored.
|
|
<DT id="90"><DD>
|
|
This operation is exposed by
|
|
<I>libkeyutils</I>
|
|
|
|
via the function
|
|
<B><A HREF="/cgi-bin/man/man2html?3+keyctl_clear">keyctl_clear</A></B>(3).
|
|
|
|
<DT id="91"><B>KEYCTL_LINK</B> (since Linux 2.6.10)
|
|
|
|
<DD>
|
|
Create a link from a keyring to a key.
|
|
<DT id="92"><DD>
|
|
The key to be linked is specified in
|
|
<I>arg2</I>
|
|
|
|
(cast to
|
|
<I>key_serial_t</I>);
|
|
|
|
the keyring is specified in
|
|
<I>arg3</I>
|
|
|
|
(cast to
|
|
<I>key_serial_t</I>).
|
|
|
|
<DT id="93"><DD>
|
|
If a key with the same type and description is already linked in the keyring,
|
|
then that key is displaced from the keyring.
|
|
<DT id="94"><DD>
|
|
Before creating the link,
|
|
the kernel checks the nesting of the keyrings and returns appropriate errors
|
|
if the link would produce a cycle
|
|
or if the nesting of keyrings would be too deep
|
|
(The limit on the nesting of keyrings is determined by the kernel constant
|
|
<B>KEYRING_SEARCH_MAX_DEPTH</B>,
|
|
|
|
defined with the value 6, and is necessary to prevent overflows
|
|
on the kernel stack when recursively searching keyrings).
|
|
<DT id="95"><DD>
|
|
The caller must have
|
|
<I>link</I>
|
|
|
|
permission on the key being added and
|
|
<I>write</I>
|
|
|
|
permission on the keyring.
|
|
<DT id="96"><DD>
|
|
The arguments
|
|
<I>arg4</I>
|
|
|
|
and
|
|
<I>arg5</I>
|
|
|
|
are ignored.
|
|
<DT id="97"><DD>
|
|
This operation is exposed by
|
|
<I>libkeyutils</I>
|
|
|
|
via the function
|
|
<B><A HREF="/cgi-bin/man/man2html?3+keyctl_link">keyctl_link</A></B>(3).
|
|
|
|
<DT id="98"><B>KEYCTL_UNLINK</B> (since Linux 2.6.10)
|
|
|
|
<DD>
|
|
Unlink a key from a keyring.
|
|
<DT id="99"><DD>
|
|
The ID of the key to be unlinked is specified in
|
|
<I>arg2</I>
|
|
|
|
(cast to
|
|
<I>key_serial_t</I>);
|
|
|
|
the ID of the keyring from which it is to be unlinked is specified in
|
|
<I>arg3</I>
|
|
|
|
(cast to
|
|
<I>key_serial_t</I>).
|
|
|
|
<DT id="100"><DD>
|
|
If the key is not currently linked into the keyring, an error results.
|
|
<DT id="101"><DD>
|
|
The caller must have
|
|
<I>write</I>
|
|
|
|
permission on the keyring from which the key is being removed.
|
|
<DT id="102"><DD>
|
|
If the last link to a key is removed,
|
|
then that key will be scheduled for destruction.
|
|
<DT id="103"><DD>
|
|
The arguments
|
|
<I>arg4</I>
|
|
|
|
and
|
|
<I>arg5</I>
|
|
|
|
are ignored.
|
|
<DT id="104"><DD>
|
|
This operation is exposed by
|
|
<I>libkeyutils</I>
|
|
|
|
via the function
|
|
<B><A HREF="/cgi-bin/man/man2html?3+keyctl_unlink">keyctl_unlink</A></B>(3).
|
|
|
|
<DT id="105"><B>KEYCTL_SEARCH</B> (since Linux 2.6.10)
|
|
|
|
<DD>
|
|
Search for a key in a keyring tree,
|
|
returning its ID and optionally linking it to a specified keyring.
|
|
<DT id="106"><DD>
|
|
The tree to be searched is specified by passing
|
|
the ID of the head keyring in
|
|
<I>arg2</I>
|
|
|
|
(cast to
|
|
<I>key_serial_t</I>).
|
|
|
|
The search is performed breadth-first and recursively.
|
|
<DT id="107"><DD>
|
|
The
|
|
<I>arg3</I>
|
|
|
|
and
|
|
<I>arg4</I>
|
|
|
|
arguments specify the key to be searched for:
|
|
<I>arg3</I>
|
|
|
|
(cast as
|
|
<I>char *</I>)
|
|
|
|
contains the key type
|
|
(a null-terminated character string up to 32 bytes in size,
|
|
including the terminating null byte), and
|
|
<I>arg4</I>
|
|
|
|
(cast as
|
|
<I>char *</I>)
|
|
|
|
contains the description of the key
|
|
(a null-terminated character string up to 4096 bytes in size,
|
|
including the terminating null byte).
|
|
<DT id="108"><DD>
|
|
The source keyring must grant
|
|
<I>search</I>
|
|
|
|
permission to the caller.
|
|
When performing the recursive search, only keyrings that grant the caller
|
|
<I>search</I>
|
|
|
|
permission will be searched.
|
|
Only keys with for which the caller has
|
|
<I>search</I>
|
|
|
|
permission can be found.
|
|
<DT id="109"><DD>
|
|
If the key is found, its ID is returned as the function result.
|
|
<DT id="110"><DD>
|
|
If the key is found and
|
|
<I>arg5</I>
|
|
|
|
(cast to
|
|
<I>key_serial_t</I>)
|
|
|
|
is nonzero, then, subject to the same constraints and rules as
|
|
<B>KEYCTL_LINK</B>,
|
|
|
|
the key is linked into the keyring whose ID is specified in
|
|
<I>arg5</I>.
|
|
|
|
If the destination keyring specified in
|
|
<I>arg5</I>
|
|
|
|
already contains a link to a key that has the same type and description,
|
|
then that link will be displaced by a link to
|
|
the key found by this operation.
|
|
<DT id="111"><DD>
|
|
Instead of valid existing keyring IDs, the source
|
|
(<I>arg2</I>)
|
|
|
|
and destination
|
|
(<I>arg5</I>)
|
|
|
|
keyrings can be one of the special keyring IDs listed under
|
|
<B>KEYCTL_GET_KEYRING_ID</B>.
|
|
|
|
<DT id="112"><DD>
|
|
This operation is exposed by
|
|
<I>libkeyutils</I>
|
|
|
|
via the function
|
|
<B><A HREF="/cgi-bin/man/man2html?3+keyctl_search">keyctl_search</A></B>(3).
|
|
|
|
<DT id="113"><B>KEYCTL_READ</B> (since Linux 2.6.10)
|
|
|
|
<DD>
|
|
Read the payload data of a key.
|
|
<DT id="114"><DD>
|
|
The ID of the key whose payload is to be read is specified in
|
|
<I>arg2</I>
|
|
|
|
(cast to
|
|
<I>key_serial_t</I>).
|
|
|
|
This can be the ID of an existing key,
|
|
or any of the special key IDs listed for
|
|
<B>KEYCTL_GET_KEYRING_ID</B>.
|
|
|
|
|
|
<DT id="115"><DD>
|
|
The payload is placed in the buffer pointed by
|
|
<I>arg3</I>
|
|
|
|
(cast to
|
|
<I>char *</I>);
|
|
|
|
the size of that buffer must be specified in
|
|
<I>arg4</I>
|
|
|
|
(cast to
|
|
<I>size_t</I>).
|
|
|
|
<DT id="116"><DD>
|
|
The returned data will be processed for presentation
|
|
according to the key type.
|
|
For example, a keyring will return an array of
|
|
<I>key_serial_t</I>
|
|
|
|
entries representing the IDs of all the keys that are linked to it.
|
|
The
|
|
<I>user</I>
|
|
|
|
key type will return its data as is.
|
|
If a key type does not implement this function,
|
|
the operation fails with the error
|
|
<B>EOPNOTSUPP</B>.
|
|
|
|
<DT id="117"><DD>
|
|
If
|
|
<I>arg3</I>
|
|
|
|
is not NULL,
|
|
as much of the payload data as will fit is copied into the buffer.
|
|
On a successful return,
|
|
the return value is always the total size of the payload data.
|
|
To determine whether the buffer was of sufficient size,
|
|
check to see that the return value is less than or equal to
|
|
the value supplied in
|
|
<I>arg4</I>.
|
|
|
|
<DT id="118"><DD>
|
|
The key must either grant the caller
|
|
<I>read</I>
|
|
|
|
permission, or grant the caller
|
|
<I>search</I>
|
|
|
|
permission when searched for from the process keyrings
|
|
(i.e., the key is possessed).
|
|
<DT id="119"><DD>
|
|
The
|
|
<I>arg5</I>
|
|
|
|
argument is ignored.
|
|
<DT id="120"><DD>
|
|
This operation is exposed by
|
|
<I>libkeyutils</I>
|
|
|
|
via the function
|
|
<B><A HREF="/cgi-bin/man/man2html?3+keyctl_read">keyctl_read</A></B>(3).
|
|
|
|
<DT id="121"><B>KEYCTL_INSTANTIATE</B> (since Linux 2.6.10)
|
|
|
|
<DD>
|
|
(Positively) instantiate an uninstantiated key with a specified payload.
|
|
<DT id="122"><DD>
|
|
The ID of the key to be instantiated is provided in
|
|
<I>arg2</I>
|
|
|
|
(cast to
|
|
<I>key_serial_t</I>).
|
|
|
|
<DT id="123"><DD>
|
|
The key payload is specified in the buffer pointed to by
|
|
<I>arg3</I>
|
|
|
|
(cast to
|
|
<I>void *);</I>
|
|
|
|
the size of that buffer is specified in
|
|
<I>arg4</I>
|
|
|
|
(cast to
|
|
<I>size_t</I>).
|
|
|
|
<DT id="124"><DD>
|
|
The payload may be a NULL pointer and the buffer size may be 0
|
|
if this is supported by the key type (e.g., it is a keyring).
|
|
<DT id="125"><DD>
|
|
The operation may be fail if the payload data is in the wrong format
|
|
or is otherwise invalid.
|
|
<DT id="126"><DD>
|
|
If
|
|
<I>arg5</I>
|
|
|
|
(cast to
|
|
<I>key_serial_t</I>)
|
|
|
|
is nonzero, then, subject to the same constraints and rules as
|
|
<B>KEYCTL_LINK</B>,
|
|
|
|
the instantiated key is linked into the keyring whose ID specified in
|
|
<I>arg5</I>.
|
|
|
|
<DT id="127"><DD>
|
|
The caller must have the appropriate authorization key,
|
|
and once the uninstantiated key has been instantiated,
|
|
the authorization key is revoked.
|
|
In other words, this operation is available only from a
|
|
<B><A HREF="/cgi-bin/man/man2html?8+request-key">request-key</A></B>(8)-style
|
|
|
|
program.
|
|
See
|
|
<B><A HREF="/cgi-bin/man/man2html?2+request_key">request_key</A></B>(2)
|
|
|
|
for an explanation of uninstantiated keys and key instantiation.
|
|
<DT id="128"><DD>
|
|
This operation is exposed by
|
|
<I>libkeyutils</I>
|
|
|
|
via the function
|
|
<B><A HREF="/cgi-bin/man/man2html?3+keyctl_instantiate">keyctl_instantiate</A></B>(3).
|
|
|
|
<DT id="129"><B>KEYCTL_NEGATE</B> (since Linux 2.6.10)
|
|
|
|
<DD>
|
|
Negatively instantiate an uninstantiated key.
|
|
<DT id="130"><DD>
|
|
This operation is equivalent to the call:
|
|
<DT id="131"><DD>
|
|
<BR> keyctl(KEYCTL_REJECT, arg2, arg3, ENOKEY, arg4);
|
|
<DT id="132"><DD>
|
|
The
|
|
<I>arg5</I>
|
|
|
|
argument is ignored.
|
|
<DT id="133"><DD>
|
|
This operation is exposed by
|
|
<I>libkeyutils</I>
|
|
|
|
via the function
|
|
<B><A HREF="/cgi-bin/man/man2html?3+keyctl_negate">keyctl_negate</A></B>(3).
|
|
|
|
<DT id="134"><B>KEYCTL_SET_REQKEY_KEYRING</B> (since Linux 2.6.13)
|
|
|
|
<DD>
|
|
Set the default keyring to which implicitly requested keys
|
|
will be linked for this thread, and return the previous setting.
|
|
Implicit key requests are those made by internal kernel components,
|
|
|
|
|
|
|
|
such as can occur when, for example, opening files
|
|
on an AFS or NFS filesystem.
|
|
Setting the default keyring also has an effect when requesting
|
|
a key from user space; see
|
|
<B><A HREF="/cgi-bin/man/man2html?2+request_key">request_key</A></B>(2)
|
|
|
|
for details.
|
|
<DT id="135"><DD>
|
|
The
|
|
<I>arg2</I>
|
|
|
|
argument (cast to
|
|
<I>int</I>)
|
|
|
|
should contain one of the following values,
|
|
to specify the new default keyring:
|
|
<DL COMPACT><DT id="136"><DD>
|
|
<DL COMPACT>
|
|
<DT id="137"><B>KEY_REQKEY_DEFL_NO_CHANGE</B>
|
|
|
|
<DD>
|
|
Don't change the default keyring.
|
|
This can be used to discover the current default keyring
|
|
(without changing it).
|
|
<DT id="138"><B>KEY_REQKEY_DEFL_DEFAULT</B>
|
|
|
|
<DD>
|
|
This selects the default behaviour,
|
|
which is to use the thread-specific keyring if there is one,
|
|
otherwise the process-specific keyring if there is one,
|
|
otherwise the session keyring if there is one,
|
|
otherwise the UID-specific session keyring,
|
|
otherwise the user-specific keyring.
|
|
<DT id="139"><B>KEY_REQKEY_DEFL_THREAD_KEYRING</B>
|
|
|
|
<DD>
|
|
Use the thread-specific keyring
|
|
(<B><A HREF="/cgi-bin/man/man2html?7+thread-keyring">thread-keyring</A></B>(7))
|
|
|
|
as the new default keyring.
|
|
<DT id="140"><B>KEY_REQKEY_DEFL_PROCESS_KEYRING</B>
|
|
|
|
<DD>
|
|
Use the process-specific keyring
|
|
(<B><A HREF="/cgi-bin/man/man2html?7+process-keyring">process-keyring</A></B>(7))
|
|
|
|
as the new default keyring.
|
|
<DT id="141"><B>KEY_REQKEY_DEFL_SESSION_KEYRING</B>
|
|
|
|
<DD>
|
|
Use the session-specific keyring
|
|
(<B><A HREF="/cgi-bin/man/man2html?7+session-keyring">session-keyring</A></B>(7))
|
|
|
|
as the new default keyring.
|
|
<DT id="142"><B>KEY_REQKEY_DEFL_USER_KEYRING</B>
|
|
|
|
<DD>
|
|
Use the UID-specific keyring
|
|
(<B><A HREF="/cgi-bin/man/man2html?7+user-keyring">user-keyring</A></B>(7))
|
|
|
|
as the new default keyring.
|
|
<DT id="143"><B>KEY_REQKEY_DEFL_USER_SESSION_KEYRING</B>
|
|
|
|
<DD>
|
|
Use the UID-specific session keyring
|
|
(<B><A HREF="/cgi-bin/man/man2html?7+user-session-keyring">user-session-keyring</A></B>(7))
|
|
|
|
as the new default keyring.
|
|
<DT id="144"><B>KEY_REQKEY_DEFL_REQUESTOR_KEYRING</B> (since Linux 2.6.29)
|
|
|
|
<DD>
|
|
|
|
Use the requestor keyring.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
</DL>
|
|
</DL>
|
|
|
|
<DT id="145"><DD>
|
|
All other values are invalid.
|
|
|
|
<DT id="146"><DD>
|
|
The arguments
|
|
<I>arg3</I>,
|
|
|
|
<I>arg4</I>,
|
|
|
|
and
|
|
<I>arg5</I>
|
|
|
|
are ignored.
|
|
<DT id="147"><DD>
|
|
The setting controlled by this operation is inherited by the child of
|
|
<B><A HREF="/cgi-bin/man/man2html?2+fork">fork</A></B>(2)
|
|
|
|
and preserved across
|
|
<B><A HREF="/cgi-bin/man/man2html?2+execve">execve</A></B>(2).
|
|
|
|
<DT id="148"><DD>
|
|
This operation is exposed by
|
|
<I>libkeyutils</I>
|
|
|
|
via the function
|
|
<B><A HREF="/cgi-bin/man/man2html?3+keyctl_set_reqkey_keyring">keyctl_set_reqkey_keyring</A></B>(3).
|
|
|
|
<DT id="149"><B>KEYCTL_SET_TIMEOUT</B> (since Linux 2.6.16)
|
|
|
|
<DD>
|
|
Set a timeout on a key.
|
|
<DT id="150"><DD>
|
|
The ID of the key is specified in
|
|
<I>arg2</I>
|
|
|
|
(cast to
|
|
<I>key_serial_t</I>).
|
|
|
|
The timeout value, in seconds from the current time,
|
|
is specified in
|
|
<I>arg3</I>
|
|
|
|
(cast to
|
|
<I>unsigned int</I>).
|
|
|
|
The timeout is measured against the realtime clock.
|
|
<DT id="151"><DD>
|
|
Specifying the timeout value as 0 clears any existing timeout on the key.
|
|
<DT id="152"><DD>
|
|
The
|
|
<I>/proc/keys</I>
|
|
|
|
file displays the remaining time until each key will expire.
|
|
(This is the only method of discovering the timeout on a key.)
|
|
<DT id="153"><DD>
|
|
The caller must either have the
|
|
<I>setattr</I>
|
|
|
|
permission on the key
|
|
or hold an instantiation authorization token for the key (see
|
|
<B><A HREF="/cgi-bin/man/man2html?2+request_key">request_key</A></B>(2)).
|
|
|
|
<DT id="154"><DD>
|
|
The key and any links to the key will be
|
|
automatically garbage collected after the timeout expires.
|
|
Subsequent attempts to access the key will then fail with the error
|
|
<B>EKEYEXPIRED</B>.
|
|
|
|
<DT id="155"><DD>
|
|
This operation cannot be used to set timeouts on revoked, expired,
|
|
or negatively instantiated keys.
|
|
<DT id="156"><DD>
|
|
The arguments
|
|
<I>arg4</I>
|
|
|
|
and
|
|
<I>arg5</I>
|
|
|
|
are ignored.
|
|
<DT id="157"><DD>
|
|
This operation is exposed by
|
|
<I>libkeyutils</I>
|
|
|
|
via the function
|
|
<B><A HREF="/cgi-bin/man/man2html?3+keyctl_set_timeout">keyctl_set_timeout</A></B>(3).
|
|
|
|
<DT id="158"><B>KEYCTL_ASSUME_AUTHORITY</B> (since Linux 2.6.16)
|
|
|
|
<DD>
|
|
Assume (or divest) the authority for the calling thread
|
|
to instantiate a key.
|
|
<DT id="159"><DD>
|
|
The
|
|
<I>arg2</I>
|
|
|
|
argument (cast to
|
|
<I>key_serial_t</I>)
|
|
|
|
specifies either a nonzero key ID to assume authority,
|
|
or the value 0 to divest authority.
|
|
<DT id="160"><DD>
|
|
If
|
|
<I>arg2</I>
|
|
|
|
is nonzero, then it specifies the ID of an uninstantiated key for which
|
|
authority is to be assumed.
|
|
That key can then be instantiated using one of
|
|
<B>KEYCTL_INSTANTIATE</B>,
|
|
|
|
<B>KEYCTL_INSTANTIATE_IOV</B>,
|
|
|
|
<B>KEYCTL_REJECT</B>,
|
|
|
|
or
|
|
<B>KEYCTL_NEGATE</B>.
|
|
|
|
Once the key has been instantiated,
|
|
the thread is automatically divested of authority to instantiate the key.
|
|
<DT id="161"><DD>
|
|
Authority over a key can be assumed only if the calling thread has present
|
|
in its keyrings the authorization key that is
|
|
associated with the specified key.
|
|
(In other words, the
|
|
<B>KEYCTL_ASSUME_AUTHORITY</B>
|
|
|
|
operation is available only from a
|
|
<B><A HREF="/cgi-bin/man/man2html?8+request-key">request-key</A></B>(8)-style
|
|
|
|
program; see
|
|
<B><A HREF="/cgi-bin/man/man2html?2+request_key">request_key</A></B>(2)
|
|
|
|
for an explanation of how this operation is used.)
|
|
The caller must have
|
|
<I>search</I>
|
|
|
|
permission on the authorization key.
|
|
<DT id="162"><DD>
|
|
If the specified key has a matching authorization key,
|
|
then the ID of that key is returned.
|
|
The authorization key can be read
|
|
(<B>KEYCTL_READ</B>)
|
|
|
|
to obtain the callout information passed to
|
|
<B><A HREF="/cgi-bin/man/man2html?2+request_key">request_key</A></B>(2).
|
|
|
|
<DT id="163"><DD>
|
|
If the ID given in
|
|
<I>arg2</I>
|
|
|
|
is 0, then the currently assumed authority is cleared (divested),
|
|
and the value 0 is returned.
|
|
<DT id="164"><DD>
|
|
The
|
|
<B>KEYCTL_ASSUME_AUTHORITY</B>
|
|
|
|
mechanism allows a program such as
|
|
<B><A HREF="/cgi-bin/man/man2html?8+request-key">request-key</A></B>(8)
|
|
|
|
to assume the necessary authority to instantiate a new uninstantiated key
|
|
that was created as a consequence of a call to
|
|
<B><A HREF="/cgi-bin/man/man2html?2+request_key">request_key</A></B>(2).
|
|
|
|
For further information, see
|
|
<B><A HREF="/cgi-bin/man/man2html?2+request_key">request_key</A></B>(2)
|
|
|
|
and the kernel source file
|
|
<I>Documentation/security/keys-request-key.txt</I>.
|
|
|
|
<DT id="165"><DD>
|
|
The arguments
|
|
<I>arg3</I>,
|
|
|
|
<I>arg4</I>,
|
|
|
|
and
|
|
<I>arg5</I>
|
|
|
|
are ignored.
|
|
<DT id="166"><DD>
|
|
This operation is exposed by
|
|
<I>libkeyutils</I>
|
|
|
|
via the function
|
|
<B><A HREF="/cgi-bin/man/man2html?3+keyctl_assume_authority">keyctl_assume_authority</A></B>(3).
|
|
|
|
<DT id="167"><B>KEYCTL_GET_SECURITY</B> (since Linux 2.6.26)
|
|
|
|
<DD>
|
|
|
|
Get the LSM (Linux Security Module) security label of the specified key.
|
|
<DT id="168"><DD>
|
|
The ID of the key whose security label is to be fetched is specified in
|
|
<I>arg2</I>
|
|
|
|
(cast to
|
|
<I>key_serial_t</I>).
|
|
|
|
The security label (terminated by a null byte)
|
|
will be placed in the buffer pointed to by
|
|
<I>arg3</I>
|
|
|
|
argument (cast to
|
|
<I>char *</I>);
|
|
|
|
the size of the buffer must be provided in
|
|
<I>arg4</I>
|
|
|
|
(cast to
|
|
<I>size_t</I>).
|
|
|
|
<DT id="169"><DD>
|
|
If
|
|
<I>arg3</I>
|
|
|
|
is specified as NULL or the buffer size specified in
|
|
<I>arg4</I>
|
|
|
|
is too small, the full size of the security label string
|
|
(including the terminating null byte)
|
|
is returned as the function result,
|
|
and nothing is copied to the buffer.
|
|
<DT id="170"><DD>
|
|
The caller must have
|
|
<I>view</I>
|
|
|
|
permission on the specified key.
|
|
<DT id="171"><DD>
|
|
The returned security label string will be rendered in a form appropriate
|
|
to the LSM in force.
|
|
For example, with SELinux, it may look like:
|
|
<DT id="172"><DD>
|
|
<BR> unconfined_u:unconfined_r:unconfined_t:s0-s0:c0.c1023
|
|
<DT id="173"><DD>
|
|
If no LSM is currently in force,
|
|
then an empty string is placed in the buffer.
|
|
<DT id="174"><DD>
|
|
The
|
|
<I>arg5</I>
|
|
|
|
argument is ignored.
|
|
<DT id="175"><DD>
|
|
This operation is exposed by
|
|
<I>libkeyutils</I>
|
|
|
|
via the functions
|
|
<B><A HREF="/cgi-bin/man/man2html?3+keyctl_get_security">keyctl_get_security</A></B>(3)
|
|
|
|
and
|
|
<B><A HREF="/cgi-bin/man/man2html?3+keyctl_get_security_alloc">keyctl_get_security_alloc</A></B>(3).
|
|
|
|
<DT id="176"><B>KEYCTL_SESSION_TO_PARENT</B> (since Linux 2.6.32)
|
|
|
|
<DD>
|
|
|
|
Replace the session keyring to which the
|
|
<I>parent</I>
|
|
|
|
of the calling process
|
|
subscribes with the session keyring of the calling process.
|
|
|
|
|
|
|
|
<DT id="177"><DD>
|
|
The keyring will be replaced in the parent process at the point
|
|
where the parent next transitions from kernel space to user space.
|
|
<DT id="178"><DD>
|
|
The keyring must exist and must grant the caller
|
|
<I>link</I>
|
|
|
|
permission.
|
|
The parent process must be single-threaded and have
|
|
the same effective ownership as this process
|
|
and must not be set-user-ID or set-group-ID.
|
|
The UID of the parent process's existing session keyring (f it has one),
|
|
as well as the UID of the caller's session keyring
|
|
much match the caller's effective UID.
|
|
<DT id="179"><DD>
|
|
The fact that it is the parent process that is affected by this operation
|
|
allows a program such as the shell to start a child process that
|
|
uses this operation to change the shell's session keyring.
|
|
(This is what the
|
|
<B><A HREF="/cgi-bin/man/man2html?1+keyctl">keyctl</A></B>(1)
|
|
|
|
<B>new_session</B>
|
|
|
|
command does.)
|
|
<DT id="180"><DD>
|
|
The arguments
|
|
<I>arg2</I>,
|
|
|
|
<I>arg3</I>,
|
|
|
|
<I>arg4</I>,
|
|
|
|
and
|
|
<I>arg5</I>
|
|
|
|
are ignored.
|
|
<DT id="181"><DD>
|
|
This operation is exposed by
|
|
<I>libkeyutils</I>
|
|
|
|
via the function
|
|
<B><A HREF="/cgi-bin/man/man2html?3+keyctl_session_to_parent">keyctl_session_to_parent</A></B>(3).
|
|
|
|
<DT id="182"><B>KEYCTL_REJECT</B> (since Linux 2.6.39)
|
|
|
|
<DD>
|
|
|
|
Mark a key as negatively instantiated and set an expiration timer
|
|
on the key.
|
|
This operation provides a superset of the functionality of the earlier
|
|
<B>KEYCTL_NEGATE</B>
|
|
|
|
operation.
|
|
<DT id="183"><DD>
|
|
The ID of the key that is to be negatively instantiated is specified in
|
|
<I>arg2</I>
|
|
|
|
(cast to
|
|
<I>key_serial_t</I>).
|
|
|
|
The
|
|
<I>arg3</I>
|
|
|
|
(cast to
|
|
<I>unsigned int</I>)
|
|
|
|
argument specifies the lifetime of the key, in seconds.
|
|
The
|
|
<I>arg4</I>
|
|
|
|
argument (cast to
|
|
<I>unsigned int</I>)
|
|
|
|
specifies the error to be returned when a search hits this key;
|
|
typically, this is one of
|
|
<B>EKEYREJECTED</B>,
|
|
|
|
<B>EKEYREVOKED</B>,
|
|
|
|
or
|
|
<B>EKEYEXPIRED</B>.
|
|
|
|
<DT id="184"><DD>
|
|
If
|
|
<I>arg5</I>
|
|
|
|
(cast to
|
|
<I>key_serial_t</I>)
|
|
|
|
is nonzero, then, subject to the same constraints and rules as
|
|
<B>KEYCTL_LINK</B>,
|
|
|
|
the negatively instantiated key is linked into the keyring
|
|
whose ID is specified in
|
|
<I>arg5</I>.
|
|
|
|
<DT id="185"><DD>
|
|
The caller must have the appropriate authorization key.
|
|
In other words, this operation is available only from a
|
|
<B><A HREF="/cgi-bin/man/man2html?8+request-key">request-key</A></B>(8)-style
|
|
|
|
program.
|
|
See
|
|
<B><A HREF="/cgi-bin/man/man2html?2+request_key">request_key</A></B>(2).
|
|
|
|
<DT id="186"><DD>
|
|
The caller must have the appropriate authorization key,
|
|
and once the uninstantiated key has been instantiated,
|
|
the authorization key is revoked.
|
|
In other words, this operation is available only from a
|
|
<B><A HREF="/cgi-bin/man/man2html?8+request-key">request-key</A></B>(8)-style
|
|
|
|
program.
|
|
See
|
|
<B><A HREF="/cgi-bin/man/man2html?2+request_key">request_key</A></B>(2)
|
|
|
|
for an explanation of uninstantiated keys and key instantiation.
|
|
<DT id="187"><DD>
|
|
This operation is exposed by
|
|
<I>libkeyutils</I>
|
|
|
|
via the function
|
|
<B><A HREF="/cgi-bin/man/man2html?3+keyctl_reject">keyctl_reject</A></B>(3).
|
|
|
|
<DT id="188"><B>KEYCTL_INSTANTIATE_IOV</B> (since Linux 2.6.39)
|
|
|
|
<DD>
|
|
|
|
Instantiate an uninstantiated key with a payload specified
|
|
via a vector of buffers.
|
|
<DT id="189"><DD>
|
|
This operation is the same as
|
|
<B>KEYCTL_INSTANTIATE</B>,
|
|
|
|
but the payload data is specified as an array of
|
|
<I>iovec</I>
|
|
|
|
structures:
|
|
<DT id="190"><DD>
|
|
|
|
|
|
struct iovec {
|
|
<BR> void *iov_base; /* Starting address of buffer */
|
|
<BR> size_t iov_len; /* Size of buffer (in bytes) */
|
|
};
|
|
|
|
|
|
<DT id="191"><DD>
|
|
The pointer to the payload vector is specified in
|
|
<I>arg3</I>
|
|
|
|
(cast as
|
|
<I>const struct iovec *</I>).
|
|
|
|
The number of items in the vector is specified in
|
|
<I>arg4</I>
|
|
|
|
(cast as
|
|
<I>unsigned int</I>).
|
|
|
|
<DT id="192"><DD>
|
|
The
|
|
<I>arg2</I>
|
|
|
|
(key ID)
|
|
and
|
|
<I>arg5</I>
|
|
|
|
(keyring ID)
|
|
are interpreted as for
|
|
<B>KEYCTL_INSTANTIATE</B>.
|
|
|
|
<DT id="193"><DD>
|
|
This operation is exposed by
|
|
<I>libkeyutils</I>
|
|
|
|
via the function
|
|
<B><A HREF="/cgi-bin/man/man2html?3+keyctl_instantiate_iov">keyctl_instantiate_iov</A></B>(3).
|
|
|
|
<DT id="194"><B>KEYCTL_INVALIDATE</B> (since Linux 3.5)
|
|
|
|
<DD>
|
|
|
|
Mark a key as invalid.
|
|
<DT id="195"><DD>
|
|
The ID of the key to be invalidated is specified in
|
|
<I>arg2</I>
|
|
|
|
(cast to
|
|
<I>key_serial_t</I>).
|
|
|
|
<DT id="196"><DD>
|
|
To invalidate a key,
|
|
the caller must have
|
|
<I>search</I>
|
|
|
|
permission on the key.
|
|
|
|
<DT id="197"><DD>
|
|
This operation marks the key as invalid
|
|
and schedules immediate garbage collection.
|
|
The garbage collector removes the invalidated key from all keyrings and
|
|
deletes the key when its reference count reaches zero.
|
|
After this operation,
|
|
the key will be ignored by all searches,
|
|
even if it is not yet deleted.
|
|
<DT id="198"><DD>
|
|
Keys that are marked invalid become invisible to normal key operations
|
|
immediately, though they are still visible in
|
|
<I>/proc/keys</I>
|
|
|
|
(marked with an 'i' flag)
|
|
until they are actually removed.
|
|
<DT id="199"><DD>
|
|
The arguments
|
|
<I>arg3</I>,
|
|
|
|
<I>arg4</I>,
|
|
|
|
and
|
|
<I>arg5</I>
|
|
|
|
are ignored.
|
|
<DT id="200"><DD>
|
|
This operation is exposed by
|
|
<I>libkeyutils</I>
|
|
|
|
via the function
|
|
<B><A HREF="/cgi-bin/man/man2html?3+keyctl_invalidate">keyctl_invalidate</A></B>(3).
|
|
|
|
<DT id="201"><B>KEYCTL_GET_PERSISTENT</B> (since Linux 3.13)
|
|
|
|
<DD>
|
|
|
|
Get the persistent keyring
|
|
(<B><A HREF="/cgi-bin/man/man2html?7+persistent-keyring">persistent-keyring</A></B>(7))
|
|
|
|
for a specified user and link it to a specified keyring.
|
|
<DT id="202"><DD>
|
|
The user ID is specified in
|
|
<I>arg2</I>
|
|
|
|
(cast to
|
|
<I>uid_t</I>).
|
|
|
|
If the value -1 is specified, the caller's real user ID is used.
|
|
The ID of the destination keyring is specified in
|
|
<I>arg3</I>
|
|
|
|
(cast to
|
|
<I>key_serial_t</I>).
|
|
|
|
<DT id="203"><DD>
|
|
The caller must have the
|
|
<B>CAP_SETUID</B>
|
|
|
|
capability in its user namespace in order to fetch the persistent keyring
|
|
for a user ID that does not match either the real or effective user ID
|
|
of the caller.
|
|
<DT id="204"><DD>
|
|
If the call is successful,
|
|
a link to the persistent keyring is added to the keyring
|
|
whose ID was specified in
|
|
<I>arg3</I>.
|
|
|
|
<DT id="205"><DD>
|
|
The caller must have
|
|
<I>write</I>
|
|
|
|
permission on the keyring.
|
|
<DT id="206"><DD>
|
|
The persistent keyring will be created by the kernel
|
|
if it does not yet exist.
|
|
<DT id="207"><DD>
|
|
Each time the
|
|
<B>KEYCTL_GET_PERSISTENT</B>
|
|
|
|
operation is performed, the persistent keyring will
|
|
have its expiration timeout reset to the value in:
|
|
<DT id="208"><DD>
|
|
|
|
|
|
/proc/sys/kernel/keys/persistent_keyring_expiry
|
|
|
|
|
|
<DT id="209"><DD>
|
|
Should the timeout be reached,
|
|
the persistent keyring will be removed and
|
|
everything it pins can then be garbage collected.
|
|
<DT id="210"><DD>
|
|
Persistent keyrings were added to Linux in kernel version 3.13.
|
|
<DT id="211"><DD>
|
|
The arguments
|
|
<I>arg4</I>
|
|
|
|
and
|
|
<I>arg5</I>
|
|
|
|
are ignored.
|
|
<DT id="212"><DD>
|
|
This operation is exposed by
|
|
<I>libkeyutils</I>
|
|
|
|
via the function
|
|
<B><A HREF="/cgi-bin/man/man2html?3+keyctl_get_persistent">keyctl_get_persistent</A></B>(3).
|
|
|
|
<DT id="213"><B>KEYCTL_DH_COMPUTE</B> (since Linux 4.7)
|
|
|
|
<DD>
|
|
|
|
Compute a Diffie-Hellman shared secret or public key,
|
|
optionally applying key derivation function (KDF) to the result.
|
|
<DT id="214"><DD>
|
|
The
|
|
<I>arg2</I>
|
|
|
|
argument is a pointer to a set of parameters containing
|
|
serial numbers for three
|
|
<I>"user"</I>
|
|
|
|
keys used in the Diffie-Hellman calculation,
|
|
packaged in a structure of the following form:
|
|
<DT id="215"><DD>
|
|
|
|
|
|
struct keyctl_dh_params {
|
|
<BR> int32_t private; /* The local private key */
|
|
<BR> int32_t prime; /* The prime, known to both parties */
|
|
<BR> int32_t base; /* The base integer: either a shared
|
|
<BR> generator or the remote public key */
|
|
};
|
|
|
|
|
|
<DT id="216"><DD>
|
|
Each of the three keys specified in this structure must grant the caller
|
|
<I>read</I>
|
|
|
|
permission.
|
|
The payloads of these keys are used to calculate the Diffie-Hellman
|
|
result as:
|
|
<DT id="217"><DD>
|
|
<BR> base ^ private mod prime
|
|
<DT id="218"><DD>
|
|
If the base is the shared generator, the result is the local public key.
|
|
If the base is the remote public key, the result is the shared secret.
|
|
<DT id="219"><DD>
|
|
The
|
|
<I>arg3</I>
|
|
|
|
argument (cast to
|
|
<I>char *</I>)
|
|
|
|
points to a buffer where the result of the calculation is placed.
|
|
The size of that buffer is specified in
|
|
<I>arg4</I>
|
|
|
|
(cast to
|
|
<I>size_t</I>).
|
|
|
|
<DT id="220"><DD>
|
|
The buffer must be large enough to accommodate the output data,
|
|
otherwise an error is returned.
|
|
If
|
|
<I>arg4</I>
|
|
|
|
is specified zero,
|
|
in which case the buffer is not used and
|
|
the operation returns the minimum required buffer size
|
|
(i.e., the length of the prime).
|
|
<DT id="221"><DD>
|
|
Diffie-Hellman computations can be performed in user space,
|
|
but require a multiple-precision integer (MPI) library.
|
|
Moving the implementation into the kernel gives access to
|
|
the kernel MPI implementation,
|
|
and allows access to secure or acceleration hardware.
|
|
<DT id="222"><DD>
|
|
Adding support for DH computation to the
|
|
<B>keyctl</B>()
|
|
|
|
system call was considered a good fit due to the DH algorithm's use
|
|
for deriving shared keys;
|
|
it also allows the type of the key to determine
|
|
which DH implementation (software or hardware) is appropriate.
|
|
|
|
<DT id="223"><DD>
|
|
If the
|
|
<I>arg5</I>
|
|
|
|
argument is
|
|
<B>NULL</B>,
|
|
|
|
then the DH result itself is returned.
|
|
Otherwise (since Linux 4.12), it is a pointer to a structure which specifies
|
|
parameters of the KDF operation to be applied:
|
|
<DT id="224"><DD>
|
|
|
|
|
|
struct keyctl_kdf_params {
|
|
<BR> char *hashname; /* Hash algorithm name */
|
|
<BR> char *otherinfo; /* SP800-56A OtherInfo */
|
|
<BR> __u32 otherinfolen; /* Length of otherinfo data */
|
|
<BR> __u32 __spare[8]; /* Reserved */
|
|
};
|
|
|
|
|
|
<DT id="225"><DD>
|
|
The
|
|
<I>hashname</I>
|
|
|
|
field is a null-terminated string which specifies a hash name
|
|
(available in the kernel's crypto API; the list of the hashes available
|
|
is rather tricky to observe; please refer to the
|
|
|
|
"Kernel Crypto API Architecture"
|
|
|
|
documentation for the information regarding how hash names are constructed and
|
|
your kernel's source and configuration regarding what ciphers
|
|
and templates with type
|
|
<B>CRYPTO_ALG_TYPE_SHASH</B>
|
|
|
|
are available)
|
|
to be applied to DH result in KDF operation.
|
|
<DT id="226"><DD>
|
|
The
|
|
<I>otherinfo</I>
|
|
|
|
field is an
|
|
<I>OtherInfo</I>
|
|
|
|
data as described in SP800-56A section 5.8.1.2 and is algorithm-specific.
|
|
This data is concatenated with the result of DH operation and is provided as
|
|
an input to the KDF operation.
|
|
Its size is provided in the
|
|
<I>otherinfolen</I>
|
|
|
|
field and is limited by
|
|
<B>KEYCTL_KDF_MAX_OI_LEN</B>
|
|
|
|
constant that defined in
|
|
<I>security/keys/internal.h</I>
|
|
|
|
to a value of 64.
|
|
<DT id="227"><DD>
|
|
The
|
|
<B>__spare</B>
|
|
|
|
field is currently unused.
|
|
|
|
It was ignored until Linux 4.13 (but still should be
|
|
user-addressable since it is copied to the kernel),
|
|
and should contain zeros since Linux 4.13.
|
|
<DT id="228"><DD>
|
|
The KDF implementation complies with SP800-56A as well
|
|
as with SP800-108 (the counter KDF).
|
|
<DT id="229"><DD>
|
|
|
|
|
|
This operation is exposed by
|
|
<I>libkeyutils</I>
|
|
|
|
(from version 1.5.10 onwards) via the functions
|
|
<B><A HREF="/cgi-bin/man/man2html?3+keyctl_dh_compute">keyctl_dh_compute</A></B>(3)
|
|
|
|
and
|
|
<B><A HREF="/cgi-bin/man/man2html?3+keyctl_dh_compute_alloc">keyctl_dh_compute_alloc</A></B>(3).
|
|
|
|
<DT id="230"><B>KEYCTL_RESTRICT_KEYRING</B> (since Linux 4.12)
|
|
|
|
<DD>
|
|
|
|
|
|
Apply a key-linking restriction to the keyring with the ID provided in
|
|
<I>arg2</I>
|
|
|
|
(cast to
|
|
<I>key_serial_t</I>).
|
|
|
|
The caller must have
|
|
<I>setattr</I>
|
|
|
|
permission on the key.
|
|
If
|
|
<I>arg3</I>
|
|
|
|
is NULL, any attempt to add a key to the keyring is blocked;
|
|
otherwise it contains a pointer to a string with a key type name and
|
|
<I>arg4</I>
|
|
|
|
contains a pointer to string that describes the type-specific restriction.
|
|
As of Linux 4.12, only the type "asymmetric" has restrictions defined:
|
|
<DL COMPACT><DT id="231"><DD>
|
|
<DL COMPACT>
|
|
<DT id="232"><B>builtin_trusted</B>
|
|
|
|
<DD>
|
|
Allows only keys that are signed by a key linked to the built-in keyring
|
|
(".builtin_trusted_keys").
|
|
<DT id="233"><B>builtin_and_secondary_trusted</B>
|
|
|
|
<DD>
|
|
Allows only keys that are signed by a key linked to the secondary keyring
|
|
(".secondary_trusted_keys") or, by extension, a key in a built-in keyring,
|
|
as the latter is linked to the former.
|
|
<DT id="234"><B>key_or_keyring:</B><I>key</I>
|
|
|
|
<DD>
|
|
|
|
<B>key_or_keyring:</B><I>key</I><B>:chain</B>
|
|
|
|
If
|
|
<I>key</I>
|
|
|
|
specifies the ID of a key of type "asymmetric",
|
|
then only keys that are signed by this key are allowed.
|
|
<DT id="235"><DD>
|
|
If
|
|
<I>key</I>
|
|
|
|
specifies the ID of a keyring,
|
|
then only keys that are signed by a key linked
|
|
to this keyring are allowed.
|
|
<DT id="236"><DD>
|
|
If ":chain" is specified, keys that are signed by a keys linked to the
|
|
destination keyring (that is, the keyring with the ID specified in the
|
|
<I>arg2</I>
|
|
|
|
argument) are also allowed.
|
|
</DL>
|
|
</DL>
|
|
|
|
<DT id="237"><DD>
|
|
Note that a restriction can be configured only once for the specified keyring;
|
|
once a restriction is set, it can't be overridden.
|
|
<DT id="238"><DD>
|
|
The argument
|
|
<I>arg5</I>
|
|
|
|
is ignored.
|
|
|
|
|
|
|
|
|
|
</DL>
|
|
<A NAME="lbAE"> </A>
|
|
<H2>RETURN VALUE</H2>
|
|
|
|
For a successful call, the return value depends on the operation:
|
|
<DL COMPACT>
|
|
<DT id="239"><B>KEYCTL_GET_KEYRING_ID</B>
|
|
|
|
<DD>
|
|
The ID of the requested keyring.
|
|
<DT id="240"><B>KEYCTL_JOIN_SESSION_KEYRING</B>
|
|
|
|
<DD>
|
|
The ID of the joined session keyring.
|
|
<DT id="241"><B>KEYCTL_DESCRIBE</B>
|
|
|
|
<DD>
|
|
The size of the description (including the terminating null byte),
|
|
irrespective of the provided buffer size.
|
|
<DT id="242"><B>KEYCTL_SEARCH</B>
|
|
|
|
<DD>
|
|
The ID of the key that was found.
|
|
<DT id="243"><B>KEYCTL_READ</B>
|
|
|
|
<DD>
|
|
The amount of data that is available in the key,
|
|
irrespective of the provided buffer size.
|
|
<DT id="244"><B>KEYCTL_SET_REQKEY_KEYRING</B>
|
|
|
|
<DD>
|
|
The ID of the previous default keyring
|
|
to which implicitly requested keys were linked
|
|
(one of
|
|
<B>KEY_REQKEY_DEFL_USER_*</B>).
|
|
|
|
<DT id="245"><B>KEYCTL_ASSUME_AUTHORITY</B>
|
|
|
|
<DD>
|
|
Either 0, if the ID given was 0,
|
|
or the ID of the authorization key matching the specified key,
|
|
if a nonzero key ID was provided.
|
|
<DT id="246"><B>KEYCTL_GET_SECURITY</B>
|
|
|
|
<DD>
|
|
The size of the LSM security label string
|
|
(including the terminating null byte),
|
|
irrespective of the provided buffer size.
|
|
<DT id="247"><B>KEYCTL_GET_PERSISTENT</B>
|
|
|
|
<DD>
|
|
The ID of the persistent keyring.
|
|
<DT id="248"><B>KEYCTL_DH_COMPUTE</B>
|
|
|
|
<DD>
|
|
The number of bytes copied to the buffer, or, if
|
|
<I>arg4</I>
|
|
|
|
is 0, the required buffer size.
|
|
<DT id="249">All other operations<DD>
|
|
Zero.
|
|
</DL>
|
|
<P>
|
|
|
|
On error, -1 is returned, and
|
|
<I>errno</I>
|
|
|
|
is set appropriately to indicate the error.
|
|
<A NAME="lbAF"> </A>
|
|
<H2>ERRORS</H2>
|
|
|
|
<DL COMPACT>
|
|
<DT id="250"><B>EACCES</B>
|
|
|
|
<DD>
|
|
The requested operation wasn't permitted.
|
|
<DT id="251"><B>EAGAIN</B>
|
|
|
|
<DD>
|
|
<I>operation</I>
|
|
|
|
was
|
|
<B>KEYCTL_DH_COMPUTE</B>
|
|
|
|
and there was an error during crypto module initialization.
|
|
<DT id="252"><B>EDEADLK</B>
|
|
|
|
<DD>
|
|
<I>operation</I>
|
|
|
|
was
|
|
<B>KEYCTL_LINK</B>
|
|
|
|
and the requested link would result in a cycle.
|
|
<DT id="253"><B>EDEADLK</B>
|
|
|
|
<DD>
|
|
<I>operation</I>
|
|
|
|
was
|
|
<B>KEYCTL_RESTRICT_KEYRING</B>
|
|
|
|
and the requested keyring restriction would result in a cycle.
|
|
<DT id="254"><B>EDQUOT</B>
|
|
|
|
<DD>
|
|
The key quota for the caller's user would be exceeded by creating a key or
|
|
linking it to the keyring.
|
|
<DT id="255"><B>EEXIST</B>
|
|
|
|
<DD>
|
|
<I>operation</I>
|
|
|
|
was
|
|
<B>KEYCTL_RESTRICT_KEYRING</B>
|
|
|
|
and keyring provided in
|
|
<I>arg2</I>
|
|
|
|
argument already has a restriction set.
|
|
<DT id="256"><B>EFAULT</B>
|
|
|
|
<DD>
|
|
<I>operation</I>
|
|
|
|
was
|
|
<B>KEYCTL_DH_COMPUTE</B>
|
|
|
|
and one of the following has failed:
|
|
<DL COMPACT><DT id="257"><DD>
|
|
<DL COMPACT>
|
|
<DT id="258">•<DD>
|
|
copying of the
|
|
<I>struct keyctl_dh_params</I>,
|
|
|
|
provided in the
|
|
<I>arg2</I>
|
|
|
|
argument, from user space;
|
|
<DT id="259">•<DD>
|
|
copying of the
|
|
<I>struct keyctl_kdf_params</I>,
|
|
|
|
provided in the non-NULL
|
|
<I>arg5</I>
|
|
|
|
argument, from user space
|
|
(in case kernel supports performing KDF operation on DH operation result);
|
|
<DT id="260">•<DD>
|
|
copying of data pointed by the
|
|
<I>hashname</I>
|
|
|
|
field of the
|
|
<I>struct keyctl_kdf_params</I>
|
|
|
|
from user space;
|
|
<DT id="261">•<DD>
|
|
copying of data pointed by the
|
|
<I>otherinfo</I>
|
|
|
|
field of the
|
|
<I>struct keyctl_kdf_params</I>
|
|
|
|
from user space if the
|
|
<I>otherinfolen</I>
|
|
|
|
field was nonzero;
|
|
<DT id="262">•<DD>
|
|
copying of the result to user space.
|
|
</DL>
|
|
</DL>
|
|
|
|
<DT id="263"><B>EINVAL</B>
|
|
|
|
<DD>
|
|
<I>operation</I>
|
|
|
|
was
|
|
<B>KEYCTL_SETPERM</B>
|
|
|
|
and an invalid permission bit was specified in
|
|
<I>arg3</I>.
|
|
|
|
<DT id="264"><B>EINVAL</B>
|
|
|
|
<DD>
|
|
<I>operation</I>
|
|
|
|
was
|
|
<B>KEYCTL_SEARCH</B>
|
|
|
|
and the size of the description in
|
|
<I>arg4</I>
|
|
|
|
(including the terminating null byte) exceeded 4096 bytes.
|
|
size of the string (including the terminating null byte) specified in
|
|
<I>arg3</I>
|
|
|
|
(the key type)
|
|
or
|
|
<I>arg4</I>
|
|
|
|
(the key description)
|
|
exceeded the limit (32 bytes and 4096 bytes respectively).
|
|
<DT id="265"><B>EINVAL</B> (Linux kernels before 4.12)
|
|
|
|
<DD>
|
|
<I>operation</I>
|
|
|
|
was
|
|
<B>KEYCTL_DH_COMPUTE</B>,
|
|
|
|
argument
|
|
<I>arg5</I>
|
|
|
|
was non-NULL.
|
|
<DT id="266"><B>EINVAL</B>
|
|
|
|
<DD>
|
|
<I>operation</I>
|
|
|
|
was
|
|
<B>KEYCTL_DH_COMPUTE</B>
|
|
|
|
And the digest size of the hashing algorithm supplied is zero.
|
|
<DT id="267"><B>EINVAL</B>
|
|
|
|
<DD>
|
|
<I>operation</I>
|
|
|
|
was
|
|
<B>KEYCTL_DH_COMPUTE</B>
|
|
|
|
and the buffer size provided is not enough to hold the result.
|
|
Provide 0 as a buffer size in order to obtain the minimum buffer size.
|
|
<DT id="268"><B>EINVAL</B>
|
|
|
|
<DD>
|
|
<I>operation</I>
|
|
|
|
was
|
|
<B>KEYCTL_DH_COMPUTE</B>
|
|
|
|
and the hash name provided in the
|
|
<I>hashname</I>
|
|
|
|
field of the
|
|
<I>struct keyctl_kdf_params</I>
|
|
|
|
pointed by
|
|
<I>arg5</I>
|
|
|
|
argument is too big (the limit is implementation-specific and varies between
|
|
kernel versions, but it is deemed big enough for all valid algorithm names).
|
|
<DT id="269"><B>EINVAL</B>
|
|
|
|
<DD>
|
|
|
|
<I>operation</I>
|
|
|
|
was
|
|
<B>KEYCTL_DH_COMPUTE</B>
|
|
|
|
and the
|
|
<I>__spare</I>
|
|
|
|
field of the
|
|
<I>struct keyctl_kdf_params</I>
|
|
|
|
provided in the
|
|
<I>arg5</I>
|
|
|
|
argument contains nonzero values.
|
|
<DT id="270"><B>EKEYEXPIRED</B>
|
|
|
|
<DD>
|
|
An expired key was found or specified.
|
|
<DT id="271"><B>EKEYREJECTED</B>
|
|
|
|
<DD>
|
|
A rejected key was found or specified.
|
|
<DT id="272"><B>EKEYREVOKED</B>
|
|
|
|
<DD>
|
|
A revoked key was found or specified.
|
|
<DT id="273"><B>ELOOP</B>
|
|
|
|
<DD>
|
|
<I>operation</I>
|
|
|
|
was
|
|
<B>KEYCTL_LINK</B>
|
|
|
|
and the requested link would cause the maximum nesting depth
|
|
for keyrings to be exceeded.
|
|
<DT id="274"><B>EMSGSIZE</B>
|
|
|
|
<DD>
|
|
<I>operation</I>
|
|
|
|
was
|
|
<B>KEYCTL_DH_COMPUTE</B>
|
|
|
|
and the buffer length exceeds
|
|
<B>KEYCTL_KDF_MAX_OUTPUT_LEN</B>
|
|
|
|
(which is 1024 currently)
|
|
or the
|
|
<I>otherinfolen</I>
|
|
|
|
field of the
|
|
<I>struct keyctl_kdf_parms</I>
|
|
|
|
passed in
|
|
<I>arg5</I>
|
|
|
|
exceeds
|
|
<B>KEYCTL_KDF_MAX_OI_LEN</B>
|
|
|
|
(which is 64 currently).
|
|
<DT id="275"><B>ENFILE</B> (Linux kernels before 3.13)
|
|
|
|
<DD>
|
|
<I>operation</I>
|
|
|
|
was
|
|
<B>KEYCTL_LINK</B>
|
|
|
|
and the keyring is full.
|
|
(Before Linux 3.13,
|
|
|
|
the available space for storing keyring links was limited to
|
|
a single page of memory; since Linux 3.13, there is no fixed limit.)
|
|
<DT id="276"><B>ENOENT</B>
|
|
|
|
<DD>
|
|
<I>operation</I>
|
|
|
|
was
|
|
<B>KEYCTL_UNLINK</B>
|
|
|
|
and the key to be unlinked isn't linked to the keyring.
|
|
<DT id="277"><B>ENOENT</B>
|
|
|
|
<DD>
|
|
<I>operation</I>
|
|
|
|
was
|
|
<B>KEYCTL_DH_COMPUTE</B>
|
|
|
|
and the hashing algorithm specified in the
|
|
<I>hashname</I>
|
|
|
|
field of the
|
|
<I>struct keyctl_kdf_params</I>
|
|
|
|
pointed by
|
|
<I>arg5</I>
|
|
|
|
argument hasn't been found.
|
|
<DT id="278"><B>ENOENT</B>
|
|
|
|
<DD>
|
|
<I>operation</I>
|
|
|
|
was
|
|
<B>KEYCTL_RESTRICT_KEYRING</B>
|
|
|
|
and the type provided in
|
|
<I>arg3</I>
|
|
|
|
argument doesn't support setting key linking restrictions.
|
|
<DT id="279"><B>ENOKEY</B>
|
|
|
|
<DD>
|
|
No matching key was found or an invalid key was specified.
|
|
<DT id="280"><B>ENOKEY</B>
|
|
|
|
<DD>
|
|
The value
|
|
<B>KEYCTL_GET_KEYRING_ID</B>
|
|
|
|
was specified in
|
|
<I>operation</I>,
|
|
|
|
the key specified in
|
|
<I>arg2</I>
|
|
|
|
did not exist, and
|
|
<I>arg3</I>
|
|
|
|
was zero (meaning don't create the key if it didn't exist).
|
|
<DT id="281"><B>ENOMEM</B>
|
|
|
|
<DD>
|
|
One of kernel memory allocation routines failed during the execution of the
|
|
syscall.
|
|
<DT id="282"><B>ENOTDIR</B>
|
|
|
|
<DD>
|
|
A key of keyring type was expected but the ID of a key with
|
|
a different type was provided.
|
|
<DT id="283"><B>EOPNOTSUPP</B>
|
|
|
|
<DD>
|
|
<I>operation</I>
|
|
|
|
was
|
|
<B>KEYCTL_READ</B>
|
|
|
|
and the key type does not support reading
|
|
(e.g., the type is
|
|
<I>"login"</I>).
|
|
|
|
<DT id="284"><B>EOPNOTSUPP</B>
|
|
|
|
<DD>
|
|
<I>operation</I>
|
|
|
|
was
|
|
<B>KEYCTL_UPDATE</B>
|
|
|
|
and the key type does not support updating.
|
|
<DT id="285"><B>EOPNOTSUPP</B>
|
|
|
|
<DD>
|
|
<I>operation</I>
|
|
|
|
was
|
|
<B>KEYCTL_RESTRICT_KEYRING</B>,
|
|
|
|
the type provided in
|
|
<I>arg3</I>
|
|
|
|
argument was "asymmetric", and the key specified in the restriction specification
|
|
provided in
|
|
<I>arg4</I>
|
|
|
|
has type other than "asymmetric" or "keyring".
|
|
<DT id="286"><B>EPERM</B>
|
|
|
|
<DD>
|
|
<I>operation</I>
|
|
|
|
was
|
|
<B>KEYCTL_GET_PERSISTENT</B>,
|
|
|
|
<I>arg2</I>
|
|
|
|
specified a UID other than the calling thread's real or effective UID,
|
|
and the caller did not have the
|
|
<B>CAP_SETUID</B>
|
|
|
|
capability.
|
|
<DT id="287"><B>EPERM</B>
|
|
|
|
<DD>
|
|
<I>operation</I>
|
|
|
|
was
|
|
<B>KEYCTL_SESSION_TO_PARENT</B>
|
|
|
|
and either:
|
|
all of the UIDs (GIDs) of the parent process do not match
|
|
the effective UID (GID) of the calling process;
|
|
the UID of the parent's existing session keyring or
|
|
the UID of the caller's session keyring did not match
|
|
the effective UID of the caller;
|
|
the parent process is not single-thread;
|
|
or the parent process is
|
|
<B><A HREF="/cgi-bin/man/man2html?1+init">init</A></B>(1)
|
|
|
|
or a kernel thread.
|
|
<DT id="288"><B>ETIMEDOUT</B>
|
|
|
|
<DD>
|
|
<I>operation</I>
|
|
|
|
was
|
|
<B>KEYCTL_DH_COMPUTE</B>
|
|
|
|
and the initialization of crypto modules has timed out.
|
|
</DL>
|
|
<A NAME="lbAG"> </A>
|
|
<H2>VERSIONS</H2>
|
|
|
|
This system call first appeared in Linux 2.6.10.
|
|
<A NAME="lbAH"> </A>
|
|
<H2>CONFORMING TO</H2>
|
|
|
|
This system call is a nonstandard Linux extension.
|
|
<A NAME="lbAI"> </A>
|
|
<H2>NOTES</H2>
|
|
|
|
No wrapper for this system call is provided in glibc.
|
|
A wrapper is provided in the
|
|
<I>libkeyutils</I>
|
|
|
|
library.
|
|
When employing the wrapper in that library, link with
|
|
<I>-lkeyutils</I>.
|
|
|
|
However, rather than using this system call directly,
|
|
you probably want to use the various library functions
|
|
mentioned in the descriptions of individual operations above.
|
|
<A NAME="lbAJ"> </A>
|
|
<H2>EXAMPLE</H2>
|
|
|
|
The program below provide subset of the functionality of the
|
|
<B><A HREF="/cgi-bin/man/man2html?8+request-key">request-key</A></B>(8)
|
|
|
|
program provided by the
|
|
<I>keyutils</I>
|
|
|
|
package.
|
|
For informational purposes,
|
|
the program records various information in a log file.
|
|
<P>
|
|
|
|
As described in
|
|
<B><A HREF="/cgi-bin/man/man2html?2+request_key">request_key</A></B>(2),
|
|
|
|
the
|
|
<B><A HREF="/cgi-bin/man/man2html?8+request-key">request-key</A></B>(8)
|
|
|
|
program is invoked with command-line arguments that
|
|
describe a key that is to be instantiated.
|
|
The example program fetches and logs these arguments.
|
|
The program assumes authority to instantiate the requested key,
|
|
and then instantiates that key.
|
|
<P>
|
|
|
|
The following shell session demonstrates the use of this program.
|
|
In the session,
|
|
we compile the program and then use it to temporarily replace the standard
|
|
<B><A HREF="/cgi-bin/man/man2html?8+request-key">request-key</A></B>(8)
|
|
|
|
program.
|
|
(Note that temporarily disabling the standard
|
|
<B><A HREF="/cgi-bin/man/man2html?8+request-key">request-key</A></B>(8)
|
|
|
|
program may not be safe on some systems.)
|
|
While our example program is installed,
|
|
we use the example program shown in
|
|
<B><A HREF="/cgi-bin/man/man2html?2+request_key">request_key</A></B>(2)
|
|
|
|
to request a key.
|
|
<P>
|
|
|
|
|
|
|
|
$ <B>cc -o key_instantiate key_instantiate.c -lkeyutils</B>
|
|
$ <B>sudo mv /sbin/request-key /sbin/request-key.backup</B>
|
|
$ <B>sudo cp key_instantiate /sbin/request-key</B>
|
|
$ <B>./t_request_key user mykey somepayloaddata</B>
|
|
Key ID is 20d035bf
|
|
$ <B>sudo mv /sbin/request-key.backup /sbin/request-key</B>
|
|
|
|
|
|
<P>
|
|
|
|
Looking at the log file created by this program,
|
|
we can see the command-line arguments supplied to our example program:
|
|
<P>
|
|
|
|
|
|
|
|
$ <B>cat /tmp/key_instantiate.log </B>
|
|
Time: Mon Nov 7 13:06:47 2016
|
|
<P>
|
|
Command line arguments:
|
|
<BR> argv[0]: /sbin/request-key
|
|
<BR> operation: create
|
|
<BR> key_to_instantiate: 20d035bf
|
|
<BR> UID: 1000
|
|
<BR> GID: 1000
|
|
<BR> thread_keyring: 0
|
|
<BR> process_keyring: 0
|
|
<BR> session_keyring: 256e6a6
|
|
<P>
|
|
Key description: user;1000;1000;3f010000;mykey
|
|
Auth key payload: somepayloaddata
|
|
Destination keyring: 256e6a6
|
|
Auth key description: .request_key_auth;1000;1000;0b010000;20d035bf
|
|
|
|
|
|
<P>
|
|
|
|
The last few lines of the above output show that the example program
|
|
was able to fetch:
|
|
<DL COMPACT>
|
|
<DT id="289">*<DD>
|
|
the description of the key to be instantiated,
|
|
which included the name of the key
|
|
(<I>mykey</I>);
|
|
|
|
<DT id="290">*<DD>
|
|
the payload of the authorization key, which consisted of the data
|
|
(<I>somepayloaddata</I>)
|
|
|
|
passed to
|
|
<B><A HREF="/cgi-bin/man/man2html?2+request_key">request_key</A></B>(2);
|
|
|
|
<DT id="291">*<DD>
|
|
the destination keyring that was specified in the call to
|
|
<B><A HREF="/cgi-bin/man/man2html?2+request_key">request_key</A></B>(2);
|
|
|
|
and
|
|
<DT id="292">*<DD>
|
|
the description of the authorization key,
|
|
where we can see that the name of the authorization key matches
|
|
the ID of the key that is to be instantiated
|
|
(<I>20d035bf</I>).
|
|
|
|
</DL>
|
|
<P>
|
|
|
|
The example program in
|
|
<B><A HREF="/cgi-bin/man/man2html?2+request_key">request_key</A></B>(2)
|
|
|
|
specified the destination keyring as
|
|
<B>KEY_SPEC_SESSION_KEYRING</B>.
|
|
|
|
By examining the contents of
|
|
<I>/proc/keys</I>,
|
|
|
|
we can see that this was translated to the ID of the destination keyring
|
|
(<I>0256e6a6</I>)
|
|
|
|
shown in the log output above;
|
|
we can also see the newly created key with the name
|
|
<I>mykey</I>
|
|
|
|
and ID
|
|
<I>20d035bf</I>.
|
|
|
|
<P>
|
|
|
|
|
|
|
|
$ <B>cat /proc/keys | egrep 'mykey|256e6a6'</B>
|
|
0256e6a6 I--Q--- 194 perm 3f030000 1000 1000 keyring _ses: 3
|
|
20d035bf I--Q--- 1 perm 3f010000 1000 1000 user mykey: 16
|
|
|
|
|
|
<A NAME="lbAK"> </A>
|
|
<H3>Program source</H3>
|
|
|
|
|
|
|
|
/* key_instantiate.c */
|
|
<P>
|
|
#include <<A HREF="file:///usr/include/sys/types.h">sys/types.h</A>>
|
|
#include <<A HREF="file:///usr/include/keyutils.h">keyutils.h</A>>
|
|
#include <<A HREF="file:///usr/include/time.h">time.h</A>>
|
|
#include <<A HREF="file:///usr/include/fcntl.h">fcntl.h</A>>
|
|
#include <<A HREF="file:///usr/include/stdio.h">stdio.h</A>>
|
|
#include <<A HREF="file:///usr/include/stdlib.h">stdlib.h</A>>
|
|
#include <<A HREF="file:///usr/include/unistd.h">unistd.h</A>>
|
|
#include <<A HREF="file:///usr/include/string.h">string.h</A>>
|
|
#include <<A HREF="file:///usr/include/errno.h">errno.h</A>>
|
|
<P>
|
|
#ifndef KEY_SPEC_REQUESTOR_KEYRING
|
|
#define KEY_SPEC_REQUESTOR_KEYRING -8
|
|
#endif
|
|
<P>
|
|
int
|
|
main(int argc, char *argv[])
|
|
{
|
|
<BR> FILE *fp;
|
|
<BR> time_t t;
|
|
<BR> char *operation;
|
|
<BR> key_serial_t key_to_instantiate, dest_keyring;
|
|
<BR> key_serial_t thread_keyring, process_keyring, session_keyring;
|
|
<BR> uid_t uid;
|
|
<BR> gid_t gid;
|
|
<BR> char dbuf[256];
|
|
<BR> char auth_key_payload[256];
|
|
<BR> int akp_size; /* Size of auth_key_payload */
|
|
<P>
|
|
<BR> fp = fopen("/tmp/key_instantiate.log", "w");
|
|
<BR> if (fp == NULL)
|
|
<BR> exit(EXIT_FAILURE);
|
|
<P>
|
|
<BR> setbuf(fp, NULL);
|
|
<P>
|
|
<BR> t = time(NULL);
|
|
<BR> fprintf(fp, "Time: %s\n", ctime(&t));
|
|
<P>
|
|
<BR> /*
|
|
<BR> * The kernel passes a fixed set of arguments to the program
|
|
<BR> * that it execs; fetch them.
|
|
<BR> */
|
|
<BR> operation = argv[1];
|
|
<BR> key_to_instantiate = atoi(argv[2]);
|
|
<BR> uid = atoi(argv[3]);
|
|
<BR> gid = atoi(argv[4]);
|
|
<BR> thread_keyring = atoi(argv[5]);
|
|
<BR> process_keyring = atoi(argv[6]);
|
|
<BR> session_keyring = atoi(argv[7]);
|
|
<P>
|
|
<BR> fprintf(fp, "Command line arguments:\n");
|
|
<BR> fprintf(fp, " argv[0]: %s\n", argv[0]);
|
|
<BR> fprintf(fp, " operation: %s\n", operation);
|
|
<BR> fprintf(fp, " key_to_instantiate: %lx\n",
|
|
<BR> (long) key_to_instantiate);
|
|
<BR> fprintf(fp, " UID: %ld\n", (long) uid);
|
|
<BR> fprintf(fp, " GID: %ld\n", (long) gid);
|
|
<BR> fprintf(fp, " thread_keyring: %lx\n", (long) thread_keyring);
|
|
<BR> fprintf(fp, " process_keyring: %lx\n", (long) process_keyring);
|
|
<BR> fprintf(fp, " session_keyring: %lx\n", (long) session_keyring);
|
|
<BR> fprintf(fp, "\n");
|
|
<P>
|
|
<BR> /*
|
|
<BR> * Assume the authority to instantiate the key named in argv[2]
|
|
<BR> */
|
|
<BR> if (keyctl(KEYCTL_ASSUME_AUTHORITY, key_to_instantiate) == -1) {
|
|
<BR> fprintf(fp, "KEYCTL_ASSUME_AUTHORITY failed: %s\n",
|
|
<BR> strerror(errno));
|
|
<BR> exit(EXIT_FAILURE);
|
|
<BR> }
|
|
<P>
|
|
<BR> /*
|
|
<BR> * Fetch the description of the key that is to be instantiated
|
|
<BR> */
|
|
<BR> if (keyctl(KEYCTL_DESCRIBE, key_to_instantiate,
|
|
<BR> dbuf, sizeof(dbuf)) == -1) {
|
|
<BR> fprintf(fp, "KEYCTL_DESCRIBE failed: %s\n", strerror(errno));
|
|
<BR> exit(EXIT_FAILURE);
|
|
<BR> }
|
|
<P>
|
|
<BR> fprintf(fp, "Key description: %s\n", dbuf);
|
|
<P>
|
|
<BR> /*
|
|
<BR> * Fetch the payload of the authorization key, which is
|
|
<BR> * actually the callout data given to request_key()
|
|
<BR> */
|
|
<BR> akp_size = keyctl(KEYCTL_READ, KEY_SPEC_REQKEY_AUTH_KEY,
|
|
<BR> auth_key_payload, sizeof(auth_key_payload));
|
|
<BR> if (akp_size == -1) {
|
|
<BR> fprintf(fp, "KEYCTL_READ failed: %s\n", strerror(errno));
|
|
<BR> exit(EXIT_FAILURE);
|
|
<BR> }
|
|
<P>
|
|
<BR> auth_key_payload[akp_size] = '\0';
|
|
<BR> fprintf(fp, "Auth key payload: %s\n", auth_key_payload);
|
|
<P>
|
|
<BR> /*
|
|
<BR> * For interest, get the ID of the authorization key and
|
|
<BR> * display it.
|
|
<BR> */
|
|
<BR> auth_key = keyctl(KEYCTL_GET_KEYRING_ID,
|
|
<BR> KEY_SPEC_REQKEY_AUTH_KEY);
|
|
<BR> if (auth_key == -1) {
|
|
<BR> fprintf(fp, "KEYCTL_GET_KEYRING_ID failed: %s\n",
|
|
<BR> strerror(errno));
|
|
<BR> exit(EXIT_FAILURE);
|
|
<BR> }
|
|
<P>
|
|
<BR> fprintf(fp, "Auth key ID: %lx\n", (long) auth_key);
|
|
<P>
|
|
<BR> /*
|
|
<BR> * Fetch key ID for the <A HREF="/cgi-bin/man/man2html?2+request_key">request_key</A>(2) destination keyring.
|
|
<BR> */
|
|
<BR> dest_keyring = keyctl(KEYCTL_GET_KEYRING_ID,
|
|
<BR> KEY_SPEC_REQUESTOR_KEYRING);
|
|
<BR> if (dest_keyring == -1) {
|
|
<BR> fprintf(fp, "KEYCTL_GET_KEYRING_ID failed: %s\n",
|
|
<BR> strerror(errno));
|
|
<BR> exit(EXIT_FAILURE);
|
|
<BR> }
|
|
<P>
|
|
<BR> fprintf(fp, "Destination keyring: %lx\n", (long) dest_keyring);
|
|
<P>
|
|
<BR> /*
|
|
<BR> * Fetch the description of the authorization key. This
|
|
<BR> * allows us to see the key type, UID, GID, permissions,
|
|
<BR> * and description (name) of the key. Among other things,
|
|
<BR> * we will see that the name of the key is a hexadecimal
|
|
<BR> * string representing the ID of the key to be instantiated.
|
|
<BR> */
|
|
<BR> if (keyctl(KEYCTL_DESCRIBE, KEY_SPEC_REQKEY_AUTH_KEY,
|
|
<BR> dbuf, sizeof(dbuf)) == -1) {
|
|
<BR> fprintf(fp, "KEYCTL_DESCRIBE failed: %s\n", strerror(errno));
|
|
<BR> exit(EXIT_FAILURE);
|
|
<BR> }
|
|
<P>
|
|
<BR> fprintf(fp, "Auth key description: %s\n", dbuf);
|
|
<P>
|
|
<BR> /*
|
|
<BR> * Instantiate the key using the callout data that was supplied
|
|
<BR> * in the payload of the authorization key.
|
|
<BR> */
|
|
<BR> if (keyctl(KEYCTL_INSTANTIATE, key_to_instantiate,
|
|
<BR> auth_key_payload, akp_size + 1, dest_keyring) == -1) {
|
|
<BR> fprintf(fp, "KEYCTL_INSTANTIATE failed: %s\n",
|
|
<BR> strerror(errno));
|
|
<BR> exit(EXIT_FAILURE);
|
|
<BR> }
|
|
<P>
|
|
<BR> exit(EXIT_SUCCESS);
|
|
}
|
|
|
|
<A NAME="lbAL"> </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+add_key">add_key</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?3+keyctl_assume_authority">keyctl_assume_authority</A></B>(3),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?3+keyctl_chown">keyctl_chown</A></B>(3),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?3+keyctl_clear">keyctl_clear</A></B>(3),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?3+keyctl_describe">keyctl_describe</A></B>(3),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?3+keyctl_describe_alloc">keyctl_describe_alloc</A></B>(3),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?3+keyctl_dh_compute">keyctl_dh_compute</A></B>(3),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?3+keyctl_dh_compute_alloc">keyctl_dh_compute_alloc</A></B>(3),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?3+keyctl_get_keyring_ID">keyctl_get_keyring_ID</A></B>(3),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?3+keyctl_get_persistent">keyctl_get_persistent</A></B>(3),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?3+keyctl_get_security">keyctl_get_security</A></B>(3),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?3+keyctl_get_security_alloc">keyctl_get_security_alloc</A></B>(3),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?3+keyctl_instantiate">keyctl_instantiate</A></B>(3),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?3+keyctl_instantiate_iov">keyctl_instantiate_iov</A></B>(3),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?3+keyctl_invalidate">keyctl_invalidate</A></B>(3),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?3+keyctl_join_session_keyring">keyctl_join_session_keyring</A></B>(3),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?3+keyctl_link">keyctl_link</A></B>(3),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?3+keyctl_negate">keyctl_negate</A></B>(3),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?3+keyctl_read">keyctl_read</A></B>(3),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?3+keyctl_read_alloc">keyctl_read_alloc</A></B>(3),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?3+keyctl_reject">keyctl_reject</A></B>(3),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?3+keyctl_revoke">keyctl_revoke</A></B>(3),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?3+keyctl_search">keyctl_search</A></B>(3),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?3+keyctl_session_to_parent">keyctl_session_to_parent</A></B>(3),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?3+keyctl_set_reqkey_keyring">keyctl_set_reqkey_keyring</A></B>(3),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?3+keyctl_set_timeout">keyctl_set_timeout</A></B>(3),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?3+keyctl_setperm">keyctl_setperm</A></B>(3),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?3+keyctl_unlink">keyctl_unlink</A></B>(3),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?3+keyctl_update">keyctl_update</A></B>(3),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?3+recursive_key_scan">recursive_key_scan</A></B>(3),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?3+recursive_session_key_scan">recursive_session_key_scan</A></B>(3),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?7+capabilities">capabilities</A></B>(7),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?7+credentials">credentials</A></B>(7),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?7+keyrings">keyrings</A></B>(7),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?7+keyutils">keyutils</A></B>(7),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?7+persistent-keyring">persistent-keyring</A></B>(7),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?7+process-keyring">process-keyring</A></B>(7),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?7+session-keyring">session-keyring</A></B>(7),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?7+thread-keyring">thread-keyring</A></B>(7),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?7+user-keyring">user-keyring</A></B>(7),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?7+user_namespaces">user_namespaces</A></B>(7),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?7+user-session-keyring">user-session-keyring</A></B>(7),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?8+request-key">request-key</A></B>(8)
|
|
|
|
<P>
|
|
|
|
The kernel source files under
|
|
<I>Documentation/security/keys/</I>
|
|
|
|
(or, before Linux 4.13, in the file
|
|
<I>Documentation/security/keys.txt</I>).
|
|
|
|
<A NAME="lbAM"> </A>
|
|
<H2>COLOPHON</H2>
|
|
|
|
This page is part of release 5.05 of the Linux
|
|
<I>man-pages</I>
|
|
|
|
project.
|
|
A description of the project,
|
|
information about reporting bugs,
|
|
and the latest version of this page,
|
|
can be found at
|
|
<A HREF="https://www.kernel.org/doc/man-pages/.">https://www.kernel.org/doc/man-pages/.</A>
|
|
<P>
|
|
|
|
<HR>
|
|
<A NAME="index"> </A><H2>Index</H2>
|
|
<DL>
|
|
<DT id="293"><A HREF="#lbAB">NAME</A><DD>
|
|
<DT id="294"><A HREF="#lbAC">SYNOPSIS</A><DD>
|
|
<DT id="295"><A HREF="#lbAD">DESCRIPTION</A><DD>
|
|
<DT id="296"><A HREF="#lbAE">RETURN VALUE</A><DD>
|
|
<DT id="297"><A HREF="#lbAF">ERRORS</A><DD>
|
|
<DT id="298"><A HREF="#lbAG">VERSIONS</A><DD>
|
|
<DT id="299"><A HREF="#lbAH">CONFORMING TO</A><DD>
|
|
<DT id="300"><A HREF="#lbAI">NOTES</A><DD>
|
|
<DT id="301"><A HREF="#lbAJ">EXAMPLE</A><DD>
|
|
<DL>
|
|
<DT id="302"><A HREF="#lbAK">Program source</A><DD>
|
|
</DL>
|
|
<DT id="303"><A HREF="#lbAL">SEE ALSO</A><DD>
|
|
<DT id="304"><A HREF="#lbAM">COLOPHON</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:33 GMT, March 31, 2021
|
|
</BODY>
|
|
</HTML>
|