Revised add_key(2) man page for review

Revised add_key(2) man page for review

[Michael Kerrisk (man-pages)]

[-- Attachment #1: Type: text/plain, Size: 7488 bytes --]

Hi David (and anyone else with an interest to review)

Following on from the request_key(2) page that I already posted,
I've pasted the current draft of the add_key(2) below. The 
changes to this page are less wide-ranging than for request_key(2),
but you may also have suggestions for further changes to tha page.

Could you take a look please? (The page source file is attached,
in case you want to see all the formatting.)

Thanks,

Michael

====

NAME
       add_key - add a key to the kernel's key management facility

SYNOPSIS
       #include <sys/types.h>
       #include <keyutils.h>

       key_serial_t add_key(const char *type, const char *description,
                            const void *payload, size_t plen,
                            key_serial_t keyring);

       No glibc wrapper is provided for this system call; see NOTES.

DESCRIPTION
       add_key()  creates  or  updates  a  key  of  the given type and
       description, instantiates it with the payload of  length  plen,
       attaches  it  to  the  nominated  keyring, and return the key's
       serial number.

       The key type may reject the data if it is in the  wrong  format
       or is in some other way invalid.

       If  the destination keyring already contains a key that matches
       the specified type and description, then, if the key type  sup‐
       ports  it, that key will be updated rather than a new key being
       created; if not, a new key (with a different ID) will  be  cre‐
       ated  and  it will displace the link to the extant key from the
       keyring.

       The destination keyring serial number may be that  of  a  valid
       keyring for which the caller has write permission, or it may be
       one of the following special keyring IDs:

       KEY_SPEC_THREAD_KEYRING
              This  specifies  the  caller's  thread-specific  keyring
              (thread-keyring(7)).

       KEY_SPEC_PROCESS_KEYRING
              This specifies  the  caller's  process-specific  keyring
              (process-keyring(7)).

       KEY_SPEC_SESSION_KEYRING
              This  specifies  the  caller's  session-specific keyring
              (session-keyring(7)).

       KEY_SPEC_USER_KEYRING
              This specifies the caller's UID-specific keyring  (user-
              keyring(7)).

       KEY_SPEC_USER_SESSION_KEYRING
              This  specifies  the caller's UID-session keyring (user-
              session-keyring(7)).

   Key types
       The key type is a string that specifies the key's type.  Inter‐
       nally, the kernel defines a number of key types that are avail‐
       able in the core key management code.  Among the types that are
       available  for  user-space use and can be specified as the type
       argument to add_key() are the following:

       "user" This is a general purpose key type whose payload may  be
              read and updated by user-space applications.  The key is
              kept entirely within kernel  memory.   The  payload  for
              keys  of  this type is a blob of arbitrary data of up to
              32,767 bytes.

       "keyring"
              Keyrings are special key types that may contain links to
              sequences  of other keys of any type.  If this interface
              is used to create a keyring, then a NULL payload  should
              be specified, and plen should be zero.

       "logon" (since Linux 3.3)
              This  key type is essentially the same as "user", but it
              does not provide reading.  This is suitable for  storing
              payloads  that  you do not want to be readable from user
              space.

              This key type vets the description to ensure that it  is
              qualified  by  a "service" prefix, by checking to ensure
              that the description contains a ':' that is preceded  by
              other characters.

       "big_key" (since Linux 3.13)
              This  key type is similar to "user", but may hold a pay‐
              load of up to 1 MiB.  If the key payload is large,  then
              it  may  be stored in swap space rather than kernel mem‐
              ory.

       For further details on these key types, see keyrings(7).

RETURN VALUE
       On success, add_key() returns the serial number of the  key  it
       created  or updated.  On error, -1 is returned and errno is set
       to indicate the cause of the error.

ERRORS
       EACCES The keyring wasn't available  for  modification  by  the
              user.

       EDQUOT The  key quota for this user would be exceeded by creat‐
              ing this key or linking it to the keyring.

       EINVAL The size of the string (including the  terminating  null
              byte)  specified  in  type  or  description exceeded the
              limit (32 bytes and 4096 bytes respectively).

       EINVAL The payload data was invalid.

       EINVAL type was "logon" and the description was  not  qualified
              with a prefix string of the form "service:".

       EKEYEXPIRED
              The keyring has expired.

       EKEYREVOKED
              The keyring has been revoked.

       ENOKEY The keyring doesn't exist.

       ENOMEM Insufficient memory to create a key.

