Re: Revised keyrings(7) man page for review

[Michael Kerrisk (man-pages)]

On 12/13/2016 03:20 PM, David Howells wrote:
> Michael Kerrisk (man-pages)  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/

Re: Revised keyrings(7) man page for review

[Michael Kerrisk (man-pages)]

On 12/13/2016 03:20 PM, David Howells wrote:
> Michael Kerrisk (man-pages)  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/

Re: Revised keyrings(7) man page for review

[David Howells]

Michael Kerrisk (man-pages)  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

Re: Revised keyrings(7) man page for review

[David Howells]

Michael Kerrisk (man-pages)  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

Re: Revised keyrings(7) man page for review

[Michael Kerrisk (man-pages)]

On 12/13/2016 02:38 PM, David Howells wrote:
> Michael Kerrisk (man-pages)  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/

Re: Revised keyrings(7) man page for review

[Michael Kerrisk (man-pages)]

On 12/13/2016 02:38 PM, David Howells wrote:
> Michael Kerrisk (man-pages)  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/

Re: Revised keyrings(7) man page for review

[Michael Kerrisk (man-pages)]

Hi David,

On 12/13/2016 02:31 PM, David Howells wrote:
> Michael Kerrisk (man-pages)  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/

Re: Revised keyrings(7) man page for review

[Michael Kerrisk (man-pages)]

Hi David,

On 12/13/2016 02:31 PM, David Howells wrote:
> Michael Kerrisk (man-pages)  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/

Re: Revised keyrings(7) man page for review

[David Howells]

Michael Kerrisk (man-pages)  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

Re: Revised keyrings(7) man page for review

[David Howells]

Michael Kerrisk (man-pages)  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

Re: Revised keyrings(7) man page for review

[David Howells]

Michael Kerrisk (man-pages)  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

Re: Revised keyrings(7) man page for review

[David Howells]

Michael Kerrisk (man-pages)  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

Re: Revised keyrings(7) man page for review

[Michael Kerrisk (man-pages)]

Hello David,

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

On 13 December 2016 at 13:43, Michael Kerrisk (man-pages)
 wrote:
> Hi David,
>
> On 12/13/2016 12:35 PM, David Howells wrote:
>> Michael Kerrisk  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/

Re: Revised keyrings(7) man page for review

[Michael Kerrisk (man-pages)]

Hello David,

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

On 13 December 2016 at 13:43, Michael Kerrisk (man-pages)
 wrote:
> Hi David,
>
> On 12/13/2016 12:35 PM, David Howells wrote:
>> Michael Kerrisk  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/

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

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

Re: Revised keyrings(7) man page for review

[David Howells]

Michael Kerrisk  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

Re: Revised keyrings(7) man page for review

[David Howells]

Michael Kerrisk  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

Re: Revised keyrings(7) man page for review

[Michael Kerrisk (man-pages)]

Hi David,

Would you have a chance to look at this page?

Cheers

Michael


