Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > linux.kernel > #1541012 > unrolled thread

Re: Revised keyrings(7) man page for review

Back to article view | Back to linux.kernel

This discussion starts older than the indexed window; earlier articles aren't shown. The article labeled Started by below is the oldest one visible, not the original post.

Contents

  Re: Revised keyrings(7) man page for review David Howells <dhowells@redhat.com> - 2016-12-13 12:40 +0100
    Re: Revised keyrings(7) man page for review "Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com> - 2016-12-13 13:50 +0100
      Re: Revised keyrings(7) man page for review "Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com> - 2016-12-13 14:00 +0100
        Re: Revised keyrings(7) man page for review David Howells <dhowells@redhat.com> - 2016-12-13 14:40 +0100
          Re: Revised keyrings(7) man page for review "Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com> - 2016-12-13 15:00 +0100
            Re: Revised keyrings(7) man page for review David Howells <dhowells@redhat.com> - 2016-12-13 15:30 +0100
              Re: Revised keyrings(7) man page for review "Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com> - 2016-12-14 08:30 +0100
      Re: Revised keyrings(7) man page for review David Howells <dhowells@redhat.com> - 2016-12-13 14:40 +0100
        Re: Revised keyrings(7) man page for review "Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com> - 2016-12-13 14:50 +0100

#1541012 — Re: Revised keyrings(7) man page for review

Michael Kerrisk <mtk@man7.org> 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".

>        access to the facility.  See keyctl(1),  keyctl(3),  and  keyu‐

Ditto.  (And some other dittos).

>               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)."

>               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)."

>    Key types
>        The facility provides several basic types of key:

Again, I think the keyring type needs to go either first or last.

>        "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).

>    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.

