diff --git a/man7/user-keyring.7 b/man7/user-keyring.7 new file mode 100644 index 000000000..db562a253 --- /dev/null +++ b/man7/user-keyring.7 @@ -0,0 +1,63 @@ +.\" +.\" 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 "USER KEYRING" 7 "20 Feb 2014" Linux "Kernel key management" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH NAME +user_keyring \- Per-user keyring +.SH DESCRIPTION +The +.B user keyring +is a keyring used to anchor keys on behalf of a user. Each UID the kernel +deals with has its own user keyring. This keyring is associated with the +record that the kernel maintains for the UID and, once created, is retained as +long as that record persists. It is shared amongst all processes of that UID. +.P +The user keyring is created on demand when a thread requests it. Normally, +this happens when \fBpam_keyinit\fP is invoked when a user logs in. +.P +The user keyring is not searched by default by \fBrequest_key\fP(). When the +pam_keyinit module creates a session keyring, it adds to it a link to the user +keyring so that the user keyring will be searched when the session keyring is. +.P +A special serial number value, \fBKEY_SPEC_USER_KEYRING\fP, is defined that +can be used in lieu of the calling process's user keyring's actual serial +number. +.P +From the keyctl utility, '\fB@u\fP' can be used instead of a numeric key ID in +much the same way. +.P +User keyrings are independent of clone(), fork(), vfork(), execve() and exit() +excepting that the keyring is destroyed when the UID record is destroyed when +the last process pinning it exits. +.P +If it necessary to for a key associated with a user to exist beyond the UID +record being garbage collected - for example for use by a cron script - then +the \fBpersistent keyring\fP should be used instead. +.P +If a user keyring does not exist when it is accessed, it will be created. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH SEE ALSO +.BR keyctl (1), +.br +.BR keyctl (3), +.br +.BR keyrings (7), +.br +.BR pam_keyinit (8), +.br +.BR process-keyring (7), +.br +.BR session-keyring (7), +.br +.BR thread-keyring (7), +.br +.BR user-session-keyring (7), +.br +.BR persistent-keyring (7)