[PATCH] lockdep: disable lock debugging when kernel state becomes untrusted

[linux-2.6] / Documentation / keys.txt

diff --git a/Documentation/keys.txt b/Documentation/keys.txt
index 6304db59bfe45619c198494c54705b8f5610a585..e373f02128434277bc53098185b393df0a7c36d5 100644 (file)
--- a/Documentation/keys.txt
+++ b/Documentation/keys.txt
@@ -19,6 +19,7 @@ This document has the following sections:
        - Key overview
        - Key service overview
        - Key access permissions
        - Key overview
        - Key service overview
        - Key access permissions

+       - SELinux support

        - New procfs files
        - Userspace system call interface
        - Kernel services
        - New procfs files
        - Userspace system call interface
        - Kernel services


@@ -232,6 +233,39 @@ For changing the ownership, group ID or permissions mask, being the owner of
 the key or having the sysadmin capability is sufficient.
 
 
 the key or having the sysadmin capability is sufficient.
 
 

+===============
+SELINUX SUPPORT
+===============
+
+The security class "key" has been added to SELinux so that mandatory access
+controls can be applied to keys created within various contexts.  This support
+is preliminary, and is likely to change quite significantly in the near future.
+Currently, all of the basic permissions explained above are provided in SELinux
+as well; SELinux is simply invoked after all basic permission checks have been
+performed.
+
+The value of the file /proc/self/attr/keycreate influences the labeling of
+newly-created keys.  If the contents of that file correspond to an SELinux
+security context, then the key will be assigned that context.  Otherwise, the
+key will be assigned the current context of the task that invoked the key
+creation request.  Tasks must be granted explicit permission to assign a
+particular context to newly-created keys, using the "create" permission in the
+key security class.
+
+The default keyrings associated with users will be labeled with the default
+context of the user if and only if the login programs have been instrumented to
+properly initialize keycreate during the login process.  Otherwise, they will
+be labeled with the context of the login program itself.
+
+Note, however, that the default keyrings associated with the root user are
+labeled with the default kernel context, since they are created early in the
+boot process, before root has a chance to log in.
+
+The keyrings associated with new threads are each labeled with the context of
+their associated thread, and both session and process keyrings are handled
+similarly.
+
+

 ================
 NEW PROCFS FILES
 ================
 ================
 NEW PROCFS FILES
 ================


@@ -241,9 +275,17 @@ about the status of the key service:
 
  (*) /proc/keys
 
 
  (*) /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:
+     This lists the keys that are currently viewable by the task reading the
+     file, giving information about their type, description and permissions.
+     It is not possible to view the payload of the key this way, though some
+     information about it may be given.
+
+     The only keys included in the list are those that grant View permission to
+     the reading process whether or not it possesses them.  Note that LSM
+     security checks are still performed, and may further filter out keys that
+     the current process is not authorised to view.
+
+     The contents of the file look like this:

 
        SERIAL   FLAGS  USAGE EXPY PERM     UID   GID   TYPE      DESCRIPTION: SUMMARY
        00000001 I-----    39 perm 1f3f0000     0     0 keyring   _uid_ses.0: 1/4
 
        SERIAL   FLAGS  USAGE EXPY PERM     UID   GID   TYPE      DESCRIPTION: SUMMARY
        00000001 I-----    39 perm 1f3f0000     0     0 keyring   _uid_ses.0: 1/4


@@ -271,7 +313,7 @@ about the status of the key service:
  (*) /proc/key-users
 
      This file lists the tracking data for each user that has at least one key
  (*) /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:
+     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
 
        [root@andromeda root]# cat /proc/key-users
        0:     46 45/45 1/100 13/10000


@@ -308,6 +350,8 @@ process making the call:
        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
        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

+       KEY_SPEC_REQKEY_AUTH_KEY        -7      assumed request_key()
+                                                 authorisation key

 
 
 The main syscalls are:
 
 
 The main syscalls are:


@@ -498,7 +542,11 @@ The keyctl syscall functions are:
      keyring is full, error ENFILE will result.
 
      The link procedure checks the nesting of the keyrings, returning ELOOP if
      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.
