Merge tag 'notifications-20200601' of git://git.kernel.org/pub/scm/linux/kernel/git...

[platform/kernel/linux-rpi.git] / Documentation / security / keys / core.rst

diff --git a/Documentation/security/keys/core.rst b/Documentation/security/keys/core.rst
index 9367d0f..cdc42cc 100644 (file)
--- a/Documentation/security/keys/core.rst
+++ b/Documentation/security/keys/core.rst
@@ -1030,6 +1030,63 @@ The keyctl syscall functions are:
      written into the output buffer.  Verification returns 0 on success.
 
 
+  *  Watch a key or keyring for changes::
+
+       long keyctl(KEYCTL_WATCH_KEY, key_serial_t key, int queue_fd,
+                   const struct watch_notification_filter *filter);
+
+     This will set or remove a watch for changes on the specified key or
+     keyring.
+
+     "key" is the ID of the key to be watched.
+
+     "queue_fd" is a file descriptor referring to an open "/dev/watch_queue"
+     which manages the buffer into which notifications will be delivered.
+
+     "filter" is either NULL to remove a watch or a filter specification to
+     indicate what events are required from the key.
+
+     See Documentation/watch_queue.rst for more information.
+
+     Note that only one watch may be emplaced for any particular { key,
+     queue_fd } combination.
+
+     Notification records look like::
+
+       struct key_notification {
+               struct watch_notification watch;
+               __u32   key_id;
+               __u32   aux;
+       };
+
+     In this, watch::type will be "WATCH_TYPE_KEY_NOTIFY" and subtype will be
+     one of::
+
+       NOTIFY_KEY_INSTANTIATED
+       NOTIFY_KEY_UPDATED
+       NOTIFY_KEY_LINKED
+       NOTIFY_KEY_UNLINKED
+       NOTIFY_KEY_CLEARED
+       NOTIFY_KEY_REVOKED
+       NOTIFY_KEY_INVALIDATED
+       NOTIFY_KEY_SETATTR
+
+     Where these indicate a key being instantiated/rejected, updated, a link
+     being made in a keyring, a link being removed from a keyring, a keyring
+     being cleared, a key being revoked, a key being invalidated or a key
+     having one of its attributes changed (user, group, perm, timeout,
+     restriction).
+
+     If a watched key is deleted, a basic watch_notification will be issued
+     with "type" set to WATCH_TYPE_META and "subtype" set to
+     watch_meta_removal_notification.  The watchpoint ID will be set in the
+     "info" field.
+
+     This needs to be configured by enabling:
+
+       "Provide key/keyring change notifications" (KEY_NOTIFICATIONS)
+
+
 Kernel Services
 ===============