Re: Revised keyrings(7) man page for review
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
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)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) 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
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
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
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
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)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
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
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) 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
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
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
Hi David, On 12/13/2016 12:35 PM, David Howells wrote: > Michael Kerriskwrote: > >>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
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 Kerriskwrote: >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 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
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
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
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
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