.\" 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
.IB "/* For direct call via the " 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 ()
(along with
.IR add_key (2))
provides abilities for userspace key manipulation. The operation performed by
the
.BR keyctl ()
call is determined by the value of the
.I option
argument, which could one of the following:
.TP
.B KEYCTL_GET_KEYRING_ID
Ask for a keyring's whose ID provided in
.I arg2
(converted to
.IR key_serial_t ).
If the
.I arg3
argument contains non-zero value, new keyring would be created. Caller should
have
.I search
permission on a keyring for it to be found. Arguments
.IR arg4 and  arg5
are ignored.
.TP
.B KEYCTL_JOIN_SESSION_KEYRING
Create new anonymous session keyring (in case
.I arg2
is
.BR NULL )
or join existing named session keyring
.RI ( arg2
should be pointer to a string containing session name in this case). The caller
should have
.I search
permission on the keyring name of which is provided in order
to successfully join. Arguments
.IR arg3 ", " arg4 ", " arg5
are ignored.
.TP
.B KEYCTL_UPDATE
Update a key's data payload using data provided. The
.I arg2
argument (converted to
.IR key_serial_t )
should contain key ID, the
.I arg3
argument is interpreted as a pointer to the new payload and
.I arg4
(converted to
.IR size_t )
should contain payload size in bytes. The caller should has
.I write
permission on the key specified and key type should support updating. Negative
key can be positively instantiated with this call. The
.I arg5
argument is ignored.
.TP
.B KEYCTL_REVOKE
Revoke a key with ID provided in
.I arg2
(converted to
.IR key_serial_t ).
The caller should have
.IR write " or " setattr
permissions. Arguments
.IR arg3 ", " arg4 ", " arg5
are ignored.
.TP
.B KEYCTL_CHOWN
Set ownership of a key. The
.I arg2
argument (converted to
.IR key_serial_t )
contains key ID, the
.I arg3
argument (converted to
.IR uid_t )
contains new user ID (or -1 in case user ID shouldn't be changed), the
.I arg4
argument (converted to
.IR gid_t )
contains new group ID (or -1 in case 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
.I CAP_SYS_ADMIN
capability (see
.IR capabilities (7)
for details). 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 attribute be changed. The
.I arg5
argument is ignored.
.TP
.B KEYCTL_SETPERM
Change the permissions of a key with ID provided in the
.I arg2
argument (converted to
.IR key_serial_t )
to the ones provided in the
.I arg3
argument (converted to
.IR key_perms_t ).
The key must grant
.I setattr
permission to the caller. If the caller doesn't have
.I CAP_SYS_ADMIN
capability, it can only change permissions of the keys it owns.
Permissions contains mask of available operations for possessor
(since Linux 2.6.14), user, group, other. Each mask is eight bit in size,
with only six currently used. The available permissions are:
.RS
.IP \(bu 3
.BR View .
Allows reading attributes of a key. Needed for
.IR KEYCTL_DESCRIBE .
.IP \(bu
.BR Read .
Allows reading key's payload. Needed for
.IR KEYCTL_READ .
.IP \(bu
.BR Write .
Allows update or instantiation of key's payload. For a keyring, it enables
adding and removal of keys to a keyring. Needed for
.IR KEYCTL_UPDATE ", " KEYCTL_REVOKE ", " KEYCTL_CLEAR ", " KEYCTL_LINK ", "
.IR KEYCTL_UNLINK .
.IP \(bu
.BR Search .
This permits keyrings to be searched and keys to be found. Searches can
only recurse into nested keyrings that have search permission set. Needed for
.IR KEYCTL_GET_KEYRING_ID ", " KEYCTL_JOIN_SESSION_KEYRING ", " KEYCTL_SEARCH
.IR KEYCTL_INVALIDATE .
.IP \(bu
.BR Link .
This permits a key or keyring to be linked to. Needed for
.IR KEYCTL_LINK ", " KEYCTL_SESSION_TO_PARENT .
.IP \(bu
.BR "Set attribute" " (since Linux. 2.6.15)."
This permits a key's UID, GID and permissions mask to be changed. Needed for
.IR KEYCTL_REVOKE ", " KEYCTL_CHOWN ", " KEYCTL_SETPERM .
.RE
.IP
The
.IR arg4 " and " arg5
arguments are ignored.
.TP
.B KEYCTL_DESCRIBE
Describe a key. Key ID to be described should be provided in the
.I arg2
argument (converted to
.IR key_serial_t ),
the
.I arg3
argument should point to destination buffer (of type
.IR "char *" ),
and the
.I arg4
argument should contain size of the buffer (of kernel's
.I size_t
type). The key must grant the caller
.I view
permission. Writing to buffer is attempted only in case buffer is non-NULL and
has enough space to accept the description.
'\" Function commentary says it copies up to buflen bytes, bu see the
'\" (buffer && buflen >= ret) condition in keyctl_describe_key() in
'\" security/keyctl.c
The description itself provided in
.RS
.IP
.IR type ; uid ; gid ; perm ; description "<NUL>"
.RE
.IP
format. The
.I arg5
argument is ignored.
.TP
.B KEYCTL_CLEAR
Clear contents of a keyring with ID provided in the
.I arg2
argument (converted to
.IR key_serial_t ).
Caller should have
.I write
permission. Arguments
.IR arg3 ", " arg4 ", " arg5
are ignored.
.TP
.B KEYCTL_LINK
Link a key (provided in the
.I arg2
argument converted to
.I key_serial_t
type) to a keyring (provided in the
.I arg3
argument converted to
.I key_serial_t
type) of there is no matching key in the keyring, or replace the link
to the matching key with a link to the new key. The caller should have
.I link
permission on the key being added and
.I write
permission on the keyring to which key being added to. Arguments
.IR arg4 " and " arg5
are ignored.
.TP
.B KEYCTL_UNLINK
Unlink a key (provided in the
.I arg2
argument converted to
.I key_serial_t
type) from a keyring (provided in the
.I arg3
argument converted to
.I key_serial_t
type). The caller should have
.I write
permission on the keyring from which key being removed from. If the last link
to a key is removed then that key will be scheduled for destruction.Arguments
.IR arg4 " and " arg5
are ignored.
.TP
.B KEYCTL_SEARCH
Search for a key in a keyring with ID provided in the
.I arg2
argument (converted to
.I key_serial_t
type). The
.I arg3
argument should be a
.I char *
pointing to the name of the type the key being searched (NUL-terminated
character string up to 32 bytes in size), and the
.I arg4
argument should be a
.I char *
pointing to the NUL-terminated character string (up to 4096 bytes in size) with
the description of the key being searched. The search is performed recursively
starting from the keyring with ID provided in
.IR arg2 .
Only keyrings that grant the caller
.I search
permission will be searched (this includes the starting keyring).
Only keys with
.I search
permission can be found. If the
.I arg5
argument (converted to
.I key_serial_t
type) contains non-zero value, it is interpreted as a keyring ID to which
the found key should be linked.
.TP
.B KEYCTL_READ
Read a payload of a key ID of which provided in the
.I arg2
argument (converted to
.I key_serial_t
type) to a buffer pointed by the
.I arg3
argument (converted to
.I char *
type) of size provided in the
.I arg4
argument (converted to kernel's
.I size_t
type). The key must either grant the caller
.I read
permission, or it must grant the caller
.I search
permission when searched for from the process keyrings. The
.I arg5
argument is ignored.
.TP
.B KEYCTL_INSTANTIATE
Instantiate a partially constructed key ID of which provided in the
.I arg2
argument (converted to
.I key_serial_t
type) with a payload pointed by the
.I arg3
argument (converted to
.I char *
type) of size provided in the
.I arg4
argument (converted to kernel's
.I size_t
type). Instantiated key will be linked to keyring Id of which provided in the
.I arg5
argument (converted to
.I key_serial_t
type). The caller must have the appropriate instantiation permit set (auth key).
.TP
.B KEYCTL_NEGATE
Negatively instantiate a partially constructed key with ID provided in the
.I arg2
argument (converted to
.I key_serial_t
type), setting timeout (in seconds) to the value provided in the
.I arg3
argument (converted to
.I unsigned int
type). Instantiated key will be linked to keyring Id of which provided in the
.I arg4
argument (converted to
.I key_serial_t
type). The caller must have the appropriate instantiation permit set
(authorisation key, see
.I KEYCTL_ASSUME_AUTHORITY
command). Negative keys are used to rate limit repeated
.BR request_key ()
calls by causing them to return
.B -ENOKEY
until the negative key expires. Equivalent to
.BI "keyctl(" KEYCTL_REJECT ", " arg2 ", " arg3 ", " ENOKEY ", " arg4 )
call.
The
.I arg5
argument is ignored.
.TP
.BR KEYCTL_SET_REQKEY_KEYRING " (since Linux 2.6.13)"
Read or set default keyring in which
.BR request_key ()
will cache keys. The
.I arg2
argument (converted to
.I int
type) should contain one of the following values, defined in
.IR <linux/keyring.h> :

.nf
.in +4n
#define KEY_REQKEY_DEFL_NO_CHANGE             -1 /* No change */
#define KEY_REQKEY_DEFL_DEFAULT               0  /* Default keyring */
#define KEY_REQKEY_DEFL_THREAD_KEYRING        1  /* Thread-specific keyring */
#define KEY_REQKEY_DEFL_PROCESS_KEYRING       2  /* Process-specific keyring */
#define KEY_REQKEY_DEFL_SESSION_KEYRING       3  /* Session-specific keyring */
#define KEY_REQKEY_DEFL_USER_KEYRING          4  /* UID-specific keyring */
#define KEY_REQKEY_DEFL_USER_SESSION_KEYRING  5  /* Session keyring of UID */
'\" 8bbf4976b59fc9fc2861e79cab7beb3f6d647640
#define KEY_REQKEY_DEFL_REQUESTOR_KEYRING     7  /* since 2.6.29: requestor keyring */
.in
.fi

All other values (including still-unsupported
.BR KEY_REQKEY_DEFL_GROUP_KEYRING )
are invalid. Arguments
.IR arg3 ", " arg4 " and " arg5
are ignored.
.TP
.BR KEYCTL_SET_TIMEOUT " (since Linux 2.6.16)"
Set timeout on a key. ID of a key provided in the
.I arg2
argument (converted to
.I key_serial_t
type), timeout value (in seconds from current time) provided in the
.I arg3
argument (converted to
.I unsigned int
type). the caller must either have the
.I setattr
permission or hold an instantiation authorisation token for the key. Timeout
value of 0 clears the timeout. The key and any links to the key will be
automatically garbage collected after the timeout expires. Arguments
.IR arg4 " and " arg5
are ignored.
.TP
.BR KEYCTL_ASSUME_AUTHORITY " (since Linux 2.6.16)"
Assume (or clear) the authority for the key instantiation. The ID of
the authorisation key provided in the
.I arg2
argument (converted to
.I key_serial_t
type). The caller must have the instantiation key in their process keyrings
with a
.I search
permission grant available to the caller. If the ID given in the
.I arg2
argument is 0, then the setting will be cleared. Arguments
.IR arg3 ", " arg4 " and " arg5
are ignored.
.TP
.BR KEYCTL_GET_SECURITY " (since Linux 2.6.26)"
Get LSM security label of the specified key. The ID of the key should be provided
in the
.I arg2
argument (converted to
.I key_serial_t
type). Buffer where security label should be stored provided in the
.I arg3
argument (converted to
.I char *
type) with its size provided in the
.I arg4
argument (converted to kernel's
.I size_t
type). The
.I arg5
argument is ignored.
.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 must have
the same effective ownership as this process and mustn't be SUID/SGID.
.IP
The keyring will be emplaced on the parent when it next resumes userspace.
Arguments
.IR arg2 ", " arg3 ", " arg4 " and " arg5
are ignored.
.TP
.BR KEYCTL_REJECT " (since Linux 2.6.39)"
Negatively instantiate a partially constructed key with ID provided in the
.I arg2
argument (converted to
.I key_serial_t
type), setting timeout (in seconds) to the value provided in the
.I arg3
argument (converted to
.I unsigned int
type) and instantiation error to the value provided in the
.I arg4
argument (converted to
.I unsigned int
type). Instantiated key will be linked to keyring Id of which provided in the
.I arg5
argument (converted to
.I key_serial_t
type). The caller must have the appropriate instantiation permit set
(authorisation key, see
.I KEYCTL_ASSUME_AUTHORITY
command). Negative keys are used to rate limit repeated
.BR request_key ()
calls by causing them to return the error specified until the negative key
expires.
.TP
.BR KEYCTL_INSTANTIATE_IOV " (since Linux 2.6.39)"
Instantiate a key (with ID specified in the
.I arg2
argument of type
.IR key_serial_t )
with the specified (in the
.I arg3
argument of type
.IR "const struct iovec *" )
multipart payload and link the key into
the destination keyring (ID of which provided in the
.I arg4
argument of type
.IR key_serial_t )
if non-zero one is given. The caller must have the appropriate instantiation
permit (authorisation key, see
.I KEYCTL_ASSUME_AUTHORITY
command) set for this to  work. No other permissions are required. The
.I arg5
argument is ignored.
.TP
.BR KEYCTL_INVALIDATE " (since Linux 3.5)"
Invalidate a key with ID provided in the
.I arg2
argument (converted to
.I key_serial_t
type). The caller must have
.I search
permission in order to perform invalidation. The key and any links to the key
will be automatically garbage collected immediately. Arguments
.IR arg3 ", " arg4 " and " arg5
are ignored.
.TP
.BR KEYCTL_GET_PERSISTENT " (since Linux 3.13)"
Get the persistent keyring of the user specified in the
.I arg2
(converted to
.I uid_t
type) and link it to the keyring with ID provided in the
.I arg3
argument (converted to
.I key_serial_t
type). If -1 is provided as UID, current user's ID is used. Arguments
.IR arg4 " and " arg5
are ignored.
.TP
.BR KEYCTL_DH_COMPUTE " (since Linux 4.7)"
Compute Diffie-Hellman values. The
.I arg2
argument is a pointer to
.B struct kayctl_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

, where
.IR private ", " prime " and " base
fields are ID's of the keys, payload of which would be used for DH values
calculation. Result is calculated as
.IR "base^private mod prime" .
The
.I arg3
argument (converted to
.I char *
type) should point to output buffer with size passed in the
.I arg4
argument (converted to kernel's
.I size_t
type). Buffer should be big enough in order to accommodate output data,
otherwise error is returned. NULL pointer can be provided as buffer in order
to obtains required buffer size. The
.I arg5
argument is reserved and should be 0.
.P
These are wrapped by
.B libkeyutils
into individual functions (listed under SEE ALSO)
to permit the compiler to check types.
.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 description (including terminating NUL byte), irrespective
of the provided buffer size.
.TP
.B KEYCTL_SEARCH
The found key ID.
.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
Old setting (one of
.IR KEY_REQKEY_DEFL_USER_* )
.TP
.B KEYCTL_ASSUME_AUTHORITY
0, if the ID given is 0. ID of the authorisation key matching key with the given
ID if non-zero key ID provided.
.TP
.B KEYCTL_GET_SECURITY
The amount of information available (including terminating NUL byte),
irrespective of the provided buffer size.
.TP
.B KEYCTL_GET_PERSISTENT
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
A key operation wasn't permitted.
.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 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 ENOKEY
No matching key was found or an invalid key was specified.
.TP
.B ENOTSUPP
.I option
is
.B KEYCTL_UPDATE
and key type does not support updating.
.TP
.B ENOTDIR
Key of keyring type is expected but ID of a key with a different type provided.
.TP
.B ENFILE
Keyring is full.
.TP
.B ENOENT
.I option
is
.B KEYCTL_UNLINK
and the key requested for unlinking isn't linked to the keyring.
.TP
.B EINVAL
.I option
is
.B KEYCTL_DH_COMPUTE
and 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 LINKING
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 file
.IR Documentation/security/keys.txt .