Re: Revised keyrings(7) man page for review

[Michael Kerrisk (man-pages)]

Hi David,

On 12/13/2016 12:35 PM, David Howells wrote:
> Michael Kerrisk <mtk@xxxxxxxx> wrote:
> 
>>        The  Linux key-management facility is primarily a way for drivâ
>>        ers to retain or  cache  security  data,  authentication  keys,
>>        encryption keys, and other data in the kernel.
> 
> No comma before "and".

I use/Linux man-pages uses the "Oxford comma" convention.

> 
>>        access to the facility.  See keyctl(1),  keyctl(3),  and  keyuâ
> 
> Ditto.  (And some other dittos).

See above.

>>               to the kernel when it was requested.   (Details  can  be
>>               found in request_key(2).)
> 
> How about dropping the brackets and making that last sentence "For further
> details, see request_key(2)."

Done.

>>               beyond the usual user, group, and other (see below).
> 
> I think this needs to say what below one is supposed to see:
> 
> "beyond the usual User, Group and Other (see 'Possession' below)."

Fixed.

>>    Key types
>>        The facility provides several basic types of key:
> 
> Again, I think the keyring type needs to go either first or last.

Fixed.

>>        "big_key" (since Linux 3.13)
>>               This  key type is similar to the "user" key type, but it
>>               may hold a payload of up to 1MiB in size.  The data  may
>>               be stored in the swap space rather than in kernel memory
> 
> stored encrypted (as of 4.8).

Added "encrypted".

> 
>>    Anchoring keys
>>        To prevent a key from being prematurely garbage  collected,  it
>>        must  anchored  to keep its reference count elevated when it is
>>        not in active use by the kernel.
> 
> I think "prematurely" is unnecessary here.

Fixed.

>>        (3) The search of the keyring tree is in preorder: each keyring
>>            is searched first for a match, then the  keyrings  referred
>>            to by that keyring are searched.
> 
> "preorder"?  How about "breadth-first order"?

Fixed.

>>               The  only keys included in the list are those that grant
>>               view permission to the reading  process,  regardless  of
>>               whether  or  not it possesses them.  LSM security checks
>>               are still performed, and may  filter  out  further  keys
>>               that the process is not authorized to view.
> 
> This is correct.  See proc_keys_show() in security/keys/proc.c:
> 
> 	rc = key_task_permission(key_ref, ctx.cred, KEY_NEED_VIEW);
> 	if (rc < 0)
> 		return 0;
> 
> Possibly it shouldn't be, but for now it is.

Okay -- thanks.


>>                      D   The key is dead (i.e., has been deleted).  (A
>>                          key  may  be  briefly  in  this  state during
>>                          garbage collection.)
> 
> No - "dead" in this context means that the key type was unregistered.

Okay, so the text should read as:

                     D   The key is dead (i.e., the key has been unregisâ
                         tered).  (A key may be  briefly  in  this  state
                         during garbage collection.)

Right?

> 
>>               Description
>>                      The key description (name).
>>
>>               Description
>>                      This field contains descriptive information about
> 
> Merge?

Yup. Already found and fixed that one.

Cheers,

Michael



-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/