On 11/04/2016 04:47 PM, Michael Kerrisk wrote:
> Hi David,
> 
> As part of the process of adopting the *.7 pages from
> keyutils into man-pages, I've made some significant
> extensions to the keyrings(7) page. Among the more notable 
> changes:
> 
> * Expanded the detail in "Key types"
> * Addition of a section on the various /proc files
> * Various other minor reworkings elsewhere in the text
> 
> Would you would be willing to review the new page, please?
> (The page source file is attached, in case you want to
> see all the formatting.)
> 
> Cheers,
> 
> Michael
> 
> 
> 
> 
> NAME
>keyrings - in-kernel key management and retention facility
> 
> DESCRIPTION
>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.
> 
>System call interfaces are provided so that user-space programs
>can manage those objects and also use the  facility  for  their
>own purposes.
> 
>A  library  and some user-space utilities are provided to allow
>access to the facility.  See keyctl(1),  keyctl(3),  and  keyu‐
>tils(7) for more information.
> 
>Keys
>A key has the following attributes:
> 
>Serial number (ID)
>   This  is  a  unique  integer  handle  by  which a key is
>   referred to in system call arguments.  The serial number
>   is  sometimes synonymously referred as the key ID.  Pro‐
>   grammatically, key serial numbers are represented  using
>   the type key_serial_t.
> 
>Type   A  key's  type  defines what sort of data can be held in
>   the key, how the proposed content of  the  key  will  be
>   parsed, and how the payload will be used.
> 
>   There  are  a number of general purpose types available,
>   plus some specialist types defined by specific drivers.
> 
>Description (name)
>   The key description is a printable string that  is  used
>   as  the search term for the key (in conjunction with the
>   key type) as well as a display name.   During  searches,
>   the  description  may  be  partially  matched or exactly
>   matched.
> 
>Payload (data)
>   The payload is the actual content of  a  key.   This  is
>   usually  set  when  a key is created, but it is possible
>   for the kernel to upcall to user  space  to  finish  the
>   instantiation  of a key if that key wasn't already known
>   to the kernel when it was requested.   (Details  can  be
>   found in request_key(2).)
> 
>   A  key's payload can be read and updated if the key type
>   supports it and if suitable permission is granted to the
>   caller.
> 
>Access rights
>   Much  as  files  do,  each key has an owning user ID, an
>   owning group ID, and a security label.  They also have a
>   set  of  permissions,  though  there are more than for a
>   normal UNIX file, and there is  an  additional  category
>   beyond the usual user, group, and other (see below).
> 
>   Note that keys are quota controlled since they represent
>   unswappable kernel memory and the owning user ID  speci‐
>   fies whose quota is to be debited.
> 
>Expiration time
>   Each  key  can  have  an expiration time set.  When that
>   time is reached, the key is marked as being expired  and
>   accesses  to  it fail with EKEYEXPIRED.  If not deleted,
>   updated, or  replaced,  after  a  set  amount  of  time,
>   expired  keys  are  automatically removed along with all
>   links to them, and attempts to access the key will  fail
>   with the error ENOKEY.
> 
>Reference count
>   Each  key has a reference count.  Keys are referenced by
>   keyrings, by currently active users, and by a  process's
>   credentials.  When the reference count reaches zero, the
>   key is scheduled for garbage collection.
> 
>Key types
>The facility provides several basic types of key:
> 
>"user" This is a general purpose key type.   The  key  is  kept
>   entirely  within kernel memory.  The payload may be read
>   and updated by user-space applications.
> 
>   The payload for keys of this type is a blob of arbitrary
>   data of up to 32,767 bytes.
> 
>   The  description  may  be any valid string, though it is
>   preferred that it start with  a  colon-delimited  prefix
>

Re: Revised keyrings(7) man page for review

[Michael Kerrisk (man-pages)]

Hi David,

Would you have a chance to look at this page?

Cheers

Michael


On 11/04/2016 04:47 PM, Michael Kerrisk wrote:
> Hi David,
> 
> As part of the process of adopting the *.7 pages from
> keyutils into man-pages, I've made some significant
> extensions to the keyrings(7) page. Among the more notable 
> changes:
> 
> * Expanded the detail in "Key types"
> * Addition of a section on the various /proc files
> * Various other minor reworkings elsewhere in the text
> 
> Would you would be willing to review the new page, please?
> (The page source file is attached, in case you want to
> see all the formatting.)
> 
> Cheers,
> 
> Michael
> 
> 
> 
> 
> NAME
>keyrings - in-kernel key management and retention facility
> 
> DESCRIPTION
>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.
> 
>System call interfaces are provided so that user-space programs
>can manage those objects and also use the  facility  for  their
>own purposes.
> 
>A  library  and some user-space utilities are provided to allow
>access to the facility.  See keyctl(1),  keyctl(3),  and  keyu‐
>tils(7) for more information.
> 
>Keys
>A key has the following attributes:
> 
>Serial number (ID)
>   This  is  a  unique  integer  handle  by  which a key is
>   referred to in system call arguments.  The serial number
>   is  sometimes synonymously referred as the key ID.  Pro‐
>   grammatically, key serial numbers are represented  using
>   the type key_serial_t.
> 
>Type   A  key's  type  defines what sort of data can be held in
>   the key, how the proposed content of  the  key  will  be
>   parsed, and how the payload will be used.
> 
>   There  are  a number of general purpose types available,
>   plus some specialist types defined by specific drivers.
> 
>Description (name)
>   The key description is a printable string that  is  used
>   as  the search term for the key (in conjunction with the
>   key type) as well as a display name.   During  searches,
>   the  description  may  be  partially  matched or exactly
>   matched.
> 
>Payload (data)
>   The payload is the actual content of  a  key.   This  is
>   usually  set  when  a key is created, but it is possible
>   for the kernel to upcall to user  space  to  finish  the
>   instantiation  of a key if that key wasn't already known
>   to the kernel when it was requested.   (Details  can  be
>   found in request_key(2).)
> 
>   A  key's payload can be read and updated if the key type
>   supports it and if suitable permission is granted to the
>   caller.
> 
>Access rights
>   Much  as  files  do,  each key has an owning user ID, an
>   owning group ID, and a security label.  They also have a
>   set  of  permissions,  though  there are more than for a
>   normal UNIX file, and there is  an  additional  category
>   beyond the usual user, group, and other (see below).
> 
>   Note that keys are quota controlled since they represent
>   unswappable kernel memory and the owning user ID  speci‐
>   fies whose quota is to be debited.
> 
>Expiration time
>   Each  key  can  have  an expiration time set.  When that
>   time is reached, the key is marked as being expired  and
>   accesses  to  it fail with EKEYEXPIRED.  If not deleted,
>   updated, or  replaced,  after  a  set  amount  of  time,
>   expired  keys  are  automatically removed along with all
>   links to them, and attempts to access the key will  fail
>   with the error ENOKEY.
> 
>Reference count
>   Each  key has a reference count.  Keys are referenced by
>   keyrings, by currently active users, and by a  process's
>   credentials.  When the reference count reaches zero, the
>   key is scheduled for garbage collection.
> 
>Key types
>The facility provides several basic types of key:
> 
>"user" This is a general purpose key type.   The  key  is  kept
>   entirely  within kernel memory.  The payload may be read
>   and updated by user-space applications.
> 
>   The payload for keys of this type is a blob of arbitrary
>   data of up to 32,767 bytes.
> 
>   The  description  may  be any valid string, though it is
>   preferred that it start with  a  colon-delimited  prefix
>

