keyctl.2, KEYCTL_SETPERM.2const: Split KEYCTL_SETPERM from keyctl(2)

Signed-off-by: Alejandro Colomar <alx@kernel.org>
author: Alejandro Colomar <alx@kernel.org> 2024-07-03 17:31:27 +0200
committer: Alejandro Colomar <alx@kernel.org> 2024-08-21 23:51:07 +0200
commit: f0e457c0a89bc64d23b10b1e07b6eb46f742358e (patch)
tree: 5a8001abbfbfbbe33a949e2da65eaf559a5577d1
parent: 94838a55318f7fe8092bf1923683e8194b661b7a (diff)
download: man-pages-f0e457c0a89bc64d23b10b1e07b6eb46f742358e.tar.gz
2 files changed, 262 insertions, 215 deletions
diff --git a/man/man2/keyctl.2 b/man/man2/keyctl.2
index 1906cb8fd3..5c75b0b759 100644
--- a/man/man2/keyctl.2
+++ b/man/man2/keyctl.2
@@ -51,213 +51,8 @@ are:
 .BR KEYCTL_REVOKE (2const)
 .TQ
 .BR KEYCTL_CHOWN (2const)
-.TP
-.BR KEYCTL_SETPERM " (since Linux 2.6.10)"
-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 ).
-.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
-.I regardless
-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
-.I 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
-.I user
-This is the permission granted to a process
-whose filesystem UID matches the UID of the key.
-.TP
-.I 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
-.I other
-This is the permission granted to other processes
-that do not match the
-.I user
-and
-.I group
-categories.
-.RE
-.IP
-The
-.IR user ,
-.IR group ,
-and
-.I other
-categories are exclusive: if a process matches the
-.I user
-category, it will not receive permissions granted in the
-.I group
-category; if a process matches the
-.I user
-or
-.I group
-category, then it will not receive permissions granted in the
-.I other
-category.
-.IP
-The
-.I possessor
-category grants permissions that are cumulative with the grants from the
-.IR user ,
-.IR group ,
-or
-.I other
-category.
-.IP
-Each permission mask is eight bits in size,
-with only six bits currently used.
-The available permissions are:
-.RS
-.TP
-.I view
-This permission allows reading attributes of a key.
-.IP
-This permission is required for the
-.B KEYCTL_DESCRIBE
-operation.
-.IP
-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
-.I read
-This permission allows reading a key's payload.
-.IP
-This permission is required for the
-.B KEYCTL_READ
-operation.
-.IP
-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
-.I 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 (2const),
-.BR KEYCTL_REVOKE (2const),
-.BR KEYCTL_CLEAR ,
-.BR KEYCTL_LINK ,
-and
-.B KEYCTL_UNLINK
-operations.
-.IP
-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
-.I search
-This permission allows keyrings to be searched and keys to be found.
-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 (2const),
-.BR KEYCTL_JOIN_SESSION_KEYRING (2const),
-.BR KEYCTL_SEARCH ,
-and
-.B KEYCTL_INVALIDATE
-operations.
-.IP
-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
-.I link
-This permission allows a key or keyring to be linked to.
-.IP
-This permission is required for the
-.B KEYCTL_LINK
-and
-.B KEYCTL_SESSION_TO_PARENT
-operations.
-.IP
-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.
-.IP
-This permission is required for the
-.BR KEYCTL_REVOKE (2const),
-.BR KEYCTL_CHOWN (2const),
-and
-.B KEYCTL_SETPERM
-operations.
-.IP
-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 .
-.IP
-The
-.I arg4
-and
-.I arg5
-arguments are ignored.
-.IP
-This operation is exposed by
-.I libkeyutils
-via the function
-.BR keyctl_setperm (3).
+.TQ
+.BR KEYCTL_SETPERM (2const)
 .TP
 .BR KEYCTL_DESCRIBE " (since Linux 2.6.10)"
 Obtain a string describing the attributes of a specified key.
@@ -1468,13 +1263,6 @@ copying of the result to user space.
 .B EINVAL
 .I operation
 was
-.B KEYCTL_SETPERM
-and an invalid permission bit was specified in
-.IR arg3 .
-.TP
-.B EINVAL
-.I operation
-was
 .B KEYCTL_SEARCH
 and the size of the description in
 .I arg4
@@ -1988,7 +1776,6 @@ main(int argc, char *argv[])
 .BR keyctl_session_to_parent (3),
 .BR keyctl_set_reqkey_keyring (3),
 .BR keyctl_set_timeout (3),
-.BR keyctl_setperm (3),
 .BR keyctl_unlink (3),
 .BR recursive_key_scan (3),
 .BR recursive_session_key_scan (3),
