From 10c4bf228645d8f0d2fb945844b53a894957c2fb Mon Sep 17 00:00:00 2001 From: Michael Kerrisk Date: Mon, 24 Oct 2016 16:25:22 +0200 Subject: [PATCH] keyctl.2: Further details for KEYCTL_READ Signed-off-by: Michael Kerrisk --- man2/keyctl.2 | 37 +++++++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) diff --git a/man2/keyctl.2 b/man2/keyctl.2 index c2ff73b91..738bd3b0b 100644 --- a/man2/keyctl.2 +++ b/man2/keyctl.2 @@ -754,6 +754,11 @@ The ID of the key whose payload is to be read is specified in .I arg2 (cast to .IR key_serial_t ). +This can be the ID of an existing key, +or any of the special key IDs listed for +.BR KEYCTL_SEARCH . +.\" including KEY_SPEC_REQKEY_AUTH_KEY + The payload is placed in the buffer pointed by .I arg3 (cast to @@ -763,10 +768,34 @@ the size of that buffer must be specified in (cast to .IR size_t ). +The returned data will be processed for presentation +according to the key type. +For example, a keyring will return an array of +.I key_serial_t +entries representing the IDs of all the keys that are linked to it. +The +.IR "user" +key type will return its data as is. +If a key type does not implement this function, +the operation fails with the error +.BR EOPNOTSUPP . + +If +.I arg3 +is not NULL, +as much of the payload data as will fit is copied into the buffer. +On a successful return, +the return value is always the total size of the payload data. +To determine whether the buffer was of sufficient size, +check to see that the return value is less than or equal to +the value supplied in +.IR arg4 . + The key must either grant the caller .I read permission, or grant the caller .I search +.\" FIXME What does the following piece mean? permission when searched for from the process keyrings. The @@ -1474,6 +1503,14 @@ a different type was provided. .B EOPNOTSUPP .I operation is +.B KEYCTL_READ +and the key type does not support reading +(e.g., the type is +.IR """login""" ). +.TP +.B EOPNOTSUPP +.I operation +is .B KEYCTL_UPDATE and the key type does not support updating. .TP