keys: update the documentation with info about "logon" keys
[linux-2.6.git] / Documentation / security / keys.txt
index 4d75931..d389acd 100644 (file)
@@ -123,7 +123,7 @@ KEY SERVICE OVERVIEW
 
 The key service provides a number of features besides keys:
 
- (*) The key service defines two special key types:
+ (*) The key service defines three special key types:
 
      (+) "keyring"
 
@@ -137,6 +137,18 @@ The key service provides a number of features besides keys:
         blobs of data. These can be created, updated and read by userspace,
         and aren't intended for use by kernel services.
 
+     (+) "logon"
+
+        Like a "user" key, a "logon" key has a payload that is an arbitrary
+        blob of data. It is intended as a place to store secrets which are
+        accessible to the kernel but not to userspace programs.
+
+        The description can be arbitrary, but must be prefixed with a non-zero
+        length string that describes the key "subclass". The subclass is
+        separated from the rest of the description by a ':'. "logon" keys can
+        be created and updated from userspace, but the payload is only
+        readable from kernel space.
+
  (*) Each process subscribes to three keyrings: a thread-specific keyring, a
      process-specific keyring, and a session-specific keyring.
 
@@ -554,6 +566,10 @@ The keyctl syscall functions are:
      process must have write permission on the keyring, and it must be a
      keyring (or else error ENOTDIR will result).
 
+     This function can also be used to clear special kernel keyrings if they
+     are appropriately marked if the user has CAP_SYS_ADMIN capability.  The
+     DNS resolver cache keyring is an example of this.
+
 
  (*) Link a key into a keyring:
 
@@ -668,7 +684,7 @@ The keyctl syscall functions are:
 
      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.
+     invoked process returns if it is unable to fulfill the request.
 
      The process must have write access on the key to be able to instantiate
      it, and the key must be uninstantiated.