Revised keyrings(7) man page for review

[Michael Kerrisk]

Hi David,

As part of the process of adopting the *.7 pages from
keyutils into man-pages, I've made some significant
extensions to the keyrings(7) page. Among the more notable 
changes:

* Expanded the detail in "Key types"
* Addition of a section on the various /proc files
* Various other minor reworkings elsewhere in the text

Would you would be willing to review the new page, please?
(The page source file is attached, in case you want to
see all the formatting.)

Cheers,

Michael




NAME
   keyrings - in-kernel key management and retention facility

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

   System call interfaces are provided so that user-space programs
   can manage those objects and also use the  facility  for  their
   own purposes.

   A  library  and some user-space utilities are provided to allow
   access to the facility.  See keyctl(1),  keyctl(3),  and  keyu‐
   tils(7) for more information.

   Keys
   A key has the following attributes:

   Serial number (ID)
  This  is  a  unique  integer  handle  by  which a key is
  referred to in system call arguments.  The serial number
  is  sometimes synonymously referred as the key ID.  Pro‐
  grammatically, key serial numbers are represented  using
  the type key_serial_t.

   Type   A  key's  type  defines what sort of data can be held in
  the key, how the proposed content of  the  key  will  be
  parsed, and how the payload will be used.

  There  are  a number of general purpose types available,
  plus some specialist types defined by specific drivers.

   Description (name)
  The key description is a printable string that  is  used
  as  the search term for the key (in conjunction with the
  key type) as well as a display name.   During  searches,
  the  description  may  be  partially  matched or exactly
  matched.

   Payload (data)
  The payload is the actual content of  a  key.   This  is
  usually  set  when  a key is created, but it is possible
  for the kernel to upcall to user  space  to  finish  the
  instantiation  of a key if that key wasn't already known
  to the kernel when it was requested.   (Details  can  be
  found in request_key(2).)

  A  key's payload can be read and updated if the key type
  supports it and if suitable permission is granted to the
  caller.

   Access rights
  Much  as  files  do,  each key has an owning user ID, an
  owning group ID, and a security label.  They also have a
  set  of  permissions,  though  there are more than for a
  normal UNIX file, and there is  an  additional  category
  beyond the usual user, group, and other (see below).

  Note that keys are quota controlled since they represent
  unswappable kernel memory and the owning user ID  speci‐
  fies whose quota is to be debited.

   Expiration time
  Each  key  can  have  an expiration time set.  When that
  time is reached, the key is marked as being expired  and
  accesses  to  it fail with EKEYEXPIRED.  If not deleted,
  updated, or  replaced,  after  a  set  amount  of  time,
  expired  keys  are  automatically removed along with all
  links to them, and attempts to access the key will  fail
  with the error ENOKEY.

   Reference count
  Each  key has a reference count.  Keys are referenced by
  keyrings, by currently active users, and by a  process's
  credentials.  When the reference count reaches zero, the
  key is scheduled for garbage collection.

   Key types
   The facility provides several basic types of key:

   "user" This is a general purpose key type.   The  key  is  kept
  entirely  within kernel memory.  The payload may be read
  and updated by user-space applications.

  The payload for keys of this type is a blob of arbitrary
  data of up to 32,767 bytes.

  The  description  may  be any valid string, though it is
  preferred that it start with  a  colon-delimited  prefix
  representing the service to which the key is of interest
  (for instance "afs:mykey").

   "keyring"
  Keyrings are special keys whose payload  consists  of  a
  set  of  links to other keys (including other keyrings),
  analogous to a directory holding links  to  files.   The