VERSIONS
       This system call first appeared in Linux 2.6.10.

CONFORMING TO
       This system call is a nonstandard Linux extension.

NOTES
       No  wrapper for this system call is provided in glibc.  A wrap‐
       per is provided in the libkeyutils package.  When employing the
       wrapper in that library, link with -lkeyutils.

EXAMPLE
       The program below creates a key with the type, description, and
       payload specified in its command-line arguments, and links that
       key  into  the  session  keyring.   The following shell session
       demonstrates the use of the program:

           $ ./a.out user mykey "Some payload"
           Key ID is 64a4dca
           $ grep '64a4dca' /proc/keys
           064a4dca I--Q---    1 perm 3f010000  1000  1000 user    mykey: 12

   Program source

       #include <sys/types.h>
       #include <keyutils.h>
       #include <stdio.h>
       #include <stdlib.h>
       #include <string.h>

       #define errExit(msg)    do { perror(msg); exit(EXIT_FAILURE); \
                               } while (0)

       int
       main(int argc, char *argv[])
       {
           key_serial_t key;

           if (argc != 4) {
               fprintf(stderr, "Usage: %s type description payload\n",
                       argv[0]);
               exit(EXIT_FAILURE);
           }

           key = add_key(argv[1], argv[2], argv[3], strlen(argv[3]),
                       KEY_SPEC_SESSION_KEYRING);
           if (key == -1)
               errExit("add_key");

           printf("Key ID is %lx\n", (long) key);

           exit(EXIT_SUCCESS);
       }

SEE ALSO
       keyctl(1), keyctl(2), request_key(2), keyctl(3), keyutils(7),
       keyrings(7), persistent-keyring(7), process-keyring(7),
       session-keyring(7), thread-keyring(7), user-keyring(7),
       user-session-keyring(7)

       The kernel source files Documentation/security/keys.txt and
       Documentation/security/keys-request-key.txt.



Linux                         2016-07-17                    ADD_KEY(2)

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

[-- Attachment #2: add_key.2 --]
[-- Type: application/x-troff-man, Size: 6841 bytes --]

[PATCH 0/5] Re: Revised add_key(2) man page for review

[Eugene Syromyatnikov]

Hello.

The possible changes to add_key.2 are provided in the following patches,
hope it helps reviewing and applying them on one-by-one basis.

Eugene Syromyatnikov (5):
  add_key.2: tfix
  add_key.2: wording change regarding the reasons of call faliure
  add_key.2: change wording regarding storing of big_key payload
  add_key.2: add information regarding EFAULT
  add_key.2: add information regarding EPERM

 man2/add_key.2 | 29 ++++++++++++++++++++++++-----
 1 file changed, 24 insertions(+), 5 deletions(-)

-- 
2.10.2

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 1/5] add_key.2: tfix

[Eugene Syromyatnikov]

---
 man2/add_key.2 | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/man2/add_key.2 b/man2/add_key.2
index 0f4d109..1dfbd7d 100644
--- a/man2/add_key.2
+++ b/man2/add_key.2
@@ -35,7 +35,7 @@ of length
 .IR plen ,
 attaches it to the nominated
 .IR keyring ,
-and return the key's serial number.
+and returns the key's serial number.
 .P
 The key type may reject the data if it is in the wrong format or
 is in some other way invalid.
-- 
2.10.2

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 2/5] add_key.2: wording change regarding the reasons of call faliure

[Eugene Syromyatnikov]

---
 man2/add_key.2 | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/man2/add_key.2 b/man2/add_key.2
index 1dfbd7d..b693927 100644
--- a/man2/add_key.2
+++ b/man2/add_key.2
@@ -37,8 +37,8 @@ attaches it to the nominated
 .IR keyring ,
 and returns the key's serial number.
 .P
-The key type may reject the data if it is in the wrong format or
-is in some other way invalid.
+The key may be rejected if the provided data is in the wrong format or
+it is invalid in some other way.
 .P
 If the destination
 .I keyring
-- 
2.10.2

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 3/5] add_key.2: change wording regarding storing of big_key payload

[Eugene Syromyatnikov]

