keyctl.2: Improve KEYCTL_ASSUME_AUTHORITY details

[thirdparty/man-pages.git] / man2 / keyctl.2

.\" Copyright (C) 2006 Red Hat, Inc. All Rights Reserved.
.\" Written by David Howells (dhowells@redhat.com)
.\"
.\" %%%LICENSE_START(GPLv2+_SW_ONEPARA)
.\" This program is free software; you can redistribute it and/or
.\" modify it under the terms of the GNU General Public License
.\" as published by the Free Software Foundation; either version
.\" 2 of the License, or (at your option) any later version.
.\" %%%LICENSE_END
.\"
.TH KEYCTL 2 2015-05-07 Linux "Linux Key Management Calls"
.SH NAME
keyctl \- manipulate the kernel's key management facility
.SH SYNOPSIS
.nf
.B #include <keyutils.h>
.sp
.BI "long keyctl(int " cmd ", ...)"
.sp
.B "/* For direct call via syscall(2): */"
.B #include <asm/unistd.h>
.B #include <linux/keyctl.h>
.B #include <unistd.h>
.sp
.BI "long syscall(__NR_keyctl, int " option ", __kernel_ulong_t " arg2 ,
.BI "             __kernel_ulong_t " arg3 ", __kernel_ulong_t " arg4 ,
.BI "             __kernel_ulong_t " arg5 );
.fi
.SH DESCRIPTION
.BR keyctl ()
allows user-space programs to perform key manipulation.

The operation performed by
.BR keyctl ()
is determined by the value of the
.I option
argument.
Each of these operations is wrapped by
.B libkeyutils
into individual functions (listed under SEE ALSO)
to permit the compiler to check types.

The permitted values for
.I option
are:
.TP
.BR KEYCTL_GET_KEYRING_ID " (since Linux 2.6.11)"
Map a special key ID to a real key ID for this process.

This operation looks up the special key whose ID is provided in
.I arg2
(cast to
.IR key_serial_t )
and (if it is found) the ID of corresponding real key is returned

If the key specified in
.I arg2
does not exist, then a new key is created if the
.I arg3
argument (cast to
.IR int )
contains a non-zero value; otherwise the operation fails with the error
.BR ENOKEY .

The caller must have
.I search
permission on a keyring in order for it to be found.

The arguments
.IR arg4
and
.IR arg5
are ignored.

This operation is exposed by
.I libkeyutils
via the function
.BR keyctl_get_keyring_ID (3).
.TP
.BR KEYCTL_JOIN_SESSION_KEYRING " (since Linux 2.6.11)"
Replace the session keyring this process subscribes to with
a new session keyring.

If
.I arg2
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.

Otherwise,
.I arg2
(cast to
.IR "char\ *" )
is treated as the description (name) of a keyring,
and the behavior is as follows:
.RS
.IP * 3
If a keyring with a matching description exists,
the process will attempt to subscribe to that keyring if possible;
if that is not possible, an error is returned.
.\" FIXME What error is returned?
In order to subscribe to the keyring,
the caller must have
.I search
permission on the keyring.
.IP *
If a keyring with a matching description does not exist,
then a new keyring with that description is created,
and the process is subscribed to that keyring as its session keyring,
displacing the previous session keyring.
.RE
.IP
The arguments
.IR arg3 ,
.IR arg4 ,
and
.IR arg5
are ignored.

This operation is exposed by
.I libkeyutils
via the function
.BR keyctl_join_session_keyring (3).
.TP
.BR KEYCTL_UPDATE " (since Linux 2.6.11)"
Update a key's data payload.

The
.I arg2
argument (cast to
.IR key_serial_t )
specifies the ID of the key to be updated.
The
.I arg3
argument (cast to
.IR "void\ *" )
points to the new payload and
.I arg4
(cast to
.IR size_t )
contains the new payload size in bytes.

The caller must have
.I write
permission on the key specified and the key type must support updating.

.\" FIXME What does the following mean?
A negative key can be positively instantiated with this call.

The
.I arg5
argument is ignored.

This operation is exposed by
.I libkeyutils
via the function
.BR keyctl_update (3).
.TP
.BR KEYCTL_REVOKE " (since Linux 2.6.11)"
Revoke the key with the ID provided in
.I arg2
(cast to
.IR key_serial_t ).

