Revised add_key(2) man page for review

[Michael Kerrisk (man-pages)]

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: add_key.2
Description: Unix manual page