---
 man2/add_key.2 | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/man2/add_key.2 b/man2/add_key.2
index b693927..78b1b99 100644
--- a/man2/add_key.2
+++ b/man2/add_key.2
@@ -126,8 +126,9 @@ contains a ':' that is preceded by other characters.
 This key type is similar to
 .IR """user""" ,
 but may hold a payload of up to 1 MiB.
-If the key payload is large,
-then it may be stored in swap space rather than kernel memory.
+If the key payload is large enough,
+then it may be stored in tmpfs (which can be swapped out) rather than kernel
+memory.
 .PP
 For further details on these key types, see
 .BR keyrings (7).
-- 
2.10.2

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 4/5] add_key.2: add information regarding EFAULT

[Eugene Syromyatnikov]

---
 man2/add_key.2 | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/man2/add_key.2 b/man2/add_key.2
index 78b1b99..082a2b8 100644
--- a/man2/add_key.2
+++ b/man2/add_key.2
@@ -148,6 +148,11 @@ The keyring wasn't available for modification by the user.
 The key quota for this user would be exceeded by creating this key or linking
 it to the keyring.
 .TP
+.B EFAULT
+(Part of)
+.IR type ", " description " or " payload
+points outside process' accessible address space.
+.TP
 .B EINVAL
 The size of the string (including the terminating null byte) specified in
 .I type
-- 
2.10.2

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 5/5] add_key.2: add information regarding EPERM

[Eugene Syromyatnikov]

---
 man2/add_key.2 | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/man2/add_key.2 b/man2/add_key.2
index 082a2b8..241eb92 100644
--- a/man2/add_key.2
+++ b/man2/add_key.2
@@ -183,6 +183,19 @@ The keyring doesn't exist.
 .TP
 .B ENOMEM
 Insufficient memory to create a key.
+.TP
+.B EPERM
+The
+.I type
+started from dot.
+.TP
+.B EPERM
+.I type
+was
+.I """keyring"""
+and the
+.I description
+started from dot.
 .SH VERSIONS
 This system call first appeared in Linux 2.6.10.
 .SH CONFORMING TO
-- 
2.10.2

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 5/5] add_key.2: add information regarding EPERM

[Michael Kerrisk (man-pages)]

Hello Eugene

On 11/15/2016 09:44 AM, Eugene Syromyatnikov wrote:
> ---
>  man2/add_key.2 | 13 +++++++++++++
>  1 file changed, 13 insertions(+)
> 
> diff --git a/man2/add_key.2 b/man2/add_key.2
> index 082a2b8..241eb92 100644
> --- a/man2/add_key.2
> +++ b/man2/add_key.2
> @@ -183,6 +183,19 @@ The keyring doesn't exist.
>  .TP
>  .B ENOMEM
>  Insufficient memory to create a key.
> +.TP
> +.B EPERM
> +The
> +.I type
> +started from dot.

Oh -- I was unaware of this! What are key types that start with "." about,
do you know?

Cheers,

Michael


> +.TP
> +.B EPERM
> +.I type
> +was
> +.I """keyring"""
> +and the
> +.I description
> +started from dot.
>  .SH VERSIONS
>  This system call first appeared in Linux 2.6.10.
>  .SH CONFORMING TO
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 5/5] add_key.2: add information regarding EPERM

[Eugene Syromyatnikov]

