Linux-2.6.12-rc2v2.6.12-rc2

Initial git repository build. I'm not bothering with the full history,
even though we have it. We can create a separate "historical" git
archive of that later if we want to, and in the meantime it's about
3.2GB when imported into git - space that would just make the early
git days unnecessarily complicated, when we don't have a lot of good
infrastructure for it.

Let it rip!

1 files changed, 869 insertions, 0 deletions

diff --git a/Documentation/keys.txt b/Documentation/keys.txt
new file mode 100644
index 000000000000..36d80aeeaf28
--- /dev/null
+++ b/Documentation/keys.txt
@@ -0,0 +1,869 @@
+                         ============================
+                         KERNEL KEY RETENTION SERVICE
+                         ============================
+
+This service allows cryptographic keys, authentication tokens, cross-domain
+user mappings, and similar to be cached in the kernel for the use of
+filesystems other kernel services.
+
+Keyrings are permitted; these are a special type of key that can hold links to
+other keys. Processes each have three standard keyring subscriptions that a
+kernel service can search for relevant keys.
+
+The key service can be configured on by enabling:
+
+        "Security options"/"Enable access key retention support" (CONFIG_KEYS)
+
+This document has the following sections:
+
+        - Key overview
+        - Key service overview
+        - Key access permissions
+        - New procfs files
+        - Userspace system call interface
+        - Kernel services
+        - Defining a key type
+        - Request-key callback service
+        - Key access filesystem
+
+
+============
+KEY OVERVIEW
+============
+
+In this context, keys represent units of cryptographic data, authentication
+tokens, keyrings, etc.. These are represented in the kernel by struct key.
+
+Each key has a number of attributes:
+
+        - A serial number.
+        - A type.
+        - A description (for matching a key in a search).
+        - Access control information.
+        - An expiry time.
+        - A payload.
+        - State.
+
+
+ (*) Each key is issued a serial number of type key_serial_t that is unique
+     for the lifetime of that key. All serial numbers are positive non-zero
+     32-bit integers.
+
+     Userspace programs can use a key's serial numbers as a way to gain access
+     to it, subject to permission checking.
+
+ (*) Each key is of a defined "type". Types must be registered inside the
+     kernel by a kernel service (such as a filesystem) before keys of that
+     type can be added or used. Userspace programs cannot define new types
+     directly.
+
+     Key types are represented in the kernel by struct key_type. This defines
+     a number of operations that can be performed on a key of that type.
+
+     Should a type be removed from the system, all the keys of that type will
+     be invalidated.
+
+ (*) Each key has a description. This should be a printable string. The key
+     type provides an operation to perform a match between the description on
+     a key and a criterion string.
+
+ (*) Each key has an owner user ID, a group ID and a permissions mask. These
+     are used to control what a process may do to a key from userspace, and
+     whether a kernel service will be able to find the key.
+
+ (*) Each key can be set to expire at a specific time by the key type's
+     instantiation function. Keys can also be immortal.
+
+ (*) Each key can have a payload. This is a quantity of data that represent
+     the actual "key". In the case of a keyring, this is a list of keys to
+     which the keyring links; in the case of a user-defined key, it's an
+     arbitrary blob of data.
+
+     Having a payload is not required; and the payload can, in fact, just be a
+     value stored in the struct key itself.
+
+     When a key is instantiated, the key type's instantiation function is
+     called with a blob of data, and that then creates the key's payload in
+     some way.
+
+     Similarly, when userspace wants to read back the contents of the key, if
+     permitted, another key type operation will be called to convert the key's
+     attached payload back into a blob of data.
+
+ (*) Each key can be in one of a number of basic states:
+
+     (*) Uninstantiated. The key exists, but does not have any data
+         attached. Keys being requested from userspace will be in this state.
+
+     (*) Instantiated. This is the normal state. The key is fully formed, and
+         has data attached.
+
+     (*) Negative. This is a relatively short-lived state. The key acts as a
+         note saying that a previous call out to userspace failed, and acts as
+         a throttle on key lookups. A negative key can be updated to a normal
+         state.
+
+     (*) Expired. Keys can have lifetimes set. If their lifetime is exceeded,
+         they traverse to this state. An expired key can be updated back to a
+         normal state.
+
+     (*) Revoked. A key is put in this state by userspace action. It can't be
+         found or operated upon (apart from by unlinking it).
+
+     (*) Dead. The key's type was unregistered, and so the key is now useless.
+
+
+====================
+KEY SERVICE OVERVIEW
+====================
+
+The key service provides a number of features besides keys:
+
+ (*) The key service defines two special key types:
+
+     (+) "keyring"
+
+         Keyrings are special keys that contain a list of other keys. Keyring
+         lists can be modified using various system calls. Keyrings should not
+         be given a payload when created.
+
+     (+) "user"
+
+         A key of this type has a description and a payload that are arbitrary
+         blobs of data. These can be created, updated and read by userspace,
+         and aren't intended for use by kernel services.
+
+ (*) Each process subscribes to three keyrings: a thread-specific keyring, a
+     process-specific keyring, and a session-specific keyring.
+
+     The thread-specific keyring is discarded from the child when any sort of
+     clone, fork, vfork or execve occurs. A new keyring is created only when
+     required.
+
+     The process-specific keyring is replaced with an empty one in the child
+     on clone, fork, vfork unless CLONE_THREAD is supplied, in which case it
+     is shared. execve also discards the process's process keyring and creates
+     a new one.
+
+     The session-specific keyring is persistent across clone, fork, vfork and
+     execve, even when the latter executes a set-UID or set-GID binary. A
+     process can, however, replace its current session keyring with a new one
+     by using PR_JOIN_SESSION_KEYRING. It is permitted to request an anonymous
+     new one, or to attempt to create or join one of a specific name.
+
+     The ownership of the thread keyring changes when the real UID and GID of
+     the thread changes.
+
+ (*) Each user ID resident in the system holds two special keyrings: a user
+     specific keyring and a default user session keyring. The default session
+     keyring is initialised with a link to the user-specific keyring.
+
+     When a process changes its real UID, if it used to have no session key, it
+     will be subscribed to the default session key for the new UID.
+
+     If a process attempts to access its session key when it doesn't have one,
+     it will be subscribed to the default for its current UID.
+
+ (*) Each user has two quotas against which the keys they own are tracked. One
+     limits the total number of keys and keyrings, the other limits the total
+     amount of description and payload space that can be consumed.
+
+     The user can view information on this and other statistics through procfs
+     files.
+
+     Process-specific and thread-specific keyrings are not counted towards a
+     user's quota.
+
+     If a system call that modifies a key or keyring in some way would put the
+     user over quota, the operation is refused and error EDQUOT is returned.
+
+ (*) There's a system call interface by which userspace programs can create
+     and manipulate keys and keyrings.
+
+ (*) There's a kernel interface by which services can register types and
+     search for keys.
+
+ (*) There's a way for the a search done from the kernel to call back to
+     userspace to request a key that can't be found in a process's keyrings.
+
+ (*) An optional filesystem is available through which the key database can be
+     viewed and manipulated.
+
+
+======================
+KEY ACCESS PERMISSIONS
+======================
+
+Keys have an owner user ID, a group access ID, and a permissions mask. The
+mask has up to eight bits each for user, group and other access. Only five of
+each set of eight bits are defined. These permissions granted are:
+
+ (*) View
+
+     This permits a key or keyring's attributes to be viewed - including key
+     type and description.
+
+ (*) Read
+
+     This permits a key's payload to be viewed or a keyring's list of linked
+     keys.
+
+ (*) Write
+
+     This permits a key's payload to be instantiated or updated, or it allows
+     a link to be added to or removed from a keyring.
+
+ (*) Search
+
+     This permits keyrings to be searched and keys to be found. Searches can
+     only recurse into nested keyrings that have search permission set.
+
+ (*) Link
+
+     This permits a key or keyring to be linked to. To create a link from a
+     keyring to a key, a process must have Write permission on the keyring and
+     Link permission on the key.
+
+For changing the ownership, group ID or permissions mask, being the owner of
+the key or having the sysadmin capability is sufficient.
+
+
+================
+NEW PROCFS FILES
+================
+
+Two files have been added to procfs by which an administrator can find out
+about the status of the key service:
+
+ (*) /proc/keys
+
+     This lists all the keys on the system, giving information about their
+     type, description and permissions. The payload of the key is not
+     available this way:
+
+        SERIAL   FLAGS  USAGE EXPY PERM   UID   GID   TYPE      DESCRIPTION: SUMMARY
+        00000001 I-----    39 perm 1f0000     0     0 keyring   _uid_ses.0: 1/4
+        00000002 I-----     2 perm 1f0000     0     0 keyring   _uid.0: empty
+        00000007 I-----     1 perm 1f0000     0     0 keyring   _pid.1: empty
+        0000018d I-----     1 perm 1f0000     0     0 keyring   _pid.412: empty
+        000004d2 I--Q--     1 perm 1f0000    32    -1 keyring   _uid.32: 1/4
+        000004d3 I--Q--     3 perm 1f0000    32    -1 keyring   _uid_ses.32: empty
+        00000892 I--QU-     1 perm 1f0000     0     0 user      metal:copper: 0
+        00000893 I--Q-N     1  35s 1f0000     0     0 user      metal:silver: 0
+        00000894 I--Q--     1  10h 1f0000     0     0 user      metal:gold: 0
+
+     The flags are:
+
+        I       Instantiated
+        R       Revoked
+        D       Dead
+        Q       Contributes to user's quota
+        U       Under contruction by callback to userspace
+        N       Negative key
+
+     This file must be enabled at kernel configuration time as it allows anyone
+     to list the keys database.
+
+ (*) /proc/key-users
+
+     This file lists the tracking data for each user that has at least one key
+     on the system. Such data includes quota information and statistics:
+
+        [root@andromeda root]# cat /proc/key-users
+        0:     46 45/45 1/100 13/10000
+        29:     2 2/2 2/100 40/10000
+        32:     2 2/2 2/100 40/10000
+        38:     2 2/2 2/100 40/10000
+
+     The format of each line is
+        <UID>:                  User ID to which this applies
+        <usage>                 Structure refcount
+        <inst>/<keys>           Total number of keys and number instantiated
+        <keys>/<max>            Key count quota
+        <bytes>/<max>           Key size quota
+
+
+===============================
+USERSPACE SYSTEM CALL INTERFACE
+===============================
+
+Userspace can manipulate keys directly through three new syscalls: add_key,
+request_key and keyctl. The latter provides a number of functions for
+manipulating keys.
+
+When referring to a key directly, userspace programs should use the key's
+serial number (a positive 32-bit integer). However, there are some special
+values available for referring to special keys and keyrings that relate to the
+process making the call:
+
+        CONSTANT                        VALUE   KEY REFERENCED
+        ==============================  ======  ===========================
+        KEY_SPEC_THREAD_KEYRING         -1      thread-specific keyring
+        KEY_SPEC_PROCESS_KEYRING        -2      process-specific keyring
+        KEY_SPEC_SESSION_KEYRING        -3      session-specific keyring
+        KEY_SPEC_USER_KEYRING           -4      UID-specific keyring
+        KEY_SPEC_USER_SESSION_KEYRING   -5      UID-session keyring
+        KEY_SPEC_GROUP_KEYRING          -6      GID-specific keyring
+
+
+The main syscalls are:
+
+ (*) Create a new key of given type, description and payload and add it to the
+     nominated keyring:
+
+        key_serial_t add_key(const char *type, const char *desc,
+                             const void *payload, size_t plen,
+                             key_serial_t keyring);
+
+     If a key of the same type and description as that proposed already exists
+     in the keyring, this will try to update it with the given payload, or it
+     will return error EEXIST if that function is not supported by the key
+     type. The process must also have permission to write to the key to be
+     able to update it. The new key will have all user permissions granted and
+     no group or third party permissions.
+
+     Otherwise, this will attempt to create a new key of the specified type
+     and description, and to instantiate it with the supplied payload and
+     attach it to the keyring. In this case, an error will be generated if the
+     process does not have permission to write to the keyring.
+
+     The payload is optional, and the pointer can be NULL if not required by
+     the type. The payload is plen in size, and plen can be zero for an empty
+     payload.
+
+     A new keyring can be generated by setting type "keyring", the keyring
+     name as the description (or NULL) and setting the payload to NULL.
+
+     User defined keys can be created by specifying type "user". It is
+     recommended that a user defined key's description by prefixed with a type
+     ID and a colon, such as "krb5tgt:" for a Kerberos 5 ticket granting
+     ticket.
+
+     Any other type must have been registered with the kernel in advance by a
+     kernel service such as a filesystem.
+
+     The ID of the new or updated key is returned if successful.
+
+
+ (*) Search the process's keyrings for a key, potentially calling out to
+     userspace to create it.
+
+        key_serial_t request_key(const char *type, const char *description,
+                                 const char *callout_info,
+                                 key_serial_t dest_keyring);
+
+     This function searches all the process's keyrings in the order thread,
+     process, session for a matching key. This works very much like
+     KEYCTL_SEARCH, including the optional attachment of the discovered key to
+     a keyring.
+
+     If a key cannot be found, and if callout_info is not NULL, then
+     /sbin/request-key will be invoked in an attempt to obtain a key. The
+     callout_info string will be passed as an argument to the program.
+
+
+The keyctl syscall functions are:
+
+ (*) Map a special key ID to a real key ID for this process:
+
+        key_serial_t keyctl(KEYCTL_GET_KEYRING_ID, key_serial_t id,
+                            int create);
+
+     The special key specified by "id" is looked up (with the key being
+     created if necessary) and the ID of the key or keyring thus found is
+     returned if it exists.
+
+     If the key does not yet exist, the key will be created if "create" is
+     non-zero; and the error ENOKEY will be returned if "create" is zero.
+
+
+ (*) Replace the session keyring this process subscribes to with a new one:
+
+        key_serial_t keyctl(KEYCTL_JOIN_SESSION_KEYRING, const char *name);
+
+     If name is NULL, an anonymous keyring is created attached to the process
+     as its session keyring, displacing the old session keyring.
+
+     If name is not NULL, if a keyring of that name exists, the process
+     attempts to attach it as the session keyring, returning an error if that
+     is not permitted; otherwise a new keyring of that name is created and
+     attached as the session keyring.
+
+     To attach to a named keyring, the keyring must have search permission for
+     the process's ownership.
+
+     The ID of the new session keyring is returned if successful.
+
+
+ (*) Update the specified key:
+
+        long keyctl(KEYCTL_UPDATE, key_serial_t key, const void *payload,
+                    size_t plen);
+
+     This will try to update the specified key with the given payload, or it
+     will return error EOPNOTSUPP if that function is not supported by the key
+     type. The process must also have permission to write to the key to be
+     able to update it.
+
+     The payload is of length plen, and may be absent or empty as for
+     add_key().
+
+
+ (*) Revoke a key:
+
+        long keyctl(KEYCTL_REVOKE, key_serial_t key);
+
+     This makes a key unavailable for further operations. Further attempts to
+     use the key will be met with error EKEYREVOKED, and the key will no longer
+     be findable.
+
+
+ (*) Change the ownership of a key:
+
+        long keyctl(KEYCTL_CHOWN, key_serial_t key, uid_t uid, gid_t gid);
+
+     This function permits a key's owner and group ID to be changed. Either
+     one of uid or gid can be set to -1 to suppress that change.
+
+     Only the superuser can change a key's owner to something other than the
+     key's current owner. Similarly, only the superuser can change a key's
+     group ID to something other than the calling process's group ID or one of
+     its group list members.
+
+
+ (*) Change the permissions mask on a key:
+
+        long keyctl(KEYCTL_SETPERM, key_serial_t key, key_perm_t perm);
+
+     This function permits the owner of a key or the superuser to change the
+     permissions mask on a key.
+
+     Only bits the available bits are permitted; if any other bits are set,
+     error EINVAL will be returned.
+
+
+ (*) Describe a key:
+
+        long keyctl(KEYCTL_DESCRIBE, key_serial_t key, char *buffer,
+                    size_t buflen);
+
+     This function returns a summary of the key's attributes (but not its
+     payload data) as a string in the buffer provided.
+
+     Unless there's an error, it always returns the amount of data it could
+     produce, even if that's too big for the buffer, but it won't copy more
+     than requested to userspace. If the buffer pointer is NULL then no copy
+     will take place.
+
+     A process must have view permission on the key for this function to be
+     successful.
+
+     If successful, a string is placed in the buffer in the following format:
+
+        <type>;<uid>;<gid>;<perm>;<description>
+
+     Where type and description are strings, uid and gid are decimal, and perm
+     is hexadecimal. A NUL character is included at the end of the string if
+     the buffer is sufficiently big.
+
+     This can be parsed with
+
+        sscanf(buffer, "%[^;];%d;%d;%o;%s", type, &uid, &gid, &mode, desc);
+
+
+ (*) Clear out a keyring:
+
+        long keyctl(KEYCTL_CLEAR, key_serial_t keyring);
+
+     This function clears the list of keys attached to a keyring. The calling
+     process must have write permission on the keyring, and it must be a
+     keyring (or else error ENOTDIR will result).
+
+
+ (*) Link a key into a keyring:
+
+        long keyctl(KEYCTL_LINK, key_serial_t keyring, key_serial_t key);
+
+     This function creates a link from the keyring to the key. The process
+     must have write permission on the keyring and must have link permission
+     on the key.
+
+     Should the keyring not be a keyring, error ENOTDIR will result; and if
+     the keyring is full, error ENFILE will result.
+
+     The link procedure checks the nesting of the keyrings, returning ELOOP if
+     it appears to deep or EDEADLK if the link would introduce a cycle.
+
+
+ (*) Unlink a key or keyring from another keyring:
+
+        long keyctl(KEYCTL_UNLINK, key_serial_t keyring, key_serial_t key);
+
+     This function looks through the keyring for the first link to the
+     specified key, and removes it if found. Subsequent links to that key are
+     ignored. The process must have write permission on the keyring.
+
+     If the keyring is not a keyring, error ENOTDIR will result; and if the
+     key is not present, error ENOENT will be the result.
+
+
+ (*) Search a keyring tree for a key:
+
+        key_serial_t keyctl(KEYCTL_SEARCH, key_serial_t keyring,
+                            const char *type, const char *description,
+                            key_serial_t dest_keyring);
+
+     This searches the keyring tree headed by the specified keyring until a
+     key is found that matches the type and description criteria. Each keyring
+     is checked for keys before recursion into its children occurs.
+
+     The process must have search permission on the top level keyring, or else
+     error EACCES will result. Only keyrings that the process has search
+     permission on will be recursed into, and only keys and keyrings for which
+     a process has search permission can be matched. If the specified keyring
+     is not a keyring, ENOTDIR will result.
+
+     If the search succeeds, the function will attempt to link the found key
+     into the destination keyring if one is supplied (non-zero ID). All the
+     constraints applicable to KEYCTL_LINK apply in this case too.
+
+     Error ENOKEY, EKEYREVOKED or EKEYEXPIRED will be returned if the search
+     fails. On success, the resulting key ID will be returned.
+
+
+ (*) Read the payload data from a key:
+
+        key_serial_t keyctl(KEYCTL_READ, key_serial_t keyring, char *buffer,
+                            size_t buflen);
+
+     This function attempts to read the payload data from the specified key
+     into the buffer. The process must have read permission on the key to
+     succeed.
+
+     The returned data will be processed for presentation by the key type. For
+     instance, a keyring will return an array of key_serial_t entries
+     representing the IDs of all the keys to which it is subscribed. The user
+     defined key type will return its data as is. If a key type does not
+     implement this function, error EOPNOTSUPP will result.
+
+     As much of the data as can be fitted into the buffer will be copied to
+     userspace if the buffer pointer is not NULL.
+
+     On a successful return, the function will always return the amount of
+     data available rather than the amount copied.
+
+
+ (*) Instantiate a partially constructed key.
+
+        key_serial_t keyctl(KEYCTL_INSTANTIATE, key_serial_t key,
+                            const void *payload, size_t plen,
+                            key_serial_t keyring);
+
+     If the kernel calls back to userspace to complete the instantiation of a
+     key, userspace should use this call to supply data for the key before the
+     invoked process returns, or else the key will be marked negative
+     automatically.
+
+     The process must have write access on the key to be able to instantiate
+     it, and the key must be uninstantiated.
+
+     If a keyring is specified (non-zero), the key will also be linked into
+     that keyring, however all the constraints applying in KEYCTL_LINK apply
+     in this case too.
+
+     The payload and plen arguments describe the payload data as for add_key().
+
+
+ (*) Negatively instantiate a partially constructed key.
+
+        key_serial_t keyctl(KEYCTL_NEGATE, key_serial_t key,
+                            unsigned timeout, key_serial_t keyring);
+
+     If the kernel calls back to userspace to complete the instantiation of a
+     key, userspace should use this call mark the key as negative before the
+     invoked process returns if it is unable to fulfil the request.
+
+     The process must have write access on the key to be able to instantiate
+     it, and the key must be uninstantiated.
+
+     If a keyring is specified (non-zero), the key will also be linked into
+     that keyring, however all the constraints applying in KEYCTL_LINK apply
+     in this case too.
+
+
+===============
+KERNEL SERVICES
+===============
+
+The kernel services for key managment are fairly simple to deal with. They can
+be broken down into two areas: keys and key types.
+
+Dealing with keys is fairly straightforward. Firstly, the kernel service
+registers its type, then it searches for a key of that type. It should retain
+the key as long as it has need of it, and then it should release it. For a
+filesystem or device file, a search would probably be performed during the
+open call, and the key released upon close. How to deal with conflicting keys
+due to two different users opening the same file is left to the filesystem
+author to solve.
+
+When accessing a key's payload data, key->lock should be at least read locked,
+or else the data may be changed by an update being performed from userspace
+whilst the driver or filesystem is trying to access it. If no update method is
+supplied, then the key's payload may be accessed without holding a lock as
+there is no way to change it, provided it can be guaranteed that the key's
+type definition won't go away.
+
+(*) To search for a key, call:
+
+        struct key *request_key(const struct key_type *type,
+                                const char *description,
+                                const char *callout_string);
+
+    This is used to request a key or keyring with a description that matches
+    the description specified according to the key type's match function. This
+    permits approximate matching to occur. If callout_string is not NULL, then
+    /sbin/request-key will be invoked in an attempt to obtain the key from
+    userspace. In that case, callout_string will be passed as an argument to
+    the program.
+
+    Should the function fail error ENOKEY, EKEYEXPIRED or EKEYREVOKED will be
+    returned.
+
+
+(*) When it is no longer required, the key should be released using:
+
+        void key_put(struct key *key);
+
+    This can be called from interrupt context. If CONFIG_KEYS is not set then
+    the argument will not be parsed.
+
+
+(*) Extra references can be made to a key by calling the following function:
+
+        struct key *key_get(struct key *key);
+
+    These need to be disposed of by calling key_put() when they've been
+    finished with. The key pointer passed in will be returned. If the pointer
+    is NULL or CONFIG_KEYS is not set then the key will not be dereferenced and
+    no increment will take place.
+
+
+(*) A key's serial number can be obtained by calling:
+
+        key_serial_t key_serial(struct key *key);
+
+    If key is NULL or if CONFIG_KEYS is not set then 0 will be returned (in the
+    latter case without parsing the argument).
+
+
+(*) If a keyring was found in the search, this can be further searched by:
+
+        struct key *keyring_search(struct key *keyring,
+                                   const struct key_type *type,
+                                   const char *description)
+
+    This searches the keyring tree specified for a matching key. Error ENOKEY
+    is returned upon failure. If successful, the returned key will need to be
+    released.
+
+
+(*) To check the validity of a key, this function can be called:
+
+        int validate_key(struct key *key);
+
+    This checks that the key in question hasn't expired or and hasn't been
+    revoked. Should the key be invalid, error EKEYEXPIRED or EKEYREVOKED will
+    be returned. If the key is NULL or if CONFIG_KEYS is not set then 0 will be
+    returned (in the latter case without parsing the argument).
+
+
+(*) To register a key type, the following function should be called:
+
+        int register_key_type(struct key_type *type);
+
+    This will return error EEXIST if a type of the same name is already
+    present.
+
+
+(*) To unregister a key type, call:
+
+        void unregister_key_type(struct key_type *type);
+
+
+===================
+DEFINING A KEY TYPE
+===================
+
+A kernel service may want to define its own key type. For instance, an AFS
+filesystem might want to define a Kerberos 5 ticket key type. To do this, it
+author fills in a struct key_type and registers it with the system.
+
+The structure has a number of fields, some of which are mandatory:
+
+ (*) const char *name
+
+     The name of the key type. This is used to translate a key type name
+     supplied by userspace into a pointer to the structure.
+
+
+ (*) size_t def_datalen
+
+     This is optional - it supplies the default payload data length as
+     contributed to the quota. If the key type's payload is always or almost
+     always the same size, then this is a more efficient way to do things.
+
+     The data length (and quota) on a particular key can always be changed
+     during instantiation or update by calling:
+
+        int key_payload_reserve(struct key *key, size_t datalen);
+
+     With the revised data length. Error EDQUOT will be returned if this is
+     not viable.
+
+
+ (*) int (*instantiate)(struct key *key, const void *data, size_t datalen);
+
+     This method is called to attach a payload to a key during construction.
+     The payload attached need not bear any relation to the data passed to
+     this function.
+
+     If the amount of data attached to the key differs from the size in
+     keytype->def_datalen, then key_payload_reserve() should be called.
+
+     This method does not have to lock the key in order to attach a payload.
+     The fact that KEY_FLAG_INSTANTIATED is not set in key->flags prevents
+     anything else from gaining access to the key.
+
+     This method may sleep if it wishes.
+
+
+ (*) int (*duplicate)(struct key *key, const struct key *source);
+
+     If this type of key can be duplicated, then this method should be
+     provided. It is called to copy the payload attached to the source into
+     the new key. The data length on the new key will have been updated and
+     the quota adjusted already.
+
+     This method will be called with the source key's semaphore read-locked to
+     prevent its payload from being changed. It is safe to sleep here.
+
+
+ (*) int (*update)(struct key *key, const void *data, size_t datalen);
+
+     If this type of key can be updated, then this method should be
+     provided. It is called to update a key's payload from the blob of data
+     provided.
+
+     key_payload_reserve() should be called if the data length might change
+     before any changes are actually made. Note that if this succeeds, the
+     type is committed to changing the key because it's already been altered,
+     so all memory allocation must be done first.
+
+     key_payload_reserve() should be called with the key->lock write locked,
+     and the changes to the key's attached payload should be made before the
+     key is locked.
+
+     The key will have its semaphore write-locked before this method is
+     called. Any changes to the key should be made with the key's rwlock
+     write-locked also. It is safe to sleep here.
+
+
+ (*) int (*match)(const struct key *key, const void *desc);
+
+     This method is called to match a key against a description. It should
+     return non-zero if the two match, zero if they don't.
+
+     This method should not need to lock the key in any way. The type and
+     description can be considered invariant, and the payload should not be
+     accessed (the key may not yet be instantiated).
+
+     It is not safe to sleep in this method; the caller may hold spinlocks.
+
+
+ (*) void (*destroy)(struct key *key);
+
+     This method is optional. It is called to discard the payload data on a
+     key when it is being destroyed.
+
+     This method does not need to lock the key; it can consider the key as
+     being inaccessible. Note that the key's type may have changed before this
+     function is called.
+
+     It is not safe to sleep in this method; the caller may hold spinlocks.
+
+
+ (*) void (*describe)(const struct key *key, struct seq_file *p);
+
+     This method is optional. It is called during /proc/keys reading to
+     summarise a key's description and payload in text form.
+
+     This method will be called with the key's rwlock read-locked. This will
+     prevent the key's payload and state changing; also the description should
+     not change. This also means it is not safe to sleep in this method.
+
+
+ (*) long (*read)(const struct key *key, char __user *buffer, size_t buflen);
+
+     This method is optional. It is called by KEYCTL_READ to translate the
+     key's payload into something a blob of data for userspace to deal
+     with. Ideally, the blob should be in the same format as that passed in to
+     the instantiate and update methods.
+
+     If successful, the blob size that could be produced should be returned
+     rather than the size copied.
+
+     This method will be called with the key's semaphore read-locked. This
+     will prevent the key's payload changing. It is not necessary to also
+     read-lock key->lock when accessing the key's payload. It is safe to sleep
+     in this method, such as might happen when the userspace buffer is
+     accessed.
+
+
+============================
+REQUEST-KEY CALLBACK SERVICE
+============================
+
+To create a new key, the kernel will attempt to execute the following command
+line:
+
+        /sbin/request-key create <key> <uid> <gid> \
+                <threadring> <processring> <sessionring> <callout_info>
+
+<key> is the key being constructed, and the three keyrings are the process
+keyrings from the process that caused the search to be issued. These are
+included for two reasons:
+
+  (1) There may be an authentication token in one of the keyrings that is
+      required to obtain the key, eg: a Kerberos Ticket-Granting Ticket.
+
+  (2) The new key should probably be cached in one of these rings.
+
+This program should set it UID and GID to those specified before attempting to
+access any more keys. It may then look around for a user specific process to
+hand the request off to (perhaps a path held in placed in another key by, for
+example, the KDE desktop manager).
+
+The program (or whatever it calls) should finish construction of the key by
+calling KEYCTL_INSTANTIATE, which also permits it to cache the key in one of
+the keyrings (probably the session ring) before returning. Alternatively, the
+key can be marked as negative with KEYCTL_NEGATE; this also permits the key to
+be cached in one of the keyrings.
+
+If it returns with the key remaining in the unconstructed state, the key will
+be marked as being negative, it will be added to the session keyring, and an
+error will be returned to the key requestor.
+
+Supplementary information may be provided from whoever or whatever invoked
+this service. This will be passed as the <callout_info> parameter. If no such
+information was made available, then "-" will be passed as this parameter
+instead.
+
+
+Similarly, the kernel may attempt to update an expired or a soon to expire key
+by executing:
+
+        /sbin/request-key update <key> <uid> <gid> \
+                <threadring> <processring> <sessionring>
+
+In this case, the program isn't required to actually attach the key to a ring;
+the rings are provided for reference.