keyctl.2: Improve KEYCTL_REJECT details

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

man2/keyctl.2

@@ -960,27 +960,49 @@ 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
+.\" commit fdd1b94581782a2ddf9124414e5b7a5f48ce2f9c
+.\" We need some text here on why it is useful to negatively instantiate a key
+Mark a key as negatively instantiated and set an expiration timer
+on the key.
+This operation provides a superset of the functionality of the earlier
+.BR KEYCTL_NEGATE
+operation.
+
+The ID of the key that is to be negatively instantiated is specified in
 .I arg2
-argument (cast to
-.IR key_serial_t ),
-setting timeout (in seconds) to the value provided in the
+(cast to
+.IR key_serial_t ).
+The
 .I arg3
-argument (cast to
+(cast to
 .IR "unsigned int" )
-and instantiation error to the value provided in the
+argument specifies the lifetime of the key, in seconds.
+The
 .I arg4
 argument (cast to
-.IR "unsigned int" ).
-The instantiated key will be linked to the keyring ID which is provided in the
+.IR "unsigned int" )
+specifies the error to be returned when a search hits this key;
+typically, this is one of
+.BR EKEYREJECTED ,
+.BR EKEYREVOKED ,
+or
+.BR EKEYEXPIRED .
+
+If
 .I arg5
-argument (cast to
-.IR key_serial_t ).
+(cast to
+.IR key_serial_t )
+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
+.IR arg5 .
 
 The caller must have the appropriate instantiation permit set
 (authorization key, see
 .B KEYCTL_ASSUME_AUTHORITY
-command).
+command and
+.BR request_key (2)).
 
 Negative keys are used to rate limit repeated
 .BR request_key (2)