.\" 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
.B KEYCTL_GET_KEYRING_ID
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
.B KEYCTL_JOIN_SESSION_KEYRING
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
.B KEYCTL_UPDATE
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
.B KEYCTL_REVOKE
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
.B KEYCTL_CHOWN
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
.B KEYCTL_SETPERM
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_perms_t ).
The key must grant
.I setattr
permission to the caller.
If the caller doesn't have
.B CAP_SYS_ADMIN
capability, it can change permissions only for the keys it owns.
Permissions contains a mask of available operations for possessor
(since Linux 2.6.14), user, group, other.
Each mask is eight bits in size, with only six bits currently used.
The available permissions are:
.RS
.IP \(bu 3
.BR View .
Allows reading attributes of a key.
Needed for
.BR KEYCTL_DESCRIBE .
.IP \(bu
.BR Read .
Allows reading a key's payload.
Needed for
.BR KEYCTL_READ .
.IP \(bu
.BR Write .
Allows update or instantiation of a key's payload.
For a keyring, it enables addition and removal of keys to a keyring.
Needed for
.BR KEYCTL_UPDATE ,
.BR KEYCTL_REVOKE ,
.BR KEYCTL_CLEAR ,
.BR KEYCTL_LINK ,
and
.BR 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
.BR KEYCTL_GET_KEYRING_ID ,
.BR KEYCTL_JOIN_SESSION_KEYRING ,
.BR KEYCTL_SEARCH ,
and
.BR KEYCTL_INVALIDATE .
.IP \(bu
.BR Link .
This permits a key or keyring to be linked to.
Needed for
.BR KEYCTL_LINK
and
.BR 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
.BR KEYCTL_REVOKE ,
.BR KEYCTL_CHOWN ,
and
.BR KEYCTL_SETPERM .
.RE
.IP
The
.IR arg4 " and " arg5
arguments are ignored.

This operation is exposed by
.I libkeyutils
via the function
.BR keyctl_setperm (3).
.TP
.B KEYCTL_DESCRIBE
Describe a key.
The ID of the key to be described should be provided in the
.I arg2
argument (cast to
.IR key_serial_t ).
The
.I arg3
argument should point to the 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 the buffer is attempted only when the 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 is provided in the format:
.RS
.IP
.IR type ; uid ; gid ; perm ; description "<NUL>"
.RE
.IP
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 the keyring with the ID provided in the
.I arg2
argument (cast to
.IR key_serial_t ).

The caller must have
.I write
permission.

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
.B KEYCTL_LINK
Link a key (provided in the
.I arg2
argument cast to
.I key_serial_t
type) to a keyring (provided in the
.I arg3
argument cast 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 must have
.I link
permission on the key being added and
.I write
permission on the keyring to which key being added to.

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

This operation is exposed by
.I libkeyutils
via the function
.BR keyctl_link (3).
.TP
.B KEYCTL_UNLINK
Unlink a key (provided in the
.I arg2
argument cast to
.I key_serial_t
type) from a keyring (provided in the
.I arg3
argument cast to
.I key_serial_t
type).

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
.B KEYCTL_SEARCH
Search for a key in a keyring with the ID provided in the
.I arg2
argument (cast to
.IR key_serial_t ).
The
.I arg3
argument should be a
.IR "char\ *"
pointing to the name of the type of the key being searched for
(NUL-terminated character string up to 32 bytes in size), and the
.I arg4
argument should be a
.IR "char\ *"
pointing to a NUL-terminated character string (up to 4096 bytes in size)
with the description of the key being searched for.
The search is performed recursively
starting from the keyring with the 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 (cast to
.IR key_serial_t )
contains a non-zero value, it is interpreted as a keyring ID to which
the found key should be linked.

This operation is exposed by
.I libkeyutils
via the function
.BR keyctl_search (3).
.TP
.B KEYCTL_READ
Read the payload of the key whose ID is provided in the
.I arg2
argument (cast to
.IR key_serial_t ).
The payload is placed in the buffer pointed by the
.I arg3
argument (cast to
.IR "char\ *" );
the size of that buffer must be provided in the
.I arg4
argument (cast to
.IR size_t ).
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.

This operation is exposed by
.I libkeyutils
via the function
.BR keyctl_read (3).
.TP
.B KEYCTL_INSTANTIATE
Instantiate a partially constructed key whose ID is provided in the
.I arg2
argument (cast to
.IR key_serial_t )
with a payload pointed by the
.I arg3
argument (cast to
.IR "char\ *")
of size provided in the
.I arg4
argument (cast to
.IR size_t ).
The instantiated key will be linked to the keyring ID which is provided in the
.I arg5
argument (cast to
.IR key_serial_t ).
The caller must have the appropriate instantiation permit set (auth key).

This operation is exposed by
.I libkeyutils
via the function
.BR keyctl_instantiate (3).
.TP
.B KEYCTL_NEGATE
Negatively instantiate a partially constructed key with the ID provided in the
.I arg2
argument (cast to
.IR key_serial_t ),
setting the timeout (in seconds) to the value provided in the
.I arg3
argument (cast to
.IR "unsigned int" ).
The instantiated key will be linked to the keyring ID which is provided in the
.I arg4
argument (cast to
.IR key_serial_t ).

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

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

This 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)"
Read or set the default keyring in which
.BR request_key (2)
will cache keys.
The
.I arg2
argument (cast to
.IR int )
should contain one of the following values, defined in
.IR <linux/keyring.h> :
.RS
.TP 33
.BR KEY_REQKEY_DEFL_NO_CHANGE
No change.
.TP
.BR KEY_REQKEY_DEFL_DEFAULT
Default keyring.
.TP
.BR KEY_REQKEY_DEFL_THREAD_KEYRING
Thread-specific keyring.
.TP
.BR KEY_REQKEY_DEFL_PROCESS_KEYRING
Process-specific keyring.
.TP
.BR KEY_REQKEY_DEFL_SESSION_KEYRING
Session-specific keyring.
.TP
.BR KEY_REQKEY_DEFL_USER_KEYRING
UID-specific keyring.
.TP
.BR KEY_REQKEY_DEFL_USER_SESSION_KEYRING 5
Session keyring of UID.
.TP
.BR KEY_REQKEY_DEFL_REQUESTOR_KEYRING " (since Linux 2.6.29)"
'\" 8bbf4976b59fc9fc2861e79cab7beb3f6d647640
Requestor keyring.
.RE
.IP
All other values are invalid (including the as-yet-unsupported
.BR KEY_REQKEY_DEFL_GROUP_KEYRING ).

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

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 timeout on a key.
ID of a key provided in the
.I arg2
argument (cast to
.IR key_serial_t ),
timeout value (in seconds from current time) provided in the
.I arg3
argument (cast to
.IR "unsigned int" ).

The caller must either have the
.I setattr
permission or hold an instantiation authorization token for the key.

A timeout value of 0 clears the timeout.
The key and any links to the key will be
automatically garbage collected after the timeout expires.

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)"
Assume (or clear) the authority for the key instantiation.
The ID of the authorization key provided in the
.I arg2
argument (cast to
.IR key_serial_t ).

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.

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)"
Negatively instantiate a partially constructed key with the ID provided in the
.I arg2
argument (cast to
.IR key_serial_t ),
setting timeout (in seconds) to the value provided in the
.I arg3
argument (cast to
.IR "unsigned int" )
and instantiation error to the value provided in the
.I arg4
argument (cast to
.IR "unsigned int" ).
The instantiated key will be linked to the keyring ID which is provided in the
.I arg5
argument (cast to
.IR key_serial_t ).

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

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)"
Instantiate a key (with the 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 (whose ID is  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 (authorization key, see
.B KEYCTL_ASSUME_AUTHORITY
command) set for this to  work.
No other permissions are required.

.\" FIXME The following sentence appears not to be true,
.\"       according to my reading of the source code.
The
.I arg5
argument is ignored.

This operation is exposed by
.I libkeyutils
via the function
.BR keyctl_instantiate_iov (3).
.TP
.BR KEYCTL_INVALIDATE " (since Linux 3.5)"
Invalidate a key with the ID provided in the
.I arg2
argument (cast to
.IR key_serial_t ).

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.

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 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
Old setting (one of
.BR KEY_REQKEY_DEFL_USER_* )
.TP
.B KEYCTL_ASSUME_AUTHORITY
0, if the ID given is 0.
ID of the authorization key matching key with the given
ID if non-zero key ID 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 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 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
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 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 .