| .\" |
| .\" 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) |