V4L/DVB (4058): Bttv: add autodetection support for Osprey 230

[firefly-linux-kernel-4.4.55.git] / Documentation / keys.txt

diff --git a/Documentation/keys.txt b/Documentation/keys.txt
index 4afe03a58c5ba912d6977d38a76314fe34d7bf66..3bbe157b45e470ca656c72e47e523138c9be6fe8 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


@@ -196,7 +197,7 @@ 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 possessor, user, group and other access. Only
 
 Keys have an owner user ID, a group access ID, and a permissions mask. The mask
 has up to eight bits each for possessor, user, group and other access. Only

-five of each set of eight bits are defined. These permissions granted are:
+six of each set of eight bits are defined. These permissions granted are:

 
  (*) View
 
 
  (*) View
 


@@ -224,10 +225,42 @@ five of each set of eight bits are defined. These permissions granted are:
      keyring to a key, a process must have Write permission on the keyring and
      Link permission on the key.
 
      keyring to a key, a process must have Write permission on the keyring and
      Link permission on the key.
 

+ (*) Set Attribute
+
+     This permits a key's UID, GID and permissions mask to be changed.
+

 For changing the ownership, group ID or permissions mask, being the owner of
 the key or having the sysadmin capability is sufficient.
 
 
 For changing the ownership, group ID or permissions mask, being the owner of
 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; SE Linux is simply invoked after all basic permission checks have been
+performed.
+
+Each key is labeled with the same context as the task to which it belongs.
+Typically, this is the same task that was running when the key was created.
+The default keyrings are handled differently, but in a way that is very
+intuitive:
+
+ (*) The user and user session keyrings that are created when the user logs in
+     are currently labeled with the context of the login manager.
+
+ (*) 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.
+
+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.
+
+

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


@@ -242,15 +275,15 @@ about the status of the key service:
      this way:
 
        SERIAL   FLAGS  USAGE EXPY PERM     UID   GID   TYPE      DESCRIPTION: SUMMARY
      this way:
 
        SERIAL   FLAGS  USAGE EXPY PERM     UID   GID   TYPE      DESCRIPTION: SUMMARY

-       00000001 I-----    39 perm 1f1f0000     0     0 keyring   _uid_ses.0: 1/4
-       00000002 I-----     2 perm 1f1f0000     0     0 keyring   _uid.0: empty
-       00000007 I-----     1 perm 1f1f0000     0     0 keyring   _pid.1: empty
-       0000018d I-----     1 perm 1f1f0000     0     0 keyring   _pid.412: empty
-       000004d2 I--Q--     1 perm 1f1f0000    32    -1 keyring   _uid.32: 1/4
-       000004d3 I--Q--     3 perm 1f1f0000    32    -1 keyring   _uid_ses.32: empty
+       00000001 I-----    39 perm 1f3f0000     0     0 keyring   _uid_ses.0: 1/4
+       00000002 I-----     2 perm 1f3f0000     0     0 keyring   _uid.0: empty
+       00000007 I-----     1 perm 1f3f0000     0     0 keyring   _pid.1: empty
+       0000018d I-----     1 perm 1f3f0000     0     0 keyring   _pid.412: empty
+       000004d2 I--Q--     1 perm 1f3f0000    32    -1 keyring   _uid.32: 1/4
+       000004d3 I--Q--     3 perm 1f3f0000    32    -1 keyring   _uid_ses.32: empty

        00000892 I--QU-     1 perm 1f000000     0     0 user      metal:copper: 0
        00000892 I--QU-     1 perm 1f000000     0     0 user      metal:copper: 0

-       00000893 I--Q-N     1  35s 1f1f0000     0     0 user      metal:silver: 0
-       00000894 I--Q--     1  10h 001f0000     0     0 user      metal:gold: 0
+       00000893 I--Q-N     1  35s 1f3f0000     0     0 user      metal:silver: 0
+       00000894 I--Q--     1  10h 003f0000     0     0 user      metal:gold: 0

 
      The flags are:
 
 
      The flags are:
 


@@ -304,6 +337,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:


@@ -494,7 +529,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:


@@ -624,6 +663,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
 ===============


@@ -856,24 +930,6 @@ The structure has a number of fields, some of which are mandatory:
      It is safe to sleep in this method.
 
 
      It is safe to sleep in this method.
 
 

- (*) 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, thus RCU constraints need not be
-     applied to the source key.
-
-     This method does not have to lock the destination 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.
-
-     It is safe to sleep in this method.
-
-

  (*) 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.
  (*) 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.


@@ -908,6 +964,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