.\" the source, must acknowledge the copyright and authors of this work.
.\" %%%LICENSE_END
.\"
-.TH KEYCTL 2 2015-05-07 Linux "Linux Key Management Calls"
+.TH KEYCTL 2 2017-09-15 Linux "Linux Key Management Calls"
.SH NAME
keyctl \- manipulate the kernel's key management facility
.SH SYNOPSIS
.nf
.B #include <sys/types.h>
.B #include <keyutils.h>
-.sp
+.PP
.BI "long keyctl(int " operation ", ...)"
-.sp
+
.B "/* For direct call via syscall(2): */"
.B #include <asm/unistd.h>
.B #include <linux/keyctl.h>
.B #include <unistd.h>
-.sp
+.PP
.BI "long syscall(__NR_keyctl, int " operation ", __kernel_ulong_t " arg2 ,
.BI " __kernel_ulong_t " arg3 ", __kernel_ulong_t " arg4 ,
.BI " __kernel_ulong_t " arg5 );
.fi
-
+.PP
No glibc wrapper is provided for this system call; see NOTES.
.SH DESCRIPTION
.BR keyctl ()
allows user-space programs to perform key manipulation.
-
+.PP
The operation performed by
.BR keyctl ()
is determined by the value of the
.I keyutils
package) into individual functions (noted below)
to permit the compiler to check types.
-
+.PP
The permitted values for
.I operation
are:
.TP
.BR KEYCTL_GET_KEYRING_ID " (since Linux 2.6.10)"
Map a special key ID to a real key ID for this process.
-
+.IP
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 the corresponding real key is returned
-as the function result.
+.IR key_serial_t ).
+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
.IR arg2 :
.RS
.BR request_key (2).
.RE
.IP
-If the key specified in
+The behavior if the key specified in
.I arg2
-does not exist, then a new key is created if the
+does not exist depends on the value of
.I arg3
-argument (cast to
-.IR int )
-contains a non-zero value; otherwise the operation fails with the error
-.BR ENOKEY .
+(cast to
+.IR int ).
+If
+.I arg3
+contains a nonzero value, then\(emif it is appropriate to do so
+(e.g., when looking up the user, user-session, or session key)\(ema new key
+is created and its real key ID returned as the function result.
.\" The keyctl_get_keyring_ID.3 page says that a new key
.\" "will be created *if it is appropriate to do so**. What is the
.\" determiner for appropriate?
.\" David Howells: Some special keys such as KEY_SPEC_REQKEY_AUTH_KEY
.\" wouldn't get created but user/user-session/session keyring would
.\" be created.
-
+Otherwise, the operation fails with the error
+.BR ENOKEY .
+.IP
+If a valid key ID is specified in
+.IR arg2 ,
+and the key exists, then this operation simply returns the key ID.
+If the key does not exist, the call fails with error
+.BR ENOKEY .
+.IP
The caller must have
.I search
permission on a keyring in order for it to be found.
-
+.IP
The arguments
.IR arg4
and
.IR arg5
are ignored.
-
+.IP
This operation is exposed by
.I libkeyutils
via the function
a new session keyring.
.\" This may be useful in conjunction with some sort of
.\" session management framework that is employed by the application.
-
+.IP
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.
-
+.IP
Otherwise,
.I arg2
(cast to
and
.IR arg5
are ignored.
-
+.IP
This operation is exposed by
.I libkeyutils
via the function
.TP
.BR KEYCTL_UPDATE " (since Linux 2.6.10)"
Update a key's data payload.
-
+.IP
The
.I arg2
argument (cast to
(cast to
.IR size_t )
contains the new payload size in bytes.
-
+.IP
The caller must have
.I write
permission on the key specified and the key type must support updating.
-
-A negatively instantiated key can be positively instantiated
-with this operation.
-
+.IP
+A negatively instantiated key (see the description of
+.BR KEYCTL_REJECT )
+can be positively instantiated with this operation.
+.IP
The
.I arg5
argument is ignored.
-
+.IP
This operation is exposed by
.I libkeyutils
via the function
and will be unavailable for further operations.
Further attempts to use the key will fail with the error
.BR EKEYREVOKED .
-
+.IP
The caller must have
.IR write
or
.\" Keys with the KEY_FLAG_KEEP bit set cause an EPERM
.\" error for KEYCTL_REVOKE. Does this need to be documented?
.\" David Howells: No significance for user space.
-
+.IP
The arguments
.IR arg3 ,
.IR arg4 ,
and
.IR arg5
are ignored.
-
+.IP
This operation is exposed by
.I libkeyutils
via the function
.TP
.BR KEYCTL_CHOWN " (since Linux 2.6.10)"
Change the ownership (user and group ID) of a key.
-
+.IP
The
.I arg2
argument (cast to
argument (cast to
.IR gid_t )
contains the new group ID (or \-1 in case the group ID shouldn't be changed).
-
+.IP
The key must grant the caller
.I setattr
permission.
-
+.IP
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)).
-
+.IP
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.
-
+.IP
The
.I arg5
argument is ignored.
-
+.IP
This operation is exposed by
.I libkeyutils
via the function
.I arg3
argument (cast to
.IR key_perm_t ).
-
+.IP
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.)
-
+.IP
The key must grant
.I setattr
permission to the caller
of the caller's capabilities.
.\" FIXME Above, is it really intended that a privileged process can't
.\" override the lack of the 'setattr' permission?
-
+.IP
The permissions in
.IR arg3
specify masks of available operations
category, then it will not receive permissions granted in the
.IR other
category.
-
+.IP
The
-.I possessor
+.I possessor
category grants permissions that are cumulative with the grants from the
.IR user ,
.IR group ,
or
.IR other
category.
-
+.IP
Each permission mask is eight bits in size,
with only six bits currently used.
The available permissions are:
.TP
.IR view
This permission allows reading attributes of a key.
-
+.IP
This permission is required for the
.BR KEYCTL_DESCRIBE
operation.
-
+.IP
The permission bits for each category are
.BR KEY_POS_VIEW ,
.BR KEY_USR_VIEW ,
.TP
.IR read
This permission allows reading a key's payload.
-
+.IP
This permission is required for the
.BR KEYCTL_READ
operation.
-
+.IP
The permission bits for each category are
.BR KEY_POS_READ ,
.BR KEY_USR_READ ,
.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,
-
+.IP
This permission is required for the
.BR KEYCTL_UPDATE ,
.BR KEYCTL_REVOKE ,
and
.BR KEYCTL_UNLINK
operations.
-
+.IP
The permission bits for each category are
.BR KEY_POS_WRITE ,
.BR KEY_USR_WRITE ,
Searches can recurse only into nested keyrings that have
.I search
permission set.
-
+.IP
This permission is required for the
.BR KEYCTL_GET_KEYRING_ID ,
.BR KEYCTL_JOIN_SESSION_KEYRING ,
and
.BR KEYCTL_INVALIDATE
operations.
-
+.IP
The permission bits for each category are
.BR KEY_POS_SEARCH ,
.BR KEY_USR_SEARCH ,
.TP
.IR link
This permission allows a key or keyring to be linked to.
-
+.IP
This permission is required for the
.BR KEYCTL_LINK
and
.BR KEYCTL_SESSION_TO_PARENT
operations.
-
+.IP
The permission bits for each category are
.BR KEY_POS_LINK ,
.BR KEY_USR_LINK ,
.TP
.IR setattr " (since Linux 2.6.15)."
This permission allows a key's UID, GID, and permissions mask to be changed.
-
+.IP
This permission is required for the
.BR KEYCTL_REVOKE ,
.BR KEYCTL_CHOWN ,
and
.BR KEYCTL_SETPERM
operations.
-
+.IP
The permission bits for each category are
.BR KEY_POS_SETATTR ,
.BR KEY_USR_SETATTR ,
.BR KEY_GRP_ALL ,
and
.BR KEY_OTH_ALL .
-
+.IP
The
.IR arg4 " and " arg5
arguments are ignored.
-
+.IP
This operation is exposed by
.I libkeyutils
via the function
.TP
.BR KEYCTL_DESCRIBE " (since Linux 2.6.10)"
Obtain a string describing the attributes of a specified key.
-
+.IP
The ID of the key to be described is specified in
.I arg2
(cast to
(cast to
.IR size_t )
specifies the size of that buffer in bytes.
-
+.IP
The key must grant the caller
.I view
permission.
-
+.IP
The returned string is null-terminated and
contains the following information about the key:
-
+.IP
.in +4n
.IR type ; uid ; gid ; perm ; description
.in
-
+.IP
In the above,
.IR type
and
.I perm
is a hexadecimal permissions mask.
The descriptive string is written with the following format:
-
+.IP
%s;%d;%d;%08x;%s
-
+.IP
.BR "Note: the intention is that the descriptive string should"
.BR "be extensible in future kernel versions".
In particular, the
to find the last semicolon.
This allows future semicolon-delimited fields to be inserted
in the descriptive string in the future.
-
+.IP
Writing to the buffer is attempted only when
.IR arg3
is non-NULL and the specified buffer size
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 .
-
+.IP
The
.I arg5
argument is ignored.
-
+.IP
This operation is exposed by
.I libkeyutils
via the function
.TP
.B KEYCTL_CLEAR
Clear the contents of (i.e., unlink all keys from) a keyring.
-
+.IP
The ID of the key
(which must be of keyring type)
.\" or the error ENOTDIR results
.\" 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.
-
+.IP
The caller must have
.I write
permission on the keyring.
-
+.IP
The arguments
.IR arg3 ,
.IR arg4 ,
and
.IR arg5
are ignored.
-
+.IP
This operation is exposed by
.I libkeyutils
via the function
.TP
.BR KEYCTL_LINK " (since Linux 2.6.10)"
Create a link from a keyring to a key.
-
+.IP
The key to be linked is specified in
.IR arg2
(cast to
.IR arg3
(cast to
.IR key_serial_t ).
-
+.IP
If a key with the same type and description is already linked in the keyring,
then that key is displaced from the keyring.
-
+.IP
Before creating the link,
the kernel checks the nesting of the keyrings and returns appropriate errors
if the link would produce a cycle
.BR KEYRING_SEARCH_MAX_DEPTH ,
defined with the value 6, and is necessary to prevent overflows
on the kernel stack when recursively searching keyrings).
-
+.IP
The caller must have
.I link
permission on the key being added and
.I write
permission on the keyring.
-
+.IP
The arguments
.IR arg4
and
.IR arg5
are ignored.
-
+.IP
This operation is exposed by
.I libkeyutils
via the function
.TP
.BR KEYCTL_UNLINK " (since Linux 2.6.10)"
Unlink a key from a keyring.
-
+.IP
The ID of the key to be unlinked is specified in
.I arg2
(cast to
.I arg3
(cast to
.IR key_serial_t ).
-
+.IP
If the key is not currently linked into the keyring, an error results.
-
+.IP
The caller must have
.I write
permission on the keyring from which the key is being removed.
-
+.IP
If the last link to a key is removed,
then that key will be scheduled for destruction.
-
+.IP
The arguments
.IR arg4
and
.IR arg5
are ignored.
-
+.IP
This operation is exposed by
.I libkeyutils
via the function
.BR KEYCTL_SEARCH " (since Linux 2.6.10)"
Search for a key in a keyring tree,
returning its ID and optionally linking it to a specified keyring.
-
+.IP
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.
-
+.IP
The
.I arg3
and
contains the description of the key
(a null-terminated character string up to 4096 bytes in size,
including the terminating null byte).
-
+.IP
The source keyring must grant
.I search
permission to the caller.
Only keys with for which the caller has
.I search
permission can be found.
-
+.IP
If the key is found, its ID is returned as the function result.
-
+.IP
If the key is found and
.I arg5
(cast to
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.
-
+.IP
Instead of valid existing keyring IDs, the source
.RI ( arg2 )
and destination
.TP
.BR KEYCTL_READ " (since Linux 2.6.10)"
Read the payload data of a key.
-
+.IP
The ID of the key whose payload is to be read is specified in
.I arg2
(cast to
or any of the special key IDs listed for
.BR KEYCTL_GET_KEYRING_ID .
.\" including KEY_SPEC_REQKEY_AUTH_KEY
-
+.IP
The payload is placed in the buffer pointed by
.I arg3
(cast to
.I arg4
(cast to
.IR size_t ).
-
+.IP
The returned data will be processed for presentation
according to the key type.
For example, a keyring will return an array of
If a key type does not implement this function,
the operation fails with the error
.BR EOPNOTSUPP .
-
+.IP
If
.I arg3
is not NULL,
check to see that the return value is less than or equal to
the value supplied in
.IR arg4 .
-
+.IP
The key must either grant the caller
.I read
permission, or grant the caller
.I search
permission when searched for from the process keyrings
-(i.e, the key is possessed).
-
+(i.e., the key is possessed).
+.IP
The
.I arg5
argument is ignored.
-
+.IP
This operation is exposed by
.I libkeyutils
via the function
.TP
.BR KEYCTL_INSTANTIATE " (since Linux 2.6.10)"
(Positively) instantiate an uninstantiated key with a specified payload.
-
+.IP
The ID of the key to be instantiated is provided in
.I arg2
(cast to
.IR key_serial_t ).
-
+.IP
The key payload is specified in the buffer pointed to by
.I arg3
(cast to
.I arg4
(cast to
.IR size_t ).
-
+.IP
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).
-
+.IP
The operation may be fail if the payload data is in the wrong format
or is otherwise invalid.
-
+.IP
If
.I arg5
(cast to
.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.
+.IP
+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
.BR request-key (8)-style
program.
See
-.BR request_key (2).
-
+.BR request_key (2)
+for an explanation of uninstantiated keys and key instantiation.
+.IP
This operation is exposed by
.I libkeyutils
via the function
.TP
.BR KEYCTL_NEGATE " (since Linux 2.6.10)"
Negatively instantiate an uninstantiated key.
-
+.IP
This operation is equivalent to the call:
-
+.IP
keyctl(KEYCTL_REJECT, arg2, arg3, ENOKEY, arg4);
-
+.IP
The
.I arg5
argument is ignored.
-
+.IP
This operation is exposed by
.I libkeyutils
via the function
a key from user space; see
.BR request_key (2)
for details.
-
+.IP
The
.I arg2
argument (cast to
.TP
.BR KEY_REQKEY_DEFL_NO_CHANGE
Don't change the default keyring.
-This option is useful, since the call returns the current default keyring
+This can be used to discover the current default keyring
(without changing it).
.TP
.BR KEY_REQKEY_DEFL_DEFAULT
.IP
All other values are invalid.
.\" (including the still-unsupported KEY_REQKEY_DEFL_GROUP_KEYRING)
-
+.IP
The arguments
.IR arg3 ,
.IR arg4 ,
and
.IR arg5
are ignored.
-
+.IP
The setting controlled by this operation is inherited by the child of
.BR fork (2)
and preserved across
.BR execve (2).
-
+.IP
This operation is exposed by
.I libkeyutils
via the function
.TP
.BR KEYCTL_SET_TIMEOUT " (since Linux 2.6.16)"
Set a timeout on a key.
-
+.IP
The ID of the key is specified in
.I arg2
(cast to
(cast to
.IR "unsigned int" ).
The timeout is measured against the realtime clock.
-
+.IP
Specifying the timeout value as 0 clears any existing timeout on the key.
-
+.IP
The
.I /proc/keys
file displays the remaining time until each key will expire.
(This is the only method of discovering the timeout on a key.)
-
+.IP
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)).
-
+.IP
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.
-
+.IP
+This operation cannot be used to set timeouts on revoked, expired,
+or negatively instantiated keys.
+.IP
The arguments
.IR arg4
and
.IR arg5
are ignored.
-
+.IP
This operation is exposed by
.I libkeyutils
via the function
.BR KEYCTL_ASSUME_AUTHORITY " (since Linux 2.6.16)"
Assume (or divest) the authority for the calling thread
to instantiate a key.
-
+.IP
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.
-
+.IP
If
.I arg2
is nonzero, then it specifies the ID of an uninstantiated key for which
.BR KEYCTL_NEGATE .
Once the key has been instantiated,
the thread is automatically divested of authority to instantiate the key.
-
+.IP
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, this operation is available only from a
+(In other words, the
+.BR KEYCTL_ASSUME_AUTHORITY
+operation is available only from a
.BR request-key (8)-style
program; see
-.BR request_key (2).)
+.BR request_key (2)
+for an explanation of how this operation is used.)
The caller must have
.I search
permission on the authorization key.
-
-
+.IP
If the specified key has a matching authorization key,
then the ID of that key is returned.
The authorization key can be read
.RB ( KEYCTL_READ )
to obtain the callout information passed to
.BR request_key (2).
-
+.IP
If the ID given in
.I arg2
is 0, then the currently assumed authority is cleared (divested),
and the value 0 is returned.
-
+.IP
The
.BR KEYCTL_ASSUME_AUTHORITY
mechanism allows a program such as
.BR request_key (2)
and the kernel source file
.IR Documentation/security/keys-request-key.txt .
-
+.IP
The arguments
.IR arg3 ,
.IR arg4 ,
and
.IR arg5
are ignored.
-
+.IP
This operation is exposed by
.I libkeyutils
via the function
.BR KEYCTL_GET_SECURITY " (since Linux 2.6.26)"
.\" commit 70a5bb72b55e82fbfbf1e22cae6975fac58a1e2d
Get the LSM (Linux Security Module) security label of the specified key.
-
+.IP
The ID of the key whose security label is to be fetched is specified in
.I arg2
(cast to
.I arg4
(cast to
.IR size_t ).
-
+.IP
If
.I arg3
is specified as NULL or the buffer size specified in
(including the terminating null byte)
is returned as the function result,
and nothing is copied to the buffer.
-
+.IP
The caller must have
.I view
permission on the specified key.
-
+.IP
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:
-
+.IP
unconfined_u:unconfined_r:unconfined_t:s0-s0:c0.c1023
-
+.IP
If no LSM is currently in force,
then an empty string is placed in the buffer.
-
+.IP
The
.I arg5
argument is ignored.
-
+.IP
This operation is exposed by
.I libkeyutils
via the functions
.\" What is the use case for KEYCTL_SESSION_TO_PARENT?
.\" David Howells: the Process Authentication Groups people requested this,
.\" but then didn't use it; maybe there are no users.
-
+.IP
The keyring will be replaced in the parent process at the point
where the parent next transitions from kernel space to user space.
-
+.IP
The keyring must exist and must grant the caller
.I link
permission.
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.
+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.
-
+.IP
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.
.BR keyctl (1)
.B new_session
command does.)
-
+.IP
The arguments
.IR arg2 ,
.IR arg3 ,
and
.IR arg5
are ignored.
-
+.IP
This operation is exposed by
.I libkeyutils
via the function
This operation provides a superset of the functionality of the earlier
.BR KEYCTL_NEGATE
operation.
-
+.IP
The ID of the key that is to be negatively instantiated is specified in
.I arg2
(cast to
.BR EKEYREVOKED ,
or
.BR EKEYEXPIRED .
-
+.IP
If
.I arg5
(cast to
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
+whose ID is specified in
.IR arg5 .
-
+.IP
The caller must have the appropriate authorization key.
In other words, this operation is available only from a
.BR request-key (8)-style
program.
See
.BR request_key (2).
-
-
-Negative keys are used to rate limit repeated
+.IP
+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
+.BR request-key (8)-style
+program.
+See
.BR request_key (2)
-calls by causing them to return the error specified until the negative key
-expires.
-
+for an explanation of uninstantiated keys and key instantiation.
+.IP
This operation is exposed by
.I libkeyutils
via the function
.\" commit ee009e4a0d4555ed522a631bae9896399674f063
Instantiate an uninstantiated key with a payload specified
via a vector of buffers.
-
+.IP
This operation is the same as
.BR KEYCTL_INSTANTIATE ,
but the payload data is specified as an array of
.IR iovec
structures:
-
+.IP
.in +4n
-.nf
+.EX
struct iovec {
void *iov_base; /* Starting address of buffer */
size_t iov_len; /* Size of buffer (in bytes) */
};
-.fi
+.EE
.in
-
+.IP
The pointer to the payload vector is specified in
.IR arg3
(cast as
.IR arg4
(cast as
.IR "unsigned int" ).
-
+.IP
The
.I arg2
(key ID)
(keyring ID)
are interpreted as for
.BR KEYCTL_INSTANTIATE .
-
+.IP
This operation is exposed by
.I libkeyutils
via the function
.BR KEYCTL_INVALIDATE " (since Linux 3.5)"
.\" commit fd75815f727f157a05f4c96b5294a4617c0557da
Mark a key as invalid.
-
+.IP
The ID of the key to be invalidated is specified in
.I arg2
(cast to
.IR key_serial_t ).
-
+.IP
To invalidate a key,
the caller must have
.I search
permission on the key.
.\" CAP_SYS_ADMIN is permitted to invalidate certain special keys
-
+.IP
This operation marks the key as invalid
and schedules immediate garbage collection.
The garbage collector removes the invalidated key from all keyrings and
After this operation,
the key will be ignored by all searches,
even if it is not yet deleted.
-
+.IP
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.
-
+.IP
The arguments
.IR arg3 ,
.IR arg4 ,
and
.IR arg5
are ignored.
-
+.IP
This operation is exposed by
.I libkeyutils
via the function
Get the persistent keyring
.RB ( persistent-keyring (7))
for a specified user and link it to a specified keyring.
-
+.IP
The user ID is specified in
.I arg2
(cast to
.I arg3
(cast to
.IR key_serial_t ).
-
+.IP
The caller must have the
.BR CAP_SETUID
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.
-
+.IP
If the call is successful,
a link to the persistent keyring is added to the keyring
whose ID was specified in
.IR arg3 .
-
+.IP
The caller must have
.I write
permission on the keyring.
-
+.IP
The persistent keyring will be created by the kernel
if it does not yet exist.
-
+.IP
Each time the
.B KEYCTL_GET_PERSISTENT
operation is performed, the persistent keyring will
have its expiration timeout reset to the value in:
-
- /proc/sys/kernel/keys/persistent_keyring_expiry
-
+.IP
+.in +4n
+.EX
+/proc/sys/kernel/keys/persistent_keyring_expiry
+.EE
+.in
+.IP
Should the timeout be reached,
the persistent keyring will be removed and
everything it pins can then be garbage collected.
-
+.IP
Persistent keyrings were added to Linux in kernel version 3.13.
-
+.IP
The arguments
.IR arg4
and
.IR arg5
are ignored.
-
+.IP
This operation is exposed by
.I libkeyutils
via the function
.TP
.BR KEYCTL_DH_COMPUTE " (since Linux 4.7)"
.\" commit ddbb41148724367394d0880c516bfaeed127b52e
-Compute a Diffie-Hellman shared secret or public key.
-
+Compute a Diffie-Hellman shared secret or public key,
+optionally applying key derivation function (KDF) to the result.
+.IP
The
.I arg2
argument is a pointer to a set of parameters containing
.IR """user"""
keys used in the Diffie-Hellman calculation,
packaged in a structure of the following form:
-
-.nf
+.IP
.in +4n
+.EX
struct keyctl_dh_params {
int32_t private; /* The local private key */
int32_t prime; /* The prime, known to both parties */
int32_t base; /* The base integer: either a shared
generator or the remote public key */
};
+.EE
.in
-.fi
-
+.IP
Each of the three keys specified in this structure must grant the caller
.I read
permission.
The payloads of these keys are used to calculate the Diffie-Hellman
result as:
-
+.IP
base ^ private mod prime
-
+.IP
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.
-
+.IP
The
.I arg3
argument (cast to
.I arg4
(cast to
.IR size_t ).
-
+.IP
The buffer must be large enough to accommodate the output data,
otherwise an error is returned.
If
in which case the buffer is not used and
the operation returns the minimum required buffer size
(i.e., the length of the prime).
-
+.IP
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.
-
+.IP
Adding support for DH computation to the
.BR keyctl()
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.
-
+.\" commit f1c316a3ab9d24df6022682422fe897492f2c0c8
+.IP
+If the
+.I arg5
+argument is
+.BR NULL ,
+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:
+.IP
+.in +4n
+.EX
+struct keyctl_kdf_params {
+ char *hashname; /* Hash algorithm name */
+ char *otherinfo; /* SP800-56A OtherInfo */
+ __u32 otherinfolen; /* Length of otherinfo data */
+ __u32 __spare[8]; /* Reserved */
+};
+.EE
+.in
+.IP
The
+.I hashname
+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
+.UR https://www.kernel.org\:/doc\:/html\:/latest\:/crypto\:/architecture.html
+"Kernel Crypto API Architecture"
+.UE
+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
+are available)
+to be applied to DH result in KDF operation.
+.IP
+The
+.I otherinfo
+field is an
+.I OtherInfo
+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
+field and is limited by
+.B KEYCTL_KDF_MAX_OI_LEN
+constant that defined in
+.I security/keys/internal.h
+to a value of 64.
+.IP
+The
+.B __spare
+field is currently unused.
+.\" commit 4f9dabfaf8df971f8a3b6aa324f8f817be38d538
+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.
+.IP
+The KDF implementation complies with SP800-56A as well
+as with SP800-108 (the counter KDF).
+.IP
+.\" keyutils commit 742c9d7b94051d3b21f9f61a73ed6b5f3544cb82
+.\" keyutils commit d68a981e5db41d059ac782071c35d1e8f3aaf61c
+This operation is exposed by
+.I libkeyutils
+(from version 1.5.10 onwards) via the functions
+.BR keyctl_dh_compute (3)
+and
+.BR keyctl_dh_compute_alloc (3).
+.TP
+.BR KEYCTL_RESTRICT_KEYRING " (since Linux 4.12)"
+.\" commit 6563c91fd645556c7801748f15bc727c77fcd311
+.\" commit 7228b66aaf723a623e578aa4db7d083bb39546c9
+Apply a key-linking restriction to the keyring with the ID provided in
+.IR arg2
+(cast to
+.IR key_serial_t ).
+The caller must have
+.IR setattr
+permission on the key.
+If
+.I arg3
+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
+contains a pointer to string that describes the type-specific restriction.
+As of Linux 4.12, only the type "asymmetric" has restrictions defined:
+.RS
+.TP
+.B builtin_trusted
+Allows only keys that are signed by a key linked to the built-in keyring
+(".builtin_trusted_keys").
+.TP
+.B builtin_and_secondary_trusted
+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.
+.TP
+.BI key_or_keyring: key
+.TQ
+.BI key_or_keyring: key :chain
+If
+.I key
+specifies the ID of a key of type "asymmetric",
+then only keys that are signed by this key are allowed.
+.IP
+If
+.I key
+specifies the ID of a keyring,
+then only keys that are signed by a key linked
+to this keyring are allowed.
+.IP
+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
+argument) are also allowed.
+.RE
+.IP
+Note that a restriction can be configured only once for the specified keyring;
+once a restriction is set, it can't be overridden.
+.IP
+The argument
.I arg5
-argument is reserved and must be 0.
+is ignored.
+.\" FIXME Document KEYCTL_RESTRICT_KEYRING, added in Linux 4.12
+.\" commit 6563c91fd645556c7801748f15bc727c77fcd311
+.\" Author: Mat Martineau <mathew.j.martineau@linux.intel.com>
+.\" See Documentation/security/keys.txt
.SH RETURN VALUE
For a successful call, the return value depends on the operation:
.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.
+if a nonzero key ID was provided.
.TP
.B KEYCTL_GET_SECURITY
The size of the LSM security label string
.I arg4
is 0, the required buffer size.
.TP
-All other commands
+All other operations
Zero.
.PP
On error, \-1 is returned, and
.B EACCES
The requested operation wasn't permitted.
.TP
+.B EAGAIN
+.I operation
+was
+.B KEYCTL_DH_COMPUTE
+and there was an error during crypto module initialization.
+.TP
.B EDEADLK
.I operation
-is
+was
.BR KEYCTL_LINK
and the requested link would result in a cycle.
.TP
+.B EDEADLK
+.I operation
+was
+.BR KEYCTL_RESTRICT_KEYRING
+and the requested keyring restriction 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 EEXIST
+.I operation
+was
+.BR KEYCTL_RESTRICT_KEYRING
+and keyring provided in
+.I arg2
+argument already has a restriction set.
+.TP
+.B EFAULT
+.I operation
+was
+.B KEYCTL_DH_COMPUTE
+and one of the following has failed:
+.RS
+.IP \(bu 3
+copying of the
+.IR "struct keyctl_dh_params" ,
+provided in the
+.I arg2
+argument, from user space;
+.IP \(bu
+copying of the
+.IR "struct keyctl_kdf_params" ,
+provided in the non-NULL
+.I arg5
+argument, from user space
+(in case kernel supports performing KDF operation on DH operation result);
+.IP \(bu
+copying of data pointed by the
+.I hashname
+field of the
+.I "struct keyctl_kdf_params"
+from user space;
+.IP \(bu
+copying of data pointed by the
+.I otherinfo
+field of the
+.I struct keyctl_kdf_params
+from user space if the
+.I otherinfolen
+field was nonzero;
+.IP \(bu
+copying of the result to user space.
+.RE
+.TP
.B EINVAL
.I operation
was
(the key description)
exceeded the limit (32 bytes and 4096 bytes respectively).
.TP
+.BR EINVAL " (Linux kernels before 4.12)"
+.I operation
+was
+.BR KEYCTL_DH_COMPUTE ,
+argument
+.I arg5
+was non-NULL.
+.TP
+.B EINVAL
+.I operation
+was
+.B KEYCTL_DH_COMPUTE
+And the digest size of the hashing algorithm supplied is zero.
+.TP
.B EINVAL
.I operation
was
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.
.TP
+.B EINVAL
+.I operation
+was
+.B KEYCTL_DH_COMPUTE
+and the hash name provided in the
+.I hashname
+field of the
+.I struct keyctl_kdf_params
+pointed by
+.I arg5
+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).
+.TP
+.B EINVAL
+.\" commit 4f9dabfaf8df971f8a3b6aa324f8f817be38d538
+.I operation
+was
+.B KEYCTL_DH_COMPUTE
+and the
+.I __spare
+field of the
+.I struct keyctl_kdf_params
+provided in the
+.I arg5
+argument contains nonzero values.
+.TP
.B EKEYEXPIRED
An expired key was found or specified.
.TP
.TP
.B ELOOP
.I operation
-is
+was
.BR KEYCTL_LINK
and the requested link would cause the maximum nesting depth
for keyrings to be exceeded.
.TP
+.B EMSGSIZE
+.I operation
+was
+.B KEYCTL_DH_COMPUTE
+and the buffer length exceeds
+.B KEYCTL_KDF_MAX_OUTPUT_LEN
+(which is 1024 currently)
+or the
+.I otherinfolen
+field of the
+.I struct keyctl_kdf_parms
+passed in
+.I arg5
+exceeds
+.B KEYCTL_KDF_MAX_OI_LEN
+(which is 64 currently).
+.TP
.BR ENFILE " (Linux kernels before 3.13)"
.IR operation
-is
+was
.BR KEYCTL_LINK
and the keyring is full.
(Before Linux 3.13,
.TP
.B ENOENT
.I operation
-is
+was
.B KEYCTL_UNLINK
and the key to be unlinked isn't linked to the keyring.
.TP
+.B ENOENT
+.I operation
+was
+.B KEYCTL_DH_COMPUTE
+and the hashing algorithm specified in the
+.I hashname
+field of the
+.I struct keyctl_kdf_params
+pointed by
+.I arg5
+argument hasn't been found.
+.TP
+.B ENOENT
+.I operation
+was
+.B KEYCTL_RESTRICT_KEYRING
+and the type provided in
+.I arg3
+argument doesn't support setting key linking restrictions.
+.TP
.B ENOKEY
No matching key was found or an invalid key was specified.
.TP
.I arg3
was zero (meaning don't create the key if it didn't exist).
.TP
+.B ENOMEM
+One of kernel memory allocation routines failed during the execution of the
+syscall.
+.TP
.B ENOTDIR
A key of keyring type was expected but the ID of a key with
a different type was provided.
.TP
.B EOPNOTSUPP
.I operation
-is
+was
.B KEYCTL_READ
and the key type does not support reading
(e.g., the type is
.TP
.B EOPNOTSUPP
.I operation
-is
+was
.B KEYCTL_UPDATE
and the key type does not support updating.
.TP
+.B EOPNOTSUPP
+.I operation
+was
+.BR KEYCTL_RESTRICT_KEYRING ,
+the type provided in
+.I arg3
+argument was "asymmetric", and the key specified in the restriction specification
+provided in
+.I arg4
+has type other than "asymmetric" or "keyring".
+.TP
.B EPERM
.I operation
was
or the parent process is
.BR init (1)
or a kernel thread.
+.TP
+.B ETIMEDOUT
+.I operation
+was
+.B KEYCTL_DH_COMPUTE
+and the initialization of crypto modules has timed out.
.SH VERSIONS
This system call first appeared in Linux 2.6.10.
.SH CONFORMING TO
package.
For informational purposes,
the program records various information in a log file.
-
+.PP
As described in
.BR request_key (2),
the
The example program fetches and logs these arguments.
The program assumes authority to instantiate the requested key,
and then instantiates that key.
-
+.PP
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
we use the example program shown in
.BR request_key (2)
to request a key.
-
-.nf
+.PP
.in +4n
+.EX
$ \fBcc \-o key_instantiate key_instantiate.c \-lkeyutils\fP
$ \fBsudo mv /sbin/request\-key /sbin/request\-key.backup\fP
$ \fBsudo cp key_instantiate /sbin/request\-key\fP
$ \fB./t_request_key user mykey somepayloaddata\fP
Key ID is 20d035bf
$ \fBsudo mv /sbin/request\-key.backup /sbin/request\-key\fP
+.EE
.in
-.fi
-
+.PP
Looking at the log file created by this program,
we can see the command-line arguments supplied to our example program:
-
-.nf
+.PP
.in +4n
+.EX
$ \fBcat /tmp/key_instantiate.log \fP
Time: Mon Nov 7 13:06:47 2016
Auth key payload: somepayloaddata
Destination keyring: 256e6a6
Auth key description: .request_key_auth;1000;1000;0b010000;20d035bf
+.EE
.in
-.fi
-
+.PP
The last few lines of the above output show that the example program
was able to fetch:
.IP * 3
.IR mykey
and ID
.IR 20d035bf .
-
-.nf
+.PP
.in +4n
+.EX
$ \fBcat /proc/keys | egrep \(aqmykey|256e6a6\(aq\fP
0256e6a6 I\-\-Q\-\-\- 194 perm 3f030000 1000 1000 keyring _ses: 3
20d035bf I\-\-Q\-\-\- 1 perm 3f010000 1000 1000 user mykey: 16
+.EE
.in
-.fi
.SS Program source
\&
-.nf
+.EX
/* key_instantiate.c */
#include <sys/types.h>
exit(EXIT_SUCCESS);
}
-.fi
+.EE
.SH SEE ALSO
.ad l
.nh
.BR keyctl_clear (3),
.BR keyctl_describe (3),
.BR keyctl_describe_alloc (3),
+.BR keyctl_dh_compute (3),
+.BR keyctl_dh_compute_alloc (3),
.BR keyctl_get_keyring_ID (3),
.BR keyctl_get_persistent (3),
.BR keyctl_get_security (3),
.BR session\-keyring (7),
.BR thread\-keyring (7),
.BR user\-keyring (7),
-.BR user\-namespaces (7),
+.BR user_namespaces (7),
.BR user\-session\-keyring (7),
.BR request\-key (8)
-
-The kernel source files
-.IR Documentation/security/keys.txt
-and
-.IR Documentation/security/keys\-request\-key.txt .
+.PP
+The kernel source files under
+.IR Documentation/security/keys/
+(or, before Linux 4.13, in the file
+.IR Documentation/security/keys.txt ).
projects / thirdparty / man-pages.git / blobdiff