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