| .\" |
| .\" Copyright (C) 2014 Red Hat, Inc. All Rights Reserved. |
| .\" Written by David Howells (dhowells@redhat.com) |
| .\" |
| .\" %%%LICENSE_START(GPLv2+_SW_ONEPARA) |
| .\" 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. |
| .\" %%%LICENSE_END |
| .\" |
| .TH "USER-KEYRING" 7 2017-03-13 Linux "Linux Programmer's Manual" |
| .SH NAME |
| user-keyring \- per-user keyring |
| .SH DESCRIPTION |
| The 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 that |
| is shared by all processes with that UID. |
| The user keyring has a name (description) of the form |
| .I _uid.<UID> |
| where |
| .I <UID> |
| is the user ID of the corresponding user. |
| .PP |
| The user keyring is associated with the record that the kernel maintains |
| for the UID. |
| It comes into existence upon the first attempt to access either the |
| user keyring, the |
| .BR user-session-keyring (7), |
| or the |
| .BR session-keyring (7). |
| The keyring remains pinned in existence so long as there are processes |
| running with that real UID or files opened by those processes remain open. |
| (The keyring can also be pinned indefinitely by linking it |
| into another keyring.) |
| .PP |
| Typically, the user keyring is created by |
| .BR pam_keyinit (8) |
| when a user logs in. |
| .PP |
| The user keyring is not searched by default by |
| .BR request_key (2). |
| When |
| .BR pam_keyinit (8) |
| 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. |
| .PP |
| A special serial number value, |
| .BR KEY_SPEC_USER_KEYRING , |
| is defined that can be used in lieu of the actual serial number of |
| the calling process's user keyring. |
| .PP |
| From the |
| .BR keyctl (1) |
| utility, '\fB@u\fP' can be used instead of a numeric key ID in |
| much the same way. |
| .PP |
| User keyrings are independent of |
| .BR clone (2), |
| .BR fork (2), |
| .BR vfork (2), |
| .BR execve (2), |
| and |
| .BR _exit (2) |
| excepting that the keyring is destroyed when the UID record is destroyed when |
| the last process pinning it exits. |
| .PP |
| If it is necessary for a key associated with a user to exist beyond the UID |
| record being garbage collected\(emfor example, for use by a |
| .BR cron (8) |
| script\(emthen the |
| .BR persistent-keyring (7) |
| should be used instead. |
| .PP |
| If a user keyring does not exist when it is accessed, it will be created. |
| .SH SEE ALSO |
| .ad l |
| .nh |
| .BR keyctl (1), |
| .BR keyctl (3), |
| .BR keyrings (7), |
| .BR persistent\-keyring (7), |
| .BR process\-keyring (7), |
| .BR session\-keyring (7), |
| .BR thread\-keyring (7), |
| .BR user\-session\-keyring (7), |
| .BR pam_keyinit (8) |