From f595473369ba6cf438f9d3d90741e9760a0b880c Mon Sep 17 00:00:00 2001 From: Michael Kerrisk Date: Thu, 20 Oct 2016 14:55:49 +0200 Subject: [PATCH] keyctl.2: Improve KEYCTL_GET_PERSISTENT details Signed-off-by: Michael Kerrisk --- man2/keyctl.2 | 48 ++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 42 insertions(+), 6 deletions(-) diff --git a/man2/keyctl.2 b/man2/keyctl.2 index b48450ab9..9d5ef7f2a 100644 --- a/man2/keyctl.2 +++ b/man2/keyctl.2 @@ -664,7 +664,7 @@ 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. +This specifies the caller thread's thread-specific keyring. See .BR thread_keyring (7). .TP @@ -1194,15 +1194,51 @@ 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 +.\" commit f36f8c75ae2e7d4da34f4c908cebdb4aa42c977e +Get the persistent keyring +.RB ( persistent_keyring (7)) +for a specified user and link it to a specified keyring. + +The user ID is specified in .I arg2 (cast to -.IR uid_t ) -and link it to the keyring with the ID provided in the +.IR uid_t ). +If the value \-1 is specified, the caller's real user ID is used. +The ID of the destination keyring is specified in .I arg3 -argument (cast to +(cast to .IR key_serial_t ). -If \-1 is provided as UID, current user's ID is used. + +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. + +If the call is successful, +a link to the persistent keyring is added to the keyring +whose ID was specified in +.IR arg3 . + +The caller must have +.I write +permission on the keyring. + +The persistent keyring will be created by the kernel +if it does not yet exist. + +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 + +Should the timeout be reached, +the persistent keyring will be removed and +everything it pins can then be garbage collected. + +Persistent keyrings were added to Linux in kernel version 3.13. The arguments .IR arg4