>        (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"?

>               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.

>                      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.

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

Merge?

David

[toc] | [next] | [standalone]

#1541047

Hi David,

On 12/13/2016 12:35 PM, David Howells wrote:
> Michael Kerrisk <mtk@man7.org> 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/

[toc] | [prev] | [next] | [standalone]

#1541049

Hello David,

Amended a piece here after Eugene's note about encrypted keys.

On 13 December 2016 at 13:43, Michael Kerrisk (man-pages)
<mtk.manpages@gmail.com> wrote:
> Hi David,
>
> On 12/13/2016 12:35 PM, David Howells wrote:
>> Michael Kerrisk <mtk@man7.org> wrote:
>>
>>>        "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".

So, I've updated this piece a couple of times since the draft that you
reviewed, and by now it reads:

       "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 1 MiB in size.  This key type is
              useful for tasks such as holding Kerberos ticket caches.

              The payload data may be stored in  the  swap  space  rather
              than in kernel memory if the data size exceeds the overhead
              of storing the data encrypted in swap space.  (A tmpfs file
              is  used,  which requires filesystem structures to be allo‐
              cated in the kernel; The size of  these  structures  deter‐
              mines  the  size  threshold  above  which the tmpfs storage
              method  is  used.)   Since  Linux  4.8,  payload  data   is
              encrypted,  to  prevent  it  being written unencrypted into
              swap space.

Okay?

Thanks,

Michael


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

[toc] | [prev] | [next] | [standalone]

#1541065

Michael Kerrisk (man-pages) <mtk.manpages@gmail.com> wrote:

> So, I've updated this piece a couple of times since the draft that you
> reviewed, and by now it reads:
> 
>        "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 1 MiB in size.  This key type is
>               useful for tasks such as holding Kerberos ticket caches.

I'm not sure that "tasks" is quite the word I'd use here (it's overloaded).
Perhaps "purposes"?

>               The payload data may be stored in  the  swap  space  rather
>               than in kernel memory if the data size exceeds the overhead
>               of storing the data encrypted in swap space.  (A tmpfs file
>               is  used,  which requires filesystem structures to be allo‐
>               cated in the kernel; The size of  these  structures  deter‐
>               mines  the  size  threshold  above  which the tmpfs storage
>               method  is  used.)   Since  Linux  4.8,  payload  data   is
>               encrypted,  to  prevent  it  being written unencrypted into
>               swap space.

I would either drop the first "encrypted" ("storing the data encrypted") since
you mention this later or move it earlier to be after the word "stored" ("may
be stored encrypted").

Note that with the "Since Linux 4.8 ..." sentence, the encryption is only
applied if it is stored into tmpfs.

Also, the payload isn't directly stored into swapspace, but is rather stored
into tmpfs, from where it can be swapped.  This is important since you can use
this type of key without any swapspace available to your system.

David

[toc] | [prev] | [next] | [standalone]

#1541086

On 12/13/2016 02:38 PM, David Howells wrote:
> Michael Kerrisk (man-pages) <mtk.manpages@gmail.com> wrote:
> 
>> So, I've updated this piece a couple of times since the draft that you
>> reviewed, and by now it reads:
>>
>>        "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 1 MiB in size.  This key type is
>>               useful for tasks such as holding Kerberos ticket caches.
> 
> I'm not sure that "tasks" is quite the word I'd use here (it's overloaded).
> Perhaps "purposes"?

Fixed.

>>               The payload data may be stored in  the  swap  space  rather
>>               than in kernel memory if the data size exceeds the overhead
>>               of storing the data encrypted in swap space.  (A tmpfs file
>>               is  used,  which requires filesystem structures to be allo‐
>>               cated in the kernel; The size of  these  structures  deter‐
>>               mines  the  size  threshold  above  which the tmpfs storage
>>               method  is  used.)   Since  Linux  4.8,  payload  data   is
>>               encrypted,  to  prevent  it  being written unencrypted into
>>               swap space.
> 
> I would either drop the first "encrypted" ("storing the data encrypted") since

I already dropped that first "encrypted".

> you mention this later or move it earlier to be after the word "stored" ("may
> be stored encrypted").
> 
> Note that with the "Since Linux 4.8 ..." sentence, the encryption is only
> applied if it is stored into tmpfs.

Thanks for that tip.

> Also, the payload isn't directly stored into swapspace, but is rather stored
> into tmpfs, from where it can be swapped.  This is important since you can use
> this type of key without any swapspace available to your system.

Yes, the text still needs some work... How about:


       "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 1 MiB in size.  This key type is
              useful for purposes such as holding Kerberos ticket caches.

              The payload data may  be  stored  in  a  tmpfs  filesystem,
              rather  than in kernel memory, if the data size exceeds the
              overhead of storing the data in the  filesystem.   (Storing
              the  data in a filesystem requires filesystem structures to
              be allocated in the kernel.  The size of  these  structures
              determines the size threshold above which the tmpfs storage
              method is used.)  Since Linux  4.8,  the  payload  data  is
              encrypted when stored in tmpfs, to prevent it being written
              unencrypted into swap space.

?

Thanks,

Michael



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

[toc] | [prev] | [next] | [standalone]

#1541117

Michael Kerrisk (man-pages) <mtk.manpages@gmail.com> wrote:

>               The payload data may  be  stored  in  a  tmpfs  filesystem,
>               rather  than in kernel memory, if the data size exceeds the
>               overhead of storing the data in the  filesystem.   (Storing
>               the  data in a filesystem requires filesystem structures to
>               be allocated in the kernel.  The size of  these  structures
>               determines the size threshold above which the tmpfs storage
>               method is used.)  Since Linux  4.8,  the  payload  data  is
>               encrypted when stored in tmpfs, to prevent it being written
>               unencrypted into swap space.

"... thereby preventing it from being written unencrypted into the swapspace"?

David

[toc] | [prev] | [next] | [standalone]

#1541732

On 12/13/2016 03:20 PM, David Howells wrote:
> Michael Kerrisk (man-pages) <mtk.manpages@gmail.com> wrote:
> 
>>               The payload data may  be  stored  in  a  tmpfs  filesystem,
>>               rather  than in kernel memory, if the data size exceeds the
>>               overhead of storing the data in the  filesystem.   (Storing
>>               the  data in a filesystem requires filesystem structures to
>>               be allocated in the kernel.  The size of  these  structures
>>               determines the size threshold above which the tmpfs storage
>>               method is used.)  Since Linux  4.8,  the  payload  data  is
>>               encrypted when stored in tmpfs, to prevent it being written
>>               unencrypted into swap space.
> 
> "... thereby preventing it from being written unencrypted into the swapspace"?

Fixed.

Thanks,

Michael

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

[toc] | [prev] | [next] | [standalone]

#1541064

Michael Kerrisk (man-pages) <mtk.manpages@gmail.com> wrote:

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

"... an optional comma ..." ;-)

There's also:

	... LSM security checks are still performed, and may filter out
        further keys that the process is not authorized to view.

but has two parts and isn't a list... ;-P

> >>                      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?

Not quite.  The driver for the key type has been unregistered, not the key.

David

[toc] | [prev] | [next] | [standalone]

#1541084

Hi David,

On 12/13/2016 02:31 PM, David Howells wrote:
> Michael Kerrisk (man-pages) <mtk.manpages@gmail.com> wrote:
> 
>> I use/Linux man-pages uses the "Oxford comma" convention.
> 
> "... an optional comma ..." ;-)
> 
> There's also:
> 
> 	... LSM security checks are still performed, and may filter out
>         further keys that the process is not authorized to view.
> 
> but has two parts and isn't a list... ;-P

Oxford comma doesn't apply there... But, to me, it depends how
you read the text aloud. I'd read it with a pause where the comma is,
and so added a comma there.

> 
>>>>                      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?
> 
> Not quite.  The driver for the key type has been unregistered, not the key.

Bother. I meant to write "key type"! Fixed.

Cheers,

Michael


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

[toc] | [prev] | [standalone]

Back to top | Article view | linux.kernel

csiph-web