KEYCTL_GRANT_PERMISSION
Section: Linux Key Management Calls (3)
Updated: 28 Aug 2019
Index
Return to Main Contents
NAME
keyctl_watch_key - Watch for changes to a key
SYNOPSIS
#include <keyutils.h>
long keyctl_watch_key(key_serial_t key,
int watch_queue_fd
int watch_id);
DESCRIPTION
keyctl_watch_key()
sets or removes a watch on
key.
watch_id
specifies the ID for a watch that will be included in notification messages.
It can be between 0 and 255 to add a key; it should be -1 to remove a key.
watch_queue_fd
is a file descriptor attached to a watch_queue device instance. Multiple
openings of a device provide separate instances. Each device instance can
only have one watch on any particular key.
Notification Record
Key-specific notification messages that the kernel emits into the buffer have
the following format:
struct key_notification {
struct watch_notification watch;
__u32 key_id;
__u32 aux;
};
The
watch.type
field will be set to
WATCH_TYPE_KEY_NOTIFY
and the
watch.subtype
field will contain one of the following constants, indicating the event that
occurred and the watch_id passed to keyctl_watch_key() will be placed in
watch.info
in the ID field. The following events are defined:
- NOTIFY_KEY_INSTANTIATED
-
This indicates that a watched key got instantiated or negatively instantiated.
key_id
indicates the key that was instantiated and
aux
is unused.
- NOTIFY_KEY_UPDATED
-
This indicates that a watched key got updated or instantiated by update.
key_id
indicates the key that was updated and
aux
is unused.
- NOTIFY_KEY_LINKED
-
This indicates that a key got linked into a watched keyring.
key_id
indicates the keyring that was modified
aux
indicates the key that was added.
- NOTIFY_KEY_UNLINKED
-
This indicates that a key got unlinked from a watched keyring.
key_id
indicates the keyring that was modified
aux
indicates the key that was removed.
- NOTIFY_KEY_CLEARED
-
This indicates that a watched keyring got cleared.
key_id
indicates the keyring that was cleared and
aux
is unused.
- NOTIFY_KEY_REVOKED
-
This indicates that a watched key got revoked.
key_id
indicates the key that was revoked and
aux
is unused.
- NOTIFY_KEY_INVALIDATED
-
This indicates that a watched key got invalidated.
key_id
indicates the key that was invalidated and
aux
is unused.
- NOTIFY_KEY_SETATTR
-
This indicates that a watched key had its attributes (owner, group,
permissions, timeout) modified.
key_id
indicates the key that was modified and
aux
is unused.
Removal Notification
When a watched key is garbage collected, all of its watches are automatically
destroyed and a notification is delivered to each watcher. This will normally
be an extended notification of the form:
struct watch_notification_removal {
struct watch_notification watch;
__u64 id;
};
The
watch.type
field will be set to
WATCH_TYPE_META
and the
watch.subtype
field will contain
WATCH_META_REMOVAL_NOTIFICATION.
If the extended notification is given, then the length will be 2 units,
otherwise it will be 1 and only the header will be present.
The watch_id passed to
keyctl_watch_key()
will be placed in
watch.info
in the ID field.
If the extension is present,
id
will be set to the ID of the destroyed key.
RETURN VALUE
On success
keyctl_watch_key()
returns
0 .
On error, the value
-1
will be returned and
errno
will have been set to an appropriate error.
ERRORS
- ENOKEY
-
The specified key does not exist.
- EKEYEXPIRED
-
The specified key has expired.
- EKEYREVOKED
-
The specified key has been revoked.
- EACCES
-
The named key exists, but does not grant
view
permission to the calling process.
- EBUSY
-
The specified key already has a watch on it for that device instance (add
only).
- EBADSLT
-
The specified key doesn't have a watch on it (removal only).
LINKING
This is a library function that can be found in
libkeyutils.
When linking,
-lkeyutils
should be specified to the linker.
SEE ALSO
keyctl(1),
add_key(2),
keyctl(2),
request_key(2),
keyctl(3),
keyrings(7),
keyutils(7)
Index
- NAME
-
- SYNOPSIS
-
- DESCRIPTION
-
- Notification Record
-
- Removal Notification
-
- RETURN VALUE
-
- ERRORS
-
- LINKING
-
- SEE ALSO
-
This document was created by
man2html,
using the manual pages.
Time: 20:54:46 GMT, April 30, 2024