On Tue, Nov 15, 2016 at 9:00 PM, Michael Kerrisk (man-pages)
<mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:
> Hello Eugene
>
> On 11/15/2016 09:44 AM, Eugene Syromyatnikov wrote:
>> ---
>>  man2/add_key.2 | 13 +++++++++++++
>>  1 file changed, 13 insertions(+)
>>
>> diff --git a/man2/add_key.2 b/man2/add_key.2
>> index 082a2b8..241eb92 100644
>> --- a/man2/add_key.2
>> +++ b/man2/add_key.2
>> @@ -183,6 +183,19 @@ The keyring doesn't exist.
>>  .TP
>>  .B ENOMEM
>>  Insufficient memory to create a key.
>> +.TP
>> +.B EPERM
>> +The
>> +.I type
>> +started from dot.
>
> Oh -- I was unaware of this! What are key types that start with "." about,
> do you know?
I can't recall any clear indication that this is for internal purposes
(and can't find any mention of this now), but there is explicit check
in keyctl.c:key_get_type_from_user and it is used for
".request_key_auth" key type. Judging by commit messages for 54e2c2c1,
1260f801 and 3e30148c, it is indeed reserved for internal purposes and
has been reserved as part of the introduction of the aforementioned
".request_key_auth" key type.

> Cheers,
>
> Michael
>
>
>> +.TP
>> +.B EPERM
>> +.I type
>> +was
>> +.I """keyring"""
>> +and the
>> +.I description
>> +started from dot.
>>  .SH VERSIONS
>>  This system call first appeared in Linux 2.6.10.
>>  .SH CONFORMING TO
>>
>
>
> --
> Michael Kerrisk
> Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
> Linux/UNIX System Programming Training: http://man7.org/training/



-- 
Eugene "eSyr" Syromyatnikov
mailto:evgSyr-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org
xmpp:eSyr@jabber.{ru|org}
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 5/5] add_key.2: add information regarding EPERM

[Eugene Syromyatnikov]

On Tue, Nov 15, 2016 at 9:17 PM, Eugene Syromyatnikov <evgsyr-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:
> I can't recall any clear indication that this is for internal purposes
> (and can't find any mention of this now),
In Documentation/security/keys*, i mean.

-- 
Eugene "eSyr" Syromyatnikov
mailto:evgSyr-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org
xmpp:eSyr@jabber.{ru|org}
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 1/5] add_key.2: tfix

[Michael Kerrisk (man-pages)]

On 11/15/2016 09:43 AM, Eugene Syromyatnikov wrote:
> ---
>  man2/add_key.2 | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)

Hi Eugene,

As it happens, I'd found and fixed this already.

Cheers,

Michael

> diff --git a/man2/add_key.2 b/man2/add_key.2
> index 0f4d109..1dfbd7d 100644
> --- a/man2/add_key.2
> +++ b/man2/add_key.2
> @@ -35,7 +35,7 @@ of length
>  .IR plen ,
>  attaches it to the nominated
>  .IR keyring ,
> -and return the key's serial number.
> +and returns the key's serial number.
>  .P
>  The key type may reject the data if it is in the wrong format or
>  is in some other way invalid.
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 2/5] add_key.2: wording change regarding the reasons of call faliure

[Michael Kerrisk (man-pages)]

On 11/15/2016 09:43 AM, Eugene Syromyatnikov wrote:
> ---
>  man2/add_key.2 | 4 ++--
>  1 file changed, 2 insertions(+), 2 deletions(-)

Thanks, Eugene. Applied.

Cheers,

Michael


> diff --git a/man2/add_key.2 b/man2/add_key.2
> index 1dfbd7d..b693927 100644
> --- a/man2/add_key.2
> +++ b/man2/add_key.2
> @@ -37,8 +37,8 @@ attaches it to the nominated
>  .IR keyring ,
>  and returns the key's serial number.
>  .P
> -The key type may reject the data if it is in the wrong format or
> -is in some other way invalid.
> +The key may be rejected if the provided data is in the wrong format or
> +it is invalid in some other way.
>  .P
>  If the destination
>  .I keyring
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 3/5] add_key.2: change wording regarding storing of big_key payload

[Michael Kerrisk (man-pages)]

On 11/15/2016 09:44 AM, Eugene Syromyatnikov wrote:
> ---
>  man2/add_key.2 | 5 +++--
>  1 file changed, 3 insertions(+), 2 deletions(-)

Hi Eugene,

Thanks. That's a rather better way of describing things. Patch applied.

Cheers,

Michael


> diff --git a/man2/add_key.2 b/man2/add_key.2
> index b693927..78b1b99 100644
> --- a/man2/add_key.2
> +++ b/man2/add_key.2
> @@ -126,8 +126,9 @@ contains a ':' that is preceded by other characters.
>  This key type is similar to
>  .IR """user""" ,
>  but may hold a payload of up to 1 MiB.
> -If the key payload is large,
> -then it may be stored in swap space rather than kernel memory.
> +If the key payload is large enough,
> +then it may be stored in tmpfs (which can be swapped out) rather than kernel
> +memory.
>  .PP
>  For further details on these key types, see
>  .BR keyrings (7).
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 4/5] add_key.2: add information regarding EFAULT

