From a6cca1b5733ca4fe07b94f361ee685208216cf63 Mon Sep 17 00:00:00 2001 From: Michael Kerrisk Date: Wed, 26 Oct 2016 16:33:40 +0200 Subject: [PATCH] keyctl.2: Further details for KEYCTL_ASSUME_AUTHORITY Signed-off-by: Michael Kerrisk --- man2/keyctl.2 | 30 +++++++++++++++++++++++++----- 1 file changed, 25 insertions(+), 5 deletions(-) diff --git a/man2/keyctl.2 b/man2/keyctl.2 index dee9e79d1..a79e339e2 100644 --- a/man2/keyctl.2 +++ b/man2/keyctl.2 @@ -988,9 +988,8 @@ via the function .BR keyctl_set_timeout (3). .TP .BR KEYCTL_ASSUME_AUTHORITY " (since Linux 2.6.16)" -.\" FIXME More needs to be said for KEYCTL_ASSUME_AUTHORITY Assume (or divest) the authority for the calling thread -to instantiate a specified key. +to instantiate a key. The .I arg2 @@ -1003,8 +1002,16 @@ If .I arg2 is nonzero, then it specifies the ID of an uninstantiated key for which authority is to be assumed. +That key can then be instantiated using one of +.BR KEYCTL_INSTANTIATE , +.BR KEYCTL_INSTANTIATE_IOV , +.BR KEYCTL_REJECT , +or +.BR KEYCTL_NEGATE . +Once the key has been instantiated, +the thread is automatically divested of authority to instantiate the key. -Authority of a key can be assumed only if the calling thread has present +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. The caller must have @@ -1013,8 +1020,9 @@ permission on the authorization key. If the specified key has a matching authorization key, then the ID of that key is returned. -The authorization key can be read to obtain -the callout information passed to +The authorization key can be read +.RB ( KEYCTL_READ ) +to obtain the callout information passed to .BR request_key (2). If the ID given in @@ -1022,6 +1030,18 @@ If the ID given in is 0, then the currently assumed authority is cleared (divested), and the value 0 is returned. +The +.BR KEYCTL_ASSUME_AUTHORITY +mechanism allows a program such as +.BR request-key (8) +to assume the necessary authority to instantiate a new uninstantiated key +that was created as a consequence of a call to +.BR request_key (2). +For further information, see +.BR request_key (2) +and the kernel source file +.IR Documentation/security/keys-request-key.txt . + The arguments .IR arg3 , .IR arg4 ,