diff options
| author | Michael Kerrisk <mtk.manpages@gmail.com> | 2016-11-01 16:43:33 +0100 |
|---|---|---|
| committer | Michael Kerrisk <mtk.manpages@gmail.com> | 2016-12-27 09:36:16 +0100 |
| commit | 33af8657ac510fd9bf72e6ac9749f3fa06aa420e (patch) | |
| tree | 0d127f20e6617ed267adb2f4bf8352180ede1181 /man7 | |
| parent | 6b71fd9acacb90935f1108993d92acf517f26a63 (diff) | |
| download | man-pages-33af8657ac510fd9bf72e6ac9749f3fa06aa420e.tar.gz | |
persistent-keyring.7: New page adopted from keyutils
Since this page documents kernel-user-space interfaces,
it makes sense to have it as part of man-pages, rather
than the keyutils package.
Signed-off-by: David Howells <dhowells@redhat.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Diffstat (limited to 'man7')
| -rw-r--r-- | man7/persistent-keyring.7 | 67 |
1 files changed, 67 insertions, 0 deletions
diff --git a/man7/persistent-keyring.7 b/man7/persistent-keyring.7 new file mode 100644 index 0000000000..6e5596cfd0 --- /dev/null +++ b/man7/persistent-keyring.7 @@ -0,0 +1,67 @@ +.\" +.\" Copyright (C) 2014 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 Licence +.\" as published by the Free Software Foundation; either version +.\" 2 of the Licence, or (at your option) any later version. +.\" +.TH "PERSISTENT KEYRING" 7 "20 Feb 2014" Linux "Kernel key management" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH NAME +persistent_keyring \- Per-user persistent keyring +.SH DESCRIPTION +The +.B persistent keyring +is a keyring used to anchor keys on behalf of a user. Each UID the kernel +deals with has its own persistent keyring that is shared between all threads +owned by that UID. +.P +The persistent keyring is created on demand when a thread requests it. The +keyring's expiration timer is reset every time it is accessed to the value in: +.IP +/proc/sys/kernel/keys/persistent_keyring_expiry +.P +The persistent keyring is not searched by \fBrequest_key\fP() unless it is +referred to by a keyring that is. +.P +The persistent keyring may not be accessed directly, even by processes with +the appropriate UID. Instead it must be linked to one of a process's keyrings +first before that keyring can access it by virtue of its possessor permits. +This is done with \fBkeyctl_get_persistent\fP(). +.P +Persistent keyrings are independent of clone(), fork(), vfork(), execve() and +exit(). They persist until their expiration timers trigger - at which point +they are garbage collected. This allows them to carry keys beyond the life of +the kernel's record of the corresponding UID (the destruction of which results +in the destruction of the user and user session keyrings). +.P +If a persistent keyring does not exist when it is accessed, it will be +created. +.SH SPECIAL OPERATIONS +The keyutils library provides a special operation for manipulating persistent +keyrings: +.IP \fBkeyctl_get_persistent\fP() +This operation allows the caller to get the persistent keyring corresponding +to their own UID or, if they have \fBCAP_SETUID\fR, the persistent keyring +corresponding to some other UID in the same user namespace. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH SEE ALSO +.BR keyctl (1), +.br +.BR keyctl (3), +.br +.BR keyctl_get_persistent (3), +.br +.BR keyrings (7), +.br +.BR process-keyring (7), +.br +.BR session-keyring (7), +.br +.BR thread-keyring (7), +.br +.BR user-keyring (7), +.br +.BR user-session-keyring (7) |