Update flex_arrays.txt

[safe/jmp/linux-2.6] / Documentation / keys.txt

diff --git a/Documentation/keys.txt b/Documentation/keys.txt
index be424b0..e4dbbdb 100644 (file)
--- a/Documentation/keys.txt
+++ b/Documentation/keys.txt
@@ -26,7 +26,7 @@ This document has the following sections:
        - Notes on accessing payload contents
        - Defining a key type
        - Request-key callback service
        - Notes on accessing payload contents
        - Defining a key type
        - Request-key callback service

-       - Key access filesystem
+       - Garbage collection

 
 
 ============
 
 
 ============


@@ -113,6 +113,9 @@ Each key has a number of attributes:
 
      (*) Dead. The key's type was unregistered, and so the key is now useless.
 
 
      (*) Dead. The key's type was unregistered, and so the key is now useless.
 

+Keys in the last three states are subject to garbage collection.  See the
+section on "Garbage collection".
+

 
 ====================
 KEY SERVICE OVERVIEW
 
 ====================
 KEY SERVICE OVERVIEW


@@ -170,7 +173,8 @@ The key service provides a number of features besides keys:
      amount of description and payload space that can be consumed.
 
      The user can view information on this and other statistics through procfs
      amount of description and payload space that can be consumed.
 
      The user can view information on this and other statistics through procfs

-     files.
+     files.  The root user may also alter the quota limits through sysctl files
+     (see the section "New procfs files").

 
      Process-specific and thread-specific keyrings are not counted towards a
      user's quota.
 
      Process-specific and thread-specific keyrings are not counted towards a
      user's quota.


@@ -329,6 +333,27 @@ about the status of the key service:
        <bytes>/<max>           Key size quota
 
 
        <bytes>/<max>           Key size quota
 
 

+Four new sysctl files have been added also for the purpose of controlling the
+quota limits on keys:
+
+ (*) /proc/sys/kernel/keys/root_maxkeys
+     /proc/sys/kernel/keys/root_maxbytes
+
+     These files hold the maximum number of keys that root may have and the
+     maximum total number of bytes of data that root may have stored in those
+     keys.
+
+ (*) /proc/sys/kernel/keys/maxkeys
+     /proc/sys/kernel/keys/maxbytes
+
+     These files hold the maximum number of keys that each non-root user may
+     have and the maximum total number of bytes of data that each of those
+     users may have stored in their keys.
+
+Root may alter these by writing each new limit as a decimal number string to
+the appropriate file.
+
+

 ===============================
 USERSPACE SYSTEM CALL INTERFACE
 ===============================
 ===============================
 USERSPACE SYSTEM CALL INTERFACE
 ===============================


@@ -732,6 +757,26 @@ The keyctl syscall functions are:
      successful.
 
 
      successful.
 
 

+ (*) Install the calling process's session keyring on its parent.
+
+       long keyctl(KEYCTL_SESSION_TO_PARENT);
+
+     This functions attempts to install the calling process's session keyring
+     on to the calling process's parent, replacing the parent's current session
+     keyring.
+
+     The calling process must have the same ownership as its parent, the
+     keyring must have the same ownership as the calling process, the calling
+     process must have LINK permission on the keyring and the active LSM module
+     mustn't deny permission, otherwise error EPERM will be returned.
+
+     Error ENOMEM will be returned if there was insufficient memory to complete
+     the operation, otherwise 0 will be returned to indicate success.
+
+     The keyring will be replaced next time the parent process leaves the
+     kernel and resumes executing userspace.
+
+

 ===============
 KERNEL SERVICES
 ===============
 ===============
 KERNEL SERVICES
 ===============


@@ -842,7 +887,7 @@ payload contents" for more information.
     request_key_with_auxdata() respectively.
 
     These two functions return with the key potentially still under
     request_key_with_auxdata() respectively.
 
     These two functions return with the key potentially still under

-    construction.  To wait for contruction completion, the following should be
+    construction.  To wait for construction completion, the following should be

     called:
 
        int wait_for_key_construction(struct key *key, bool intr);
     called:
 
        int wait_for_key_construction(struct key *key, bool intr);


@@ -1209,3 +1254,17 @@ by executing:
 
 In this case, the program isn't required to actually attach the key to a ring;
 the rings are provided for reference.
 
 In this case, the program isn't required to actually attach the key to a ring;
 the rings are provided for reference.

+
+
+==================
+GARBAGE COLLECTION
+==================
+
+Dead keys (for which the type has been removed) will be automatically unlinked
+from those keyrings that point to them and deleted as soon as possible by a
+background garbage collector.
+
+Similarly, revoked and expired keys will be garbage collected, but only after a
+certain amount of time has passed.  This time is set as a number of seconds in:
+
+       /proc/sys/kernel/keys/gc_delay