[Michael Kerrisk (man-pages)]

On 11/15/2016 09:44 AM, Eugene Syromyatnikov wrote:
> ---
>  man2/add_key.2 | 5 +++++
>  1 file changed, 5 insertions(+)

Thanks, Eugene. Applied.

Cheers,

Michael


> diff --git a/man2/add_key.2 b/man2/add_key.2
> index 78b1b99..082a2b8 100644
> --- a/man2/add_key.2
> +++ b/man2/add_key.2
> @@ -148,6 +148,11 @@ The keyring wasn't available for modification by the user.
>  The key quota for this user would be exceeded by creating this key or linking
>  it to the keyring.
>  .TP
> +.B EFAULT
> +(Part of)
> +.IR type ", " description " or " payload
> +points outside process' accessible address space.
> +.TP
>  .B EINVAL
>  The size of the string (including the terminating null byte) specified in
>  .I type
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 5/5] add_key.2: add information regarding EPERM

[Michael Kerrisk (man-pages)]

Hi Eugene,

On 11/15/2016 10:17 PM, Eugene Syromyatnikov wrote:
> On Tue, Nov 15, 2016 at 9:00 PM, Michael Kerrisk (man-pages)
> <mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:
>> Hello Eugene
>>
>> On 11/15/2016 09:44 AM, Eugene Syromyatnikov wrote:
>>> ---
>>>  man2/add_key.2 | 13 +++++++++++++
>>>  1 file changed, 13 insertions(+)
>>>
>>> diff --git a/man2/add_key.2 b/man2/add_key.2
>>> index 082a2b8..241eb92 100644
>>> --- a/man2/add_key.2
>>> +++ b/man2/add_key.2
>>> @@ -183,6 +183,19 @@ The keyring doesn't exist.
>>>  .TP
>>>  .B ENOMEM
>>>  Insufficient memory to create a key.
>>> +.TP
>>> +.B EPERM
>>> +The
>>> +.I type
>>> +started from dot.
>>
>> Oh -- I was unaware of this! What are key types that start with "." about,
>> do you know?
> I can't recall any clear indication that this is for internal purposes
> (and can't find any mention of this now), but there is explicit check
> in keyctl.c:key_get_type_from_user and it is used for
> ".request_key_auth" key type. Judging by commit messages for 54e2c2c1,
> 1260f801 and 3e30148c, it is indeed reserved for internal purposes and
> has been reserved as part of the introduction of the aforementioned
> ".request_key_auth" key type.

Ahh yes. That makes sense. Patch applied. And I'll add a few more words
about the types starting with "." being reserved.

Cheers,

Michael

>>> +.TP
>>> +.B EPERM
>>> +.I type
>>> +was
>>> +.I """keyring"""
>>> +and the
>>> +.I description
>>> +started from dot.
>>>  .SH VERSIONS
>>>  This system call first appeared in Linux 2.6.10.
>>>  .SH CONFORMING TO
>>>
>>
>>
>> --
>> Michael Kerrisk
>> Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
>> Linux/UNIX System Programming Training: http://man7.org/training/
> 
> 
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: Revised add_key(2) man page for review

[David Howells]

Michael Kerrisk (man-pages) <mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:

>        The destination keyring serial number may be that  of  a  valid
>        keyring for which the caller has write permission, or it may be
>        one of the following special keyring IDs:

No comma before "or".

>        "user" This is a general purpose key type whose payload may  be
> ...
>       "keyring"

It probably makes sense to put keyring either first or last.

>        "keyring"
>               Keyrings are special key types that may contain links to
>               sequences  of other keys of any type.  If this interface
>               is used to create a keyring, then a NULL payload  should
>               be specified, and plen should be zero.

I think "then payload should be NULL and plen should be zero." sounds better.

>        "logon" (since Linux 3.3)
>               This  key type is essentially the same as "user", but it
>               does not provide reading.

"permit the key to be read" rather than "provide reading", I think.

>        "big_key" (since Linux 3.13)
>               This  key type is similar to "user", but may hold a pay‐
>               load of up to 1 MiB.  If the key payload is large,  then
>               it  may  be stored in swap space rather than kernel mem‐
>               ory.

"stored encrypted in swap space".

>            printf("Key ID is %lx\n", (long) key);

key_serial_t is an int.  It doesn't really need casting to long.

David
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: Revised add_key(2) man page for review

[Michael Kerrisk (man-pages)]

Hello David

Thanks for the review!

On 12/13/2016 11:58 AM, David Howells wrote:
> Michael Kerrisk (man-pages) <mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:
> 
>>        The destination keyring serial number may be that  of  a  valid
>>        keyring for which the caller has write permission, or it may be
>>        one of the following special keyring IDs:
> 
> No comma before "or".

Actually, I think its okay with the comma. But I decided anyway to 
reword this into two sentences.

>>        "user" This is a general purpose key type whose payload may  be
>> ...
>>       "keyring"
> 
> It probably makes sense to put keyring either first or last.

Done.

> 
>>        "keyring"
>>               Keyrings are special key types that may contain links to
>>               sequences  of other keys of any type.  If this interface
>>               is used to create a keyring, then a NULL payload  should
>>               be specified, and plen should be zero.
> 
> I think "then payload should be NULL and plen should be zero." sounds better.

Agreed. Fixed.

>>        "logon" (since Linux 3.3)
>>               This  key type is essentially the same as "user", but it
>>               does not provide reading.
> 
> "permit the key to be read" rather than "provide reading", I think.

Fixed.

>>        "big_key" (since Linux 3.13)
>>               This  key type is similar to "user", but may hold a pay‐
>>               load of up to 1 MiB.  If the key payload is large,  then
>>               it  may  be stored in swap space rather than kernel mem‐
>>               ory.
> 
> "stored encrypted in swap space".

Fixed.

>>            printf("Key ID is %lx\n", (long) key);
> 
> key_serial_t is an int.  It doesn't really need casting to long.

Well, this is a common way of dealing with opaque integer system data
types, so that one does not encode a representational dependency into
printf(). (Relies on the assumption that the underlying type is no
bigger than long. The alternative these days is a cast to (intmax_t) 
plus %jd.) [So, for the moment, I'll leave the text as is.]

Cheers,

Micael

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: Revised add_key(2) man page for review

[David Howells]

Michael Kerrisk (man-pages) <mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:

> > "stored encrypted in swap space".
> 
> Fixed.

Since 4.8, that is.

David
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: Revised add_key(2) man page for review

[Michael Kerrisk (man-pages)]

On 13 December 2016 at 12:37, David Howells <dhowells@redhat.com> wrote:
> Michael Kerrisk (man-pages) <mtk.manpages@gmail.com> wrote:
>
>> > "stored encrypted in swap space".
>>
>> Fixed.
>
> Since 4.8, that is.

Which commit was that? I could not find it?


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

Re: Revised add_key(2) man page for review

[Eugene Syromyatnikov]

On Tue, Dec 13, 2016 at 11:49 AM, Michael Kerrisk (man-pages)
<mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:
> On 13 December 2016 at 12:37, David Howells <dhowells-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org> wrote:
>> Michael Kerrisk (man-pages) <mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:
>>
>>> > "stored encrypted in swap space".
>>>
>>> Fixed.
>>
>> Since 4.8, that is.
>
> Which commit was that? I could not find it?
13100a72f40f5748a04017e0ab3df4cf27c809ef, v4.7-rc1~124^2~2^2~2^2~1

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



-- 
Eugene Syromyatnikov
mailto:evgsyr-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org
xmpp:esyr@jabber.{ru|org}
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: Revised add_key(2) man page for review

[Michael Kerrisk (man-pages)]

Hi Eugene,

On 13 December 2016 at 13:06, Eugene Syromyatnikov <evgsyr-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:
> On Tue, Dec 13, 2016 at 11:49 AM, Michael Kerrisk (man-pages)
> <mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:
>> On 13 December 2016 at 12:37, David Howells <dhowells-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org> wrote:
>>> Michael Kerrisk (man-pages) <mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:
>>>
>>>> > "stored encrypted in swap space".
>>>>
>>>> Fixed.
>>>
>>> Since 4.8, that is.
>>
>> Which commit was that? I could not find it?
> 13100a72f40f5748a04017e0ab3df4cf27c809ef, v4.7-rc1~124^2~2^2~2^2~1

Thanks! See my reply  (in a moment) on the keyrings(7) page.

Cheers,

Michael

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html