1 files changed, 81 insertions, 0 deletions
diff --git a/man/man7/user-keyring.7 b/man/man7/user-keyring.7
new file mode 100644
index 000000000..77c4bb0a9
--- /dev/null
+++ b/man/man7/user-keyring.7
@@ -0,0 +1,81 @@
+.\" Copyright (C) 2014 Red Hat, Inc. All Rights Reserved.
+.\" Written by David Howells (dhowells@redhat.com)
+.\"
+.\" SPDX-License-Identifier: GPL-2.0-or-later
+.\"
+.TH user-keyring 7 (date) "Linux man-pages (unreleased)"
+.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.
+.P
+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.)
+.P
+Typically, the user keyring is created by
+.BR pam_keyinit (8)
+when a user logs in.
+.P
+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.
+.P
+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.
+.P
+From the
+.BR keyctl (1)
+utility, '\fB@u\fP' can be used instead of a numeric key ID in
+much the same way.
+.P
+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.
+.P
+If it is necessary for a key associated with a user to exist beyond the UID
+record being garbage collected\[em]for example, for use by a
+.BR cron (8)
+script\[em]then the
+.BR persistent\-keyring (7)
+should be used instead.
+.P
+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)