path: root/Documentation/security/keys.txt
diff options
authorDavid Howells <dhowells@redhat.com>2012-05-11 10:56:56 +0100
committerDavid Howells <dhowells@redhat.com>2012-05-11 10:56:56 +0100
commitfd75815f727f157a05f4c96b5294a4617c0557da (patch)
treeb2e76abf176d37b5d810b0c813b8c0219754b88c /Documentation/security/keys.txt
parentKEYS: Do LRU discard in full keyrings (diff)
KEYS: Add invalidation support
Add support for invalidating a key - which renders it immediately invisible to further searches and causes the garbage collector to immediately wake up, remove it from keyrings and then destroy it when it's no longer referenced. It's better not to do this with keyctl_revoke() as that marks the key to start returning -EKEYREVOKED to searches when what is actually desired is to have the key refetched. To invalidate a key the caller must be granted SEARCH permission by the key. This may be too strict. It may be better to also permit invalidation if the caller has any of READ, WRITE or SETATTR permission. The primary use for this is to evict keys that are cached in special keyrings, such as the DNS resolver or an ID mapper. Signed-off-by: David Howells <dhowells@redhat.com>
Diffstat (limited to 'Documentation/security/keys.txt')
1 files changed, 17 insertions, 0 deletions
diff --git a/Documentation/security/keys.txt b/Documentation/security/keys.txt
index d389acd31e19..aa0dbd74b71b 100644
--- a/Documentation/security/keys.txt
+++ b/Documentation/security/keys.txt
@@ -805,6 +805,23 @@ The keyctl syscall functions are:
kernel and resumes executing userspace.
+ (*) Invalidate a key.
+ long keyctl(KEYCTL_INVALIDATE, key_serial_t key);
+ This function marks a key as being invalidated and then wakes up the
+ garbage collector. The garbage collector immediately removes invalidated
+ keys from all keyrings and deletes the key when its reference count
+ reaches zero.
+ Keys that are marked invalidated become invisible to normal key operations
+ immediately, though they are still visible in /proc/keys until deleted
+ (they're marked with an 'i' flag).
+ A process must have search permission on the key for this function to be
+ successful.