diff --git a/man/man2const/KEYCTL_SETPERM.2const b/man/man2const/KEYCTL_SETPERM.2const
new file mode 100644
index 0000000000..4ee23f6948
--- /dev/null
+++ b/man/man2const/KEYCTL_SETPERM.2const
@@ -0,0 +1,260 @@
+.\" Copyright 2016, Michael Kerrisk <mtk.manpages@gmail.com>
+.\" Copyright 2016, Eugene Syromyatnikov <evgsyr@gmail.com>
+.\" A very few fragments remain from an earlier version of this page
+.\" written by David Howells (dhowells@redhat.com)
+.\" Copyright 2024, Alejandro Colomar <alx@kernel.org>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.TH KEYCTL_SETPERM 2const (date) "Linux man-pages (unreleased)"
+.SH NAME
+KEYCTL_SETPERM
+\-
+change the permissions mask on a key
+.SH LIBRARY
+Standard C library
+.RI ( libc ,\~ \-lc )
+.SH SYNOPSIS
+.nf
+.BR "#include <linux/keyctl.h>" "  /* Definition of " KEY* " constants */"
+.BR "#include <sys/syscall.h>" "   /* Definition of " SYS_* " constants */"
+.B #include <unistd.h>
+.P
+.BI "long syscall(SYS_keyctl, int " operation ", unsigned long " arg2 ,
+.BI "             unsigned long " arg3 );
+.fi
+.SH DESCRIPTION
+.TP
+.BR KEYCTL_SETPERM " (since Linux 2.6.10)"
+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 ).
+.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
+.I regardless
+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
+.I 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
+.I user
+This is the permission granted to a process
+whose filesystem UID matches the UID of the key.
+.TP
+.I 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
+.I other
+This is the permission granted to other processes
+that do not match the
+.I user
+and
+.I group
+categories.
+.RE
+.IP
+The
+.IR user ,
+.IR group ,
+and
+.I other
+categories are exclusive: if a process matches the
+.I user
+category, it will not receive permissions granted in the
+.I group
+category; if a process matches the
+.I user
+or
+.I group
+category, then it will not receive permissions granted in the
+.I other
+category.
+.IP
+The
+.I possessor
+category grants permissions that are cumulative with the grants from the
+.IR user ,
+.IR group ,
+or
+.I other
+category.
+.IP
+Each permission mask is eight bits in size,
+with only six bits currently used.
+The available permissions are:
+.RS
+.TP
+.I view
+This permission allows reading attributes of a key.
+.IP
+This permission is required for the
+.B KEYCTL_DESCRIBE
+operation.
+.IP
+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
+.I read
+This permission allows reading a key's payload.
+.IP
+This permission is required for the
+.B KEYCTL_READ
+operation.
+.IP
+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
+.I 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 (2const),
+.BR KEYCTL_REVOKE (2const),
+.BR KEYCTL_CLEAR ,
+.BR KEYCTL_LINK ,
+and
+.B KEYCTL_UNLINK
+operations.
+.IP
+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
+.I search
+This permission allows keyrings to be searched and keys to be found.
+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 (2const),
+.BR KEYCTL_JOIN_SESSION_KEYRING (2const),
+.BR KEYCTL_SEARCH ,
+and
+.B KEYCTL_INVALIDATE
+operations.
+.IP
+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
+.I link
+This permission allows a key or keyring to be linked to.
+.IP
+This permission is required for the
+.B KEYCTL_LINK
+and
+.B KEYCTL_SESSION_TO_PARENT
+operations.
+.IP
+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.
+.IP
+This permission is required for the
+.BR KEYCTL_REVOKE (2const),
+.BR KEYCTL_CHOWN (2const),
+and
+.B KEYCTL_SETPERM
+operations.
+.IP
+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 .
+.IP
+The
+.I arg4
+and
+.I arg5
+arguments are ignored.
+.IP
+This operation is exposed by
+.I libkeyutils
+via the function
+.BR keyctl_setperm (3).
+.SH RETURN VALUE
+On success,
+0 is returned.
+.P
+On error, \-1 is returned, and
+.I errno
+is set to indicate the error.
+.SH ERRORS
+.TP
+.B EINVAL
+.I operation
+was
+.B KEYCTL_SETPERM
+and an invalid permission bit was specified in
+.IR arg3 .
+.SH VERSIONS
+A wrapper is provided in the
+.I libkeyutils
+library:
+.BR keyctl_setperm (3).
+.SH STANDARDS
+Linux.
+.SH HISTORY
+Linux 2.6.10.
+.SH SEE ALSO
+.BR keyctl (2),
+.BR keyctl_setperm (3)
author	Alejandro Colomar <alx@kernel.org>	2024-07-03 17:31:27 +0200
committer	Alejandro Colomar <alx@kernel.org>	2024-08-21 23:51:07 +0200
commit	f0e457c0a89bc64d23b10b1e07b6eb46f742358e (patch)
tree	5a8001abbfbfbbe33a949e2da65eaf559a5577d1
parent	94838a55318f7fe8092bf1923683e8194b661b7a (diff)
download	man-pages-f0e457c0a89bc64d23b10b1e07b6eb46f742358e.tar.gz