The caller must have
.IR write
or
.IR setattr
permission on the key.
.\" FIXME Keys with the KEY_FLAG_KEEP bit set cause an EPERM
.\"       error for KEYCTL_REVOKE. Does this need to be documented?
.\"       (It's not clear how KEY_FLAG_KEEP gets set.)

The arguments
.IR arg3 ,
.IR arg4 ,
and
.IR arg5
are ignored.

This operation is exposed by
.I libkeyutils
via the function
.BR keyctl_revoke (3).
.TP
.BR KEYCTL_CHOWN " (since Linux 2.6.11)"
Change the ownership (user and group ID) of a key.

The
.I arg2
argument (cast to
.IR key_serial_t )
contains the key ID.
The
.I arg3
argument (cast to
.IR uid_t )
contains the new user ID (or \-1 in case the user ID shouldn't be changed).
The
.I arg4
argument (cast to
.IR gid_t )
contains the new group ID (or \-1 in case the group ID shouldn't be changed).

The key must grant the caller
.I setattr
permission.

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
capability (see
.BR capabilities (7)).

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.

The
.I arg5
argument is ignored.

This operation is exposed by
.I libkeyutils
via the function
.BR keyctl_chown (3).
.TP
.BR KEYCTL_SETPERM " (since Linux 2.6.11)"
Change the permissions of the key with the ID provided in the
.I arg2
argument (cast to
.IR key_serial_t )
to the permissions provided in the
.I arg3
argument (cast to
.IR key_perm_t ).

The key must grant
.I setattr
permission to the caller.

If the caller doesn't have the
.B CAP_SYS_ADMIN
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.)

The permissions in
.IR arg3
specify masks of available operations
for each of the following user categories:
.RS
.TP
.IR possessor " (since Linux 2.6.14)"
.\" commit 664cceb0093b755739e56572b836a99104ee8a75
This is the permission granted to a process that possesses the key
(has it attached searchably to one of the process's keyrings);
see
.BR keyrings (7).
.TP
.IR user
This is the permission granted to a process
whose filesystem UID matches the UID of the key.
.TP
.IR group
This is the permission granted to a process
whose filesystem GID or any of its supplementary GIDs
matches the GID of the key.
.TP
.IR other
This is the permission granted to other processes
that do not match the
.IR user
and
.IR group
categories.
.RE
.IP
The
.IR user ,
.IR group ,
and
.IR other
categories are exclusive: if a process matches the
.IR user
category, it will not receive permissions granted in the
.IR group
category; if a process matches the
.I user
or
.IR group
category, then it will not receive permissions granted in the
.IR other
category.

The
.I possessor 
category grants permissions that are cumulative with the grants from the
.IR user ,
.IR group ,
or
.IR other
category.

Each permission mask is eight bits in size,
with only six bits currently used.
The available permissions are:
.RS
.TP
.IR view
This permission allows reading attributes of a key.

This permission is required for the
.BR KEYCTL_DESCRIBE
operation.

The permission bits for each category are
.BR KEY_POS_VIEW ,
.BR KEY_USR_VIEW ,
.BR KEY_GRP_VIEW ,
and
.BR KEY_OTH_VIEW .
.TP
.IR read
This permission allows reading a key's payload.

This permission is required for the
.BR KEYCTL_READ
operation.

The permission bits for each category are
.BR KEY_POS_READ ,
.BR KEY_USR_READ ,
.BR KEY_GRP_READ ,
and
.BR KEY_OTH_READ .
.TP
.IR write
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,

This permission is required for the
.BR KEYCTL_UPDATE ,
.BR KEYCTL_REVOKE ,
.BR KEYCTL_CLEAR ,
.BR KEYCTL_LINK ,
and
.BR KEYCTL_UNLINK
operations.

The permission bits for each category are
.BR KEY_POS_WRITE ,
.BR KEY_USR_WRITE ,
.BR KEY_GRP_WRITE ,
and
.BR KEY_OTH_WRITE .
.TP
.IR search
This permission allows keyrings to be searched and keys to be found.
Searches can recurse only into nested keyrings
that have search permission set.

This permission is required for the
.BR KEYCTL_GET_KEYRING_ID ,
.BR KEYCTL_JOIN_SESSION_KEYRING ,
.BR KEYCTL_SEARCH ,
and
.BR KEYCTL_INVALIDATE
operations.

The permission bits for each category are
.BR KEY_POS_SEARCH ,
.BR KEY_USR_SEARCH ,
.BR KEY_GRP_SEARCH ,
and
.BR KEY_OTH_SEARCH .
.TP
.IR link
This permission allows a key or keyring to be linked to.

This permission is required for the
.BR KEYCTL_LINK
and
.BR KEYCTL_SESSION_TO_PARENT
operations.

The permission bits for each category are
.BR KEY_POS_LINK ,
.BR KEY_USR_LINK ,
.BR KEY_GRP_LINK ,
and
.BR KEY_OTH_LINK .
.TP
.IR setattr " (since Linux 2.6.15)."
This permission allows a key's UID, GID, and permissions mask to be changed.

This permission is required for the
.BR KEYCTL_REVOKE ,
.BR KEYCTL_CHOWN ,
and
.BR KEYCTL_SETPERM
operations.

The permission bits for each category are
.BR KEY_POS_SETATTR ,
.BR KEY_USR_SETATTR ,
.BR KEY_GRP_SETATTR ,
and
.BR KEY_OTH_SETATTR .
.RE
.IP
As a convenience, the following macros are defined as masks for
all of the permission bits in each of the user categories:
.BR KEY_POS_ALL ,
.BR KEY_USR_ALL,
.BR KEY_GRP_ALL ,
and
.BR KEY_OTH_ALL .

The
.IR arg4 " and " arg5
arguments are ignored.

This operation is exposed by
.I libkeyutils
via the function
.BR keyctl_setperm (3).
.TP
.BR KEYCTL_DESCRIBE " (since Linux 2.6.11)"
Obtain a description of a key.

The ID of the key to be described is specified in
.I arg2
(cast to
.IR key_serial_t ).
The description is returned in the buffer pointed to by
.I arg3
(cast to
.IR "char\ *" ),
and
.I arg4
(cast to
.IR size_t )
specifies the size of that buffer in bytes.

The key must grant the caller
.I view
permission.

The returned description contains the following information about the key:

.in +4n
.IR type ; uid ; gid ; perm ; description "<NUL>"
.in

In the above,
.IR type
and
.IR description
are strings,
.IR uid
and
.IR gid
are decimal strings, and
.I perm
is a hexadecimal permissions mask.
The description is written with the following format string:

    %s;%d;%d;%08x;%s

.BR "Note: the intention is that the key description string should"
.BR "be extensible in future kernel versions".
In particular, the
.IR description
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 key description in the future.

Writing to the buffer is attempted only when
.IR arg3
is non-NULL and the specified buffer size
is large enough to accept the description
(including the terminating null byte).
'\" Function commentary says it copies up to buflen bytes, but see the
'\" (buffer && buflen >= ret) condition in keyctl_describe_key() in
'\" security/keyctl.c
In order to determine whether the buffer size was too small,
check to see if the return value of the operation is greater than
.IR arg4 .

The
.I arg5
argument is ignored.

This operation is exposed by
.I libkeyutils
via the function
.BR keyctl_describe (3).
.TP
.B KEYCTL_CLEAR
Clear the contents of (i.e., unlink all keys from) a keyring.

The ID of the key
(which must be of keyring type)
.\" or the error ENOTDIR results
is provided in
.I arg2
(cast to
.IR key_serial_t ).
.\" According to Documentation/security/keys.txt:
.\"     This function can also be used to clear special kernel keyrings if they
.\"     are appropriately marked if the user has CAP_SYS_ADMIN capability.  The
.\"     DNS resolver cache keyring is an example of this.

The caller must have
.I write
permission on the keyring.

The arguments
.IR arg3 ,
.IR arg4 ,
and
.IR arg5
are ignored.

This operation is exposed by
.I libkeyutils
via the function
.BR keyctl_clear (3).
.TP
.BR KEYCTL_LINK " (since Linux 2.6.11)"
Create a link from a keyring to a key.

The key to be linked is specified in
.IR arg2
(cast to
.IR key_serial_t );
the keyring is specified in
.IR arg3
(cast to
.IR key_serial_t ).

If a key with the same type and description is already linked in the keyring,
then that key is displaced from the keyring.

Before creating the link,
the kernel checks the nesting of the keyrings and returns appropriate errors
if the nesting is too deep
.\" KEYRING_SEARCH_MAX_DEPTH 6
or if the link would produce a cycle.

The caller must have
.I link
permission on the key being added and
.I write
permission on the keyring.

The arguments
.IR arg4
and
.IR arg5
are ignored.

This operation is exposed by
.I libkeyutils
via the function
.BR keyctl_link (3).
.TP
.BR KEYCTL_UNLINK " (since Linux 2.6.11)"
Unlink a key from a keyring.

The ID of the key to be unlinked is specified in
.I arg2
(cast to
.IR key_serial_t );
the ID of the keyring from which it is to be unlinked is specified in
.I arg3
(cast to
.IR key_serial_t ).

If the key is not currently linked into the keyring, an error results.

The caller must have
.I write
permission on the keyring from which the key is being removed.

If the last link to a key is removed,
then that key will be scheduled for destruction.

The arguments
.IR arg4
and
.IR arg5
are ignored.

This operation is exposed by
.I libkeyutils
via the function
.BR keyctl_unlink (3).
.TP
.BR KEYCTL_SEARCH " (since Linux 2.6.11)"
Search for a key in a keyring tree,
returning its ID and optionally linking it to a specified keyring.

The tree to be searched is specified by passing
the ID of the head keyring in
.IR arg2
(cast to
.IR key_serial_t ).
The search is performed breadth-first and recursively.

The
.I arg3
and
.I arg4
arguments specify the key to be searched for:
.I arg3
(cast as
.IR "char\ *" )
contains the key type
(a null-terminated character string up to 32 bytes in size,
including the terminating null byte), and
.I arg4
(cast as
.IR "char\ *" )
contains the description of the key
(a null-terminated character string up to 4096 bytes in size,
including the terminating null byte).

The source keyring must grant
.I search
permission to the caller.
When performing the recursive search, only keyrings that grant the caller
.I search
permission will be searched.
Only keys with for which the caller has
.I search
permission can be found.

If the key is found, its ID is returned as the function result.

If the key is found and
.I arg5
(cast to
.IR key_serial_t )
is nonzero, then, subject to the same constraints and rules as
.BR KEYCTL_LINK ,
the key is linked into the keyring whose ID is specified in
.IR arg5 .
If the destination keyring specified in
.I arg5
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.

Instead of valid existing keyring IDs, the source
.RI ( arg2 )
and destination
.RI ( arg5 )
keyrings can be one of the following special keyring IDs:
.RS
.TP
.B KEY_SPEC_THREAD_KEYRING
This specifies the caller's thread-specific keyring.
See
.BR thread_keyring (7).
.TP
.B KEY_SPEC_PROCESS_KEYRING
This specifies the caller's process-specific keyring.
See
.BR process_keyring (7).
.TP
.B KEY_SPEC_SESSION_KEYRING
This specifies the caller's session-specific keyring.
See
.BR session_keyring (7).
.TP
.B KEY_SPEC_USER_KEYRING
This specifies the caller's UID-specific keyring.
See
.BR user_keyring (7).
.TP
.B KEY_SPEC_USER_SESSION_KEYRING
This specifies the caller's UID-session keyring.
See
.BR user_session_keyring (7).
.TP
.BR KEY_SPEC_REQKEY_AUTH_KEY " (since Linux 2.6.16)"
.\"            commit b5f545c880a2a47947ba2118b2509644ab7a2969
This specifies the authorization key created by
.BR request_key (2)
and passed to the process it spawns to generate a key.
.TP
.BR KEY_SPEC_REQUESTOR_KEYRING " (since Linux 2.6.29)"
.\"            commit 8bbf4976b59fc9fc2861e79cab7beb3f6d647640
This specifies the key ID for the
.BR request_key (2)
destination keyring.
.\" FIXME What about:
.\"    KEY_SPEC_REQKEY_AUTH_KEY (2.6.16)
.\"    KEY_SPEC_REQUESTOR_KEYRING (2.6.29)
.RE
.IP
This operation is exposed by
.I libkeyutils
via the function
.BR keyctl_search (3).
.TP
.BR KEYCTL_READ " (since Linux 2.6.11)"
Read the payload data of a key.

The ID of the key whose payload is to be read is specified in
.I arg2
(cast to
.IR key_serial_t ).
The payload is placed in the buffer pointed by
.I arg3
(cast to
.IR "char\ *" );
the size of that buffer must be specified in
.I arg4
(cast to
.IR size_t ).

The key must either grant the caller
.I read
permission, or grant the caller
.I search
permission when searched for from the process keyrings.

The
.I arg5
argument is ignored.

This operation is exposed by
.I libkeyutils
via the function
.BR keyctl_read (3).
.TP
.BR KEYCTL_INSTANTIATE " (since Linux 2.6.11)"
.\" FIXME There's a lot more detail to add here...
Instantiate a partially constructed key with a specified payload.

The ID of the key to be instantiated is provided in
.I arg2
(cast to
.IR key_serial_t ).

The key payload is specified in the buffer pointed to by
.I arg3
(cast to
.IR "void\ *");
the size of that buffer is specified in
.I arg4
(cast to
.IR size_t ).

The payload may be a NULL pointer and the buffer size may be 0
if this is supported by the key type.
The operation may be fail if the payload data is in the wrong format
or is otherwise invalid.

If
.I arg5
(cast to
.IR key_serial_t )
is nonzero, then, subject to the same constraints and rules as
.BR KEYCTL_LINK ,
the instantiated key is linked into the keyring whose ID specified in
.IR arg5 .

The caller must have the appropriate authorization key;
see
.BR request_key (2).

This operation is exposed by
.I libkeyutils
via the function
.BR keyctl_instantiate (3).
.TP
.BR KEYCTL_NEGATE " (since Linux 2.6.11)"
Negatively instantiate a partially constructed key.

This operation is equivalent to the call:

    keyctl(KEYCTL_REJECT, arg2, arg3, ENOKEY, arg4);

The
.I arg5
argument is ignored.

This operation is exposed by
.I libkeyutils
via the function
.BR keyctl_negate (3).
.TP
.BR KEYCTL_SET_REQKEY_KEYRING " (since Linux 2.6.13)"
Set the default keyring to which implicitly requested keys
.\" The implicit requests make use of the kernel-internal request_key()
.\" function (which is not the same as the request_key(2) system call).
will be linked for this thread, and return the previous setting.
Implicit key requests can occur when, for example, opening files
on an AFS or NFS filesystem.

The
.I arg2
argument (cast to
.IR int )
should contain one of the following values,
to specify the new default keyring:
.RS
.TP
.BR KEY_REQKEY_DEFL_NO_CHANGE
No change.
.TP
.BR KEY_REQKEY_DEFL_DEFAULT
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.
.TP
.BR KEY_REQKEY_DEFL_THREAD_KEYRING
Use the thread-specific keyring
.RB ( thread_keyring (7))
as the new default keyring.
.TP
.BR KEY_REQKEY_DEFL_PROCESS_KEYRING
Use the process-specific keyring
.RB ( process_keyring (7))
as the new default keyring.
.TP
.TP
.BR KEY_REQKEY_DEFL_SESSION_KEYRING
Use the session-specific keyring
.RB ( session_keyring (7))
as the new default keyring.
.TP
.BR KEY_REQKEY_DEFL_USER_KEYRING
Use the UID-specific keyring
.RB ( user_keyring (7))
as the new default keyring.
.TP
.BR KEY_REQKEY_DEFL_USER_SESSION_KEYRING
Use the UID-specific session keyring
.RB ( user_session_keyring (7))
as the new default keyring.
.TP
.BR KEY_REQKEY_DEFL_REQUESTOR_KEYRING " (since Linux 2.6.29)"
'\" 8bbf4976b59fc9fc2861e79cab7beb3f6d647640
.\" FIXME The following needs to be expanded.
Use the requestor keyring.
.RE
.IP
All other values are invalid.
.\" (including the still-unsupported KEY_REQKEY_DEFL_GROUP_KEYRING)

The arguments
.IR arg3 ,
.IR arg4 ,
and
.IR arg5
are ignored.

The setting controlled by this operation is inherited by the child of
.BR fork (2)
and preserved across
.BR  execve (2).

This operation is exposed by
.I libkeyutils
via the function
.BR keyctl_set_reqkey_keyring (3).
.TP
.BR KEYCTL_SET_TIMEOUT " (since Linux 2.6.16)"
Set a timeout on a key.

The ID of the key is specified in
.I arg2
(cast to
.IR key_serial_t ).
The timeout value, in seconds from the current time,
is specified in
.I arg3
(cast to
.IR "unsigned int" ).

Specifying the timeout value as 0 clears any existing timeout on the key.

The caller must either have the
.I setattr
permission on the key
or hold an instantiation authorization token for the key (see
.BR request_key (2)).

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
.BR EKEYEXPIRED .

This operation cannot be used to set timeouts on negative, revoked,
or expired keys.

The arguments
.IR arg4
and
.IR arg5
are ignored.

This operation is exposed by
.I libkeyutils
via the function
.BR keyctl_set_timeout (3).
.TP
.BR KEYCTL_ASSUME_AUTHORITY " (since Linux 2.6.16)"
.\" FIXME More needs to be said for KEYCTL_ASSUME_AUTHORITY
Assume (or divest) the authority for the calling thread
to instantiate a specified key.

The
.I arg2
argument (cast to
.IR key_serial_t )
specifies either a nonzero key ID to assume authority,
or the value 0 to divest authority.

If
.I arg2
is nonzero, then it specifies the ID of an uninstantiated key for which
authority is to be assumed.

Authority of 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.
The caller must have
.I search
permission on the authorization key.

If the specified key has a matching authorization key,
then the ID of that key is returned.
The authorization key can be read to obtain
the callout information passed to
.BR request_key (2).

If the ID given in
.I arg2
is 0, then the currently assumed authority is cleared (divested),
and the value 0 is returned.

The arguments
.IR arg3 ,
.IR arg4 ,
and
.IR arg5
are ignored.

This operation is exposed by
.I libkeyutils
via the function
.BR keyctl_assume_authority (3).
.TP
.BR KEYCTL_GET_SECURITY " (since Linux 2.6.26)"
Get the LSM security label of the specified key.
The ID of the key should be provided in the
.I arg2
argument (cast to
.IR key_serial_t ).
The buffer where the security label should be stored is provided in the
.I arg3
argument (cast to
.IR "char\ *" )
with its size provided in the
.I arg4
argument (cast to
.IR size_t ).

The
.I arg5
argument is ignored.

This operation is exposed by
.I libkeyutils
via the function
.BR keyctl_get_security (3)
and
.BR keyctl_get_security_alloc (3).
.TP
.BR KEYCTL_SESSION_TO_PARENT " (since Linux 2.6.32)"
Apply session keyring to parent process.
.IP
Attempt to install the calling process's session keyring
on the process's parent process.
The keyring must exist and must grant the caller
.I link
permission, and the parent process must be single-threaded and have
the same effective ownership as this process
and must not be be set-user-ID or set-group-ID.
.IP
The keyring will be emplaced on the parent when it next resumes userspace.

The arguments
.IR arg2 ,
.IR arg3 ,
.IR arg4 ,
and
.IR arg5
are ignored.

This operation is exposed by
.I libkeyutils
via the function
.BR keyctl_session_to_parent (3).
.TP
.BR KEYCTL_REJECT " (since Linux 2.6.39)"
.\" commit fdd1b94581782a2ddf9124414e5b7a5f48ce2f9c
.\" We need some text here on why it is useful to negatively instantiate a key
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
.BR KEYCTL_NEGATE
operation.

The ID of the key that is to be negatively instantiated is specified in
.I arg2
(cast to
.IR key_serial_t ).
The
.I arg3
(cast to
.IR "unsigned int" )
argument specifies the lifetime of the key, in seconds.
The
.I arg4
argument (cast to
.IR "unsigned int" )
specifies the error to be returned when a search hits this key;
typically, this is one of
.BR EKEYREJECTED ,
.BR EKEYREVOKED ,
or
.BR EKEYEXPIRED .

If
.I arg5
(cast to
.IR key_serial_t )
is nonzero, then, subject to the same constraints and rules as
.BR KEYCTL_LINK ,
the negatively instantiated key is linked into the keyring
whose ID specified in
.IR arg5 .

The caller must have the appropriate instantiation permit set
(authorization key, see
.B KEYCTL_ASSUME_AUTHORITY
command and
.BR request_key (2)).

Negative keys are used to rate limit repeated
.BR request_key (2)
calls by causing them to return the error specified until the negative key
expires.

This operation is exposed by
.I libkeyutils
via the function
.BR keyctl_reject (3).
.TP
.BR KEYCTL_INSTANTIATE_IOV " (since Linux 2.6.39)"
.\" commit ee009e4a0d4555ed522a631bae9896399674f063
Instantiate a partially constructed key with a payload specified
via a vector of buffers.

This operation is the same as
.BR KEYCTL_INSTANTIATE ,
but the payload data is specified as an array of
.IR iovec
structures:

.in +4n
.nf
struct iovec {
    void  *iov_base;    /* Starting address of buffer */
    size_t iov_len;     /* Size of buffer (in bytes) */
};
.fi
.in

The pointer to the payload vector is specified in
.IR arg3
(cast as
.IR "const struct iovec\ *" ).
The number of items in the vector is specified in
.IR arg4
(cast as
.IR "unsigned int" ).

The
.I arg2
(key ID)
and
.I arg5
(keyring ID)
are interpreted as for
.BR KEYCTL_INSTANTIATE .

This operation is exposed by
.I libkeyutils
via the function
.BR keyctl_instantiate_iov (3).
.TP
.BR KEYCTL_INVALIDATE " (since Linux 3.5)"
.\" commit fd75815f727f157a05f4c96b5294a4617c0557da
Mark a key as invalid.

The ID of the key to be invalidated is specified in
.I arg2
(cast to
.IR key_serial_t ).

To invalidate a key,
the caller must have
.I search
permission on the key.
.\" CAP_SYS_ADMIN is permitted to invalidate certain special keys

This operation immediately marks the key as invalid
and schedules 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.

Keys that are marked invalid become invisible to normal key operations
immediately, though they are still visible in
.I /proc/keys
(marked with an 'i' flag)
until they are actually removed.

The arguments
.IR arg3 ,
.IR arg4 ,
and
.IR arg5
are ignored.

This operation is exposed by
.I libkeyutils
via the function
.BR keyctl_invalidate (3).
.TP
.BR KEYCTL_GET_PERSISTENT " (since Linux 3.13)"
Get the persistent keyring of the user specified in the
.I arg2
(cast to
.IR uid_t )
and link it to the keyring with the ID provided in the
.I arg3
argument (cast to
.IR key_serial_t ).
If \-1 is provided as UID, current user's ID is used.

The arguments
.IR arg4
and
.IR arg5
are ignored.

This operation is exposed by
.I libkeyutils
via the function
.BR keyctl_get_persistent (3).
.TP
.BR KEYCTL_DH_COMPUTE " (since Linux 4.7)"
Compute Diffie-Hellman values.
The
.I arg2
argument is a pointer to
.I struct keyctl_dh_params
which is defined in
.I <linux/keyctl.h>
as follows:

.nf
.in +4n
struct keyctl_dh_params {
    int32_t private;
    int32_t prime;
    int32_t base;
};
.in
.fi

The
.IR private ", " prime " and " base
fields are IDs of the keys, payload of which would be used for DH values
calculation.
The result is calculated as
.IR "base^private mod prime" .

The
.I arg3
argument (cast to
.IR "char\ *" )
should point to an output buffer whose size is passed in the
.I arg4
argument (cast to
.IR size_t ).
The buffer should be big enough in order to accommodate the output data,
otherwise an error is returned.
A NULL pointer can be provided as buffer in order
to obtain the required buffer size.

The
.I arg5
argument is reserved and must be 0.
.SH RETURN VALUE
For a successful call, the return value depends on the operation:
.TP
.B KEYCTL_GET_KEYRING_ID
The ID of the requested keyring.
.TP
.B KEYCTL_JOIN_SESSION_KEYRING
The ID of the joined session keyring.
.TP
.B KEYCTL_DESCRIBE
The size of the description (including the terminating null byte),
irrespective of the provided buffer size.
.TP
.B KEYCTL_SEARCH
The ID of the key that was found.
.TP
.B KEYCTL_READ
The amount of data that is available in the key,
irrespective of the provided buffer size.
.TP
.B KEYCTL_SET_REQKEY_KEYRING
The ID of the previous default keyring
to which implicitly requested keys were linked
(one of
.BR KEY_REQKEY_DEFL_USER_* ).
.TP
.B KEYCTL_ASSUME_AUTHORITY
Either 0, if the ID given was 0,
or the ID of the authorization key matching the specified key,
if a non-zero key ID was provided.
.TP
.B KEYCTL_GET_SECURITY
The amount of information available (including the terminating null byte),
irrespective of the provided buffer size.
.TP
.B KEYCTL_GET_PERSISTENT
The ID of the persistent keyring.
.TP
.B KEYCTL_DH_COMPUTE
Amount of bytes being copied.
.TP
All other commands
Zero.
.PP
On error, \-1 is returned, and
.I errno
is set appropriately to indicate the error.
.SH ERRORS
.TP
.B EACCES
The requested operation wasn't permitted.
.TP
.B EDEADLK
.I option
is
.BR KEYCTL_LINK
and the requested link would result in a cycle.
.TP
.B EDQUOT
The key quota for the caller's user would be exceeded by creating a key or
linking it to the keyring.
.TP
.B EINVAL
.I option
was
.B KEYCTL_SETPERM
and an invalid permission bit was specified in
.IR arg3 .
.TP
.B EKEYEXPIRED
An expired key was found or specified.
.TP
.B EKEYREJECTED
A rejected key was found or specified.
.TP
.B EKEYREVOKED
A revoked key was found or specified.
.TP
.B ELOOP
.I option
is
.BR KEYCTL_LINK
and the requested link would cause the maximum nesting depth
for keyrings to be exceeded.
.TP
.B ENOKEY
No matching key was found or an invalid key was specified.
.TP
.B ENOKEY
The value
.B KEYCTL_GET_KEYRING_ID
was specified in
.IR option ,
the key specified in
.I arg2
did not exist, and
.I arg3
was zero (meaning don't create the key if it didn't exist).
.TP
.B EOPNOTSUPP
.I option
is
.B KEYCTL_UPDATE
and the key type does not support updating.
.TP
.B ENOTDIR
A key of keyring type was expected but the ID of a key with
a different type was provided.
.TP
.B ENFILE
.\" FIXME Does this error really occur? I could not find where
.\"       in the kernel source it is generated, but have not tested
.\"       this case from a user-space program
.IR option
is
.BR KEYCTL_LINK
and the keyring is full.
.TP
.B ENOENT
.I option
is
.B KEYCTL_UNLINK
and the key to be unlinked isn't linked to the keyring.
.TP
.B EINVAL
.I option
is
.B KEYCTL_DH_COMPUTE
and the buffer size provided is not enough for the result to fit in.
Provide 0 as
a buffer size in order to obtain minimum buffer size first.
.SH VERSIONS
This system call first appeared in Linux 2.6.11.
.SH CONFORMING TO
This system call is a nonstandard Linux extension.
.SH NOTES
Although this is a Linux system call, it is not present in
.I libc
but can be found rather in
.IR libkeyutils .
When linking,
.B \-lkeyutils
should be specified to the linker.
.SH SEE ALSO
.ad l
.nh
.BR keyctl (1),
.BR add_key (2),
.BR request_key (2),
.BR keyctl_chown (3),
.BR keyctl_clear (3),
.BR keyctl_describe (3),
.BR keyctl_describe_alloc (3),
.BR keyctl_get_keyring_ID (3),
.BR keyctl_instantiate (3),
.BR keyctl_join_session_keyring (3),
.BR keyctl_link (3),
.BR keyctl_negate (3),
.BR keyctl_read (3),
.BR keyctl_read_alloc (3),
.BR keyctl_revoke (3),
.BR keyctl_search (3),
.BR keyctl_set_reqkey_keyring (3),
.BR keyctl_set_timeout (3),
.BR keyctl_setperm (3),
.BR keyctl_unlink (3),
.BR keyctl_update (3),
.BR keyrings (7),
.BR request-key (8)

The kernel source files
.IR Documentation/security/keys.txt 
and
.IR Documentation/security/keys-request-key.txt .