diff options
Diffstat (limited to 'man/keyctl_watch_key.3')
| -rw-r--r-- | man/keyctl_watch_key.3 | 206 |
1 files changed, 206 insertions, 0 deletions
diff --git a/man/keyctl_watch_key.3 b/man/keyctl_watch_key.3 new file mode 100644 index 0000000..044b7a3 --- /dev/null +++ b/man/keyctl_watch_key.3 @@ -0,0 +1,206 @@ +.\" +.\" Copyright (C) 2019 Red Hat, Inc. All Rights Reserved. +.\" Written by David Howells (dhowells@redhat.com) +.\" +.\" This program is free software; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public License +.\" as published by the Free Software Foundation; either version +.\" 2 of the License, or (at your option) any later version. +.\" +.TH KEYCTL_GRANT_PERMISSION 3 "28 Aug 2019" Linux "Linux Key Management Calls" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH NAME +keyctl_watch_key \- Watch for changes to a key +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH SYNOPSIS +.nf +.B #include <keyutils.h> +.sp +.BI "long keyctl_watch_key(key_serial_t " key , +.BI " int " watch_queue_fd +.BI " int " watch_id ");" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH DESCRIPTION +.BR keyctl_watch_key () +sets or removes a watch on +.IR key . +.PP +.I 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. +.PP +.I 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. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SS Notification Record +.PP +Key-specific notification messages that the kernel emits into the buffer have +the following format: +.PP +.in +4n +.EX +struct key_notification { + struct watch_notification watch; + __u32 key_id; + __u32 aux; +}; +.EE +.in +.PP +The +.I watch.type +field will be set to +.B WATCH_TYPE_KEY_NOTIFY +and the +.I 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 +.I watch.info +in the ID field. The following events are defined: +.TP +.B NOTIFY_KEY_INSTANTIATED +This indicates that a watched key got instantiated or negatively instantiated. +.I key_id +indicates the key that was instantiated and +.I aux +is unused. +.TP +.B NOTIFY_KEY_UPDATED +This indicates that a watched key got updated or instantiated by update. +.I key_id +indicates the key that was updated and +.I aux +is unused. +.TP +.B NOTIFY_KEY_LINKED +This indicates that a key got linked into a watched keyring. +.I key_id +indicates the keyring that was modified +.I aux +indicates the key that was added. +.TP +.B NOTIFY_KEY_UNLINKED +This indicates that a key got unlinked from a watched keyring. +.I key_id +indicates the keyring that was modified +.I aux +indicates the key that was removed. +.TP +.B NOTIFY_KEY_CLEARED +This indicates that a watched keyring got cleared. +.I key_id +indicates the keyring that was cleared and +.I aux +is unused. +.TP +.B NOTIFY_KEY_REVOKED +This indicates that a watched key got revoked. +.I key_id +indicates the key that was revoked and +.I aux +is unused. +.TP +.B NOTIFY_KEY_INVALIDATED +This indicates that a watched key got invalidated. +.I key_id +indicates the key that was invalidated and +.I aux +is unused. +.TP +.B NOTIFY_KEY_SETATTR +This indicates that a watched key had its attributes (owner, group, +permissions, timeout) modified. +.I key_id +indicates the key that was modified and +.I aux +is unused. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SS 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: +.PP +.in +4n +.EX +struct watch_notification_removal { + struct watch_notification watch; + __u64 id; +}; +.EE +.in +.PP +The +.I watch.type +field will be set to +.B WATCH_TYPE_META +and the +.I watch.subtype +field will contain +.BR 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. +.PP +The watch_id passed to +.IR keyctl_watch_key () +will be placed in +.I watch.info +in the ID field. +.PP +If the extension is present, +.I id +will be set to the ID of the destroyed key. +.PP +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH RETURN VALUE +On success +.BR keyctl_watch_key () +returns +.B 0 . +On error, the value +.B -1 +will be returned and +.I errno +will have been set to an appropriate error. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH ERRORS +.TP +.B ENOKEY +The specified key does not exist. +.TP +.B EKEYEXPIRED +The specified key has expired. +.TP +.B EKEYREVOKED +The specified key has been revoked. +.TP +.B EACCES +The named key exists, but does not grant +.B view +permission to the calling process. +.TP +.B EBUSY +The specified key already has a watch on it for that device instance (add +only). +.TP +.B EBADSLT +The specified key doesn't have a watch on it (removal only). +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH LINKING +This is a library function that can be found in +.IR libkeyutils . +When linking, +.B \-lkeyutils +should be specified to the linker. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH SEE ALSO +.ad l +.nh +.BR keyctl (1), +.BR add_key (2), +.BR keyctl (2), +.BR request_key (2), +.BR keyctl (3), +.BR keyrings (7), +.BR keyutils (7) |