+     it appears too deep or EDEADLK if the link would introduce a cycle.
+
+     Any links within the keyring to keys that match the new key in terms of
+     type and description will be discarded from the keyring as the new one is
+     added.

 
 
  (*) Unlink a key or keyring from another keyring:
 
 
  (*) Unlink a key or keyring from another keyring:


@@ -628,6 +676,41 @@ The keyctl syscall functions are:
      there is one, otherwise the user default session keyring.
 
 
      there is one, otherwise the user default session keyring.
 
 

+ (*) Set the timeout on a key.
+
+       long keyctl(KEYCTL_SET_TIMEOUT, key_serial_t key, unsigned timeout);
+
+     This sets or clears the timeout on a key. The timeout can be 0 to clear
+     the timeout or a number of seconds to set the expiry time that far into
+     the future.
+
+     The process must have attribute modification access on a key to set its
+     timeout. Timeouts may not be set with this function on negative, revoked
+     or expired keys.
+
+
+ (*) Assume the authority granted to instantiate a key
+
+       long keyctl(KEYCTL_ASSUME_AUTHORITY, key_serial_t key);
+
+     This assumes or divests the authority required to instantiate the
+     specified key. Authority can only be assumed if the thread has the
+     authorisation key associated with the specified key in its keyrings
+     somewhere.
+
+     Once authority is assumed, searches for keys will also search the
+     requester's keyrings using the requester's security label, UID, GID and
+     groups.
+
+     If the requested authority is unavailable, error EPERM will be returned,
+     likewise if the authority has been revoked because the target key is
+     already instantiated.
+
+     If the specified key is 0, then any assumed authority will be divested.
+
+     The assumed authorititive key is inherited across fork and exec.
+
+

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


@@ -697,6 +780,17 @@ payload contents" for more information.
     See also Documentation/keys-request-key.txt.
 
 
     See also Documentation/keys-request-key.txt.
 
 

+(*) To search for a key, passing auxiliary data to the upcaller, call:
+
+       struct key *request_key_with_auxdata(const struct key_type *type,
+                                            const char *description,
+                                            const char *callout_string,
+                                            void *aux);
+
+    This is identical to request_key(), except that the auxiliary data is
+    passed to the key_type->request_key() op if it exists.
+
+

 (*) When it is no longer required, the key should be released using:
 
        void key_put(struct key *key);
 (*) When it is no longer required, the key should be released using:
 
        void key_put(struct key *key);


@@ -894,6 +988,16 @@ The structure has a number of fields, some of which are mandatory:
      It is not safe to sleep in this method; the caller may hold spinlocks.
 
 
      It is not safe to sleep in this method; the caller may hold spinlocks.
 
 

+ (*) void (*revoke)(struct key *key);
+
+     This method is optional.  It is called to discard part of the payload
+     data upon a key being revoked.  The caller will have the key semaphore
+     write-locked.
+
+     It is safe to sleep in this method, though care should be taken to avoid
+     a deadlock against the key semaphore.
+
+

  (*) void (*destroy)(struct key *key);
 
      This method is optional. It is called to discard the payload data on a key
  (*) void (*destroy)(struct key *key);
 
      This method is optional. It is called to discard the payload data on a key


@@ -938,6 +1042,24 @@ The structure has a number of fields, some of which are mandatory:
      as might happen when the userspace buffer is accessed.
 
 
      as might happen when the userspace buffer is accessed.
 
 

+ (*) int (*request_key)(struct key *key, struct key *authkey, const char *op,
+                       void *aux);
+
+     This method is optional.  If provided, request_key() and
+     request_key_with_auxdata() will invoke this function rather than
+     upcalling to /sbin/request-key to operate upon a key of this type.
+
+     The aux parameter is as passed to request_key_with_auxdata() or is NULL
+     otherwise.  Also passed are the key to be operated upon, the
+     authorisation key for this operation and the operation type (currently
+     only "create").
+
+     This function should return only when the upcall is complete.  Upon return
+     the authorisation key will be revoked, and the target key will be
+     negatively instantiated if it is still uninstantiated.  The error will be
+     returned to the caller of request_key*().
+
+

 ============================
 REQUEST-KEY CALLBACK SERVICE
 ============================
 ============================
 REQUEST-KEY CALLBACK SERVICE
 ============================