Revised keyrings(7) man page for review

[Michael Kerrisk]

Hi David,

As part of the process of adopting the *.7 pages from
keyutils into man-pages, I've made some significant
extensions to the keyrings(7) page. Among the more notable 
changes:

* Expanded the detail in "Key types"
* Addition of a section on the various /proc files
* Various other minor reworkings elsewhere in the text

Would you would be willing to review the new page, please?
(The page source file is attached, in case you want to
see all the formatting.)

Cheers,

Michael




NAME
   keyrings - in-kernel key management and retention facility

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

   System call interfaces are provided so that user-space programs
   can manage those objects and also use the  facility  for  their
   own purposes.

   A  library  and some user-space utilities are provided to allow
   access to the facility.  See keyctl(1),  keyctl(3),  and  keyu‐
   tils(7) for more information.

   Keys
   A key has the following attributes:

   Serial number (ID)
  This  is  a  unique  integer  handle  by  which a key is
  referred to in system call arguments.  The serial number
  is  sometimes synonymously referred as the key ID.  Pro‐
  grammatically, key serial numbers are represented  using
  the type key_serial_t.

   Type   A  key's  type  defines what sort of data can be held in
  the key, how the proposed content of  the  key  will  be
  parsed, and how the payload will be used.

  There  are  a number of general purpose types available,
  plus some specialist types defined by specific drivers.

   Description (name)
  The key description is a printable string that  is  used
  as  the search term for the key (in conjunction with the
  key type) as well as a display name.   During  searches,
  the  description  may  be  partially  matched or exactly
  matched.

   Payload (data)
  The payload is the actual content of  a  key.   This  is
  usually  set  when  a key is created, but it is possible
  for the kernel to upcall to user  space  to  finish  the
  instantiation  of a key if that key wasn't already known
  to the kernel when it was requested.   (Details  can  be
  found in request_key(2).)

  A  key's payload can be read and updated if the key type
  supports it and if suitable permission is granted to the
  caller.

   Access rights
  Much  as  files  do,  each key has an owning user ID, an
  owning group ID, and a security label.  They also have a
  set  of  permissions,  though  there are more than for a
  normal UNIX file, and there is  an  additional  category
  beyond the usual user, group, and other (see below).

  Note that keys are quota controlled since they represent
  unswappable kernel memory and the owning user ID  speci‐
  fies whose quota is to be debited.

   Expiration time
  Each  key  can  have  an expiration time set.  When that
  time is reached, the key is marked as being expired  and
  accesses  to  it fail with EKEYEXPIRED.  If not deleted,
  updated, or  replaced,  after  a  set  amount  of  time,
  expired  keys  are  automatically removed along with all
  links to them, and attempts to access the key will  fail
  with the error ENOKEY.

   Reference count
  Each  key has a reference count.  Keys are referenced by
  keyrings, by currently active users, and by a  process's
  credentials.  When the reference count reaches zero, the
  key is scheduled for garbage collection.

   Key types
   The facility provides several basic types of key:

   "user" This is a general purpose key type.   The  key  is  kept
  entirely  within kernel memory.  The payload may be read
  and updated by user-space applications.

  The payload for keys of this type is a blob of arbitrary
  data of up to 32,767 bytes.

  The  description  may  be any valid string, though it is
  preferred that it start with  a  colon-delimited  prefix
  representing the service to which the key is of interest
  (for instance "afs:mykey").

   "keyring"
  Keyrings are special keys whose payload  consists  of  a
  set  of  links to other keys (including other keyrings),
  analogous to a directory holding links  to  files.   The